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 allow-GET
  47 .Op Fl Fl no-allow-GET
  48 .Op Fl Fl GET-with-csrf-token
  49 .Op Fl Fl csrf-header= Ns Ar HEADER-NAME
  50 .Op Fl Fl temp-dir= Ns Ar DIRECTORY
  51 .Op Fl Fl cert=HX509-STORE
  52 .Op Fl Fl private-key=HX509-STORE
  53 .Op Fl T | Fl Fl token-authentication-type=Negotiate|Bearer
  54 .Op Fl Fl realm=REALM
  55 .Op Fl Fl read-only
  56 .Op Fl l | Fl Fl local
  57 .Op Fl Fl local-read-only
  58 .Op Fl Fl hdb=HDB
  59 .Op Fl Fl stash-file=FILENAME
  60 .Op Fl Fl primary-server-uri=URI
  61 .Op Fl Fl read-only-admin-server=HOSTNAME[:PORT]
  62 .Op Fl Fl writable-admin-server=HOSTNAME[:PORT]
  63 .Op Fl Fl kadmin-client-name=PRINCIPAL
  64 .Op Fl Fl kadmin-client-keytab=KEYTAB
  65 .Op Fl t | Fl Fl thread-per-client
  66 .Oo Fl v \*(Ba Xo
  67 .Fl Fl verbose= Ns Ar run verbosely
  68 .Xc
  69 .Oc
  70 .Sh DESCRIPTION
  71 Serves the following resources over HTTP:
  72 .Ar /get-keys and
  73 .Ar /get-config .
  74 .Pp
  75 The
  76 .Ar /get-keys
  77 end-point allows callers to get a principal's keys in
  78 .Dq keytab
  79 format for named principals, possibly performing write operations
  80 such as creating a non-existent principal, or rotating its keys,
  81 if requested.
  82 Note that this end-point can cause KDC HDB principal entries to
  83 be modified or created incidental to fetching the principal's
  84 keys.
  85 The use of the HTTP POST method is required when this end-point
  86 writes to the KDC's HDB.
  87 See below.
  88 .Pp
  89 The
  90 .Ar /get-config
  91 end-point allows callers to get
  92 .Nm krb5.conf
  93 contents for a given principal.
  94 .Pp
  95 This service can run against a local HDB, or against a remote HDB
  96 via the
  97 .Nm kadmind(8)
  98 protocol.
  99 Read operations are always allowed, but write operations can be
 100 preformed either against writable
 101 .Nm kadmind(8)
 102 server(s) or redirected to another
 103 .Nm httpkadmind(8).
 104 .Pp
 105 The
 106 .Ar /get-config
 107 end-point accepts a single query parameter:
 108 .Bl -tag -width Ds -offset indent
 109 .It Ar princ=PRINCIPAL .
 110 .El
 111 .Sh HTTP APIS
 112 All HTTP APIs served by this program accept POSTs, with all
 113 request parameters given as either URI query parameters, and/or
 114 as form data in the POST request body, in either
 115 .Ar application/x-www-form-urlencoded
 116 or
 117 .Ar multipart/formdata .
 118 If GETs are enabled, then request parameters must be supplied as
 119 URI query parameters.
 120 .Pp
 121 Note that requests that cause changes to the HDB must always be
 122 done via POST, never GET.
 123 .Pp
 124 URI query parameters must be of the form
 125 .Ar param0=value&param1=value...
 126 Some parameters can be given multiple values -- see the
 127 descriptions of the end-points.
 128 .Sh CROSS-SITE REQUEST FORGERY PROTECTION
 129 .Em None
 130 of the resources service by this service are intended to be
 131 executed by web pages.
 132 .Pp
 133 Most of the resources provided by this service are
 134 .Dq safe
 135 in the sense that they do not change server-side state besides
 136 logging, and in that they are idempotent, but they are
 137 only safe to execute
 138 .Em if and only if
 139 the requesting party is trusted to see the response.
 140 Since none of these resources are intended to be used from web
 141 pages, it is important that web pages not be able to execute them
 142 .Em and
 143 observe the responses.
 144 .Pp
 145 Some of the resources provided by this service do change
 146 server-side state, specifically principal entries in the KDC's
 147 HDB.
 148 Those always require the use of POST, not GET.
 149 .Pp
 150 In a web browser context, pages from other origins will be able
 151 to attempt requests to this service, but should never be able to
 152 see the responses because browsers normally wouldn't allow that.
 153 Nonetheless, anti cross site request forgery (CSRF) protection
 154 may be desirable.
 155 .Pp
 156 This service provides the following CSRF protection features:
 157 .Bl -tag -width Ds -offset indent
 158 .It requests are rejected if they have a
 159 .Dq Referer
 160 (except the experimental /get-negotiate-token end-point)
 161 .It the service can be configured to require a header that would make the
 162 request not Dq simple
 163 .It GETs can be disabled (see options), thus requiring POSTs
 164 .It GETs can be required to have a CSRF token (see below)
 165 .It POSTs can be required to have a CSRF token
 166 .El
 167 .Pp
 168 The experimental
 169 .Ar /get-negotiate-token
 170 end-point, however, always accepts
 171 .Dq Referer
 172 requests.
 173 .Pp
 174 To obtain a CSRF token, first execute the request without the
 175 CSRF token, and the resulting error
 176 response will include a
 177 .Ar X-CSRF-Token
 178 response header.
 179 .Pp
 180 To execute a request with a CSRF token, first obtain a CSRF token
 181 as described above, then copy the token to the request as the
 182 value of the request's
 183 .Ar X-CSRF-Token
 184 header.
 185 .Pp
 186 The key for keying the CSRF token HMAC is that of the first
 187 current key for the
 188 .Sq WELLKNOWN/CSRFTOKEN
 189 principal for the realm being used.
 190 Every realm served by this service must have this principal.
 191 .Sh GETTING KEYTABS
 192 The
 193 .Ar /get-keys
 194 end-point accepts various parameters:
 195 .Bl -tag -width Ds -offset indent
 196 .It Ar spn=PRINCIPAL
 197 Names the host-based service principal whose keys to get.
 198 May be given multiple times, and all named principal's keys will
 199 be fetched.
 200 .It Ar dNSName=HOSTNAME
 201 Names the host-based service principal's hostname whose keys to get.
 202 May be given multiple times, and all named principal's keys will
 203 be fetched.
 204 .It Ar service=SERVICE
 205 Hostnames given with
 206 .Ar dNSName=HOSTNAME
 207 will be qualified with this service name to form a host-based
 208 service principal.
 209 May be given multiple times, in which case the cartesian product
 210 of
 211 .Ar dNSName=HOSTNAME
 212 ad
 213 .Ar service=SERVICE
 214 will be used.
 215 Defaults to
 216 .Ar HTTP .
 217 .It realm=REALM
 218 Must be present if the
 219 .Nm httpkadmind
 220 daemon's default realm is not desired.
 221 .It Ar enctypes=ENCTYPE,...
 222 A comma-separated list of enctypes that the principal is expected
 223 to support (used for Kerberos Ticket session key negotiation).
 224 Defaults to the
 225 .Ar supported_enctypes
 226 configured in
 227 .Nm krb5.conf(5) .
 228 .It Ar materialize=true
 229 If the named principal(s) is (are) virtual, this will cause it
 230 (them) to be materialized as a concrete principal.
 231 (Currently not supported.)
 232 .It Ar create=true
 233 If the named principal(s) does not (do not) exist, this will
 234 cause it (them) to be created.
 235 The default attributes for new principals created this way will
 236 be taken (except for the disabled attribute) from any containing
 237 virtual host-based service principal namespace that include a
 238 leading
 239 .Sq .
 240 in the hostname component, or from
 241 .Nm krb5.conf(5)
 242 (see the CONFIGURATION section).
 243 .It Ar rotate=true
 244 This will cause the keys of concrete principals to be rotated.
 245 .It Ar revoke=true
 246 This will cause old keys of concrete principals to be deleted
 247 if their keys are being rotated.
 248 This means that extant service tickets with those principals as
 249 the target will not be able to be decrypted by the caller as it
 250 will not have the necessary keys.
 251 .El
 252 .Pp
 253 The HTTP
 254 .Nm Cache-Control
 255 header will be set on
 256 .Nm get-keys
 257 responses to
 258 .Dq Nm no-store ,
 259 and the
 260 .Nm max-age
 261 cache control parameter will be set to the least number of
 262 seconds until before any of the requested principal's keys could
 263 change.
 264 For virtual principals this will be either the time left until a
 265 quarter of the rotation period before the next rotation, or the
 266 time left until a
 267 quarter of the rotation period after the next rotation.
 268 For concrete principals this will be the time left to the first
 269 such principal's password expiration, or, if none of them have a
 270 configured password expiration time, then half of the
 271 .Nm new_service_key_delay
 272 configured in the
 273 .Nm [hdb]
 274 section of the
 275 .Nm krb5.conf(5)
 276 file.
 277 .Pp
 278 Authorization is handled via the same mechanism as in
 279 .Nm bx509d(8)
 280 which was originally intended to authorize certification requests
 281 (CSRs).
 282 Authorization for extracting keys is specified like for
 283 .Nm bx509d(8) ,
 284 but using
 285 .Nm [ext_keytab]
 286 as the
 287 .Nm krb5.conf(5) section.
 288 Clients with host-based principals for the
 289 .Dq host
 290 service can create and extract keys for their own service name,
 291 but otherwise a number of service names are denied:
 292 .Bl -tag -width Ds -offset indent
 293 .It Dq host
 294 .It Dq root
 295 .It Dq exceed
 296 .El
 297 as well as all the service names for Heimdal-specific services:
 298 .Bl -tag -width Ds -offset indent
 299 .It Dq krbtgt
 300 .It Dq iprop
 301 .It Dq kadmin
 302 .It Dq hprop
 303 .It Dq WELLKNOWN
 304 .It Dq K
 305 .El
 306 .Pp
 307 Supported options:
 308 .Bl -tag -width Ds -offset indent
 309 .It Xo
 310 .Fl h ,
 311 .Fl Fl help
 312 .Xc
 313 Print usage message.
 314 .It Xo
 315 .Fl Fl version
 316 .Xc
 317 Print version.
 318 .It Xo
 319 .Fl H Ar HOSTNAME
 320 .Xc
 321 Expected audience(s) of bearer tokens (i.e., acceptor name).
 322 .It Xo
 323 .Fl d ,
 324 .Fl Fl daemon
 325 .Xc
 326 Detach from TTY and run in the background.
 327 .It Xo
 328 .Fl Fl reverse-proxied
 329 .Xc
 330 Serves HTTP instead of HTTPS, accepting only looped-back connections.
 331 .It Xo
 332 .Fl p Ar port number (default: 443)
 333 .Xc
 334 PORT
 335 .It Xo
 336 .Fl Fl allow-GET
 337 .Xc
 338 If given, then HTTP GET will be allowed for the various end-points
 339 other than
 340 .Ar /health .
 341 Otherwise only HEAD and POST will be allowed.
 342 By default GETs are allowed, but this will change soon.
 343 .It Xo
 344 .Fl Fl no-allow-GET
 345 .Xc
 346 If given then HTTP GETs will be rejected for the various
 347 end-points other than
 348 .Ar /health .
 349 .It Xo
 350 .Fl Fl csrf-protection-type= Ns Ar CSRF-PROTECTION-TYPE
 351 .Xc
 352 Possible values of
 353 .Ar CSRF-PROTECTION-TYPE
 354 are
 355 .Bl -bullet -compact -offset indent
 356 .It
 357 .Li GET-with-header
 358 .It
 359 .Li GET-with-token
 360 .It
 361 .Li POST-with-header
 362 .It
 363 .Li POST-with-token
 364 .El
 365 This may be given multiple times.
 366 The default is to require CSRF tokens for POST requests, and to
 367 require neither a non-simple header nor a CSRF token for GET
 368 requests.
 369 .Pp
 370 See
 371 .Sx CROSS-SITE REQUEST FORGERY PROTECTION .
 372 .It Xo
 373 .Fl Fl csrf-header= Ns Ar HEADER-NAME
 374 .Xc
 375 If given, then all requests other than to the
 376 .Ar /health
 377 service must have the given request
 378 .Ar HEADER-NAME
 379 set (the value is irrelevant).
 380 .It Xo
 381 .Fl Fl temp-dir= Ns Ar DIRECTORY
 382 .Xc
 383 Directory for temp files.
 384 If not specified then a temporary directory will be made.
 385 .It Xo
 386 .Fl Fl cert= Ns Ar HX509-STORE
 387 .Xc
 388 Certificate file path (PEM) for HTTPS service.
 389 May contain private key as well.
 390 .It Xo
 391 .Fl Fl private-key= Ns Ar HX509-STORE
 392 .Xc
 393 Private key file path (PEM), if the private key is not stored along with the
 394 certificiate.
 395 .It Xo
 396 .Fl T Ar HTTP-AUTH-TYPE,
 397 .Fl Fl token-authentication-type= Ns Ar HTTP-AUTH-TYPE
 398 .Xc
 399 HTTP bearer token authentication type(s) supported (may be given more than
 400 once).
 401 For example,
 402 .Ar Negotiate
 403 or
 404 .Ar Bearer
 405 (JWT).
 406 .It Xo
 407 .Fl t ,
 408 .Fl Fl thread-per-client
 409 .Xc
 410 Uses a thread per-client instead of as many threads as there are CPUs.
 411 .It Xo
 412 .Fl Fl realm= Ns Ar REALM
 413 .Xc
 414 The realm to serve, if not the default realm.
 415 Note that clients can request keys for principals in other realms, and
 416 .Nm httpkadmind
 417 will attempt to satisfy those requests too.
 418 .It Xo
 419 .Fl Fl read-only
 420 .Xc
 421 Do not perform write operations.
 422 Write operations will either fail or if a primary
 423 .Nm httpkadmind
 424 URI is configured, then they will be redirected there.
 425 .It Xo
 426 .Fl Fl local
 427 .Xc
 428 Use a local HDB, at least for read operations, and, if
 429 .Fl Fl local-read-only
 430 is not given, then also write operations.
 431 .It Xo
 432 .Fl Fl local-read-only
 433 .Xc
 434 Do not perform writes on a local HDB.
 435 Either redirect write operations if a primary
 436 .Nm httpkadmind
 437 URI is configured, or use a writable remote
 438 .Nm kadmind
 439 server.
 440 .It Xo
 441 .Fl Fl hdb=HDB
 442 .Xc
 443 A local HDB to serve.
 444 Note that this can be obtained from the
 445 .Nm krb5.conf .
 446 .It Xo
 447 .Fl Fl stash-file=FILENAME
 448 .Xc
 449 A stash file containing a master key for a local HDB.
 450 Note that this can be obtained from the
 451 .Nm krb5.conf .
 452 .It Xo
 453 .Fl Fl primary-server-uri=URI
 454 .Xc
 455 The URL of an httpkadmind to which to redirect write operations.
 456 .It Xo
 457 .Fl Fl read-only-admin-server=HOSTNAME[:PORT]
 458 .Xc
 459 The hostname (and possibly port number) of a
 460 .Nm kadmind(8)
 461 service to use for read-only operations.
 462 Recall that the
 463 .Nm kadmind(8)
 464 service's principal name is
 465 .Ar kadmin/admin .
 466 The
 467 .Ar HOSTNAME
 468 given here can be a name that resolves to the IP addresses of all
 469 the
 470 .Nm kadmind(8)
 471 services for the
 472 .Ar REALM .
 473 If not specified, but needed, this will be obtained by looking for
 474 .Nm readonly_admin_server
 475 in
 476 .Nm krb5.conf
 477 or, if enabled, performing
 478 DNS lookups for SRV resource records named
 479 .Ar _kerberos-adm-readonly._tcp.<realm> .
 480 .It Xo
 481 .Fl Fl writable-admin-server=HOSTNAME[:PORT]
 482 .Xc
 483 The hostname (and possibly port number) of a
 484 .Nm kadmind(8)
 485 service to use for write operations.
 486 If not specified, but needed, this will be obtained by looking for
 487 .Nm admin_server
 488 in
 489 .Nm krb5.conf
 490 or, if enabled, performing DNS lookups for SRV resource records named
 491 .Ar _kerberos-adm._tcp.<realm> .
 492 .It Xo
 493 .Fl Fl kadmin-client-name=PRINCIPAL
 494 .Xc
 495 The client principal name to use when connecting to a
 496 .Nm kadmind(8)
 497 server.
 498 Defaults to
 499 .Ar httpkadmind/admin .
 500 .It Xo
 501 .Fl Fl kadmin-client-keytab=KEYTAB
 502 .Xc
 503 The keytab containing keys for the
 504 .Ar kadmin-client-name .
 505 Note that you may use an
 506 .Ar HDB
 507 as a keytab as
 508 .Ar HDBGET:/var/heimdal/heimdal.db
 509 (or whatever the HDB specification is).
 510 .It Xo
 511 .Fl v ,
 512 .Fl Fl verbose= Ns Ar run verbosely
 513 .Xc
 514 verbose
 515 .El
 516 .Sh ENVIRONMENT
 517 .Bl -tag -width Ds
 518 .It Ev KRB5_CONFIG
 519 The file name of
 520 .Pa krb5.conf ,
 521 the default being
 522 .Pa /etc/krb5.conf .
 523 .El
 524 .Sh FILES
 525 .Bl -tag -width Ds
 526 .It Pa /etc/krb5.conf
 527 .El
 528 .Sh CONFIGURATION
 529 Authorizer configuration goes in
 530 .Br
 531 .Ar [ext_keytab]
 532 in
 533 .Nm krb5.conf(5).  For example:
 534 .Pp
 535 .Bd -literal -offset indent
 536 [ext_keytab]
 537   simple_csr_authorizer_directory = /etc/krb5/simple_csr_authz
 538   ipc_csr_authorizer = {
 539     service = UNIX:/var/heimdal/csr_authorizer_sock
 540   }
 541 .Ed
 542 .Pp
 543 Configuration parameters specific to
 544 .Nm httpkadmind :
 545 .Bl -tag -width Ds -offset indent
 546 .It csr_authorizer_handles_svc_names = BOOL
 547 .It new_hostbased_service_principal_attributes = ...
 548 .El
 549 .Pp
 550 The
 551 .Nm [ext_keytab]
 552 .Nm get_keys_max_spns = NUMBER
 553 parameter can be used to specify a maximum number of principals whose
 554 keys can be retrieved in one
 555 .Nm GET
 556 of the
 557 .Nm /get-keys
 558 end-point.
 559 Defaults to 400.
 560 .Pp
 561 The
 562 .Nm [ext_keytab]
 563 .Nm new_hostbased_service_principal_attributes
 564 parameter may be used instead of virtual host-based service
 565 namespace principals to specify the attributes of new principals
 566 created by
 567 .Nm httpkadmind ,
 568 and its value is a hive with a service name then a hostname or
 569 namespace, and whose value is a set of attributes as given in the
 570 .Nm kadmin(1) modify
 571 command.
 572 For example:
 573 .Bd -literal -offset indent
 574 [ext_keytab]
 575   new_hostbased_service_principal_attributes = {
 576     host = {
 577         a-particular-hostname.test.h5l.se = ok-as-delegate
 578         .prod.test.h5l.se = ok-as-delegate
 579     }
 580   }
 581 .Ed
 582 .Pp
 583 which means that
 584 .Dq host/a-particular-hostname.test.h5l.se ,
 585 if created via
 586 .Nm httpkadmind ,
 587 will be allowed to get delegated credentials (ticket forwarding),
 588 and that hostnames matching the glob pattern
 589 .Dq host/*.prod.test.h5l.se ,
 590 if created via
 591 .Nm httpkadmind ,
 592 will also allowed to get delegated credentials.
 593 All host-based service principals created via
 594 .Nm httpkadmind
 595 not matchining any
 596 .Nm new_hostbased_service_principal_attributes
 597 service namespaces will have the empty attribute set.
 598 .Sh EXAMPLES
 599 To start
 600 .Nm httpkadmind
 601 on a primary KDC:
 602 .Pp
 603 .Ar $ httpkadmind -d --cert=PEM-FILE:/etc/httpkadmind.pem
 604 \\
 605 .Br
 606    --local -T Negotiate
 607 .Pp
 608 To start
 609 .Nm httpkadmind
 610 on a secondary KDC, using redirects for write operations:
 611 .Pp
 612 .Ar $ httpkadmind -d --cert=PEM-FILE:/etc/httpkadmind.pem
 613 \\
 614 .Br
 615   --local-read-only -T Negotiate
 616 \\
 617 .Br
 618   --primary-server-uri=https://the-primary-server.fqdn/
 619 .Pp
 620 To start
 621 .Nm httpkadmind
 622 on a secondary KDC, proxying kadmin to perform writes at the primary KDC, using
 623 DNS to discover the kadmin server:
 624 .Pp
 625 .Ar $ httpkadmind -d --cert=PEM-FILE:/etc/httpkadmind.pem
 626 \\
 627 .Br
 628   --local-read-only -T Negotiate
 629 \\
 630 .Br
 631   --kadmin-client-keytab=FILE:/etc/krb5.keytab
 632 .Pp
 633 To start
 634 .Nm httpkadmind
 635 on a non-KDC:
 636 .Pp
 637 .Ar $ httpkadmind -d --cert=PEM-FILE:/etc/httpkadmind.pem
 638 \\
 639 .Br
 640   -T Negotiate --kadmin-client-keytab=FILE:/etc/krb5.keytab
 641 .Pp
 642 .Sh DIAGNOSTICS
 643 See logging section of
 644 .Nm krb5.conf.5
 645 .Sh SEE ALSO
 646 .Xr bx509d 8 ,
 647 .Xr kadmin 1 ,
 648 .Xr kadmind 8 ,
 649 .Xr krb5.conf 5 .
 650 .\".Sh STANDARDS
 651 .\".Sh HISTORY
 652 .\".Sh AUTHORS
 653 .\".Sh BUGS