stefanberger / libtpms / #2037

// SPDX-License-Identifier: BSD-2-Clause

//** Description

//

// This file contains implementation of cryptographic functions for hashing.

//

//** Includes, Defines, and Types

#define _CRYPT_HASH_C_

#include "Tpm.h"

#include "CryptHash_fp.h"

#include "CryptHash.h"

#include "OIDs.h"

#if USE_OPENSSL_FUNCTIONS_SSKDF

# include "Helpers_fp.h"

# include <openssl/kdf.h>

# include <openssl/core_names.h>

#endif

// Instance each of the hash descriptors based on the implemented algorithms

FOR_EACH_HASH(HASH_DEF_TEMPLATE)

// Instance a 'null' def.

HASH_DEF NULL_Def = {{0}};

// Create a table of pointers to the defined hash definitions

#define HASH_DEF_ENTRY(HASH, Hash) &Hash##_Def,

PHASH_DEF HashDefArray[] = {

    // for each implemented HASH, expands to: &HASH_Def,

    FOR_EACH_HASH(HASH_DEF_ENTRY) & NULL_Def};

#undef HASH_DEF_ENTRY

//** Obligatory Initialization Functions

//*** CryptHashInit()

// This function is called by _TPM_Init do perform the initialization operations for

// the library.

{

}

//*** CryptHashStartup()

// This function is called by TPM2_Startup(). It checks that the size of the

// HashDefArray is consistent with the HASH_COUNT.

{

}

//** Hash Information Access Functions

//*** Introduction

// These functions provide access to the hash algorithm description information.

//*** CryptGetHashDef()

// This function accesses the hash descriptor associated with a hash a

// algorithm. The function returns a pointer to a 'null' descriptor if hashAlg is

// TPM_ALG_NULL or not a defined algorithm.

PHASH_DEF

{

#define GET_DEF(HASH, Hash)  \

    case ALG_##HASH##_VALUE: \

        return &Hash##_Def;

    {

    }

#undef GET_DEF

}

//*** CryptHashIsValidAlg()

// This function tests to see if an algorithm ID is a valid hash algorithm. If

// flag is true, then TPM_ALG_NULL is a valid hash.

//  Return Type: BOOL

//      TRUE(1)         hashAlg is a valid, implemented hash on this TPM

//      FALSE(0)        hashAlg is not valid for this TPM

    TPM_ALG_ID hashAlg,        // IN: the algorithm to check

    BOOL       isAlgNullValid  // IN: TRUE if TPM_ALG_NULL is to be treated

                               //     as a valid hash

)

{

        return isAlgNullValid;

}

//*** CryptHashGetAlgByIndex()

// This function is used to iterate through the hashes. TPM_ALG_NULL

// is returned for all indexes that are not valid hashes.

// If the TPM implements 3 hashes, then an 'index' value of 0 will

// return the first implemented hash and an 'index' of 2 will return the

// last. All other index values will return TPM_ALG_NULL.

//

//  Return Type: TPM_ALG_ID

// TPM_ALG_xxx         a hash algorithm

// TPM_ALG_NULL        this can be used as a stop value

)

{

        hashAlg = TPM_ALG_NULL;

    else

}

//*** CryptHashGetDigestSize()

// Returns the size of the digest produced by the hash. If 'hashAlg' is not a hash

// algorithm, the TPM will FAIL.

//  Return Type: UINT16

//   0       TPM_ALG_NULL

//   > 0     the digest size

//

    TPM_ALG_ID hashAlg  // IN: hash algorithm to look up

)

{

}

//*** CryptHashGetBlockSize()

// Returns the size of the block used by the hash. If 'hashAlg' is not a hash

// algorithm, the TPM will FAIL.

//  Return Type: UINT16

//   0       TPM_ALG_NULL

//   > 0     the digest size

//

    TPM_ALG_ID hashAlg  // IN: hash algorithm to look up

)

{

}

#if 0                // libtpms added

//*** CryptHashGetOid()

// This function returns a pointer to DER=encoded OID for a hash algorithm. All OIDs

// are full OID values including the Tag (0x06) and length byte.

LIB_EXPORT const BYTE* CryptHashGetOid(TPM_ALG_ID hashAlg)

{

    return CryptGetHashDef(hashAlg)->OID;

}

#endif                // libtpms added

#if 0                // libtpms added

//***  CryptHashGetContextAlg()

// This function returns the hash algorithm associated with a hash context.

TPM_ALG_ID

CryptHashGetContextAlg(PHASH_STATE state  // IN: the context to check

)

{

    return state->hashAlg;

}

#endif                // libtpms added

#if 0 // libtpms added

//** State Import and Export

//*** CryptHashCopyState

// This function is used to clone a HASH_STATE.

LIB_EXPORT void CryptHashCopyState(HASH_STATE* out,  // OUT: destination of the state

                                   const HASH_STATE* in  // IN: source of the state

)

{

    pAssert(out->type == in->type);

    out->hashAlg = in->hashAlg;

    out->def     = in->def;

    if(in->hashAlg != TPM_ALG_NULL)

    {

        HASH_STATE_COPY(out, in);

    }

    if(in->type == HASH_STATE_HMAC)

    {

        const HMAC_STATE* hIn  = (HMAC_STATE*)in;

        HMAC_STATE*       hOut = (HMAC_STATE*)out;

        hOut->hmacKey          = hIn->hmacKey;

    }

    return;

}

#endif // libtpms added

#if 0  // libtpms added

//*** CryptHashExportState()

// This function is used to export a hash or HMAC hash state. This function

// would be called when preparing to context save a sequence object.

void CryptHashExportState(

    PCHASH_STATE internalFmt,       // IN: the hash state formatted for use by

                                    //     library

    PEXPORT_HASH_STATE externalFmt  // OUT: the exported hash state

)

{

    BYTE* outBuf = (BYTE*)externalFmt;

    //

    MUST_BE(sizeof(HASH_STATE) <= sizeof(EXPORT_HASH_STATE));

    // the following #define is used to move data from an aligned internal data

    // structure to a byte buffer (external format data.

#define CopyToOffset(value)                      \

    memcpy(&outBuf[offsetof(HASH_STATE, value)], \

           &internalFmt->value,                  \

           sizeof(internalFmt->value))

    // Copy the hashAlg

    CopyToOffset(hashAlg);

    CopyToOffset(type);

#ifdef HASH_STATE_SMAC

    if(internalFmt->type == HASH_STATE_SMAC)

    {

        memcpy(outBuf, internalFmt, sizeof(HASH_STATE));

        return;

    }

#endif

    if(internalFmt->type == HASH_STATE_HMAC)

    {

        HMAC_STATE* from = (HMAC_STATE*)internalFmt;

        memcpy(&outBuf[offsetof(HMAC_STATE, hmacKey)],

               &from->hmacKey,

               sizeof(from->hmacKey));

    }

    if(internalFmt->hashAlg != TPM_ALG_NULL)

        HASH_STATE_EXPORT(externalFmt, internalFmt);

}

//*** CryptHashImportState()

// This function is used to import the hash state. This function

// would be called to import a hash state when the context of a sequence object

// was being loaded.

void CryptHashImportState(

    PHASH_STATE internalFmt,         // OUT: the hash state formatted for use by

                                     //     the library

    PCEXPORT_HASH_STATE externalFmt  // IN: the exported hash state

)

{

    BYTE* inBuf = (BYTE*)externalFmt;

//

#define CopyFromOffset(value)                   \

    memcpy(&internalFmt->value,                 \

           &inBuf[offsetof(HASH_STATE, value)], \

           sizeof(internalFmt->value))

    // Copy the hashAlg of the byte-aligned input structure to the structure-aligned

    // internal structure.

    CopyFromOffset(hashAlg);

    CopyFromOffset(type);

    if(internalFmt->hashAlg != TPM_ALG_NULL)

    {

#ifdef HASH_STATE_SMAC

        if(internalFmt->type == HASH_STATE_SMAC)

        {

            memcpy(internalFmt, inBuf, sizeof(HASH_STATE));

            return;

        }

#endif

        internalFmt->def = CryptGetHashDef(internalFmt->hashAlg);

        HASH_STATE_IMPORT(internalFmt, inBuf);

        if(internalFmt->type == HASH_STATE_HMAC)

        {

            HMAC_STATE* to = (HMAC_STATE*)internalFmt;

            memcpy(&to->hmacKey,

                   &inBuf[offsetof(HMAC_STATE, hmacKey)],

                   sizeof(to->hmacKey));

        }

    }

}

#endif  // libtpms added

//** State Modification Functions

//***HashEnd()

// Local function to complete a hash that uses the hashDef instead of an algorithm

// ID. This function is used to complete the hash and only return a partial digest.

// The return value is the size of the data copied.

                      UINT32      dOutSize,   // IN: the size of receive buffer

                      PBYTE       dOut        // OUT: the receive buffer

)

{

        dOutSize = 0;

    {

        // Set the final size

        // Complete into the temp buffer and then copy

        // Don't want any other functions calling the HASH_END method

        // directly.

#undef HASH_END

    }

}

//*** CryptHashStart()

// Functions starts a hash stack

// Start a hash stack and returns the digest size. As a side effect, the

// value of 'stateSize' in hashState is updated to indicate the number of bytes

// of state that were saved. This function calls GetHashServer() and that function

// will put the TPM into failure mode if the hash algorithm is not supported.

//

// This function does not use the sequence parameter. If it is necessary to import

// or export context, this will start the sequence in a local state

// and export the state to the input buffer. Will need to add a flag to the state

// structure to indicate that it needs to be imported before it can be used.

// (BLEH).

//  Return Type: UINT16

//  0           hash is TPM_ALG_NULL

// >0           digest size

    PHASH_STATE hashState,  // OUT: the running hash state

    TPM_ALG_ID  hashAlg     // IN: hash algorithm

)

{

    {

        retVal = 0;

    }

    else

    {

    }

#undef HASH_START

}

//*** CryptDigestUpdate()

// Add data to a hash or HMAC, SMAC stack.

//

                       UINT32      dataSize,   // IN: the size of data to be added

                       const BYTE* data        // IN: data to be hashed

)

{

    {

#if SMAC_IMPLEMENTED

#endif  // SMAC_IMPLEMENTED

        else

        {

            // this void assert is OK because these values only indicate the

            // intention of the hash, but don't actually affect the hash

            // calculation or buffer size calculations.  IOW, the failure

            // set here can safely percolate out and be checked at a higher

            // level.

        }

    }

}

//*** CryptHashEnd()

// Complete a hash or HMAC computation. This function will place the smaller of

// 'digestSize' or the size of the digest in 'dOut'. The number of bytes in the

// placed in the buffer is returned. If there is a failure, the returned value

// is <= 0.

//  Return Type: UINT16

//       0      no data returned

//      > 0     the number of bytes in the digest or dOutSize, whichever is smaller

                               UINT32      dOutSize,   // IN: size of digest buffer

                               BYTE*       dOut        // OUT: hash digest

)

{

}

//*** CryptHashBlock()

// Start a hash, hash a single block, update 'digest' and return the size of

// the results.

//

// The 'digestSize' parameter can be smaller than the digest. If so, only the more

// significant bytes are returned.

//  Return Type: UINT16

//  >= 0        number of bytes placed in 'dOut'

                                 UINT32      dataSize,  // IN: size of buffer to hash

                                 const BYTE* data,      // IN: the buffer to hash

                                 UINT32 dOutSize,  // IN: size of the digest buffer

                                 BYTE*  dOut       // OUT: digest buffer

)

{

}

//*** CryptDigestUpdate2B()

// This function updates a digest (hash or HMAC) with a TPM2B.

//

// This function can be used for both HMAC and hash functions so the

// 'digestState' is void so that either state type can be passed.

                                    const TPM2B* bIn     // IN: 2B containing the data

)

{

    // Only compute the digest if a pointer to the 2B is provided.

    // In CryptDigestUpdate(), if size is zero or buffer is NULL, then no change

    // to the digest occurs. This function should not provide a buffer if bIn is

    // not provided.

    // as indicated by the comment above CryptDigestUpdate is tolerant of null, but

    // we don't expect a null pointer here, so simply return but trigger failure

    // mode because this is an unexpected internal programming error.

}

//*** CryptHashEnd2B()

// This function is the same as CryptCompleteHash() but the digest is

// placed in a TPM2B. This is the most common use and this is provided

// for specification clarity. 'digest.size' should be set to indicate the number of

// bytes to place in the buffer

//  Return Type: UINT16

//      >=0     the number of bytes placed in 'digest.buffer'

    PHASH_STATE state,  // IN: the hash state

    P2B         digest  // IN: the size of the buffer Out: requested

                        //     number of bytes

)

{

}

//*** CryptDigestUpdateInt()

// This function is used to include an integer value to a hash stack. The function

// marshals the integer into its canonical form before calling CryptDigestUpdate().

    void*  state,    // IN: the state of hash stack

    UINT32 intSize,  // IN: the size of 'intValue' in bytes

    UINT64 intValue  // IN: integer value to be hashed

)

{

#if LITTLE_ENDIAN_TPM

#endif

//** HMAC Functions

//*** CryptHmacStart()

// This function is used to start an HMAC using a temp

// hash context. The function does the initialization

// of the hash with the HMAC key XOR iPad and updates the

// HMAC key XOR oPad.

//

// The function returns the number of bytes in a digest produced by 'hashAlg'.

//  Return Type: UINT16

//  >= 0        number of bytes in digest produced by 'hashAlg' (may be zero)

//

                                 TPM_ALG_ID  hashAlg,  // IN: the algorithm to use

                                 UINT16      keySize,  // IN: the size of the HMAC key

                                 const BYTE* key       // IN: the HMAC key

)

{

    //

    {

        // If the HMAC key is larger than the hash block size, it has to be reduced

        // to fit. The reduction is a digest of the hashKey.

        {

            // if the key is too big, reduce it to a digest of itself

        }

        else

        {

        }

        // XOR the key with iPad (0x36)

        // if the keySize is smaller than a block, fill the rest with 0x36

        // Increase the oPadSize to a full block

        // Start a new hash with the HMAC key

        // This will go in the caller's state structure and may be a sequence or not

        // XOR the key block with 0x5c ^ 0x36

    }

    // Set the hash algorithm

    // Set the hash state type

}

//*** CryptHmacEnd()

// This function is called to complete an HMAC. It will finish the current

// digest, and start a new digest. It will then add the oPadKey and the

// completed digest and return the results in dOut. It will not return more

// than dOutSize bytes.

//  Return Type: UINT16

//  >= 0        number of bytes in 'dOut' (may be zero)

                               UINT32      dOutSize,  // IN: size of digest buffer

                               BYTE*       dOut       // OUT: hash digest

)

{

#if SMAC_IMPLEMENTED

#endif

    // Change the state type for completion processing

        dOutSize = 0;

    else

    {

        // Complete the current hash

        // Do another hash starting with the oPad

    }

}

//*** CryptHmacStart2B()

// This function starts an HMAC and returns the size of the digest

// that will be produced.

//

// This function is provided to support the most common use of starting an HMAC

// with a TPM2B key.

//

// The caller must provide a block of memory in which the hash sequence state

// is kept.  The caller should not alter the contents of this buffer until the

// hash sequence is completed or abandoned.

//

//  Return Type: UINT16

//      > 0     the digest size of the algorithm

//      = 0     the hashAlg was TPM_ALG_NULL

    PHMAC_STATE hmacState,  // OUT: the state of HMAC stack. It will be used

                            //     in HMAC update and completion

    TPMI_ALG_HASH hashAlg,  // IN: hash algorithm

    P2B           key       // IN: HMAC key

)

{

}

//*** CryptHmacEnd2B()

//   This function is the same as CryptHmacEnd() but the HMAC result

//   is returned in a TPM2B which is the most common use.

//  Return Type: UINT16

//      >=0     the number of bytes placed in 'digest'

    PHMAC_STATE hmacState,  // IN: the state of HMAC stack

    P2B         digest      // OUT: HMAC

)

{

}

//** Mask and Key Generation Functions

//*** CryptMGF_KDF()

// This function performs MGF1/KDF1 or KDF2 using the selected hash. KDF1 and KDF2 are

// T('n') = T('n'-1) || H('seed' || 'counter') with the difference being that, with

// KDF1, 'counter' starts at 0 but with KDF2, 'counter' starts at 1. The caller

// determines which version by setting the initial value of counter to either 0 or 1.

// Note: Any value that is not 0 is considered to be 1.

//

// This function returns the length of the mask produced which

// could be zero if the digest algorithm is not supported

//  Return Type: UINT16

//      0       hash algorithm was TPM_ALG_NULL

//    > 0       should be the same as 'mSize'

                               BYTE*  mask,   // OUT: buffer to receive the mask

                               TPM_ALG_ID hashAlg,   // IN: hash to use

                               UINT32     seedSize,  // IN: size of the seed

                               BYTE*      seed,      // IN: seed size

                               UINT32     counter    // IN: counter initial value

)

{

    //

    // If there is no digest to compute return

        return 0;

    {

        // Start the hash and include the seed and counter

        // Get as much as will fit.

    }

}

//*** CryptKDFa()

// This function performs the key generation according to Part 1 of the

// TPM specification.

//

// This function returns the number of bytes generated which may be zero.

//

// The 'key' and 'keyStream' pointers are not allowed to be NULL. The other

// pointer values may be NULL. The value of 'sizeInBits' must be no larger

// than (2^18)-1 = 256K bits (32385 bytes).

//

// The 'once' parameter is set to allow incremental generation of a large

// value. If this flag is TRUE, 'sizeInBits' will be used in the HMAC computation

// but only one iteration of the KDF is performed. This would be used for

// XOR obfuscation so that the mask value can be generated in digest-sized

// chunks rather than having to be generated all at once in an arbitrarily

// large buffer and then XORed into the result. If 'once' is TRUE, then

// 'sizeInBits' must be a multiple of 8.

//

// Any error in the processing of this command is considered fatal.

//  Return Type: UINT16

//     0            hash algorithm is not supported or is TPM_ALG_NULL

//    > 0           the number of bytes in the 'keyStream' buffer

    TPM_ALG_ID   hashAlg,       // IN: hash algorithm used in HMAC

    const TPM2B* key,           // IN: HMAC key

    const TPM2B* label,         // IN: a label for the KDF

    const TPM2B* contextU,      // IN: context U

    const TPM2B* contextV,      // IN: context V

    UINT32       sizeInBits,    // IN: size of generated key in bits

    BYTE*        keyStream,     // OUT: key buffer

    UINT32*      counterInOut,  // IN/OUT: caller may provide the iteration

                                //     counter for incremental operations to

                                //     avoid large intermediate buffers.

    UINT16 blocks               // IN: If non-zero, this is the maximum number

                                //     of blocks to be returned, regardless

                                //     of sizeInBits

)

{

        return 0;

    // If the size of the request is larger than the numbers will handle,

    // it is a fatal error.

    // The number of bytes to be generated is the smaller of the sizeInBits bytes or

    // the number of requested blocks. The number of blocks is the smaller of the

    // number requested or the number allowed by sizeInBits. A partial block is

    // a full block.

    // Generate required bytes

    {

        // Start HMAC

            return 0;

        // Adding counter

        // Adding label

        // Add a null. SP108 is not very clear about when the 0 is needed but to

        // make this like the previous version that did not add an 0x00 after

        // a null-terminated string, this version will only add a null byte

        // if the label parameter did not end in a null byte, or if no label

        // is present.

        // Adding contextU

        // Adding contextV

        // Adding size in bits

        // Complete and put the data in the buffer

    }

    // Masking in the KDF is disabled. If the calling function wants something

    // less than even number of bytes, then the caller should do the masking

    // because there is no universal way to do it here

    return generated;

}

//*** CryptKDFe()

// This function implements KDFe() as defined in TPM specification part 1.

//

// This function returns the number of bytes generated which may be zero.

//

// The 'Z' and 'keyStream' pointers are not allowed to be NULL. The other

// pointer values may be NULL. The value of 'sizeInBits' must be no larger

// than (2^18)-1 = 256K bits (32385 bytes).

// Any error in the processing of this command is considered fatal.

//  Return Type: UINT16

//     0            hash algorithm is not supported or is TPM_ALG_NULL

//    > 0           the number of bytes in the 'keyStream' buffer

//

#if ! USE_OPENSSL_FUNCTIONS_SSKDF                // libtpms added

LIB_EXPORT UINT16 CryptKDFe(TPM_ALG_ID   hashAlg,  // IN: hash algorithm used in HMAC

                            TPM2B*       Z,        // IN: Z

                            const TPM2B* label,    // IN: a label value for the KDF

                            TPM2B*       partyUInfo,  // IN: PartyUInfo

                            TPM2B*       partyVInfo,  // IN: PartyVInfo

                            UINT32 sizeInBits,  // IN: size of generated key in bits

                            BYTE*  keyStream    // OUT: key buffer

)

{

    HASH_STATE hashState;

    PHASH_DEF  hashDef = CryptGetHashDef(hashAlg);

    UINT32     counter = 0;  // counter value

    UINT16     hLen;

    BYTE*      stream = keyStream;

    INT16      bytes;  // number of bytes to generate

    pAssert_ZERO(

        keyStream != NULL && Z != NULL && ((sizeInBits + 7) / 8) < INT16_MAX);

    //

    hLen  = hashDef->digestSize;

    bytes = (INT16)((sizeInBits + 7) / 8);

    if(hashAlg == TPM_ALG_NULL || bytes == 0)

        return 0;

    // Generate required bytes

    //The inner loop of that KDF uses:

    //  Hash[i] := H(counter | Z | OtherInfo) (5)

    // Where:

    //  Hash[i]         the hash generated on the i-th iteration of the loop.

    //  H()             an approved hash function

    //  counter         a 32-bit counter that is initialized to 1 and incremented

    //                  on each iteration

    //  Z               the X coordinate of the product of a public ECC key and a

    //                  different private ECC key.

    //  OtherInfo       a collection of qualifying data for the KDF defined below.

    //  In this specification, OtherInfo will be constructed by:

    //      OtherInfo := Use | PartyUInfo  | PartyVInfo

    for(; bytes > 0; stream = &stream[hLen], bytes = bytes - hLen)

    {

        if(bytes < hLen)

            hLen = bytes;

        counter++;

        // Do the hash

        CryptHashStart(&hashState, hashAlg);

        // Add counter

        CryptDigestUpdateInt(&hashState, 4, counter);

        // Add Z

        if(Z != NULL)

            CryptDigestUpdate2B(&hashState, Z);

        // Add label

        if(label != NULL)

            CryptDigestUpdate2B(&hashState, label);

        // NIST.SP.800-56Cr2.pdf section 4.1 states that no NULL

        // character is required here.

        // Note, this is different from KDFa which is specified in

        // NIST.SP.800-108r1.pdf section 4 (a NULL character is required

        // for that case).

        // Add PartyUInfo

        if(partyUInfo != NULL)

            CryptDigestUpdate2B(&hashState, partyUInfo);

        // Add PartyVInfo

        if(partyVInfo != NULL)

            CryptDigestUpdate2B(&hashState, partyVInfo);

        // Compute Hash. hLen was changed to be the smaller of bytes or hLen

        // at the start of each iteration.

        CryptHashEnd(&hashState, hLen, stream);

    }

    // Mask off bits if the required bits is not a multiple of byte size

    if((sizeInBits % 8) != 0)

        keyStream[0] &= ((1 << (sizeInBits % 8)) - 1);

    return (UINT16)((sizeInBits + 7) / 8);

}

#else // USE_OPENSSL_FUNCTIONS_SSKDF

                            TPM2B*       Z,        // IN: Z

                            const TPM2B* label,    // IN: a label value for the KDF

                            TPM2B*       partyUInfo,  // IN: PartyUInfo

                            TPM2B*       partyVInfo,  // IN: PartyVInfo

                            UINT32       sizeInBits,  // IN: size of generated key in bits

                            BYTE*        keyStream    // OUT: key buffer

                            )

{

                         sizeInBits, keyStream);

}

#endif //  USE_OPENSSL_FUNCTIONS_SSKDF