.\" 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 allow-GET
.Op Fl Fl no-allow-GET
.Op Fl Fl GET-with-csrf-token
.Op Fl Fl csrf-header= Ns Ar HEADER-NAME
.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 over HTTP:
.Ar /get-keys and
.Ar /get-config .
.Pp
The
.Ar /get-keys
end-point allows callers to get a principal's keys in
.Dq keytab
format for named principals, possibly performing write operations
such as creating a non-existent principal, or rotating its keys,
if requested.
Note that this end-point can cause KDC HDB principal entries to
be modified or created incidental to fetching the principal's
keys.
The use of the HTTP POST method is required when this end-point
writes to the KDC's HDB.
See below.
.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
.Sh HTTP APIS
All HTTP APIs served by this program accept POSTs, with all
request parameters given as either URI query parameters, and/or
as form data in the POST request body, in either
.Ar application/x-www-form-urlencoded
or
.Ar multipart/formdata .
If GETs are enabled, then request parameters must be supplied as
URI query parameters.
.Pp
Note that requests that cause changes to the HDB must always be
done via POST, never GET.
.Pp
URI query parameters must be of the form
.Ar param0=value&param1=value...
Some parameters can be given multiple values -- see the
descriptions of the end-points.
.Sh CROSS-SITE REQUEST FORGERY PROTECTION
.Em None
of the resources service by this service are intended to be
executed by web pages.
.Pp
Most of the resources provided by this service are
.Dq safe
in the sense that they do not change server-side state besides
logging, and in that they are idempotent, but they are
only safe to execute
.Em if and only if
the requesting party is trusted to see the response.
Since none of these resources are intended to be used from web
pages, it is important that web pages not be able to execute them
.Em and
observe the responses.
.Pp
Some of the resources provided by this service do change
server-side state, specifically principal entries in the KDC's
HDB.
Those always require the use of POST, not GET.
.Pp
In a web browser context, pages from other origins will be able
to attempt requests to this service, but should never be able to
see the responses because browsers normally wouldn't allow that.
Nonetheless, anti cross site request forgery (CSRF) protection
may be desirable.
.Pp
This service provides the following CSRF protection features:
.Bl -tag -width Ds -offset indent
.It requests are rejected if they have a
.Dq Referer
(except the experimental /get-negotiate-token end-point)
.It the service can be configured to require a header that would make the
request not Dq simple
.It GETs can be disabled (see options), thus requiring POSTs
.It GETs can be required to have a CSRF token (see below)
.It POSTs can be required to have a CSRF token
.El
.Pp
The experimental
.Ar /get-negotiate-token
end-point, however, always accepts
.Dq Referer
requests.
.Pp
To obtain a CSRF token, first execute the request without the
CSRF token, and the resulting error
response will include a
.Ar X-CSRF-Token
response header.
.Pp
To execute a request with a CSRF token, first obtain a CSRF token
as described above, then copy the token to the request as the
value of the request's
.Ar X-CSRF-Token
header.
.Pp
The key for keying the CSRF token HMAC is that of the first
current key for the
.Sq WELLKNOWN/CSRFTOKEN
principal for the realm being used.
Every realm served by this service must have this principal.
.Sh GETTING KEYTABS
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.
The default attributes for new principals created this way will
be taken (except for the disabled attribute) from any containing
virtual host-based service principal namespace that include a
leading
.Sq .
in the hostname component, or from
.Nm krb5.conf(5)
(see the CONFIGURATION section).
.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
The HTTP
.Nm Cache-Control
header will be set on
.Nm get-keys
responses to
.Dq Nm no-store ,
and the
.Nm max-age
cache control parameter will be set to the least number of
seconds until before any of the requested principal's keys could
change.
For virtual principals this will be either the time left until a
quarter of the rotation period before the next rotation, or the
time left until a
quarter of the rotation period after the next rotation.
For concrete principals this will be the time left to the first
such principal's password expiration, or, if none of them have a
configured password expiration time, then half of the
.Nm new_service_key_delay
configured in the
.Nm [hdb]
section of the
.Nm krb5.conf(5)
file.
.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
.Dq host
service can create and extract keys for their own service name,
but otherwise a number of service names are 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 allow-GET
.Xc
If given, then HTTP GET will be allowed for the various end-points
other than
.Ar /health .
Otherwise only HEAD and POST will be allowed.
By default GETs are allowed, but this will change soon.
.It Xo
.Fl Fl no-allow-GET
.Xc
If given then HTTP GETs will be rejected for the various
end-points other than
.Ar /health .
.It Xo
.Fl Fl csrf-protection-type= Ns Ar CSRF-PROTECTION-TYPE
.Xc
Possible values of
.Ar CSRF-PROTECTION-TYPE
are
.Bl -bullet -compact -offset indent
.It
.Li GET-with-header
.It
.Li GET-with-token
.It
.Li POST-with-header
.It
.Li POST-with-token
.El
This may be given multiple times.
The default is to require CSRF tokens for POST requests, and to
require neither a non-simple header nor a CSRF token for GET
requests.
.Pp
See
.Sx CROSS-SITE REQUEST FORGERY PROTECTION .
.It Xo
.Fl Fl csrf-header= Ns Ar HEADER-NAME
.Xc
If given, then all requests other than to the
.Ar /health
service must have the given request
.Ar HEADER-NAME
set (the value is irrelevant).
.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
.Bd -literal -offset indent
[ext_keytab]
  simple_csr_authorizer_directory = /etc/krb5/simple_csr_authz
  ipc_csr_authorizer = {
    service = UNIX:/var/heimdal/csr_authorizer_sock
  }
.Ed
.Pp
Configuration parameters specific to
.Nm httpkadmind :
.Bl -tag -width Ds -offset indent
.It csr_authorizer_handles_svc_names = BOOL
.It new_hostbased_service_principal_attributes = ...
.El
.Pp
The
.Nm [ext_keytab]
.Nm get_keys_max_spns = NUMBER
parameter can be used to specify a maximum number of principals whose
keys can be retrieved in one
.Nm GET
of the
.Nm /get-keys
end-point.
Defaults to 400.
.Pp
The
.Nm [ext_keytab]
.Nm new_hostbased_service_principal_attributes
parameter may be used instead of virtual host-based service
namespace principals to specify the attributes of new principals
created by
.Nm httpkadmind ,
and its value is a hive with a service name then a hostname or
namespace, and whose value is a set of attributes as given in the
.Nm kadmin(1) modify
command.
For example:
.Bd -literal -offset indent
[ext_keytab]
  new_hostbased_service_principal_attributes = {
    host = {
        a-particular-hostname.test.h5l.se = ok-as-delegate
        .prod.test.h5l.se = ok-as-delegate
    }
  }
.Ed
.Pp
which means that
.Dq host/a-particular-hostname.test.h5l.se ,
if created via
.Nm httpkadmind ,
will be allowed to get delegated credentials (ticket forwarding),
and that hostnames matching the glob pattern
.Dq host/*.prod.test.h5l.se ,
if created via
.Nm httpkadmind ,
will also allowed to get delegated credentials.
All host-based service principals created via
.Nm httpkadmind
not matchining any
.Nm new_hostbased_service_principal_attributes
service namespaces will have the empty attribute set.
.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