Nicolas Williams
fbb1a4e3ec
Add a `lifetime=NUMunit` query parameter. Also add a krb5.conf parameter to indicate whether this is allowed. We already have a max lifetime configuration parameter.
179 lines
4.9 KiB
Plaintext
179 lines
4.9 KiB
Plaintext
.\" 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 API
|
|
This service provides an HTTP-based Certification Authority (CA).
|
|
The protocol consists of a
|
|
.Ar GET
|
|
of
|
|
.Ar /bx509
|
|
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
|
|
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 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 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
|