From 752574e288c8322001d1b4e62f5fd99c579a3403 Mon Sep 17 00:00:00 2001
From: Greg Hudson <ghudson@mit.edu>
Date: Sun, 16 Aug 2015 00:30:46 -0400
Subject: [PATCH] Document secure cookie format and callbacks

In kdcpreauth.rst, describe the set_cookie and get_cookie callbacks
and explain how to generate a KDC_ERR_MORE_PREAUTH_DATA_REQUIRED error
for multi-round-trip mechanisms.  Add a new file formats/cookie.rst
documenting the secure cookie format.

ticket: 8233
---
 doc/formats/cookie.rst       | 60 ++++++++++++++++++++++++++++++++++++
 doc/formats/index.rst        |  1 +
 doc/plugindev/kdcpreauth.rst | 14 +++++++++
 3 files changed, 75 insertions(+)
 create mode 100644 doc/formats/cookie.rst

diff --git a/doc/formats/cookie.rst b/doc/formats/cookie.rst
new file mode 100644
index 0000000000..640955c90b
--- /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.
diff --git a/doc/formats/index.rst b/doc/formats/index.rst
index d1681fb6d2..8b30626d4b 100644
--- a/doc/formats/index.rst
+++ b/doc/formats/index.rst
@@ -6,3 +6,4 @@ Protocols and file formats
 
    ccache_file_format
    keytab_file_format
+   cookie
diff --git a/doc/plugindev/kdcpreauth.rst b/doc/plugindev/kdcpreauth.rst
index 99696fa695..ab7f3a9022 100644
--- a/doc/plugindev/kdcpreauth.rst
+++ b/doc/plugindev/kdcpreauth.rst
@@ -55,6 +55,20 @@ client's database entry, and the client's database entry itself.  The
 be included in the issued ticket using the ``add_auth_indicator``
 callback (new in release 1.14).
 
+A module can generate state information to be included with the next
+client request using the ``set_cookie`` callback (new in release
+1.14).  On the next request, the module can read this state
+information using the ``get_cookie`` callback.  Cookie information is
+encrypted, timestamped, and transmitted to the client in a
+``PA-FX-COOKIE`` pa-data item.  Older clients may not support cookies
+and therefore may not transmit the cookie in the next request; in this
+case, ``get_cookie`` will not yield the saved information.
+
+If a module implements a mechanism which requires multiple round
+trips, its **verify** method can respond with the code
+``KRB5KDC_ERR_MORE_PREAUTH_DATA_REQUIRED`` and a list of pa-data in
+the *e_data* parameter to be processed by the client.
+
 The **edata** and **verify** methods can be implemented
 asynchronously.  Because of this, they do not return values directly
 to the caller, but must instead invoke responder functions with their
-- 
2.47.2