krb5 commit [krb5-1.13]: Add formats section to documentation
Tom Yu
tlyu at mit.edu
Mon Mar 2 17:32:52 EST 2015
https://github.com/krb5/krb5/commit/37c02e7fc50a9633b639cbf3daeaeaf1c9c75724
commit 37c02e7fc50a9633b639cbf3daeaeaf1c9c75724
Author: Greg Hudson <ghudson at 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 \
More information about the cvs-krb5
mailing list