kdc/bx509d.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 BX509 8
  33 .Os HEIMDAL
  34 .Sh NAME
  35 .Nm bx509d
  36 .Nd Authentication Bridge for Bearer tokens, Kerberos, and PKIX
  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 allow-GET
  44 .Op Fl Fl no-allow-GET
  45 .Op Fl Fl csrf-protection-type= Ns Ar CSRF-PROTECTION-TYPE
  46 .Op Fl Fl csrf-header= Ns Ar HEADER-NAME
  47 .Op Fl Fl csrf-key-file= Ns Ar FILE
  48 .Op Fl Fl reverse-proxied
  49 .Op Fl p Ar port number (default: 443)
  50 .Op Fl Fl cache-dir= Ns Ar DIRECTORY
  51 .Op Fl Fl cert= Ns Ar HX509-STORE
  52 .Op Fl Fl private-key= Ns Ar HX509-STORE
  53 .Op Fl t | Fl Fl thread-per-client
  54 .Oo Fl v \*(Ba Xo
  55 .Fl Fl verbose= Ns Ar run verbosely
  56 .Xc
  57 .Oc
  58 .Sh DESCRIPTION
  59 Serves RESTful (HTTPS) GETs of
  60 .Ar /get-cert ,
  61 .Ar /get-tgt ,
  62 .Ar /get-tgts ,
  63 and
  64 .Ar /get-negotiate-token ,
  65 end-points that implement various experimental Heimdal features:
  66 .Bl -bullet -compact -offset indent
  67 .It
  68 .Li an online CA service over HTTPS,
  69 .It
  70 .Li a kinit-over-HTTPS service, and
  71 .It
  72 .Li a Negotiate token over HTTPS service.
  73 .El
  74 .Pp
  75 As well, a
  76 .Ar /health
  77 service can be used for checking service status.
  78 .Pp
  79 Supported options:
  80 .Bl -tag -width Ds
  81 .It Xo
  82 .Fl h ,
  83 .Fl Fl help
  84 .Xc
  85 Print usage message.
  86 .It Xo
  87 .Fl Fl version
  88 .Xc
  89 Print version.
  90 .It Xo
  91 .Fl H Ar HOSTNAME
  92 .Xc
  93 Expected audience(s) of bearer tokens (i.e., acceptor name).
  94 .It Xo
  95 .Fl Fl allow-GET
  96 .Xc
  97 If given, then HTTP GET will be allowed for the various
  98 end-points other than
  99 .Ar /health .
 100 Otherwise only HEAD and POST will be allowed.
 101 By default GETs are allowed, but this will change soon.
 102 .It Xo
 103 .Fl Fl no-allow-GET
 104 .Xc
 105 If given then HTTP GETs will be rejected for the various
 106 end-points other than
 107 .Ar /health .
 108 .It Xo
 109 .Fl Fl csrf-protection-type= Ns Ar CSRF-PROTECTION-TYPE
 110 .Xc
 111 Possible values of
 112 .Ar CSRF-PROTECTION-TYPE
 113 are
 114 .Bl -bullet -compact -offset indent
 115 .It
 116 .Li GET-with-header
 117 .It
 118 .Li GET-with-token
 119 .It
 120 .Li POST-with-header
 121 .It
 122 .Li POST-with-token
 123 .El
 124 This may be given multiple times.
 125 The default is to require CSRF tokens for POST requests, and to
 126 require neither a non-simple header nor a CSRF token for GET
 127 requests.
 128 .Pp
 129 See
 130 .Sx CROSS-SITE REQUEST FORGERY PROTECTION .
 131 .It Xo
 132 .Fl Fl csrf-header= Ns Ar HEADER-NAME
 133 .Xc
 134 If given, then all requests other than to the
 135 .Ar /health
 136 service must have the given request
 137 .Ar HEADER-NAME
 138 set (the value is irrelevant).
 139 The
 140 .Ar HEADER-NAME
 141 must be a request header name such that a request having it makes
 142 it not a
 143 .Dq simple
 144 request (see the Cross-Origin Resource Sharing specification).
 145 Defaults to
 146 .Ar X-CSRF .
 147 .It Xo
 148 .Fl Fl csrf-key-file= Ns Ar FILE
 149 .Xc
 150 If given, this file must contain a 16 byte binary key for keying
 151 the HMAC used in CSRF token construction.
 152 .It Xo
 153 .Fl d ,
 154 .Fl Fl daemon
 155 .Xc
 156 Detach from TTY and run in the background.
 157 .It Xo
 158 .Fl Fl reverse-proxied
 159 .Xc
 160 Serves HTTP instead of HTTPS, accepting only looped-back
 161 connections.
 162 .It Xo
 163 .Fl p Ar port number (default: 443)
 164 .Xc
 165 PORT
 166 .It Xo
 167 .Fl Fl cache-dir= Ns Ar DIRECTORY
 168 .Xc
 169 Directory for various caches.
 170 If not specified then a temporary directory will be made.
 171 .It Xo
 172 .Fl Fl cert= Ns Ar HX509-STORE
 173 .Xc
 174 Certificate file path (PEM) for HTTPS service.
 175 May contain private key as well.
 176 .It Xo
 177 .Fl Fl private-key= Ns Ar HX509-STORE
 178 .Xc
 179 Private key file path (PEM), if the private key is not stored
 180 along with the certificiate.
 181 .It Xo
 182 .Fl t ,
 183 .Fl Fl thread-per-client
 184 .Xc
 185 Uses a thread per-client instead of as many threads as there are
 186 CPUs.
 187 .It Xo
 188 .Fl v ,
 189 .Fl Fl verbose= Ns Ar run verbosely
 190 .Xc
 191 verbose
 192 .El
 193 .Sh HTTP APIS
 194 All HTTP APIs served by this program accept POSTs, with all
 195 request parameters given as URI query parameters and/or as
 196 form data in the POST request body, in either
 197 .Ar application/x-www-form-urlencoded
 198 or
 199 .Ar multipart/formdata .
 200 If request parameters are given both as URI query parameters
 201 and as POST forms, then they are merged into a set.
 202 .Pp
 203 If GETs are enabled, then request parameters must be supplied
 204 only as URI query parameters, as GET requests do not have request
 205 bodies.
 206 .Pp
 207 URI query parameters must be of the form
 208 .Ar param0=value&param1=value...
 209 .Pp
 210 Some request parameters can only have one value.
 211 If multiple values are given for such parameters, then either an
 212 error will be produced, or only the first URI query parameter
 213 value will be used, or the first POST form data parameter will be
 214 used.
 215 Other request parameters can have multiple values.
 216 See below.
 217 .Sh CROSS-SITE REQUEST FORGERY PROTECTION
 218 .Em None
 219 of the resources service by this service are intended to be
 220 executed by web pages.
 221 .Pp
 222 All the resources provided by this service are
 223 .Dq safe
 224 in the sense that they do not change server-side state besides
 225 logging, and in that they are idempotent, but they are
 226 only safe to execute
 227 .Em if and only if
 228 the requesting party is trusted to see the response.
 229 Since none of these resources are intended to be used from web
 230 pages, it is important that web pages not be able to execute them
 231 .Em and
 232 observe the responses.
 233 .Pp
 234 In a web browser context, pages from other origins will be able
 235 to attempt requests to this service, but should never be able to
 236 see the responses because browsers normally wouldn't allow that.
 237 Nonetheless, anti cross site request forgery (CSRF) protection
 238 may be desirable.
 239 .Pp
 240 This service provides the following CSRF protection features:
 241 .Bl -tag -width Ds -offset indent
 242 .It requests are rejected if they have a
 243 .Dq Referer
 244 (except the experimental /get-negotiate-token end-point)
 245 .It the service can be configured to require a header that would make the
 246 request not Dq simple
 247 .It GETs can be disabled (see options), thus requiring POSTs
 248 .It GETs can be required to have a CSRF token (see below)
 249 .It POSTs can be required to have a CSRF token
 250 .El
 251 .Pp
 252 The experimental
 253 .Ar /get-negotiate-token
 254 end-point, however, always accepts
 255 .Dq Referer
 256 requests.
 257 .Pp
 258 To obtain a CSRF token, first execute the request without the
 259 CSRF token, and the resulting error
 260 response will include a
 261 .Ar X-CSRF-Token
 262 response header.
 263 .Pp
 264 To execute a request with a CSRF token, first obtain a CSRF token
 265 as described above, then copy the token to the request as the
 266 value of the request's
 267 .Ar X-CSRF-Token
 268 header.
 269 .Sh ONLINE CERTIFICATION AUTHORITY HTTP API
 270 This service provides an HTTP-based Certification Authority (CA).
 271 CA credentials and configuration are specified in the
 272 .Va [bx509]
 273 section of
 274 .Xr krb5.conf 5 .
 275 .Pp
 276 The protocol consists of a
 277 .Ar GET
 278 of
 279 .Ar /get-cert
 280 with the base-63 encoding of a DER encoding of a PKCS#10
 281 .Ar CertificationRequest
 282 (Certificate Signing Request, or CSR) in a
 283 .Ar csr
 284 required request parameter.
 285 In a successful request, the response body will contain a PEM
 286 encoded end entity certificate and certification chain.
 287 .Pp
 288 Or
 289 .Ar GET
 290 of
 291 .Ar /bx509 ,
 292 as this used to be called.
 293 .Pp
 294 Authentication is required.
 295 Unauthenticated requests will elicit a 401 response.
 296 .Pp
 297 Authorization is required.
 298 Unauthorized requests will elicit a 403 response.
 299 .Pp
 300 Subject Alternative Names (SANs) and Extended Key Usage values
 301 may be requested, both in-band in the CSR as a requested
 302 extensions attribute, and/or via optional request parameters.
 303 .Pp
 304 Supported request parameters:
 305 .Bl -tag -width Ds -offset indent
 306 .It Li csr = Va base64-encoded-DER-encoded-CSR
 307 .It Li dNSName = Va hostname
 308 .It Li rfc822Name = Va email-address
 309 .It Li xMPPName = Va XMPP-address
 310 .It Li krb5PrincipalName = Va Kerberos-principal-name
 311 .It Li ms-upn = Va UPN
 312 .It Li eku = Va OID
 313 .It Li lifetime = Va lifetime
 314 .El
 315 .Pp
 316 More than one name or EKU may be requested.
 317 .Pp
 318 Certificate lifetimes are expressed as a decimal number and
 319 an optional unit (which defaults to
 320 .Dq day
 321 ).
 322 .Sh NEGOTIATE TOKEN HTTP API
 323 This service provides an HTTP-based Negotiate token service.
 324 This service requires a certification authority (CA) issuer
 325 credential as it impersonates client principals to the KDC using
 326 PKINIT client certificates it issues itself.
 327 .Pp
 328 The protocol consists of a
 329 .Ar GET
 330 of
 331 .Ar /get-negotiate-token
 332 with a
 333 .Ar target = Ar service@host
 334 request parameter.
 335 .Pp
 336 In a successful request, the response body will contain a
 337 Negotiate token for the authenticated client principal to the
 338 requested target.
 339 .Pp
 340 Authentication is required.
 341 Unauthenticated requests will elicit a 401 response.
 342 .Pp
 343 Subject Alternative Names (SANs) and Extended Key Usage values
 344 may be requested, both in-band in the CSR as a requested
 345 extensions attribute, and/or via optional request parameters.
 346 .Pp
 347 Supported request parameters:
 348 .Bl -tag -width Ds -offset indent
 349 .It Li target = Va service@hostname
 350 .It Li redirect = Va URI
 351 .El
 352 .Pp
 353 If a redirect URI is given and a matching
 354 .Va Referer
 355 header is included in the request, then the response will be a
 356 redirect to that URI with the Negotiate token in an
 357 .Va Authorization
 358 header that the user-agent should copy to the redirected request.
 359 .Pp
 360 The certification authority configuration is the same as for the
 361 .Va /get-cert
 362 end-point, but as configured in the
 363 .Va [get-tgt]
 364 section of
 365 .Xr krb5.conf 5 .
 366 .Sh TGT HTTP API
 367 This service provides an HTTP-based "kinit" service.
 368 This service requires a certification authority (CA) issuer
 369 credential as it impersonates client principals to the KDC using
 370 PKINIT client certificates it issues itself.
 371 .Pp
 372 The protocol consists of a
 373 .Ar GET
 374 of
 375 .Ar /get-tgt .
 376 .Pp
 377 Supported request parameters:
 378 .Bl -tag -width Ds -offset indent
 379 .It Li cname = Va principal-name
 380 .It Li address = Va IP-address
 381 .It Li lifetime = Va relative-time
 382 .El
 383 .Pp
 384 In a successful request, the response body will contain a TGT and
 385 its session key encoded as a "ccache" file contents.
 386 .Pp
 387 Authentication is required.
 388 Unauthenticated requests will elicit a 401 response.
 389 .Pp
 390 Authorization is required, where the authorization check is the
 391 same as for
 392 .Va /get-cert
 393 by the authenticated client principal to get a certificate with
 394 a PKINIT SAN for itself or the requested principal if a
 395 .Va cname
 396 request parameter was included.
 397 .Pp
 398 Unauthorized requests will elicit a 403 response.
 399 .Pp
 400 Requested IP addresses will be added to the issued TGT if
 401 allowed.
 402 The IP address of the client will be included if address-less
 403 TGTs are not allowed.
 404 See the
 405 .Va [get-tgt]
 406 section of
 407 .Xr krb5.conf 5 .
 408 .Pp
 409 The certification authority configuration is the same as for the
 410 .Va /get-cert
 411 end-point, but as configured in the
 412 .Va [get-tgt]
 413 section of
 414 .Xr krb5.conf 5 .
 415 .Sh BATCH TGT HTTP API
 416 Some sites may have special users that operate batch jobs systems
 417 and that can impersonate many others by obtaining TGTs for them,
 418 and which
 419 .Dq prestash
 420 credentials for those users in their credentials caches.
 421 To support these sytems, a
 422 .Ar GET
 423 of
 424 .Ar /get-tgts
 425 with multiple
 426 .Ar cname
 427 request parameters will return those principals' TGTs (if the
 428 caller is authorized).
 429 .Pp
 430 This is similar to the
 431 .Ar /get-tgt
 432 end-point, but a) multiple
 433 .Ar cname
 434 request parameter values may be given, and b) the caller's
 435 principal name is not used as a default for the
 436 .Ar cname
 437 request parameter.
 438 The
 439 .Ar address
 440 and
 441 .Ar lifetime
 442 request parameters are honored.
 443 .Pp
 444 For successful
 445 .Ar GETs
 446 the response body is a sequence of JSON texts each of which is a
 447 JSON object with two keys:
 448 .Bl -tag -width Ds -offset indent
 449 .It Ar ccache
 450 with a base64-encoded FILE-type ccache;
 451 .It Ar name
 452 the name of the principal whose credentials are in that ccache.
 453 .El
 454 .Sh NOTES
 455 A future release may split all these end-points into separate
 456 services.
 457 .Sh ENVIRONMENT
 458 .Bl -tag -width Ds
 459 .It Ev KRB5_CONFIG
 460 The file name of
 461 .Pa krb5.conf ,
 462 the default being
 463 .Pa /etc/krb5.conf .
 464 .El
 465 .Sh FILES
 466 Configuration parameters are specified in
 467 .Ar /etc/krb5.conf .
 468 .Bl -tag -width Ds
 469 .It Pa /etc/krb5.conf
 470 .El
 471 .\".Sh EXAMPLES
 472 .Sh DIAGNOSTICS
 473 See logging section of
 474 .Nm krb5.conf.5
 475 .Sh SEE ALSO
 476 .Xr krb5.conf 5
 477 .\".Sh STANDARDS
 478 .\".Sh HISTORY
 479 .\".Sh AUTHORS
 480 .\".Sh BUGS