summaryrefslogtreecommitdiffstats
path: root/third_party/heimdal/kdc/bx509d.8
diff options
context:
space:
mode:
Diffstat (limited to 'third_party/heimdal/kdc/bx509d.8')
-rw-r--r--third_party/heimdal/kdc/bx509d.8283
1 files changed, 283 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..512d054
--- /dev/null
+++ b/third_party/heimdal/kdc/bx509d.8
@@ -0,0 +1,283 @@
+.\" 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 daemon-child
+.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 /bx509 and
+.Ar /bnegotiate ,
+end-points
+performing corresponding kx509 and, possibly, PKINIT requests
+to the KDCs of the requested realms (or just the given REALM).
+.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 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 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 query parameter.
+In a successful query, 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 query parameters.
+.Pp
+Supported query parameters (separated by ampersands)
+.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
+query parameter.
+.Pp
+In a successful query, 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 query parameters.
+.Pp
+Supported query parameters (separated by ampersands)
+.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 query parameters (separated by ampersands)
+.Bl -tag -width Ds -offset indent
+.It Li cname = Va principal-name
+.It Li address = Va IP-address
+.El
+.Pp
+In a successful query, 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
+query 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 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