Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
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
1 parent
fcc1076
commit 68ac7ac
Showing
5 changed files
with
237 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,8 @@ | ||
Protocols and file formats | ||
========================== | ||
|
||
.. toctree:: | ||
:maxdepth: 1 | ||
|
||
ccache_file_format | ||
keytab_file_format |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -21,6 +21,7 @@ RST_SOURCES= _static \ | |
appdev \ | ||
basic \ | ||
build \ | ||
formats \ | ||
plugindev \ | ||
user \ | ||
about.rst \ | ||
|