BX509(8)

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

    - -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
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
Some sites may have special users that operate batch jobs systems and that can impersonate many others by obtaining TGTs for them, and which “prestash” credentials for those users in their credentials caches. To support these sytems, a GET of /get-tgts with multiple cname request parameters will return those principals' TGTs (if the caller is authorized).

This is similar to the /get-tgt end-point, but a) multiple cname request parameter values may be given, and b) the caller's principal name is not used as a default for the cname request parameter. The address and lifetime request parameters are honored.

For successful GETs the response body is a sequence of JSON texts each of which is a JSON object with two keys:

ccache
    with a base64-encoded FILE-type ccache;

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

NOTES
A future release may split all these end-points into separate services.

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)