BX509(8)

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

🦋 BX509(8) — System Manager's Manual 🦋

okay bestie, this is the System Manager's Manual page for bx509d, aka the Authentication Bridge for Bearer tokens, Kerberos, and PKIX. We're reading it together, no skipped flags, no vibes-based guessing. 💅

✨ NAME ✨

bx509d — Authentication Bridge for Bearer tokens, Kerberos, and PKIX.

🌸 SYNOPSIS 🌸

bx509d [-h | --help] [--version] [-H HOSTNAME] [-d | --daemon]
       [--allow-GET] [--no-allow-GET]
       [--csrf-protection-type=CSRF-PROTECTION-TYPE]
       [--csrf-header=HEADER-NAME] [--csrf-key-file=FILE]
       [--reverse-proxied] [-p port number (default: 443)]
       [--cache-dir=DIRECTORY] [--cert=HX509-STORE]
       [--private-key=HX509-STORE] [-t | --thread-per-client] [-v |
       --verbose=run verbosely]

🎀 DESCRIPTION 🎀

okay so bx509d serves RESTful (HTTPS) GETs of /get-cert, /get-tgt, /get-tgts, and /get-negotiate-token — end-points that implement various experimental Heimdal features:

an online CA service over HTTPS,
a kinit-over-HTTPS service, and
a Negotiate token over HTTPS service.

As well, a /health service can be used for checking service status.

Supported options:

-h, --help — Print usage message.
--version — Print version.
-H HOSTNAME — Expected audience(s) of bearer tokens (i.e., acceptor name).
--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). The HEADER-NAME must be a request header name such that a request having it makes it not a “simple” request (see the Cross-Origin Resource Sharing specification). Defaults to X-CSRF.
--csrf-key-file=FILE — If given, this file must contain a 16 byte binary key for keying the HMAC used in CSRF token construction.
-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 (yes bestie, that is literally the whole description in the page; keeping it exact 💀).
--cache-dir=DIRECTORY — Directory for various caches. 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, --thread-per-client — Uses a thread per-client instead of as many threads as there are CPUs.
-v, --verbose=run verbosely — verbose.

🌈 HTTP APIS 🌈

okay so all HTTP APIs served by this program accept POSTs, with all request parameters given as URI query parameters and/or as form data in the POST request body, in either application/x-www-form-urlencoded or multipart/formdata. If request parameters are given both as URI query parameters and as POST forms, then they are merged into a set.

If GETs are enabled, then request parameters must be supplied only as URI query parameters, as GET requests do not have request bodies.

URI query parameters must be of the form param0=value&param1=value...

Some request parameters can only have one value. If multiple values are given for such parameters, then either an error will be produced, or only the first URI query parameter value will be used, or the first POST form data parameter will be used. Other request parameters can have multiple values. See below.

🛡️ CROSS-SITE REQUEST FORGERY PROTECTION 🛡️

None of the resources service by this service are intended to be executed by web pages.

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

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.

👑 ONLINE CERTIFICATION AUTHORITY HTTP API 👑

This service provides an HTTP-based Certification Authority (CA). CA credentials and configuration are specified in the [bx509] section of krb5.conf(5).

The protocol consists of a GET of /get-cert with the base-63 encoding of a DER encoding of a PKCS#10 CertificationRequest (Certificate Signing Request, or CSR) in a csr required request parameter. In a successful request, the response body will contain a PEM encoded end entity certificate and certification chain.

Or GET of /bx509, as this used to be called.

Authentication is required. Unauthenticated requests will elicit a 401 response.

Authorization is required. Unauthorized requests will elicit a 403 response.

Subject Alternative Names (SANs) and Extended Key Usage values may be requested, both in-band in the CSR as a requested extensions attribute, and/or via optional request parameters.

Supported request parameters:

csr = base64-encoded-DER-encoded-CSR
dNSName = hostname
rfc822Name = email-address
xMPPName = XMPP-address
krb5PrincipalName = Kerberos-principal-name
ms-upn = UPN
eku = OID
lifetime = lifetime

More than one name or EKU may be requested.

Certificate lifetimes are expressed as a decimal number and an optional unit (which defaults to “day” ).

🎟️ NEGOTIATE TOKEN HTTP API 🎟️

This service provides an HTTP-based Negotiate token service. This service requires a certification authority (CA) issuer credential as it impersonates client principals to the KDC using PKINIT client certificates it issues itself.

The protocol consists of a GET of /get-negotiate-token with a target = service@host request parameter.

In a successful request, the response body will contain a Negotiate token for the authenticated client principal to the requested target.

Authentication is required. Unauthenticated requests will elicit a 401 response.

Subject Alternative Names (SANs) and Extended Key Usage values may be requested, both in-band in the CSR as a requested extensions attribute, and/or via optional request parameters.

Supported request parameters:

target = service@hostname
redirect = URI

If a redirect URI is given and a matching Referer header is included in the request, then the response will be a redirect to that URI with the Negotiate token in an Authorization header that the user-agent should copy to the redirected request.

The certification authority configuration is the same as for the /get-cert end-point, but as configured in the [get-tgt] section of krb5.conf(5).

🎫 TGT HTTP API 🎫

This service provides an HTTP-based "kinit" service. This service requires a certification authority (CA) issuer credential as it impersonates client principals to the KDC using PKINIT client certificates it issues itself.

The protocol consists of a GET of /get-tgt.

Supported request parameters:

cname = principal-name
address = IP-address
lifetime = relative-time

In a successful request, the response body will contain a TGT and its session key encoded as a "ccache" file contents.

Authentication is required. Unauthenticated requests will elicit a 401 response.

Authorization is required, where the authorization check is the same as for /get-cert by the authenticated client principal to get a certificate with a PKINIT SAN for itself or the requested principal if a cname request parameter was included.

Unauthorized requests will elicit a 403 response.

Requested IP addresses will be added to the issued TGT if allowed. The IP address of the client will be included if address-less TGTs are not allowed. See the [get-tgt] section of krb5.conf(5).

The certification authority configuration is the same as for the /get-cert end-point, but as configured in the [get-tgt] section of krb5.conf(5).

💅 BATCH TGT HTTP API

okay so picture this: some sites have these special users that run batch job systems, and those users can impersonate a whole bunch of other people by getting TGTs for them — and they literally prestash credentials for all those people in their credential caches. iconic but also kind of a lot of responsibility tbh. 🫶

so to support these systems, a GET of /get-tgts with multiple cname request parameters will return those principals' TGTs — but only if the caller is authorized, obviously. no cap, authorization still applies. ✨

it's giving /get-tgt end-point energy, but there are two (2) big differences, bestie, and you need to know both:

a) you can pass multiple cname request parameter values, and
b) the caller's principal name is not used as a default for the cname request parameter. nope, not happening. 🙈

the address and lifetime request parameters are honored, same as always. 💖

for successful GETs, the response body is a sequence of JSON texts, and each one of those is a JSON object with exactly two keys:

ccache  with a base64-encoded FILE-type ccache;

name    the name of the principal whose credentials are in that
        ccache.

so yeah, one object per principal, each carrying the base64-encoded FILE-type ccache and the name of the principal whose creds are living in it. 🔥

👀 NOTES

heads up: a future release may split all these end-points into separate services. not today, but like, maybe someday. consider yourself warned. 💀

🌸 ENVIRONMENT

KRB5_CONFIG — the file name of krb5.conf, and the default is /etc/krb5.conf. yes, that exact path. 🎀

🎀 FILES

configuration parameters are specified in /etc/krb5.conf. that's the spot. that's where they live.

/etc/krb5.conf

🩺 DIAGNOSTICS

see the logging section of krb5.conf.5. it's all in there, iykyk. 💜

🦋 SEE ALSO

krb5.conf(5)

and that's the whole page, bestie! 🌈 this gem came from HEIMDAL, dated January 2, 2020, and yes it's BX509(8) — the manual page, section 8, periodt. 👑 go forth and configure responsibly 💅✨

📦 where this page comes from

nixpkgs unstable: heimdal 7.8.0-unstable-2024-09-10
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-04: a language model's rewrite of the original, under its terms