diff options
Diffstat (limited to 'crypto/krb5/doc/formats')
| -rw-r--r-- | crypto/krb5/doc/formats/ccache_file_format.rst | 182 | ||||
| -rw-r--r-- | crypto/krb5/doc/formats/cookie.rst | 97 | ||||
| -rw-r--r-- | crypto/krb5/doc/formats/freshness_token.rst | 19 | ||||
| -rw-r--r-- | crypto/krb5/doc/formats/index.rst | 11 | ||||
| -rw-r--r-- | crypto/krb5/doc/formats/keytab_file_format.rst | 51 | ||||
| -rw-r--r-- | crypto/krb5/doc/formats/rcache_file_format.rst | 50 |
6 files changed, 0 insertions, 410 deletions
diff --git a/crypto/krb5/doc/formats/ccache_file_format.rst b/crypto/krb5/doc/formats/ccache_file_format.rst deleted file mode 100644 index 6138c1b58cdf..000000000000 --- a/crypto/krb5/doc/formats/ccache_file_format.rst +++ /dev/null @@ -1,182 +0,0 @@ -.. _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. - -start_realm - This key indicates the realm of the ticket-granting ticket to be - used for TGS requests, when making a referrals request or - beginning a cross-realm request. If it is not present, the client - realm is used. diff --git a/crypto/krb5/doc/formats/cookie.rst b/crypto/krb5/doc/formats/cookie.rst deleted file mode 100644 index e32365daa6f2..000000000000 --- a/crypto/krb5/doc/formats/cookie.rst +++ /dev/null @@ -1,97 +0,0 @@ -KDC cookie format -================= - -:rfc:`6113` section 5.2 specifies a pa-data type PA-FX-COOKIE, which -clients are required to reflect back to the KDC during -pre-authentication. The MIT krb5 KDC uses the following formats for -cookies. - - -Trivial cookie (version 0) --------------------------- - -If there is no pre-authentication mechanism state information to save, -a trivial cookie containing the value "MIT" is used. A trivial cookie -is needed to indicate that the conversation can continue. - - -Secure cookie (version 1) -------------------------- - -In release 1.14 and later, a secure cookie can be sent if there is any -mechanism state to save for the next request. A secure cookie -contains the concatenation of the following: - -* the four bytes "MIT1" -* a four-byte big-endian kvno value -* an :rfc:`3961` ciphertext - -The ciphertext is encrypted in the cookie key with key usage -number 513. The cookie key is derived from a key in the local krbtgt -principal entry for the realm (e.g. ``krbtgt/KRBTEST.COM@KRBTEST.COM`` -if the request is to the ``KRBTEST.COM`` realm). The first krbtgt key -for the indicated kvno value is combined with the client principal as -follows:: - - cookie-key <- random-to-key(PRF+(tgt-key, "COOKIE" | client-princ)) - -where **random-to-key** is the :rfc:`3961` random-to-key operation for -the krbtgt key's encryption type, **PRF+** is defined in :rfc:`6113`, -and ``|`` denotes concatenation. *client-princ* is the request client -principal name with realm, marshalled according to :rfc:`1964` section -2.1.1. - -The plain text of the encrypted part of a cookie is the DER encoding -of the following ASN.1 type:: - - SecureCookie ::= SEQUENCE { - time INTEGER, - data SEQUENCE OF PA-DATA, - ... - } - -The time field represents the cookie creation time; for brevity, it is -encoded as an integer giving the POSIX timestamp rather than as an -ASN.1 GeneralizedTime value. The data field contains one element for -each pre-authentication type which requires saved state. For -mechanisms which have separate request and reply types, the request -type is used; this allows the KDC to determine whether a cookie is -relevant to a request by comparing the request pa-data types to the -cookie data types. - -SPAKE cookie format (version 1) -------------------------------- - -Inside the SecureCookie wrapper, a data value of type 151 contains -state for SPAKE pre-authentication. This data is the concatenation of -the following: - -* a two-byte big-endian version number with the value 1 -* a two-byte big-endian stage number -* a four-byte big-endian group number -* a four-byte big-endian length and data for the SPAKE value -* a four-byte big-endian length and data for the transcript hash -* zero or more second factor records, each consisting of: - - a four-byte big-endian second-factor type - - a four-byte big-endian length and data - -The stage value is 0 if the cookie was sent with a challenge message. -Otherwise it is 1 for the first encdata message sent by the KDC during -an exchange, 2 for the second, etc.. - -The group value indicates the group number used in the SPAKE challenge. - -For a stage-0 cookie, the SPAKE value is the KDC private key, -represented in the scalar marshalling form of the group. For other -cookies, the SPAKE value is the SPAKE result K, represented in the -group element marshalling form. - -For a stage-0 cookie, the transcript hash is the intermediate hash -after updating with the client support message (if one was sent) and -challenge. For other cookies it is the final hash. - -For a stage-0 cookie, there may be any number of second-factor -records, including none; a second-factor type need not create a state -field if it does not need one, and no record is created for SF-NONE. -For other cookies, there must be exactly one second-factor record -corresponding to the factor type chosen by the client. diff --git a/crypto/krb5/doc/formats/freshness_token.rst b/crypto/krb5/doc/formats/freshness_token.rst deleted file mode 100644 index 3127621a9f0b..000000000000 --- a/crypto/krb5/doc/formats/freshness_token.rst +++ /dev/null @@ -1,19 +0,0 @@ -PKINIT freshness tokens -======================= - -:rfc:`8070` specifies a pa-data type PA_AS_FRESHNESS, which clients -should reflect within signed PKINIT data to prove recent access to the -client certificate private key. The contents of a freshness token are -left to the KDC implementation. The MIT krb5 KDC uses the following -format for freshness tokens (starting in release 1.17): - -* a four-byte big-endian POSIX timestamp -* a four-byte big-endian key version number -* an :rfc:`3961` checksum, with no ASN.1 wrapper - -The checksum is computed using the first key in the local krbtgt -principal entry for the realm (e.g. ``krbtgt/KRBTEST.COM@KRBTEST.COM`` -if the request is to the ``KRBTEST.COM`` realm) of the indicated key -version. The checksum type must be the mandatory checksum type for -the encryption type of the krbtgt key. The key usage value for the -checksum is 514. diff --git a/crypto/krb5/doc/formats/index.rst b/crypto/krb5/doc/formats/index.rst deleted file mode 100644 index 47dea12fcf6b..000000000000 --- a/crypto/krb5/doc/formats/index.rst +++ /dev/null @@ -1,11 +0,0 @@ -Protocols and file formats -========================== - -.. toctree:: - :maxdepth: 1 - - ccache_file_format - keytab_file_format - rcache_file_format - cookie - freshness_token diff --git a/crypto/krb5/doc/formats/keytab_file_format.rst b/crypto/krb5/doc/formats/keytab_file_format.rst deleted file mode 100644 index 8424d058ff46..000000000000 --- a/crypto/krb5/doc/formats/keytab_file_format.rst +++ /dev/null @@ -1,51 +0,0 @@ -.. _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 (16 bits) - key contents - key version (32 bits) [in release 1.14 and later] - - principal ::= - count of components (16 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) - -The 32-bit key version overrides the 8-bit key version. To determine -if it is present, the implementation must check that at least 4 bytes -remain in the record after the other fields are read, and that the -value of the 32-bit integer contained in those bytes is non-zero. diff --git a/crypto/krb5/doc/formats/rcache_file_format.rst b/crypto/krb5/doc/formats/rcache_file_format.rst deleted file mode 100644 index 42ee82817ac1..000000000000 --- a/crypto/krb5/doc/formats/rcache_file_format.rst +++ /dev/null @@ -1,50 +0,0 @@ -Replay cache file format -======================== - -This section documents the second version of the replay cache file -format, used by the "file2" replay cache type (new in release 1.18). -The first version of the file replay cache format is not documented. - -All accesses to the replay cache file take place under an exclusive -POSIX or Windows file lock, obtained when the file is opened and -released when it is closed. Replay cache files are automatically -created when first accessed. - -For each store operation, a tag is derived from the checksum part of -the :RFC:`3961` ciphertext of the authenticator. The checksum is -coerced to a fixed length of 12 bytes, either through truncation or -right-padding with zero bytes. A four-byte timestamp is appended to -the tag to produce a total record length of 16 bytes. - -Bytes 0 through 15 of the file contain a hash seed for the SipHash-2-4 -algorithm (siphash_); this field is populated with random bytes when -the file is first created. All remaining bytes are divided into a -series of expanding hash tables: - -* Bytes 16-16383: hash table 1 (1023 slots) -* Bytes 16384-49151: hash table 2 (2048 slots) -* Bytes 49152-114687: hash table 3 (4096 slots) -* ... - -Only some hash tables will be present in the file at any specific -time, and the final table may be only partially filled. Replay cache -files may be sparse if the filesystem supports it. - -For each table present in the file, the tag is hashed with SipHash-2-4 -using the seed recorded in the file. The first byte of the seed is -incremented by one (modulo 256) for each table after the first. The -resulting hash value is taken modulo one less than the table size -(1022 for the first hash table, 2047 for the second) to produce the -index. The record may be found at the slot given by the index or at -the next slot. - -All candidate locations for the record must be searched until a slot -is found with a timestamp of zero (indicating a slot which has never -been written to) or an offset is reached at or beyond the end of the -file. Any candidate location with a timestamp value of zero, with a -timestamp value less than the current time minus clockskew, or at or -beyond the end of the file is available for writing. When all -candidate locations have been searched without finding a match, the -new entry is written to the earliest candidate available for writing. - -.. _siphash: https://131002.net/siphash/siphash.pdf |