krb5 commit: Document secure cookie format and callbacks

[Greg Hudson]

https://github.com/krb5/krb5/commit/752574e288c8322001d1b4e62f5fd99c579a3403
commit 752574e288c8322001d1b4e62f5fd99c579a3403
Author: Greg Hudson <ghudson at mit.edu>
Date:   Sun Aug 16 00:30:46 2015 -0400

    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(+), 0 deletions(-)

diff --git a/doc/formats/cookie.rst b/doc/formats/cookie.rst
new file mode 100644
index 0000000..640955c
--- /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 at 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 d1681fb..8b30626 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 99696fa..ab7f3a9 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