HTTPKADMIND(8)

NAME
httpkadmind - HTTP HDB Administration Interface

SYNOPSIS
httpkadmind [-h | - -help] [- -version] [-H HOSTNAME] [-d | - -daemon] [- -daemon-child] [- -reverse-proxied] [-p port number (default: 443)] [- -allow-GET] [- -no-allow-GET] [- -GET-with-csrf-token] [- -csrf-header=HEADER-NAME] [- -temp-dir=DIRECTORY] [- -cert=HX509-STORE] [- -private-key=HX509-STORE] [-T | - -token-authentication-type=Negotiate|Bearer] [- -realm=REALM] [- -read-only] [-l | - -local] [- -local-read-only] [- -hdb=HDB] [- -stash-file=FILENAME] [- -primary-server-uri=URI] [- -read-only-admin-server=HOSTNAME[:PORT]] [- -writable-admin-server=HOSTNAME[:PORT]] [- -kadmin-client-name=PRINCIPAL] [- -kadmin-client-keytab=KEYTAB] [-t | - -thread-per-client] [-v - - -verbose=run verbosely]

DESCRIPTION
Serves the following resources over HTTP: /get-keys and /get-config.

The /get-keys end-point allows callers to get a principal's keys in “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.

The /get-config end-point allows callers to get krb5.conf contents for a given principal.

This service can run against a local HDB, or against a remote HDB via the kadmind(8) protocol. Read operations are always allowed, but write operations can be preformed either against writable kadmind(8) server(s) or redirected to another httpkadmind(8).

The /get-config end-point accepts a single query parameter:

princ=PRINCIPAL.

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 application/x-www-form-urlencoded or multipart/formdata. If GETs are enabled, then request parameters must be supplied as URI query parameters.

Note that requests that cause changes to the HDB must always be done via POST, never GET.

URI query parameters must be of the form param0=value&param1=value... Some parameters can be given multiple values -- see the descriptions of the end-points.

CROSS-SITE REQUEST FORGERY PROTECTION
None of the resources service by this service are intended to be executed by web pages.

Most of the resources provided by this service are “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 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 and observe the responses.

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.

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.

This service provides the following CSRF protection features:

requests are rejected if they have a
    “Referer” (except the experimental /get-negotiate-token end-point)

the service can be configured to require a header that would make the
    request not Dq simple

GETs can be disabled (see options), thus requiring POSTs

GETs can be required to have a CSRF token (see below)

POSTs can be required to have a CSRF token

The experimental /get-negotiate-token end-point, however, always accepts “Referer” requests.

To obtain a CSRF token, first execute the request without the CSRF token, and the resulting error response will include a X-CSRF-Token response header.

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 X-CSRF-Token header.

The key for keying the CSRF token HMAC is that of the first current key for the ‘WELLKNOWN/CSRFTOKEN’ principal for the realm being used. Every realm served by this service must have this principal.

GETTING KEYTABS
The /get-keys end-point accepts various parameters:

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.

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.

service=SERVICE
    Hostnames given with 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 dNSName=HOSTNAME ad service=SERVICE will be used. Defaults to HTTP.

realm=REALM
    Must be present if the httpkadmind daemon's default realm is not desired.

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 supported_enctypes configured in krb5.conf(5).

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.)

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 ‘’. in the hostname component, or from krb5.conf(5) (see the CONFIGURATION section).

rotate=true
    This will cause the keys of concrete principals to be rotated.

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.

The HTTP Cache-Control header will be set on get-keys responses to “no-store”, and the 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 new_service_key_delay configured in the [hdb] section of the krb5.conf(5) file.

Authorization is handled via the same mechanism as in bx509d(8) which was originally intended to authorize certification requests (CSRs). Authorization for extracting keys is specified like for bx509d(8), but using [ext_keytab] as the krb5.conf(5) section. Clients with host-based principals for the “host” service can create and extract keys for their own service name, but otherwise a number of service names are denied:

“host”

“root”

“exceed”
as well as all the service names for Heimdal-specific services:

“krbtgt”

“iprop”

“kadmin”

“hprop”

“WELLKNOWN”

“K”

Supported options:

    -h, - -help Print usage message.

    - -version Print version.

    -H HOSTNAME Expected audience(s) of bearer tokens (i.e., acceptor name).

    -d, - -daemon Detach from TTY and run in the background.

    - -reverse-proxied Serves HTTP instead of HTTPS, accepting only looped-back connections.

    -p port number (default: 443) PORT

    - -allow-GET If given, then HTTP GET will be allowed for the various end-points other than /health. Otherwise only HEAD and POST will be allowed. By default GETs are allowed, but this will change soon.

    - -no-allow-GET If given then HTTP GETs will be rejected for the various end-points other than /health.

    - -csrf-protection-type=CSRF-PROTECTION-TYPE Possible values of CSRF-PROTECTION-TYPE are
    •   GET-with-header
    •   GET-with-token
    •   POST-with-header
    •   POST-with-token
    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.

    See CROSS-SITE REQUEST FORGERY PROTECTION.

    - -csrf-header=HEADER-NAME If given, then all requests other than to the /health service must have the given request HEADER-NAME set (the value is irrelevant).

    - -temp-dir=DIRECTORY Directory for temp files. If not specified then a temporary directory will be made.

    - -cert=HX509-STORE Certificate file path (PEM) for HTTPS service. May contain private key as well.

    - -private-key=HX509-STORE Private key file path (PEM), if the private key is not stored along with the certificiate.

    -T HTTP-AUTH-TYPE, - -token-authentication-type=HTTP-AUTH-TYPE HTTP bearer token authentication type(s) supported (may be given more than once). For example, Negotiate or Bearer (JWT).

    -t, - -thread-per-client Uses a thread per-client instead of as many threads as there are CPUs.

    - -realm=REALM The realm to serve, if not the default realm. Note that clients can request keys for principals in other realms, and httpkadmind will attempt to satisfy those requests too.

    - -read-only Do not perform write operations. Write operations will either fail or if a primary httpkadmind URI is configured, then they will be redirected there.

    - -local Use a local HDB, at least for read operations, and, if - -local-read-only is not given, then also write operations.

    - -local-read-only Do not perform writes on a local HDB. Either redirect write operations if a primary httpkadmind URI is configured, or use a writable remote kadmind server.

    - -hdb=HDB A local HDB to serve. Note that this can be obtained from the krb5.conf.

    - -stash-file=FILENAME A stash file containing a master key for a local HDB. Note that this can be obtained from the krb5.conf.

    - -primary-server-uri=URI The URL of an httpkadmind to which to redirect write operations.

    - -read-only-admin-server=HOSTNAME[:PORT] The hostname (and possibly port number) of a kadmind(8) service to use for read-only operations. Recall that the kadmind(8) service's principal name is kadmin/admin. The HOSTNAME given here can be a name that resolves to the IP addresses of all the kadmind(8) services for the REALM. If not specified, but needed, this will be obtained by looking for readonly_admin_server in krb5.conf or, if enabled, performing DNS lookups for SRV resource records named _kerberos-adm-readonly._tcp.<realm>.

    - -writable-admin-server=HOSTNAME[:PORT] The hostname (and possibly port number) of a kadmind(8) service to use for write operations. If not specified, but needed, this will be obtained by looking for admin_server in krb5.conf or, if enabled, performing DNS lookups for SRV resource records named _kerberos-adm._tcp.<realm>.

    - -kadmin-client-name=PRINCIPAL The client principal name to use when connecting to a kadmind(8) server. Defaults to httpkadmind/admin.

    - -kadmin-client-keytab=KEYTAB The keytab containing keys for the kadmin-client-name. Note that you may use an HDB as a keytab as HDBGET:/var/heimdal/heimdal.db (or whatever the HDB specification is).

    -v, - -verbose=run verbosely verbose

ENVIRONMENT

KRB5_CONFIG
    The file name of krb5.conf, the default being /etc/krb5.conf.

FILES

/etc/krb5.conf

CONFIGURATION
Authorizer configuration goes in [ext_keytab] in krb5.conf(5). For example:

    [ext_keytab]
      simple_csr_authorizer_directory = /etc/krb5/simple_csr_authz
      ipc_csr_authorizer = {
        service = UNIX:/var/heimdal/csr_authorizer_sock
      }

Configuration parameters specific to httpkadmind:

csr_authorizer_handles_svc_names = BOOL

new_hostbased_service_principal_attributes = ...

The [ext_keytab] get_keys_max_spns = NUMBER parameter can be used to specify a maximum number of principals whose keys can be retrieved in one GET of the /get-keys end-point. Defaults to 400.

The [ext_keytab] 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 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 kadmin(1) modify command. For example:

    [ext_keytab]
      new_hostbased_service_principal_attributes = {
        host = {
            a-particular-hostname.test.h5l.se = ok-as-delegate
            .prod.test.h5l.se = ok-as-delegate
        }
      }

which means that “host/a-particular-hostname.test.h5l.se”, if created via httpkadmind, will be allowed to get delegated credentials (ticket forwarding), and that hostnames matching the glob pattern “host/*.prod.test.h5l.se”, if created via httpkadmind, will also allowed to get delegated credentials. All host-based service principals created via httpkadmind not matchining any new_hostbased_service_principal_attributes service namespaces will have the empty attribute set.

EXAMPLES
To start httpkadmind on a primary KDC:

$ httpkadmind -d --cert=PEM-FILE:/etc/httpkadmind.pem \ --local -T Negotiate

To start httpkadmind on a secondary KDC, using redirects for write operations:

$ httpkadmind -d --cert=PEM-FILE:/etc/httpkadmind.pem \ --local-read-only -T Negotiate \ --primary-server-uri=https://the-primary-server.fqdn/

To start httpkadmind on a secondary KDC, proxying kadmin to perform writes at the primary KDC, using DNS to discover the kadmin server:

$ httpkadmind -d --cert=PEM-FILE:/etc/httpkadmind.pem \ --local-read-only -T Negotiate \ --kadmin-client-keytab=FILE:/etc/krb5.keytab

To start httpkadmind on a non-KDC:

$ httpkadmind -d --cert=PEM-FILE:/etc/httpkadmind.pem \ -T Negotiate --kadmin-client-keytab=FILE:/etc/krb5.keytab

DIAGNOSTICS
See logging section of krb5.conf.5

SEE ALSO
bx509d(8), kadmin(1), kadmind(8), krb5.conf(5).