krb5 commit [krb5-1.12]: Add formats section to documentation
Tom Yu
tlyu at mit.edu
Tue May 12 15:45:59 EDT 2015
https://github.com/krb5/krb5/commit/adeec7bcf86bb2af15850d511598dcd83f6a603a
commit adeec7bcf86bb2af15850d511598dcd83f6a603a
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)
(cherry picked from commit 37c02e7fc50a9633b639cbf3daeaeaf1c9c75724)
ticket: 8181 (new)
version_fixed: 1.12.4
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 a6bb7c5..8006462 100644
--- a/src/doc/Makefile.in
+++ b/src/doc/Makefile.in
@@ -20,6 +20,7 @@ RST_SOURCES= _static \
appdev \
basic \
build \
+ formats \
plugindev \
user \
about.rst \
More information about the cvs-krb5
mailing list