[28826] in CVS-changelog-for-Kerberos-V5

home help back first fref pref prev next nref lref last post

krb5 commit [krb5-1.13]: Add formats section to documentation

daemon@ATHENA.MIT.EDU (Tom Yu)
Mon Mar 2 17:32:57 2015

Date: Mon, 2 Mar 2015 17:32:52 -0500
From: Tom Yu <tlyu@mit.edu>
Message-Id: <201503022232.t22MWqHl015873@drugstore.mit.edu>
To: cvs-krb5@mit.edu
Reply-To: krbdev@mit.edu
MIME-Version: 1.0
Content-Type: text/plain; charset="us-ascii"
Content-Transfer-Encoding: 7bit
Errors-To: cvs-krb5-bounces@mit.edu

https://github.com/krb5/krb5/commit/37c02e7fc50a9633b639cbf3daeaeaf1c9c75724
commit 37c02e7fc50a9633b639cbf3daeaeaf1c9c75724
Author: Greg Hudson <ghudson@mit.edu>
Date:   Fri Feb 20 12:56:17 2015 -0500

    Add formats section to documentation
    
    Add a new "formats" section to the RST documentation and populate it
    with documentation of the credential cache and keytab file formats.
    
    (cherry picked from commit 68ac7ac1f1a1d2939a2c99fa49cecd734614d16d)
    
    ticket: 8149
    version_fixed: 1.13.2
    status: resolved

 doc/formats/ccache_file_format.rst |  176 ++++++++++++++++++++++++++++++++++++
 doc/formats/index.rst              |    8 ++
 doc/formats/keytab_file_format.rst |   51 +++++++++++
 doc/index.rst                      |    1 +
 src/doc/Makefile.in                |    1 +
 5 files changed, 237 insertions(+), 0 deletions(-)

diff --git a/doc/formats/ccache_file_format.rst b/doc/formats/ccache_file_format.rst
new file mode 100644
index 0000000..6349e0d
--- /dev/null
+++ b/doc/formats/ccache_file_format.rst
@@ -0,0 +1,176 @@
+.. _ccache_file_format:
+
+Credential cache file format
+============================
+
+There are four versions of the file format used by the FILE credential
+cache type.  The first byte of the file always has the value 5, and
+the value of the second byte contains the version number (1 through
+4).  Versions 1 and 2 of the file format use native byte order for integer
+representations.  Versions 3 and 4 always use big-endian byte order.
+
+After the two-byte version indicator, the file has three parts: the
+header (in version 4 only), the default principal name, and a sequence
+of credentials.
+
+
+Header format
+-------------
+
+The header appears only in format version 4.  It begins with a 16-bit
+integer giving the length of the entire header, followed by a sequence
+of fields.  Each field consists of a 16-bit tag, a 16-bit length, and
+a value of the given length.  A file format implementation should
+ignore fields with unknown tags.
+
+At this time there is only one defined header field.  Its tag value is
+1, its length is always 8, and its contents are two 32-bit integers
+giving the seconds and microseconds of the time offset of the KDC
+relative to the client.  Adding this offset to the current time on the
+client should give the current time on the KDC, if that offset has not
+changed since the initial authentication.
+
+
+.. _cache_principal_format:
+
+Principal format
+----------------
+
+The default principal is marshalled using the following informal
+grammar::
+
+    principal ::=
+        name type (32 bits) [omitted in version 1]
+        count of components (32 bits) [includes realm in version 1]
+        realm (data)
+        component1 (data)
+        component2 (data)
+        ...
+
+    data ::=
+        length (32 bits)
+        value (length bytes)
+
+There is no external framing on the default principal, so it must be
+parsed according to the above grammar in order to find the sequence of
+credentials which follows.
+
+
+.. _ccache_credential_format:
+
+Credential format
+-----------------
+
+The credential format uses the following informal grammar (referencing
+the ``principal`` and ``data`` types from the previous section)::
+
+    credential ::=
+        client (principal)
+        server (principal)
+        keyblock (keyblock)
+        authtime (32 bits)
+        starttime (32 bits)
+        endtime (32 bits)
+        renew_till (32 bits)
+        is_skey (1 byte, 0 or 1)
+        ticket_flags (32 bits)
+        addresses (addresses)
+        authdata (authdata)
+        ticket (data)
+        second_ticket (data)
+
+    keyblock ::=
+        enctype (16 bits) [repeated twice in version 3]
+        data
+
+    addresses ::=
+        count (32 bits)
+        address1
+        address2
+        ...
+
+    address ::=
+        addrtype (16 bits)
+        data
+
+    authdata ::=
+        count (32 bits)
+        authdata1
+        authdata2
+        ...
+
+    authdata ::=
+        ad_type (16 bits)
+        data
+
+There is no external framing on a marshalled credential, so it must be
+parsed according to the above grammar in order to find the next
+credential.  There is also no count of credentials or marker at the
+end of the sequence of credentials; the sequence ends when the file
+ends.
+
+
+Credential cache configuration entries
+--------------------------------------
+
+Configuration entries are encoded as credential entries.  The client
+principal of the entry is the default principal of the cache.  The
+server principal has the realm ``X-CACHECONF:`` and two or three
+components, the first of which is ``krb5_ccache_conf_data``.  The
+server principal's second component is the configuration key.  The
+third component, if it exists, is a principal to which the
+configuration key is associated.  The configuration value is stored in
+the ticket field of the entry.  All other entry fields are zeroed.
+
+Programs using credential caches must be aware of configuration
+entries for several reasons:
+
+* A program which displays the contents of a cache should not
+  generally display configuration entries.
+
+* The ticket field of a configuration entry is not (usually) a valid
+  encoding of a Kerberos ticket.  An implementation must not treat the
+  cache file as malformed if it cannot decode the ticket field.
+
+* Configuration entries have an endtime field of 0 and might therefore
+  always be considered expired, but they should not be treated as
+  unimportant as a result.  For instance, a program which copies
+  credentials from one cache to another should not omit configuration
+  entries because of the endtime.
+
+The following configuration keys are currently used in MIT krb5:
+
+fast_avail
+    The presence of this key with a non-empty value indicates that the
+    KDC asserted support for FAST (see :rfc:`6113`) during the initial
+    authentication, using the negotiation method described in
+    :rfc:`6806` section 11.  This key is not associated with any
+    principal.
+
+pa_config_data
+    The value of this key contains a JSON object representation of
+    parameters remembered by the preauthentication mechanism used
+    during the initial authentication.  These parameters may be used
+    when refreshing credentials.  This key is associated with the
+    server principal of the initial authentication (usually the local
+    krbtgt principal of the client realm).
+
+pa_type
+    The value of this key is the ASCII decimal representation of the
+    preauth type number used during the initial authentication.  This
+    key is associated with the server principal of the initial
+    authentication.
+
+proxy_impersonator
+    The presence of this key indicates that the cache is a synthetic
+    delegated credential for use with S4U2Proxy.  The value is the
+    name of the intermediate service whose TGT can be used to make
+    S4U2Proxy requests for target services.  This key is not
+    associated with any principal.
+
+refresh_time
+    The presence of this key indicates that the cache was acquired by
+    the GSS mechanism using a client keytab.  The value is the ASCII
+    decimal representation of a timestamp at which the GSS mechanism
+    should attempt to refresh the credential cache from the client
+    keytab.
diff --git a/doc/formats/index.rst b/doc/formats/index.rst
new file mode 100644
index 0000000..d1681fb
--- /dev/null
+++ b/doc/formats/index.rst
@@ -0,0 +1,8 @@
+Protocols and file formats
+==========================
+
+.. toctree::
+   :maxdepth: 1
+
+   ccache_file_format
+   keytab_file_format
diff --git a/doc/formats/keytab_file_format.rst b/doc/formats/keytab_file_format.rst
new file mode 100644
index 0000000..10caf95
--- /dev/null
+++ b/doc/formats/keytab_file_format.rst
@@ -0,0 +1,51 @@
+.. _keytab_file_format:
+
+Keytab file format
+==================
+
+There are two versions of the file format used by the FILE keytab
+type.  The first byte of the file always has the value 5, and the
+value of the second byte contains the version number (1 or 2).
+Version 1 of the file format uses native byte order for integer
+representations.  Version 2 always uses big-endian byte order.
+
+After the two-byte version indicator, the file contains a sequence of
+signed 32-bit record lengths followed by key records or holes.  A
+positive record length indicates a valid key entry whose size is equal
+to or less than the record length.  A negative length indicates a
+zero-filled hole whose size is the inverse of the length.  A length of
+0 indicates the end of the file.
+
+
+Key entry format
+----------------
+
+A key entry may be smaller in size than the record length which
+precedes it, because it may have replaced a hole which is larger than
+the key entry.  Key entries use the following informal grammar::
+
+    entry ::=
+        principal
+        timestamp (32 bits)
+        key version (8 bits)
+        enctype (16 bits)
+        key length (32 bits)
+        key contents
+
+    principal ::=
+        count of components (32 bits) [includes realm in version 1]
+        realm (data)
+        component1 (data)
+        component2 (data)
+        ...
+        name type (32 bits) [omitted in version 1]
+
+    data ::=
+        length (16 bits)
+        value (length bytes)
+
+Some implementations of Kerberos recognize a 32-bit key version at the
+end of an entry, if the record length is at least 4 bytes longer than
+the entry and the value of those 32 bits is not 0.  If present, this
+key version supersedes the 8-bit key version.  MIT krb5 does not yet
+implement this extension.
diff --git a/doc/index.rst b/doc/index.rst
index 5c308da..543a9d1 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -11,6 +11,7 @@ MIT Kerberos Documentation (|release|)
    plugindev/index.rst
    build/index.rst
    basic/index.rst
+   formats/index.rst
    mitK5features.rst
    build_this.rst
    about.rst
diff --git a/src/doc/Makefile.in b/src/doc/Makefile.in
index b07e16a..0963a8f 100644
--- a/src/doc/Makefile.in
+++ b/src/doc/Makefile.in
@@ -21,6 +21,7 @@ RST_SOURCES= _static \
 	appdev \
 	basic \
 	build \
+	formats \
 	plugindev \
 	user \
 	about.rst \
_______________________________________________
cvs-krb5 mailing list
cvs-krb5@mit.edu
https://mailman.mit.edu/mailman/listinfo/cvs-krb5

home help back first fref pref prev next nref lref last post