source4/heimdal/kdc/httpkadmind.8

   1 .\" Copyright (c) 2020 Kungliga Tekniska Högskolan
   2 .\" (Royal Institute of Technology, Stockholm, Sweden).
   3 .\" All rights reserved.
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\"
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\"
  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.
  15 .\"
  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.
  19 .\"
  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
  30 .\" SUCH DAMAGE.
  31 .Dd January  2, 2020
  32 .Dt HTTPKADMIND 8
  33 .Os HEIMDAL
  34 .Sh NAME
  35 .Nm httpkadmind
  36 .Nd HTTP HDB Administration Interface
  37 .Sh SYNOPSIS
  38 .Nm
  39 .Op Fl h | Fl Fl help
  40 .Op Fl Fl version
  41 .Op Fl H Ar HOSTNAME
  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
  50 .Op Fl Fl realm=REALM
  51 .Op Fl Fl read-only
  52 .Op Fl l | Fl Fl local
  53 .Op Fl Fl local-read-only
  54 .Op Fl Fl hdb=HDB
  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
  62 .Oo Fl v \*(Ba Xo
  63 .Fl Fl verbose= Ns Ar run verbosely
  64 .Xc
  65 .Oc
  66 .Sh DESCRIPTION
  67 Serves the following resources:
  68 .Ar /get-keys and
  69 .Ar /get-config .
  70 .Pp
  71 The
  72 .Ar /get-keys
  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.
  76 .Pp
  77 The
  78 .Ar /get-config
  79 end-point allows callers to get
  80 .Nm krb5.conf
  81 contents for a given principal.
  82 .Pp
  83 This service can run against a local HDB, or against a remote HDB
  84 via the
  85 .Nm kadmind(8)
  86 protocol.
  87 Read operations are always allowed, but write operations can be
  88 preformed either against writable
  89 .Nm kadmind(8)
  90 server(s) or redirected to another
  91 .Nm httpkadmind(8).
  92 .Pp
  93 The
  94 .Ar /get-config
  95 end-point accepts a single query parameter:
  96 .Bl -tag -width Ds -offset indent
  97 .It Ar princ=PRINCIPAL .
  98 .El
  99 .Pp
 100 The
 101 .Ar /get-keys
 102 end-point accepts various parameters:
 103 .Bl -tag -width Ds -offset indent
 104 .It Ar spn=PRINCIPAL
 105 Names the host-based service principal whose keys to get.
 106 May be given multiple times, and all named principal's keys will
 107 be fetched.
 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
 111 be fetched.
 112 .It Ar service=SERVICE
 113 Hostnames given with
 114 .Ar dNSName=HOSTNAME
 115 will be qualified with this service name to form a host-based
 116 service principal.
 117 May be given multiple times, in which case the cartesian product
 118 of
 119 .Ar dNSName=HOSTNAME
 120 ad
 121 .Ar service=SERVICE
 122 will be used.
 123 Defaults to
 124 .Ar HTTP .
 125 .It realm=REALM
 126 Must be present if the
 127 .Nm httpkadmind
 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).
 132 Defaults to the
 133 .Ar supported_enctypes
 134 configured in
 135 .Nm krb5.conf(5) .
 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.)
 140 .It Ar create=true
 141 If the named principal(s) does not (do not) exist, this will
 142 cause it (them) to be created.
 143 .It Ar rotate=true
 144 This will cause the keys of concrete principals to be rotated.
 145 .It Ar revoke=true
 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.
 151 .El
 152 .Pp
 153 Authorization is handled via the same mechanism as in
 154 .Nm bx509d(8)
 155 which was originally intended to authorize certification requests
 156 (CSRs).
 157 Authorization for extracting keys is specified like for
 158 .Nm bx509d(8) ,
 159 but using
 160 .Nm [ext_keytab]
 161 as the
 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
 167 .It Dq host
 168 .It Dq root
 169 .It Dq exceed
 170 .El
 171 as well as all the service names for Heimdal-specific services:
 172 .Bl -tag -width Ds -offset indent
 173 .It Dq krbtgt
 174 .It Dq iprop
 175 .It Dq kadmin
 176 .It Dq hprop
 177 .It Dq WELLKNOWN
 178 .It Dq K
 179 .El
 180 .Pp
 181 Supported options:
 182 .Bl -tag -width Ds -offset indent
 183 .It Xo
 184 .Fl h ,
 185 .Fl Fl help
 186 .Xc
 187 Print usage message.
 188 .It Xo
 189 .Fl Fl version
 190 .Xc
 191 Print version.
 192 .It Xo
 193 .Fl H Ar HOSTNAME
 194 .Xc
 195 Expected audience(s) of bearer tokens (i.e., acceptor name).
 196 .It Xo
 197 .Fl d ,
 198 .Fl Fl daemon
 199 .Xc
 200 Detach from TTY and run in the background.
 201 .It Xo
 202 .Fl Fl reverse-proxied
 203 .Xc
 204 Serves HTTP instead of HTTPS, accepting only looped-back connections.
 205 .It Xo
 206 .Fl p Ar port number (default: 443)
 207 .Xc
 208 PORT
 209 .It Xo
 210 .Fl Fl temp-dir= Ns Ar DIRECTORY
 211 .Xc
 212 Directory for temp files.
 213 If not specified then a temporary directory will be made.
 214 .It Xo
 215 .Fl Fl cert= Ns Ar HX509-STORE
 216 .Xc
 217 Certificate file path (PEM) for HTTPS service.
 218 May contain private key as well.
 219 .It Xo
 220 .Fl Fl private-key= Ns Ar HX509-STORE
 221 .Xc
 222 Private key file path (PEM), if the private key is not stored along with the
 223 certificiate.
 224 .It Xo
 225 .Fl T Ar HTTP-AUTH-TYPE,
 226 .Fl Fl token-authentication-type= Ns Ar HTTP-AUTH-TYPE
 227 .Xc
 228 HTTP bearer token authentication type(s) supported (may be given more than
 229 once).
 230 For example,
 231 .Ar Negotiate
 232 or
 233 .Ar Bearer
 234 (JWT).
 235 .It Xo
 236 .Fl t ,
 237 .Fl Fl thread-per-client
 238 .Xc
 239 Uses a thread per-client instead of as many threads as there are CPUs.
 240 .It Xo
 241 .Fl Fl realm= Ns Ar REALM
 242 .Xc
 243 The realm to serve, if not the default realm.
 244 Note that clients can request keys for principals in other realms, and
 245 .Nm httpkadmind
 246 will attempt to satisfy those requests too.
 247 .It Xo
 248 .Fl Fl read-only
 249 .Xc
 250 Do not perform write operations.
 251 Write operations will either fail or if a primary
 252 .Nm httpkadmind
 253 URI is configured, then they will be redirected there.
 254 .It Xo
 255 .Fl Fl local
 256 .Xc
 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.
 260 .It Xo
 261 .Fl Fl local-read-only
 262 .Xc
 263 Do not perform writes on a local HDB.
 264 Either redirect write operations if a primary
 265 .Nm httpkadmind
 266 URI is configured, or use a writable remote
 267 .Nm kadmind
 268 server.
 269 .It Xo
 270 .Fl Fl hdb=HDB
 271 .Xc
 272 A local HDB to serve.
 273 Note that this can be obtained from the
 274 .Nm krb5.conf .
 275 .It Xo
 276 .Fl Fl stash-file=FILENAME
 277 .Xc
 278 A stash file containing a master key for a local HDB.
 279 Note that this can be obtained from the
 280 .Nm krb5.conf .
 281 .It Xo
 282 .Fl Fl primary-server-uri=URI
 283 .Xc
 284 The URL of an httpkadmind to which to redirect write operations.
 285 .It Xo
 286 .Fl Fl read-only-admin-server=HOSTNAME[:PORT]
 287 .Xc
 288 The hostname (and possibly port number) of a
 289 .Nm kadmind(8)
 290 service to use for read-only operations.
 291 Recall that the
 292 .Nm kadmind(8)
 293 service's principal name is
 294 .Ar kadmin/admin .
 295 The
 296 .Ar HOSTNAME
 297 given here can be a name that resolves to the IP addresses of all
 298 the
 299 .Nm kadmind(8)
 300 services for the
 301 .Ar REALM .
 302 If not specified, but needed, this will be obtained by looking for
 303 .Nm readonly_admin_server
 304 in
 305 .Nm krb5.conf
 306 or, if enabled, performing
 307 DNS lookups for SRV resource records named
 308 .Ar _kerberos-adm-readonly._tcp.<realm> .
 309 .It Xo
 310 .Fl Fl writable-admin-server=HOSTNAME[:PORT]
 311 .Xc
 312 The hostname (and possibly port number) of a
 313 .Nm kadmind(8)
 314 service to use for write operations.
 315 If not specified, but needed, this will be obtained by looking for
 316 .Nm admin_server
 317 in
 318 .Nm krb5.conf
 319 or, if enabled, performing DNS lookups for SRV resource records named
 320 .Ar _kerberos-adm._tcp.<realm> .
 321 .It Xo
 322 .Fl Fl kadmin-client-name=PRINCIPAL
 323 .Xc
 324 The client principal name to use when connecting to a
 325 .Nm kadmind(8)
 326 server.
 327 Defaults to
 328 .Ar httpkadmind/admin .
 329 .It Xo
 330 .Fl Fl kadmin-client-keytab=KEYTAB
 331 .Xc
 332 The keytab containing keys for the
 333 .Ar kadmin-client-name .
 334 Note that you may use an
 335 .Ar HDB
 336 as a keytab as
 337 .Ar HDBGET:/var/heimdal/heimdal.db
 338 (or whatever the HDB specification is).
 339 .It Xo
 340 .Fl v ,
 341 .Fl Fl verbose= Ns Ar run verbosely
 342 .Xc
 343 verbose
 344 .El
 345 .Sh ENVIRONMENT
 346 .Bl -tag -width Ds
 347 .It Ev KRB5_CONFIG
 348 The file name of
 349 .Pa krb5.conf ,
 350 the default being
 351 .Pa /etc/krb5.conf .
 352 .El
 353 .Sh FILES
 354 .Bl -tag -width Ds
 355 .It Pa /etc/krb5.conf
 356 .El
 357 .Sh CONFIGURATION
 358 Authorizer configuration goes in
 359 .Br
 360 .Ar [ext_keytab]
 361 in
 362 .Nm krb5.conf(5).  For example:
 363 .Pp
 364 [ext_keytab]
 365   simple_csr_authorizer_directory = /etc/krb5/simple_csr_authz
 366   ipc_csr_authorizer = {
 367     service = UNIX:/var/heimdal/csr_authorizer_sock
 368   }
 369 .Sh EXAMPLES
 370 To start
 371 .Nm httpkadmind
 372 on a primary KDC:
 373 .Pp
 374 .Ar $ httpkadmind -d --cert=PEM-FILE:/etc/httpkadmind.pem
 375 \\
 376 .Br
 377    --local -T Negotiate
 378 .Pp
 379 To start
 380 .Nm httpkadmind
 381 on a secondary KDC, using redirects for write operations:
 382 .Pp
 383 .Ar $ httpkadmind -d --cert=PEM-FILE:/etc/httpkadmind.pem
 384 \\
 385 .Br
 386   --local-read-only -T Negotiate
 387 \\
 388 .Br
 389   --primary-server-uri=https://the-primary-server.fqdn/
 390 .Pp
 391 To start
 392 .Nm httpkadmind
 393 on a secondary KDC, proxying kadmin to perform writes at the primary KDC, using
 394 DNS to discover the kadmin server:
 395 .Pp
 396 .Ar $ httpkadmind -d --cert=PEM-FILE:/etc/httpkadmind.pem
 397 \\
 398 .Br
 399   --local-read-only -T Negotiate
 400 \\
 401 .Br
 402   --kadmin-client-keytab=FILE:/etc/krb5.keytab
 403 .Pp
 404 To start
 405 .Nm httpkadmind
 406 on a non-KDC:
 407 .Pp
 408 .Ar $ httpkadmind -d --cert=PEM-FILE:/etc/httpkadmind.pem
 409 \\
 410 .Br
 411   -T Negotiate --kadmin-client-keytab=FILE:/etc/krb5.keytab
 412 .Pp
 413 .Sh DIAGNOSTICS
 414 See logging section of
 415 .Nm krb5.conf.5
 416 .Sh SEE ALSO
 417 .Xr bx509d 8 ,
 418 .Xr kadmin 1 ,
 419 .Xr kadmind 8 ,
 420 .Xr krb5.conf 5 .
 421 .\".Sh STANDARDS
 422 .\".Sh HISTORY
 423 .\".Sh AUTHORS
 424 .\".Sh BUGS