diff options
Diffstat (limited to 'third_party/heimdal/kdc/httpkadmind.8')
| -rw-r--r-- | third_party/heimdal/kdc/httpkadmind.8 | 653 |
1 files changed, 653 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..345e959 --- /dev/null +++ b/third_party/heimdal/kdc/httpkadmind.8 @@ -0,0 +1,653 @@ +.\" 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 allow-GET +.Op Fl Fl no-allow-GET +.Op Fl Fl GET-with-csrf-token +.Op Fl Fl csrf-header= Ns Ar HEADER-NAME +.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 over HTTP: +.Ar /get-keys and +.Ar /get-config . +.Pp +The +.Ar /get-keys +end-point allows callers to get a principal's keys in +.Dq keytab +format for named principals, possibly performing write operations +such as creating a non-existent principal, or rotating its keys, +if requested. +Note that this end-point can cause KDC HDB principal entries to +be modified or created incidental to fetching the principal's +keys. +The use of the HTTP POST method is required when this end-point +writes to the KDC's HDB. +See below. +.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 +.Sh HTTP APIS +All HTTP APIs served by this program accept POSTs, with all +request parameters given as either URI query parameters, and/or +as form data in the POST request body, in either +.Ar application/x-www-form-urlencoded +or +.Ar multipart/formdata . +If GETs are enabled, then request parameters must be supplied as +URI query parameters. +.Pp +Note that requests that cause changes to the HDB must always be +done via POST, never GET. +.Pp +URI query parameters must be of the form +.Ar param0=value¶m1=value... +Some parameters can be given multiple values -- see the +descriptions of the end-points. +.Sh CROSS-SITE REQUEST FORGERY PROTECTION +.Em None +of the resources service by this service are intended to be +executed by web pages. +.Pp +Most of the resources provided by this service are +.Dq safe +in the sense that they do not change server-side state besides +logging, and in that they are idempotent, but they are +only safe to execute +.Em if and only if +the requesting party is trusted to see the response. +Since none of these resources are intended to be used from web +pages, it is important that web pages not be able to execute them +.Em and +observe the responses. +.Pp +Some of the resources provided by this service do change +server-side state, specifically principal entries in the KDC's +HDB. +Those always require the use of POST, not GET. +.Pp +In a web browser context, pages from other origins will be able +to attempt requests to this service, but should never be able to +see the responses because browsers normally wouldn't allow that. +Nonetheless, anti cross site request forgery (CSRF) protection +may be desirable. +.Pp +This service provides the following CSRF protection features: +.Bl -tag -width Ds -offset indent +.It requests are rejected if they have a +.Dq Referer +(except the experimental /get-negotiate-token end-point) +.It the service can be configured to require a header that would make the +request not Dq simple +.It GETs can be disabled (see options), thus requiring POSTs +.It GETs can be required to have a CSRF token (see below) +.It POSTs can be required to have a CSRF token +.El +.Pp +The experimental +.Ar /get-negotiate-token +end-point, however, always accepts +.Dq Referer +requests. +.Pp +To obtain a CSRF token, first execute the request without the +CSRF token, and the resulting error +response will include a +.Ar X-CSRF-Token +response header. +.Pp +To execute a request with a CSRF token, first obtain a CSRF token +as described above, then copy the token to the request as the +value of the request's +.Ar X-CSRF-Token +header. +.Pp +The key for keying the CSRF token HMAC is that of the first +current key for the +.Sq WELLKNOWN/CSRFTOKEN +principal for the realm being used. +Every realm served by this service must have this principal. +.Sh GETTING KEYTABS +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. +The default attributes for new principals created this way will +be taken (except for the disabled attribute) from any containing +virtual host-based service principal namespace that include a +leading +.Sq . +in the hostname component, or from +.Nm krb5.conf(5) +(see the CONFIGURATION section). +.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 +The HTTP +.Nm Cache-Control +header will be set on +.Nm get-keys +responses to +.Dq Nm no-store , +and the +.Nm max-age +cache control parameter will be set to the least number of +seconds until before any of the requested principal's keys could +change. +For virtual principals this will be either the time left until a +quarter of the rotation period before the next rotation, or the +time left until a +quarter of the rotation period after the next rotation. +For concrete principals this will be the time left to the first +such principal's password expiration, or, if none of them have a +configured password expiration time, then half of the +.Nm new_service_key_delay +configured in the +.Nm [hdb] +section of the +.Nm krb5.conf(5) +file. +.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 +.Dq host +service can create and extract keys for their own service name, +but otherwise a number of service names are 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 allow-GET +.Xc +If given, then HTTP GET will be allowed for the various end-points +other than +.Ar /health . +Otherwise only HEAD and POST will be allowed. +By default GETs are allowed, but this will change soon. +.It Xo +.Fl Fl no-allow-GET +.Xc +If given then HTTP GETs will be rejected for the various +end-points other than +.Ar /health . +.It Xo +.Fl Fl csrf-protection-type= Ns Ar CSRF-PROTECTION-TYPE +.Xc +Possible values of +.Ar CSRF-PROTECTION-TYPE +are +.Bl -bullet -compact -offset indent +.It +.Li GET-with-header +.It +.Li GET-with-token +.It +.Li POST-with-header +.It +.Li POST-with-token +.El +This may be given multiple times. +The default is to require CSRF tokens for POST requests, and to +require neither a non-simple header nor a CSRF token for GET +requests. +.Pp +See +.Sx CROSS-SITE REQUEST FORGERY PROTECTION . +.It Xo +.Fl Fl csrf-header= Ns Ar HEADER-NAME +.Xc +If given, then all requests other than to the +.Ar /health +service must have the given request +.Ar HEADER-NAME +set (the value is irrelevant). +.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 +.Bd -literal -offset indent +[ext_keytab] + simple_csr_authorizer_directory = /etc/krb5/simple_csr_authz + ipc_csr_authorizer = { + service = UNIX:/var/heimdal/csr_authorizer_sock + } +.Ed +.Pp +Configuration parameters specific to +.Nm httpkadmind : +.Bl -tag -width Ds -offset indent +.It csr_authorizer_handles_svc_names = BOOL +.It new_hostbased_service_principal_attributes = ... +.El +.Pp +The +.Nm [ext_keytab] +.Nm get_keys_max_spns = NUMBER +parameter can be used to specify a maximum number of principals whose +keys can be retrieved in one +.Nm GET +of the +.Nm /get-keys +end-point. +Defaults to 400. +.Pp +The +.Nm [ext_keytab] +.Nm new_hostbased_service_principal_attributes +parameter may be used instead of virtual host-based service +namespace principals to specify the attributes of new principals +created by +.Nm httpkadmind , +and its value is a hive with a service name then a hostname or +namespace, and whose value is a set of attributes as given in the +.Nm kadmin(1) modify +command. +For example: +.Bd -literal -offset indent +[ext_keytab] + new_hostbased_service_principal_attributes = { + host = { + a-particular-hostname.test.h5l.se = ok-as-delegate + .prod.test.h5l.se = ok-as-delegate + } + } +.Ed +.Pp +which means that +.Dq host/a-particular-hostname.test.h5l.se , +if created via +.Nm httpkadmind , +will be allowed to get delegated credentials (ticket forwarding), +and that hostnames matching the glob pattern +.Dq host/*.prod.test.h5l.se , +if created via +.Nm httpkadmind , +will also allowed to get delegated credentials. +All host-based service principals created via +.Nm httpkadmind +not matchining any +.Nm new_hostbased_service_principal_attributes +service namespaces will have the empty attribute set. +.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 |