284 lines
7.8 KiB
Groff
284 lines
7.8 KiB
Groff
.\" 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
|