HTTPKADMIND(8)

📦 version 7.8.0-unstable-2024-09, in nixpkgs unstable

💅 httpkadmind(8) — the HTTP HDB Administration Interface era

okay bestie, settle in, because this is the man page for httpkadmind from the System Manager's Manual and it is a lot in the best way. this is part one of three so don't go anywhere. 🎀

✨ NAME ✨

httpkadmind — HTTP HDB Administration Interface. yes that's it. that's the whole name. iconic. 👑

🌸 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]

like, look at all those flags. she's got range. 💅

🦋 DESCRIPTION 🦋

so what does she actually do? she serves the following resources over HTTP: /get-keys and /get-config. that's the whole menu, two items, both bangers.

🔑 the /get-keys end-point

this one lets callers get a principal's keys in “keytab” format for named principals, and she may also perform write operations — like creating a principal that doesn't exist yet, or rotating its keys — if requested. 🫶

⚠️ bestie, listen: this end-point can cause KDC HDB principal entries to be modified or created incidental to fetching the principal's keys. that's not a vibe, that's just the truth. when this end-point writes to the KDC's HDB, the HTTP POST method is required. see below, i got you. 💖

⚙️ the /get-config end-point

this one lets callers get krb5.conf contents for a given principal. simple, clean, slay.

🧚 how she runs

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 performed either against writable kadmind(8) server(s) or redirected to another httpkadmind(8). multitasking queen behavior honestly.

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

princ=PRINCIPAL.

that's it. one parameter. she's low maintenance. ✨

🌈 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. and if GETs are enabled, then request parameters must be supplied as URI query parameters.

💀 and here's the rule you do not break: requests that cause changes to the HDB must always be done via POST, never GET. periodt.

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. iykyk. 🌸

👑 CROSS-SITE REQUEST FORGERY PROTECTION 👑

none of the resources served by this service are intended to be executed by web pages. like, at all. 🙈

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. and since none of these resources are intended to be used from web pages, it's important that web pages not be able to execute them and observe the responses. no peeking. 🚫👀

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. non-negotiable, bestie.

here's the browser situation: 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. better safe than sorry, right? 🎀

🛡️ the CSRF protection features she ships with:

  • 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 “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. she's special like that. 💜

🎟️ how to actually get and use a CSRF token

  1. to obtain a CSRF token, first execute the request without the CSRF token — the resulting error response will include a X-CSRF-Token response header. 😭 (yes, the error is the point, it's giving chaotic-good)
  2. 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. done. ate. 🔥

and 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. no cap — if it's missing, that realm is not passing the vibe check. ⭐

🔑 GETTING KEYTABS ✨

okay bestie, so the /get-keys end-point is the whole reason we're here and it takes a bunch of parameters — here's the full rundown, no cap 🫶

  • spn=PRINCIPAL — names the host-based service principal whose keys you wanna get. you can pass this multiple times and it'll fetch keys for all the named principals. slay.
  • dNSName=HOSTNAME — same deal but you name the host-based service principal's hostname instead. also multiple-times-able, and again all the named principals' keys get fetched.
  • service=SERVICE — hostnames you give with dNSName=HOSTNAME get qualified with this service name to form a host-based service principal. you can pass this multiple times too, and in that case the cartesian product of dNSName=HOSTNAME and service=SERVICE gets used. defaults to HTTP.
  • realm=REALM — must be present if the httpkadmind daemon's default realm isn't what you want. 💅
  • enctypes=ENCTYPE,... — a comma-separated list of enctypes the principal is expected to support (this is used for Kerberos Ticket session key negotiation, iykyk). defaults to the supported_enctypes configured in krb5.conf(5).
  • materialize=true — if the named principal(s) is (are) virtual, this causes it (them) to be materialized as a concrete principal. (currently not supported, so don't come for me 🙈)
  • create=true — if the named principal(s) doesn't (don't) exist, this causes it (them) to be created. the default attributes for new principals created this way get 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) (peep the CONFIGURATION section).
  • rotate=true — causes the keys of concrete principals to be rotated. spinning that key like a fidget spinner 🌀
  • revoke=true — causes old keys of concrete principals to be deleted if their keys are being rotated. ⚠️ heads up: this means extant service tickets with those principals as the target won't be able to be decrypted by the caller, because it won't have the necessary keys. dramatic but true.

so about caching — the HTTP Cache-Control header gets set on get-keys responses to “no-store”, and the max-age cache control parameter is set to the least number of seconds until before any of the requested principal's keys could change. (yes that sentence is a mouthful, but it's exactly what happens 🎀)

for virtual principals that's 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 it's 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 — iconic, love that for them — 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”
🚫 like, do not try these. they are very much not for you.

supported options, literally all of them 💅

  • -h, --help — print usage message. classic.
  • --version — print version. also classic.
  • -H HOSTNAME — expected audience(s) of bearer tokens (i.e., acceptor name).
  • -d, --daemon — detach from TTY and run in the background. bye bestie 👋
  • --reverse-proxied — serves HTTP instead of HTTPS, accepting only looped-back connections.
  • -p PORT — port number (default: 443).
  • --allow-GET — if given, then HTTP GET is allowed for the various end-points other than /health. otherwise only HEAD and POST are allowed. by default GETs are allowed, but this will change soon 👀 (so like, don't get too attached).
  • --no-allow-GET — if given then HTTP GETs are 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, it just has to be there, vibe check only).
  • --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 the private key as well.
  • --private-key=HX509-STORE — private key file path (PEM), if the private key is not stored along with the certificate.
  • -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. main character energy for every single client, honestly.
  • --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. generous queen.
  • --read-only — do not perform write operations. write operations will either fail or, if a primary httpkadmind URI is configured, then they'll 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.

🌱 ENVIRONMENT 🌱

  • KRB5_CONFIG — the file name of krb5.conf, the default being /etc/krb5.conf. 💜

📁 FILES 📁

/etc/krb5.conf

literally that's the file. iconic of it. 🎀

⚙️ CONFIGURATION ⚙️

Okay so bestie, authorizer configuration goes in [ext_keytab] inside krb5.conf(5). Like, that's the vibe. 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 — the page just drops these names, no extra lore:

  • csr_authorizer_handles_svc_names = BOOL
  • new_hostbased_service_principal_attributes = ...

There's also the [ext_keytab] get_keys_maxspns = NUMBER parameter. It 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, periodt.

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

So what does that mean? It means that “host/a-particular-hostname.test.h5l.se”, if created via httpkadmind, will be allowed to get delegated credentials (ticket forwarding). And hostnames matching the glob pattern “host/*.prod.test.h5l.se”, if created via httpkadmind, will also be allowed to get delegated credentials. All host-based service principals created via httpkadmind not matching any new_hostbased_service_principal_attributes service namespaces will have the empty attribute set. Empty means empty, bestie — no sneaky defaults. 💅

✨ 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. That's it — that's the whole diagnostic moment. 🫶

👀 SEE ALSO 👀

The whole squad:

💖 That's the whole HEIMDAL page, bestie — source/version HEIMDAL, dated January 2, 2020, and it's HTTPKADMIND(8) signing off with main character energy. 🎀✨

📦 where this page comes from