From: Greg Hudson Date: Fri, 20 Feb 2015 17:56:17 +0000 (-0500) Subject: Add formats section to documentation X-Git-Tag: krb5-1.14-alpha1~159 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=68ac7ac1f1a1d2939a2c99fa49cecd734614d16d;p=thirdparty%2Fkrb5.git 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. ticket: 8149 (new) target_version: 1.13.2 tags: pullup --- diff --git a/doc/formats/ccache_file_format.rst b/doc/formats/ccache_file_format.rst new file mode 100644 index 0000000000..6349e0d294 --- /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 0000000000..d1681fb6d2 --- /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 0000000000..10caf95124 --- /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 5c308da039..543a9d1b56 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 b07e16a672..0963a8f7d4 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 \