diff options
Diffstat (limited to 'third_party/heimdal/kdc/httpkadmind.8')
-rw-r--r-- | third_party/heimdal/kdc/httpkadmind.8 | 424 |
1 files changed, 424 insertions, 0 deletions
diff --git a/third_party/heimdal/kdc/httpkadmind.8 b/third_party/heimdal/kdc/httpkadmind.8 new file mode 100644 index 0000000..90b4f63 --- /dev/null +++ b/third_party/heimdal/kdc/httpkadmind.8 @@ -0,0 +1,424 @@ +.\" Copyright (c) 2020 Kungliga Tekniska Högskolan +.\" (Royal Institute of Technology, Stockholm, Sweden). +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" 3. Neither the name of the Institute nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.Dd January 2, 2020 +.Dt HTTPKADMIND 8 +.Os HEIMDAL +.Sh NAME +.Nm httpkadmind +.Nd HTTP HDB Administration Interface +.Sh SYNOPSIS +.Nm +.Op Fl h | Fl Fl help +.Op Fl Fl version +.Op Fl H Ar HOSTNAME +.Op Fl d | Fl Fl daemon +.Op Fl Fl daemon-child +.Op Fl Fl reverse-proxied +.Op Fl p Ar port number (default: 443) +.Op Fl Fl temp-dir= Ns Ar DIRECTORY +.Op Fl Fl cert=HX509-STORE +.Op Fl Fl private-key=HX509-STORE +.Op Fl T | Fl Fl token-authentication-type=Negotiate|Bearer +.Op Fl Fl realm=REALM +.Op Fl Fl read-only +.Op Fl l | Fl Fl local +.Op Fl Fl local-read-only +.Op Fl Fl hdb=HDB +.Op Fl Fl stash-file=FILENAME +.Op Fl Fl primary-server-uri=URI +.Op Fl Fl read-only-admin-server=HOSTNAME[:PORT] +.Op Fl Fl writable-admin-server=HOSTNAME[:PORT] +.Op Fl Fl kadmin-client-name=PRINCIPAL +.Op Fl Fl kadmin-client-keytab=KEYTAB +.Op Fl t | Fl Fl thread-per-client +.Oo Fl v \*(Ba Xo +.Fl Fl verbose= Ns Ar run verbosely +.Xc +.Oc +.Sh DESCRIPTION +Serves the following resources: +.Ar /get-keys and +.Ar /get-config . +.Pp +The +.Ar /get-keys +end-point allows callers to get keytab content for named +principals, possibly performing write operations such as creating +a non-existent principal, or rotating its keys, if requested. +.Pp +The +.Ar /get-config +end-point allows callers to get +.Nm krb5.conf +contents for a given principal. +.Pp +This service can run against a local HDB, or against a remote HDB +via the +.Nm kadmind(8) +protocol. +Read operations are always allowed, but write operations can be +preformed either against writable +.Nm kadmind(8) +server(s) or redirected to another +.Nm httpkadmind(8). +.Pp +The +.Ar /get-config +end-point accepts a single query parameter: +.Bl -tag -width Ds -offset indent +.It Ar princ=PRINCIPAL . +.El +.Pp +The +.Ar /get-keys +end-point accepts various parameters: +.Bl -tag -width Ds -offset indent +.It Ar spn=PRINCIPAL +Names the host-based service principal whose keys to get. +May be given multiple times, and all named principal's keys will +be fetched. +.It Ar dNSName=HOSTNAME +Names the host-based service principal's hostname whose keys to get. +May be given multiple times, and all named principal's keys will +be fetched. +.It Ar service=SERVICE +Hostnames given with +.Ar dNSName=HOSTNAME +will be qualified with this service name to form a host-based +service principal. +May be given multiple times, in which case the cartesian product +of +.Ar dNSName=HOSTNAME +ad +.Ar service=SERVICE +will be used. +Defaults to +.Ar HTTP . +.It realm=REALM +Must be present if the +.Nm httpkadmind +daemon's default realm is not desired. +.It Ar enctypes=ENCTYPE,... +A comma-separated list of enctypes that the principal is expected +to support (used for Kerberos Ticket session key negotiation). +Defaults to the +.Ar supported_enctypes +configured in +.Nm krb5.conf(5) . +.It Ar materialize=true +If the named principal(s) is (are) virtual, this will cause it +(them) to be materialized as a concrete principal. +(Currently not supported.) +.It Ar create=true +If the named principal(s) does not (do not) exist, this will +cause it (them) to be created. +.It Ar rotate=true +This will cause the keys of concrete principals to be rotated. +.It Ar revoke=true +This will cause old keys of concrete principals to be deleted +if their keys are being rotated. +This means that extant service tickets with those principals as +the target will not be able to be decrypted by the caller as it +will not have the necessary keys. +.El +.Pp +Authorization is handled via the same mechanism as in +.Nm bx509d(8) +which was originally intended to authorize certification requests +(CSRs). +Authorization for extracting keys is specified like for +.Nm bx509d(8) , +but using +.Nm [ext_keytab] +as the +.Nm krb5.conf(5) section. +Clients with host-based principals for the the host service can +create and extract keys for their own service name, but otherwise +a number of service names are not denied: +.Bl -tag -width Ds -offset indent +.It Dq host +.It Dq root +.It Dq exceed +.El +as well as all the service names for Heimdal-specific services: +.Bl -tag -width Ds -offset indent +.It Dq krbtgt +.It Dq iprop +.It Dq kadmin +.It Dq hprop +.It Dq WELLKNOWN +.It Dq K +.El +.Pp +Supported options: +.Bl -tag -width Ds -offset indent +.It Xo +.Fl h , +.Fl Fl help +.Xc +Print usage message. +.It Xo +.Fl Fl version +.Xc +Print version. +.It Xo +.Fl H Ar HOSTNAME +.Xc +Expected audience(s) of bearer tokens (i.e., acceptor name). +.It Xo +.Fl d , +.Fl Fl daemon +.Xc +Detach from TTY and run in the background. +.It Xo +.Fl Fl reverse-proxied +.Xc +Serves HTTP instead of HTTPS, accepting only looped-back connections. +.It Xo +.Fl p Ar port number (default: 443) +.Xc +PORT +.It Xo +.Fl Fl temp-dir= Ns Ar DIRECTORY +.Xc +Directory for temp files. +If not specified then a temporary directory will be made. +.It Xo +.Fl Fl cert= Ns Ar HX509-STORE +.Xc +Certificate file path (PEM) for HTTPS service. +May contain private key as well. +.It Xo +.Fl Fl private-key= Ns Ar HX509-STORE +.Xc +Private key file path (PEM), if the private key is not stored along with the +certificiate. +.It Xo +.Fl T Ar HTTP-AUTH-TYPE, +.Fl Fl token-authentication-type= Ns Ar HTTP-AUTH-TYPE +.Xc +HTTP bearer token authentication type(s) supported (may be given more than +once). +For example, +.Ar Negotiate +or +.Ar Bearer +(JWT). +.It Xo +.Fl t , +.Fl Fl thread-per-client +.Xc +Uses a thread per-client instead of as many threads as there are CPUs. +.It Xo +.Fl Fl realm= Ns Ar REALM +.Xc +The realm to serve, if not the default realm. +Note that clients can request keys for principals in other realms, and +.Nm httpkadmind +will attempt to satisfy those requests too. +.It Xo +.Fl Fl read-only +.Xc +Do not perform write operations. +Write operations will either fail or if a primary +.Nm httpkadmind +URI is configured, then they will be redirected there. +.It Xo +.Fl Fl local +.Xc +Use a local HDB, at least for read operations, and, if +.Fl Fl local-read-only +is not given, then also write operations. +.It Xo +.Fl Fl local-read-only +.Xc +Do not perform writes on a local HDB. +Either redirect write operations if a primary +.Nm httpkadmind +URI is configured, or use a writable remote +.Nm kadmind +server. +.It Xo +.Fl Fl hdb=HDB +.Xc +A local HDB to serve. +Note that this can be obtained from the +.Nm krb5.conf . +.It Xo +.Fl Fl stash-file=FILENAME +.Xc +A stash file containing a master key for a local HDB. +Note that this can be obtained from the +.Nm krb5.conf . +.It Xo +.Fl Fl primary-server-uri=URI +.Xc +The URL of an httpkadmind to which to redirect write operations. +.It Xo +.Fl Fl read-only-admin-server=HOSTNAME[:PORT] +.Xc +The hostname (and possibly port number) of a +.Nm kadmind(8) +service to use for read-only operations. +Recall that the +.Nm kadmind(8) +service's principal name is +.Ar kadmin/admin . +The +.Ar HOSTNAME +given here can be a name that resolves to the IP addresses of all +the +.Nm kadmind(8) +services for the +.Ar REALM . +If not specified, but needed, this will be obtained by looking for +.Nm readonly_admin_server +in +.Nm krb5.conf +or, if enabled, performing +DNS lookups for SRV resource records named +.Ar _kerberos-adm-readonly._tcp.<realm> . +.It Xo +.Fl Fl writable-admin-server=HOSTNAME[:PORT] +.Xc +The hostname (and possibly port number) of a +.Nm kadmind(8) +service to use for write operations. +If not specified, but needed, this will be obtained by looking for +.Nm admin_server +in +.Nm krb5.conf +or, if enabled, performing DNS lookups for SRV resource records named +.Ar _kerberos-adm._tcp.<realm> . +.It Xo +.Fl Fl kadmin-client-name=PRINCIPAL +.Xc +The client principal name to use when connecting to a +.Nm kadmind(8) +server. +Defaults to +.Ar httpkadmind/admin . +.It Xo +.Fl Fl kadmin-client-keytab=KEYTAB +.Xc +The keytab containing keys for the +.Ar kadmin-client-name . +Note that you may use an +.Ar HDB +as a keytab as +.Ar HDBGET:/var/heimdal/heimdal.db +(or whatever the HDB specification is). +.It Xo +.Fl v , +.Fl Fl verbose= Ns Ar run verbosely +.Xc +verbose +.El +.Sh ENVIRONMENT +.Bl -tag -width Ds +.It Ev KRB5_CONFIG +The file name of +.Pa krb5.conf , +the default being +.Pa /etc/krb5.conf . +.El +.Sh FILES +.Bl -tag -width Ds +.It Pa /etc/krb5.conf +.El +.Sh CONFIGURATION +Authorizer configuration goes in +.Br +.Ar [ext_keytab] +in +.Nm krb5.conf(5). For example: +.Pp +[ext_keytab] + simple_csr_authorizer_directory = /etc/krb5/simple_csr_authz + ipc_csr_authorizer = { + service = UNIX:/var/heimdal/csr_authorizer_sock + } +.Sh EXAMPLES +To start +.Nm httpkadmind +on a primary KDC: +.Pp +.Ar $ httpkadmind -d --cert=PEM-FILE:/etc/httpkadmind.pem +\\ +.Br + --local -T Negotiate +.Pp +To start +.Nm httpkadmind +on a secondary KDC, using redirects for write operations: +.Pp +.Ar $ httpkadmind -d --cert=PEM-FILE:/etc/httpkadmind.pem +\\ +.Br + --local-read-only -T Negotiate +\\ +.Br + --primary-server-uri=https://the-primary-server.fqdn/ +.Pp +To start +.Nm httpkadmind +on a secondary KDC, proxying kadmin to perform writes at the primary KDC, using +DNS to discover the kadmin server: +.Pp +.Ar $ httpkadmind -d --cert=PEM-FILE:/etc/httpkadmind.pem +\\ +.Br + --local-read-only -T Negotiate +\\ +.Br + --kadmin-client-keytab=FILE:/etc/krb5.keytab +.Pp +To start +.Nm httpkadmind +on a non-KDC: +.Pp +.Ar $ httpkadmind -d --cert=PEM-FILE:/etc/httpkadmind.pem +\\ +.Br + -T Negotiate --kadmin-client-keytab=FILE:/etc/krb5.keytab +.Pp +.Sh DIAGNOSTICS +See logging section of +.Nm krb5.conf.5 +.Sh SEE ALSO +.Xr bx509d 8 , +.Xr kadmin 1 , +.Xr kadmind 8 , +.Xr krb5.conf 5 . +.\".Sh STANDARDS +.\".Sh HISTORY +.\".Sh AUTHORS +.\".Sh BUGS |