Add submodule dependency filesHEADmaster

Change-Id: Iaf8d18082d3991dec7c0ebbea540f092188eb4ec

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.