1 files changed, 480 insertions, 0 deletions
diff --git a/third_party/heimdal/kdc/bx509d.8 b/third_party/heimdal/kdc/bx509d.8
new file mode 100644
index 0000000..f940155
--- /dev/null
+++ b/third_party/heimdal/kdc/bx509d.8
@@ -0,0 +1,480 @@
+.\" 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