1 files changed, 60 insertions, 0 deletions
diff --git a/doc/formats/cookie.rst b/doc/formats/cookie.rst
new file mode 100644
index 000000000000..640955c90b43
--- /dev/null
+++ b/doc/formats/cookie.rst
@@ -0,0 +1,60 @@
+KDC cookie format
+=================
+
+:rfc:`6113` section 5.2 specifies a pa-data type PA-FX-COOKIE, which
+clients are required to reflect back to the KDC during
+pre-authentication.  The MIT krb5 KDC uses the following formats for
+cookies.
+
+
+Trivial cookie (version 0)
+--------------------------
+
+If there is no pre-authentication mechanism state information to save,
+a trivial cookie containing the value "MIT" is used.  A trivial cookie
+is needed to indicate that the conversation can continue.
+
+
+Secure cookie (version 1)
+-------------------------
+
+In release 1.14 and later, a secure cookie can be sent if there is any
+mechanism state to save for the next request.  A secure cookie
+contains the concatenation of the following:
+
+* the four bytes "MIT1"
+* a four-byte big-endian kvno value
+* an :rfc:`3961` ciphertext
+
+The ciphertext is encrypted in the cookie key with key usage
+number 513.  The cookie key is derived from a key in the local krbtgt
+principal entry for the realm (e.g. ``krbtgt/KRBTEST.COM@KRBTEST.COM``
+if the request is to the ``KRBTEST.COM`` realm).  The first krbtgt key
+for the indicated kvno value is combined with the client principal as
+follows::
+
+    cookie-key <- random-to-key(PRF+(tgt-key, "COOKIE" | client-princ))
+
+where **random-to-key** is the :rfc:`3961` random-to-key operation for
+the krbtgt key's encryption type, **PRF+** is defined in :rfc:`6113`,
+and ``|`` denotes concatenation.  *client-princ* is the request client
+principal name with realm, marshalled according to :rfc:`1964` section
+2.1.1.
+
+The plain text of the encrypted part of a cookie is the DER encoding
+of the following ASN.1 type::
+
+    SecureCookie ::= SEQUENCE {
+        time     INTEGER,
+        data     SEQUENCE OF PA-DATA,
+        ...
+    }
+
+The time field represents the cookie creation time; for brevity, it is
+encoded as an integer giving the POSIX timestamp rather than as an
+ASN.1 GeneralizedTime value.  The data field contains one element for
+each pre-authentication type which requires saved state.  For
+mechanisms which have separate request and reply types, the request
+type is used; this allows the KDC to determine whether a cookie is
+relevant to a request by comparing the request pa-data types to the
+cookie data types.