path: root/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 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