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)] [- -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: /get-keys and /get-config.

The /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.

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.

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.

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.

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 the host service can create and extract keys for their own service name, but otherwise a number of service names are not 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

    - -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 }

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