BX509(8)

NAME
bx509d - Authentication Bridge for Bearer tokens, Kerberos, and PKIX

SYNOPSIS
bx509d [-h | - -help] [- -version] [-H HOSTNAME] [-d | - -daemon] [- -daemon-child] [- -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
Serves RESTful (HTTPS) GETs of /bx509 and /bnegotiate, end-points performing corresponding kx509 and, possibly, PKINIT requests to the KDCs of the requested realms (or just the given REALM).

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

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

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 query parameter. In a successful query, 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 query parameters.

Supported query parameters (separated by ampersands)

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 query parameter.

In a successful query, 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 query parameters.

Supported query parameters (separated by ampersands)

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 query parameters (separated by ampersands)

cname = principal-name

address = IP-address

In a successful query, 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 query 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).

ENVIRONMENT

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

FILES
Configuration parameters are specified in /etc/krb5.conf.

/etc/krb5.conf

DIAGNOSTICS
See logging section of krb5.conf.5

SEE ALSO
krb5.conf(5)