samba-mirror/third_party/heimdal/kdc/bx509d.8

.\" Copyright (c) 2020 Kungliga Tekniska Högskolan
.\" (Royal Institute of Technology, Stockholm, Sweden).
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\"
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\"
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" 3. Neither the name of the Institute nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.Dd January  2, 2020
.Dt BX509 8
.Os HEIMDAL
.Sh NAME
.Nm bx509d
.Nd Authentication Bridge for Bearer tokens, Kerberos, and PKIX
.Sh SYNOPSIS
.Nm
.Op Fl h | Fl Fl help
.Op Fl Fl version
.Op Fl H Ar HOSTNAME
.Op Fl d | Fl Fl daemon
.Op Fl Fl allow-GET
.Op Fl Fl no-allow-GET
.Op Fl Fl csrf-protection-type= Ns Ar CSRF-PROTECTION-TYPE
.Op Fl Fl csrf-header= Ns Ar HEADER-NAME
.Op Fl Fl csrf-key-file= Ns Ar FILE
.Op Fl Fl reverse-proxied
.Op Fl p Ar port number (default: 443)
.Op Fl Fl cache-dir= Ns Ar DIRECTORY
.Op Fl Fl cert= Ns Ar HX509-STORE
.Op Fl Fl private-key= Ns Ar HX509-STORE
.Op Fl t | Fl Fl thread-per-client
.Oo Fl v \*(Ba Xo
.Fl Fl verbose= Ns Ar run verbosely
.Xc
.Oc
.Sh DESCRIPTION
Serves RESTful (HTTPS) GETs of
.Ar /get-cert ,
.Ar /get-tgt ,
.Ar /get-tgts ,
and
.Ar /get-negotiate-token ,
end-points that implement various experimental Heimdal features:
.Bl -bullet -compact -offset indent
.It
.Li an online CA service over HTTPS,
.It
.Li a kinit-over-HTTPS service, and
.It
.Li a Negotiate token over HTTPS service.
.El
.Pp
As well, a
.Ar /health
service can be used for checking service status.
.Pp
Supported options:
.Bl -tag -width Ds
.It Xo
.Fl h ,
.Fl Fl help
.Xc
Print usage message.
.It Xo
.Fl Fl version
.Xc
Print version.
.It Xo
.Fl H Ar HOSTNAME
.Xc
Expected audience(s) of bearer tokens (i.e., acceptor name).
.It Xo
.Fl Fl allow-GET
.Xc
If given, then HTTP GET will be allowed for the various
end-points other than
.Ar /health .
Otherwise only HEAD and POST will be allowed.
By default GETs are allowed, but this will change soon.
.It Xo
.Fl Fl no-allow-GET
.Xc
If given then HTTP GETs will be rejected for the various
end-points other than
.Ar /health .
.It Xo
.Fl Fl csrf-protection-type= Ns Ar CSRF-PROTECTION-TYPE
.Xc
Possible values of
.Ar CSRF-PROTECTION-TYPE
are
.Bl -bullet -compact -offset indent
.It
.Li GET-with-header
.It
.Li GET-with-token
.It
.Li POST-with-header
.It
.Li POST-with-token
.El
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.
.Pp
See
.Sx CROSS-SITE REQUEST FORGERY PROTECTION .
.It Xo
.Fl Fl csrf-header= Ns Ar HEADER-NAME
.Xc
If given, then all requests other than to the
.Ar /health
service must have the given request
.Ar HEADER-NAME
set (the value is irrelevant).
The
.Ar HEADER-NAME
must be a request header name such that a request having it makes
it not a
.Dq simple
request (see the Cross-Origin Resource Sharing specification).
Defaults to
.Ar X-CSRF .
.It Xo
.Fl Fl csrf-key-file= Ns Ar FILE
.Xc
If given, this file must contain a 16 byte binary key for keying
the HMAC used in CSRF token construction.
.It Xo
.Fl d ,
.Fl Fl daemon
.Xc
Detach from TTY and run in the background.
.It Xo
.Fl Fl reverse-proxied
.Xc
Serves HTTP instead of HTTPS, accepting only looped-back
connections.
.It Xo
.Fl p Ar port number (default: 443)
.Xc
PORT
.It Xo
.Fl Fl cache-dir= Ns Ar DIRECTORY
.Xc
Directory for various caches.
If not specified then a temporary directory will be made.
.It Xo
.Fl Fl cert= Ns Ar HX509-STORE
.Xc
Certificate file path (PEM) for HTTPS service.
May contain private key as well.
.It Xo
.Fl Fl private-key= Ns Ar HX509-STORE
.Xc
Private key file path (PEM), if the private key is not stored
along with the certificiate.
.It Xo
.Fl t ,
.Fl Fl thread-per-client
.Xc
Uses a thread per-client instead of as many threads as there are
CPUs.
.It Xo
.Fl v ,
.Fl Fl verbose= Ns Ar run verbosely
.Xc
verbose
.El
.Sh 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
.Ar application/x-www-form-urlencoded
or
.Ar multipart/formdata .
If request parameters are given both as URI query parameters
and as POST forms, then they are merged into a set.
.Pp
If GETs are enabled, then request parameters must be supplied
only as URI query parameters, as GET requests do not have request
bodies.
.Pp
URI query parameters must be of the form
.Ar param0=value&param1=value...
.Pp
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.
.Sh CROSS-SITE REQUEST FORGERY PROTECTION
.Em None
of the resources service by this service are intended to be
executed by web pages.
.Pp
All the resources provided by this service are
.Dq 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
.Em 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
.Em and
observe the responses.
.Pp
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.
.Pp
This service provides the following CSRF protection features:
.Bl -tag -width Ds -offset indent
.It requests are rejected if they have a
.Dq Referer
(except the experimental /get-negotiate-token end-point)
.It the service can be configured to require a header that would make the
request not Dq simple
.It GETs can be disabled (see options), thus requiring POSTs
.It GETs can be required to have a CSRF token (see below)
.It POSTs can be required to have a CSRF token
.El
.Pp
The experimental
.Ar /get-negotiate-token
end-point, however, always accepts
.Dq Referer
requests.
.Pp
To obtain a CSRF token, first execute the request without the
CSRF token, and the resulting error
response will include a
.Ar X-CSRF-Token
response header.
.Pp
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
.Ar X-CSRF-Token
header.
.Sh ONLINE CERTIFICATION AUTHORITY HTTP API
This service provides an HTTP-based Certification Authority (CA).
CA credentials and configuration are specified in the
.Va [bx509]
section of
.Xr krb5.conf 5 .
.Pp
The protocol consists of a
.Ar GET
of
.Ar /get-cert
with the base-63 encoding of a DER encoding of a PKCS#10
.Ar CertificationRequest
(Certificate Signing Request, or CSR) in a
.Ar csr
required request parameter.
In a successful request, the response body will contain a PEM
encoded end entity certificate and certification chain.
.Pp
Or
.Ar GET
of
.Ar /bx509 ,
as this used to be called.
.Pp
Authentication is required.
Unauthenticated requests will elicit a 401 response.
.Pp
Authorization is required.
Unauthorized requests will elicit a 403 response.
.Pp
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.
.Pp
Supported request parameters:
.Bl -tag -width Ds -offset indent
.It Li csr = Va base64-encoded-DER-encoded-CSR
.It Li dNSName = Va hostname
.It Li rfc822Name = Va email-address
.It Li xMPPName = Va XMPP-address
.It Li krb5PrincipalName = Va Kerberos-principal-name
.It Li ms-upn = Va UPN
.It Li eku = Va OID
.It Li lifetime = Va lifetime
.El
.Pp
More than one name or EKU may be requested.
.Pp
Certificate lifetimes are expressed as a decimal number and
an optional unit (which defaults to
.Dq day
).
.Sh 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.
.Pp
The protocol consists of a
.Ar GET
of
.Ar /get-negotiate-token
with a
.Ar target = Ar service@host
request parameter.
.Pp
In a successful request, the response body will contain a
Negotiate token for the authenticated client principal to the
requested target.
.Pp
Authentication is required.
Unauthenticated requests will elicit a 401 response.
.Pp
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.
.Pp
Supported request parameters:
.Bl -tag -width Ds -offset indent
.It Li target = Va service@hostname
.It Li redirect = Va URI
.El
.Pp
If a redirect URI is given and a matching
.Va Referer
header is included in the request, then the response will be a
redirect to that URI with the Negotiate token in an
.Va Authorization
header that the user-agent should copy to the redirected request.
.Pp
The certification authority configuration is the same as for the
.Va /get-cert
end-point, but as configured in the
.Va [get-tgt]
section of
.Xr krb5.conf 5 .
.Sh 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.
.Pp
The protocol consists of a
.Ar GET
of
.Ar /get-tgt .
.Pp
Supported request parameters:
.Bl -tag -width Ds -offset indent
.It Li cname = Va principal-name
.It Li address = Va IP-address
.It Li lifetime = Va relative-time
.El
.Pp
In a successful request, the response body will contain a TGT and
its session key encoded as a "ccache" file contents.
.Pp
Authentication is required.
Unauthenticated requests will elicit a 401 response.
.Pp
Authorization is required, where the authorization check is the
same as for
.Va /get-cert
by the authenticated client principal to get a certificate with
a PKINIT SAN for itself or the requested principal if a
.Va cname
request parameter was included.
.Pp
Unauthorized requests will elicit a 403 response.
.Pp
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
.Va [get-tgt]
section of
.Xr krb5.conf 5 .
.Pp
The certification authority configuration is the same as for the
.Va /get-cert
end-point, but as configured in the
.Va [get-tgt]
section of
.Xr krb5.conf 5 .
.Sh 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
.Dq prestash
credentials for those users in their credentials caches.
To support these sytems, a
.Ar GET
of
.Ar /get-tgts
with multiple
.Ar cname
request parameters will return those principals' TGTs (if the
caller is authorized).
.Pp
This is similar to the
.Ar /get-tgt
end-point, but a) multiple
.Ar cname
request parameter values may be given, and b) the caller's
principal name is not used as a default for the
.Ar cname
request parameter.
The
.Ar address
and
.Ar lifetime
request parameters are honored.
.Pp
For successful
.Ar GETs
the response body is a sequence of JSON texts each of which is a
JSON object with two keys:
.Bl -tag -width Ds -offset indent
.It Ar ccache
with a base64-encoded FILE-type ccache;
.It Ar name
the name of the principal whose credentials are in that ccache.
.El
.Sh NOTES
A future release may split all these end-points into separate
services.
.Sh ENVIRONMENT
.Bl -tag -width Ds
.It Ev KRB5_CONFIG
The file name of
.Pa krb5.conf ,
the default being
.Pa /etc/krb5.conf .
.El
.Sh FILES
Configuration parameters are specified in
.Ar /etc/krb5.conf .
.Bl -tag -width Ds
.It Pa /etc/krb5.conf
.El
.\".Sh EXAMPLES
.Sh DIAGNOSTICS
See logging section of
.Nm krb5.conf.5
.Sh SEE ALSO
.Xr krb5.conf 5
.\".Sh STANDARDS
.\".Sh HISTORY
.\".Sh AUTHORS
.\".Sh BUGS