855b27ccfb
Combined with the synthetic_clients feature, this will allow hosts that have a PKINIT-worthy client certificate with a SAN with their host principals to create their own principals and "extract" their host keytabs. Together with some other PKIX credential bootstrapping protocol, this can help hosts bootstrap Kerberos host credentials.
425 lines
11 KiB
Groff
425 lines
11 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 HTTPKADMIND 8
|
|
.Os HEIMDAL
|
|
.Sh NAME
|
|
.Nm httpkadmind
|
|
.Nd HTTP HDB Administration Interface
|
|
.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 temp-dir= Ns Ar DIRECTORY
|
|
.Op Fl Fl cert=HX509-STORE
|
|
.Op Fl Fl private-key=HX509-STORE
|
|
.Op Fl T | Fl Fl token-authentication-type=Negotiate|Bearer
|
|
.Op Fl Fl realm=REALM
|
|
.Op Fl Fl read-only
|
|
.Op Fl l | Fl Fl local
|
|
.Op Fl Fl local-read-only
|
|
.Op Fl Fl hdb=HDB
|
|
.Op Fl Fl stash-file=FILENAME
|
|
.Op Fl Fl primary-server-uri=URI
|
|
.Op Fl Fl read-only-admin-server=HOSTNAME[:PORT]
|
|
.Op Fl Fl writable-admin-server=HOSTNAME[:PORT]
|
|
.Op Fl Fl kadmin-client-name=PRINCIPAL
|
|
.Op Fl Fl kadmin-client-keytab=KEYTAB
|
|
.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 the following resources:
|
|
.Ar /get-keys and
|
|
.Ar /get-config .
|
|
.Pp
|
|
The
|
|
.Ar /get-keys
|
|
end-point allows callers to get keytab content for named
|
|
principals, possibly performing write operations such as creating
|
|
a non-existent principal, or rotating its keys, if requested.
|
|
.Pp
|
|
The
|
|
.Ar /get-config
|
|
end-point allows callers to get
|
|
.Nm krb5.conf
|
|
contents for a given principal.
|
|
.Pp
|
|
This service can run against a local HDB, or against a remote HDB
|
|
via the
|
|
.Nm kadmind(8)
|
|
protocol.
|
|
Read operations are always allowed, but write operations can be
|
|
preformed either against writable
|
|
.Nm kadmind(8)
|
|
server(s) or redirected to another
|
|
.Nm httpkadmind(8).
|
|
.Pp
|
|
The
|
|
.Ar /get-config
|
|
end-point accepts a single query parameter:
|
|
.Bl -tag -width Ds -offset indent
|
|
.It Ar princ=PRINCIPAL .
|
|
.El
|
|
.Pp
|
|
The
|
|
.Ar /get-keys
|
|
end-point accepts various parameters:
|
|
.Bl -tag -width Ds -offset indent
|
|
.It Ar spn=PRINCIPAL
|
|
Names the host-based service principal whose keys to get.
|
|
May be given multiple times, and all named principal's keys will
|
|
be fetched.
|
|
.It Ar dNSName=HOSTNAME
|
|
Names the host-based service principal's hostname whose keys to get.
|
|
May be given multiple times, and all named principal's keys will
|
|
be fetched.
|
|
.It Ar service=SERVICE
|
|
Hostnames given with
|
|
.Ar dNSName=HOSTNAME
|
|
will be qualified with this service name to form a host-based
|
|
service principal.
|
|
May be given multiple times, in which case the cartesian product
|
|
of
|
|
.Ar dNSName=HOSTNAME
|
|
ad
|
|
.Ar service=SERVICE
|
|
will be used.
|
|
Defaults to
|
|
.Ar HTTP .
|
|
.It realm=REALM
|
|
Must be present if the
|
|
.Nm httpkadmind
|
|
daemon's default realm is not desired.
|
|
.It Ar enctypes=ENCTYPE,...
|
|
A comma-separated list of enctypes that the principal is expected
|
|
to support (used for Kerberos Ticket session key negotiation).
|
|
Defaults to the
|
|
.Ar supported_enctypes
|
|
configured in
|
|
.Nm krb5.conf(5) .
|
|
.It Ar materialize=true
|
|
If the named principal(s) is (are) virtual, this will cause it
|
|
(them) to be materialized as a concrete principal.
|
|
(Currently not supported.)
|
|
.It Ar create=true
|
|
If the named principal(s) does not (do not) exist, this will
|
|
cause it (them) to be created.
|
|
.It Ar rotate=true
|
|
This will cause the keys of concrete principals to be rotated.
|
|
.It Ar revoke=true
|
|
This will cause old keys of concrete principals to be deleted
|
|
if their keys are being rotated.
|
|
This means that extant service tickets with those principals as
|
|
the target will not be able to be decrypted by the caller as it
|
|
will not have the necessary keys.
|
|
.El
|
|
.Pp
|
|
Authorization is handled via the same mechanism as in
|
|
.Nm bx509d(8)
|
|
which was originally intended to authorize certification requests
|
|
(CSRs).
|
|
Authorization for extracting keys is specified like for
|
|
.Nm bx509d(8) ,
|
|
but using
|
|
.Nm [ext_keytab]
|
|
as the
|
|
.Nm krb5.conf(5) section.
|
|
Clients with host-based principals for the the host service can
|
|
create and extract keys for their own service name, but otherwise
|
|
a number of service names are not denied:
|
|
.Bl -tag -width Ds -offset indent
|
|
.It Dq host
|
|
.It Dq root
|
|
.It Dq exceed
|
|
.El
|
|
as well as all the service names for Heimdal-specific services:
|
|
.Bl -tag -width Ds -offset indent
|
|
.It Dq krbtgt
|
|
.It Dq iprop
|
|
.It Dq kadmin
|
|
.It Dq hprop
|
|
.It Dq WELLKNOWN
|
|
.It Dq K
|
|
.El
|
|
.Pp
|
|
Supported options:
|
|
.Bl -tag -width Ds -offset indent
|
|
.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 temp-dir= Ns Ar DIRECTORY
|
|
.Xc
|
|
Directory for temp files.
|
|
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 Ar HTTP-AUTH-TYPE,
|
|
.Fl Fl token-authentication-type= Ns Ar HTTP-AUTH-TYPE
|
|
.Xc
|
|
HTTP bearer token authentication type(s) supported (may be given more than
|
|
once).
|
|
For example,
|
|
.Ar Negotiate
|
|
or
|
|
.Ar Bearer
|
|
(JWT).
|
|
.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 Fl realm= Ns Ar REALM
|
|
.Xc
|
|
The realm to serve, if not the default realm.
|
|
Note that clients can request keys for principals in other realms, and
|
|
.Nm httpkadmind
|
|
will attempt to satisfy those requests too.
|
|
.It Xo
|
|
.Fl Fl read-only
|
|
.Xc
|
|
Do not perform write operations.
|
|
Write operations will either fail or if a primary
|
|
.Nm httpkadmind
|
|
URI is configured, then they will be redirected there.
|
|
.It Xo
|
|
.Fl Fl local
|
|
.Xc
|
|
Use a local HDB, at least for read operations, and, if
|
|
.Fl Fl local-read-only
|
|
is not given, then also write operations.
|
|
.It Xo
|
|
.Fl Fl local-read-only
|
|
.Xc
|
|
Do not perform writes on a local HDB.
|
|
Either redirect write operations if a primary
|
|
.Nm httpkadmind
|
|
URI is configured, or use a writable remote
|
|
.Nm kadmind
|
|
server.
|
|
.It Xo
|
|
.Fl Fl hdb=HDB
|
|
.Xc
|
|
A local HDB to serve.
|
|
Note that this can be obtained from the
|
|
.Nm krb5.conf .
|
|
.It Xo
|
|
.Fl Fl stash-file=FILENAME
|
|
.Xc
|
|
A stash file containing a master key for a local HDB.
|
|
Note that this can be obtained from the
|
|
.Nm krb5.conf .
|
|
.It Xo
|
|
.Fl Fl primary-server-uri=URI
|
|
.Xc
|
|
The URL of an httpkadmind to which to redirect write operations.
|
|
.It Xo
|
|
.Fl Fl read-only-admin-server=HOSTNAME[:PORT]
|
|
.Xc
|
|
The hostname (and possibly port number) of a
|
|
.Nm kadmind(8)
|
|
service to use for read-only operations.
|
|
Recall that the
|
|
.Nm kadmind(8)
|
|
service's principal name is
|
|
.Ar kadmin/admin .
|
|
The
|
|
.Ar HOSTNAME
|
|
given here can be a name that resolves to the IP addresses of all
|
|
the
|
|
.Nm kadmind(8)
|
|
services for the
|
|
.Ar REALM .
|
|
If not specified, but needed, this will be obtained by looking for
|
|
.Nm readonly_admin_server
|
|
in
|
|
.Nm krb5.conf
|
|
or, if enabled, performing
|
|
DNS lookups for SRV resource records named
|
|
.Ar _kerberos-adm-readonly._tcp.<realm> .
|
|
.It Xo
|
|
.Fl Fl writable-admin-server=HOSTNAME[:PORT]
|
|
.Xc
|
|
The hostname (and possibly port number) of a
|
|
.Nm kadmind(8)
|
|
service to use for write operations.
|
|
If not specified, but needed, this will be obtained by looking for
|
|
.Nm admin_server
|
|
in
|
|
.Nm krb5.conf
|
|
or, if enabled, performing DNS lookups for SRV resource records named
|
|
.Ar _kerberos-adm._tcp.<realm> .
|
|
.It Xo
|
|
.Fl Fl kadmin-client-name=PRINCIPAL
|
|
.Xc
|
|
The client principal name to use when connecting to a
|
|
.Nm kadmind(8)
|
|
server.
|
|
Defaults to
|
|
.Ar httpkadmind/admin .
|
|
.It Xo
|
|
.Fl Fl kadmin-client-keytab=KEYTAB
|
|
.Xc
|
|
The keytab containing keys for the
|
|
.Ar kadmin-client-name .
|
|
Note that you may use an
|
|
.Ar HDB
|
|
as a keytab as
|
|
.Ar HDBGET:/var/heimdal/heimdal.db
|
|
(or whatever the HDB specification is).
|
|
.It Xo
|
|
.Fl v ,
|
|
.Fl Fl verbose= Ns Ar run verbosely
|
|
.Xc
|
|
verbose
|
|
.El
|
|
.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
|
|
.Bl -tag -width Ds
|
|
.It Pa /etc/krb5.conf
|
|
.El
|
|
.Sh CONFIGURATION
|
|
Authorizer configuration goes in
|
|
.Br
|
|
.Ar [ext_keytab]
|
|
in
|
|
.Nm krb5.conf(5). For example:
|
|
.Pp
|
|
[ext_keytab]
|
|
simple_csr_authorizer_directory = /etc/krb5/simple_csr_authz
|
|
ipc_csr_authorizer = {
|
|
service = UNIX:/var/heimdal/csr_authorizer_sock
|
|
}
|
|
.Sh EXAMPLES
|
|
To start
|
|
.Nm httpkadmind
|
|
on a primary KDC:
|
|
.Pp
|
|
.Ar $ httpkadmind -d --cert=PEM-FILE:/etc/httpkadmind.pem
|
|
\\
|
|
.Br
|
|
--local -T Negotiate
|
|
.Pp
|
|
To start
|
|
.Nm httpkadmind
|
|
on a secondary KDC, using redirects for write operations:
|
|
.Pp
|
|
.Ar $ httpkadmind -d --cert=PEM-FILE:/etc/httpkadmind.pem
|
|
\\
|
|
.Br
|
|
--local-read-only -T Negotiate
|
|
\\
|
|
.Br
|
|
--primary-server-uri=https://the-primary-server.fqdn/
|
|
.Pp
|
|
To start
|
|
.Nm httpkadmind
|
|
on a secondary KDC, proxying kadmin to perform writes at the primary KDC, using
|
|
DNS to discover the kadmin server:
|
|
.Pp
|
|
.Ar $ httpkadmind -d --cert=PEM-FILE:/etc/httpkadmind.pem
|
|
\\
|
|
.Br
|
|
--local-read-only -T Negotiate
|
|
\\
|
|
.Br
|
|
--kadmin-client-keytab=FILE:/etc/krb5.keytab
|
|
.Pp
|
|
To start
|
|
.Nm httpkadmind
|
|
on a non-KDC:
|
|
.Pp
|
|
.Ar $ httpkadmind -d --cert=PEM-FILE:/etc/httpkadmind.pem
|
|
\\
|
|
.Br
|
|
-T Negotiate --kadmin-client-keytab=FILE:/etc/krb5.keytab
|
|
.Pp
|
|
.Sh DIAGNOSTICS
|
|
See logging section of
|
|
.Nm krb5.conf.5
|
|
.Sh SEE ALSO
|
|
.Xr bx509d 8 ,
|
|
.Xr kadmin 1 ,
|
|
.Xr kadmind 8 ,
|
|
.Xr krb5.conf 5 .
|
|
.\".Sh STANDARDS
|
|
.\".Sh HISTORY
|
|
.\".Sh AUTHORS
|
|
.\".Sh BUGS
|