1 .\" Copyright (c) 2020 Kungliga Tekniska Högskolan
2 .\" (Royal Institute of Technology, Stockholm, Sweden).
3 .\" All rights reserved.
5 .\" Redistribution and use in source and binary forms, with or without
6 .\" modification, are permitted provided that the following conditions
9 .\" 1. Redistributions of source code must retain the above copyright
10 .\" notice, this list of conditions and the following disclaimer.
12 .\" 2. Redistributions in binary form must reproduce the above copyright
13 .\" notice, this list of conditions and the following disclaimer in the
14 .\" documentation and/or other materials provided with the distribution.
16 .\" 3. Neither the name of the Institute nor the names of its contributors
17 .\" may be used to endorse or promote products derived from this software
18 .\" without specific prior written permission.
20 .\" THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND
21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
23 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE
24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
36 .Nd HTTP HDB Administration Interface
42 .Op Fl d | Fl Fl daemon
43 .Op Fl Fl daemon-child
44 .Op Fl Fl reverse-proxied
45 .Op Fl p Ar port number (default: 443)
46 .Op Fl Fl temp-dir= Ns Ar DIRECTORY
47 .Op Fl Fl cert=HX509-STORE
48 .Op Fl Fl private-key=HX509-STORE
49 .Op Fl T | Fl Fl token-authentication-type=Negotiate|Bearer
52 .Op Fl l | Fl Fl local
53 .Op Fl Fl local-read-only
55 .Op Fl Fl stash-file=FILENAME
56 .Op Fl Fl primary-server-uri=URI
57 .Op Fl Fl read-only-admin-server=HOSTNAME[:PORT]
58 .Op Fl Fl writable-admin-server=HOSTNAME[:PORT]
59 .Op Fl Fl kadmin-client-name=PRINCIPAL
60 .Op Fl Fl kadmin-client-keytab=KEYTAB
61 .Op Fl t | Fl Fl thread-per-client
63 .Fl Fl verbose= Ns Ar run verbosely
67 Serves the following resources:
73 end-point allows callers to get keytab content for named
74 principals, possibly performing write operations such as creating
75 a non-existent principal, or rotating its keys, if requested.
79 end-point allows callers to get
81 contents for a given principal.
83 This service can run against a local HDB, or against a remote HDB
87 Read operations are always allowed, but write operations can be
88 preformed either against writable
90 server(s) or redirected to another
95 end-point accepts a single query parameter:
96 .Bl -tag -width Ds -offset indent
97 .It Ar princ=PRINCIPAL .
102 end-point accepts various parameters:
103 .Bl -tag -width Ds -offset indent
105 Names the host-based service principal whose keys to get.
106 May be given multiple times, and all named principal's keys will
108 .It Ar dNSName=HOSTNAME
109 Names the host-based service principal's hostname whose keys to get.
110 May be given multiple times, and all named principal's keys will
112 .It Ar service=SERVICE
115 will be qualified with this service name to form a host-based
117 May be given multiple times, in which case the cartesian product
126 Must be present if the
128 daemon's default realm is not desired.
129 .It Ar enctypes=ENCTYPE,...
130 A comma-separated list of enctypes that the principal is expected
131 to support (used for Kerberos Ticket session key negotiation).
133 .Ar supported_enctypes
136 .It Ar materialize=true
137 If the named principal(s) is (are) virtual, this will cause it
138 (them) to be materialized as a concrete principal.
139 (Currently not supported.)
141 If the named principal(s) does not (do not) exist, this will
142 cause it (them) to be created.
144 This will cause the keys of concrete principals to be rotated.
146 This will cause old keys of concrete principals to be deleted
147 if their keys are being rotated.
148 This means that extant service tickets with those principals as
149 the target will not be able to be decrypted by the caller as it
150 will not have the necessary keys.
153 Authorization is handled via the same mechanism as in
155 which was originally intended to authorize certification requests
157 Authorization for extracting keys is specified like for
162 .Nm krb5.conf(5) section.
163 Clients with host-based principals for the the host service can
164 create and extract keys for their own service name, but otherwise
165 a number of service names are not denied:
166 .Bl -tag -width Ds -offset indent
171 as well as all the service names for Heimdal-specific services:
172 .Bl -tag -width Ds -offset indent
182 .Bl -tag -width Ds -offset indent
195 Expected audience(s) of bearer tokens (i.e., acceptor name).
200 Detach from TTY and run in the background.
202 .Fl Fl reverse-proxied
204 Serves HTTP instead of HTTPS, accepting only looped-back connections.
206 .Fl p Ar port number (default: 443)
210 .Fl Fl temp-dir= Ns Ar DIRECTORY
212 Directory for temp files.
213 If not specified then a temporary directory will be made.
215 .Fl Fl cert= Ns Ar HX509-STORE
217 Certificate file path (PEM) for HTTPS service.
218 May contain private key as well.
220 .Fl Fl private-key= Ns Ar HX509-STORE
222 Private key file path (PEM), if the private key is not stored along with the
225 .Fl T Ar HTTP-AUTH-TYPE,
226 .Fl Fl token-authentication-type= Ns Ar HTTP-AUTH-TYPE
228 HTTP bearer token authentication type(s) supported (may be given more than
237 .Fl Fl thread-per-client
239 Uses a thread per-client instead of as many threads as there are CPUs.
241 .Fl Fl realm= Ns Ar REALM
243 The realm to serve, if not the default realm.
244 Note that clients can request keys for principals in other realms, and
246 will attempt to satisfy those requests too.
250 Do not perform write operations.
251 Write operations will either fail or if a primary
253 URI is configured, then they will be redirected there.
257 Use a local HDB, at least for read operations, and, if
258 .Fl Fl local-read-only
259 is not given, then also write operations.
261 .Fl Fl local-read-only
263 Do not perform writes on a local HDB.
264 Either redirect write operations if a primary
266 URI is configured, or use a writable remote
272 A local HDB to serve.
273 Note that this can be obtained from the
276 .Fl Fl stash-file=FILENAME
278 A stash file containing a master key for a local HDB.
279 Note that this can be obtained from the
282 .Fl Fl primary-server-uri=URI
284 The URL of an httpkadmind to which to redirect write operations.
286 .Fl Fl read-only-admin-server=HOSTNAME[:PORT]
288 The hostname (and possibly port number) of a
290 service to use for read-only operations.
293 service's principal name is
297 given here can be a name that resolves to the IP addresses of all
302 If not specified, but needed, this will be obtained by looking for
303 .Nm readonly_admin_server
306 or, if enabled, performing
307 DNS lookups for SRV resource records named
308 .Ar _kerberos-adm-readonly._tcp.<realm> .
310 .Fl Fl writable-admin-server=HOSTNAME[:PORT]
312 The hostname (and possibly port number) of a
314 service to use for write operations.
315 If not specified, but needed, this will be obtained by looking for
319 or, if enabled, performing DNS lookups for SRV resource records named
320 .Ar _kerberos-adm._tcp.<realm> .
322 .Fl Fl kadmin-client-name=PRINCIPAL
324 The client principal name to use when connecting to a
328 .Ar httpkadmind/admin .
330 .Fl Fl kadmin-client-keytab=KEYTAB
332 The keytab containing keys for the
333 .Ar kadmin-client-name .
334 Note that you may use an
337 .Ar HDBGET:/var/heimdal/heimdal.db
338 (or whatever the HDB specification is).
341 .Fl Fl verbose= Ns Ar run verbosely
355 .It Pa /etc/krb5.conf
358 Authorizer configuration goes in
362 .Nm krb5.conf(5). For example:
365 simple_csr_authorizer_directory = /etc/krb5/simple_csr_authz
366 ipc_csr_authorizer = {
367 service = UNIX:/var/heimdal/csr_authorizer_sock
374 .Ar $ httpkadmind -d --cert=PEM-FILE:/etc/httpkadmind.pem
381 on a secondary KDC, using redirects for write operations:
383 .Ar $ httpkadmind -d --cert=PEM-FILE:/etc/httpkadmind.pem
386 --local-read-only -T Negotiate
389 --primary-server-uri=https://the-primary-server.fqdn/
393 on a secondary KDC, proxying kadmin to perform writes at the primary KDC, using
394 DNS to discover the kadmin server:
396 .Ar $ httpkadmind -d --cert=PEM-FILE:/etc/httpkadmind.pem
399 --local-read-only -T Negotiate
402 --kadmin-client-keytab=FILE:/etc/krb5.keytab
408 .Ar $ httpkadmind -d --cert=PEM-FILE:/etc/httpkadmind.pem
411 -T Negotiate --kadmin-client-keytab=FILE:/etc/krb5.keytab
414 See logging section of