Skip to content

Commit

Permalink
Browse files Browse the repository at this point in the history
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
  • Loading branch information
greghudson committed Feb 27, 2015
1 parent fcc1076 commit 68ac7ac
Show file tree
Hide file tree
Showing 5 changed files with 237 additions and 0 deletions.
176 changes: 176 additions & 0 deletions 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.
8 changes: 8 additions & 0 deletions doc/formats/index.rst
@@ -0,0 +1,8 @@
Protocols and file formats
==========================

.. toctree::
:maxdepth: 1

ccache_file_format
keytab_file_format
51 changes: 51 additions & 0 deletions 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.
1 change: 1 addition & 0 deletions doc/index.rst
Expand Up @@ -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
Expand Down
1 change: 1 addition & 0 deletions src/doc/Makefile.in
Expand Up @@ -21,6 +21,7 @@ RST_SOURCES= _static \
appdev \
basic \
build \
formats \
plugindev \
user \
about.rst \
Expand Down

0 comments on commit 68ac7ac

Please sign in to comment.