doc/formats/cookie.rst

   1 KDC cookie format
   2 =================
   3
   4 :rfc:`6113` section 5.2 specifies a pa-data type PA-FX-COOKIE, which
   5 clients are required to reflect back to the KDC during
   6 pre-authentication.  The MIT krb5 KDC uses the following formats for
   7 cookies.
   8
   9
  10 Trivial cookie (version 0)
  11 --------------------------
  12
  13 If there is no pre-authentication mechanism state information to save,
  14 a trivial cookie containing the value "MIT" is used.  A trivial cookie
  15 is needed to indicate that the conversation can continue.
  16
  17
  18 Secure cookie (version 1)
  19 -------------------------
  20
  21 In release 1.14 and later, a secure cookie can be sent if there is any
  22 mechanism state to save for the next request.  A secure cookie
  23 contains the concatenation of the following:
  24
  25 * the four bytes "MIT1"
  26 * a four-byte big-endian kvno value
  27 * an :rfc:`3961` ciphertext
  28
  29 The ciphertext is encrypted in the cookie key with key usage
  30 number 513.  The cookie key is derived from a key in the local krbtgt
  31 principal entry for the realm (e.g. ``krbtgt/KRBTEST.COM@KRBTEST.COM``
  32 if the request is to the ``KRBTEST.COM`` realm).  The first krbtgt key
  33 for the indicated kvno value is combined with the client principal as
  34 follows::
  35
  36     cookie-key <- random-to-key(PRF+(tgt-key, "COOKIE" | client-princ))
  37
  38 where **random-to-key** is the :rfc:`3961` random-to-key operation for
  39 the krbtgt key's encryption type, **PRF+** is defined in :rfc:`6113`,
  40 and ``|`` denotes concatenation.  *client-princ* is the request client
  41 principal name with realm, marshalled according to :rfc:`1964` section
  42 2.1.1.
  43
  44 The plain text of the encrypted part of a cookie is the DER encoding
  45 of the following ASN.1 type::
  46
  47     SecureCookie ::= SEQUENCE {
  48         time     INTEGER,
  49         data     SEQUENCE OF PA-DATA,
  50         ...
  51     }
  52
  53 The time field represents the cookie creation time; for brevity, it is
  54 encoded as an integer giving the POSIX timestamp rather than as an
  55 ASN.1 GeneralizedTime value.  The data field contains one element for
  56 each pre-authentication type which requires saved state.  For
  57 mechanisms which have separate request and reply types, the request
  58 type is used; this allows the KDC to determine whether a cookie is
  59 relevant to a request by comparing the request pa-data types to the
  60 cookie data types.