diff options
Diffstat (limited to 'roms/edk2/CryptoPkg/Library/OpensslLib/openssl/krb5/doc/formats')
5 files changed, 353 insertions, 0 deletions
diff --git a/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/krb5/doc/formats/ccache_file_format.rst b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/krb5/doc/formats/ccache_file_format.rst new file mode 100644 index 000000000..6349e0d29 --- /dev/null +++ b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/krb5/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/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/krb5/doc/formats/cookie.rst b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/krb5/doc/formats/cookie.rst new file mode 100644 index 000000000..e32365daa --- /dev/null +++ b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/krb5/doc/formats/cookie.rst @@ -0,0 +1,97 @@ +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/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/krb5/doc/formats/freshness_token.rst b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/krb5/doc/formats/freshness_token.rst new file mode 100644 index 000000000..3127621a9 --- /dev/null +++ b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/krb5/doc/formats/freshness_token.rst @@ -0,0 +1,19 @@ +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/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/krb5/doc/formats/index.rst b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/krb5/doc/formats/index.rst new file mode 100644 index 000000000..4ad534424 --- /dev/null +++ b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/krb5/doc/formats/index.rst @@ -0,0 +1,10 @@ +Protocols and file formats +========================== + +.. toctree:: + :maxdepth: 1 + + ccache_file_format + keytab_file_format + cookie + freshness_token diff --git a/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/krb5/doc/formats/keytab_file_format.rst b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/krb5/doc/formats/keytab_file_format.rst new file mode 100644 index 000000000..8424d058f --- /dev/null +++ b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/krb5/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 (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. |