path: root/base/symkey/src/com/netscape/symkey/NistSP800_108KDF.cpp

/*
 * NistSP800_108KDF.cpp - Implements the new Key Diversification Function (KDF) as required
 *                        by the latest Department of Defense SIPRnet token interface
 *                        specification.  The functions in this file are internally called
 *                        by other functions in the Symkey library.  We have made patches
 *                        to these other Symkey functions to trigger this new KDF routine
 *                        at the appropriate times.
 *
 *                        Also provides a utility function for adding DES key parity.
 */

//*******************************************************************************

#include "NistSP800_108KDF.h"

//*******************************************************************************

#include <cstring>    // memset()
#include <sstream>    // std::ostringstream

#ifdef NISTSP800_108_KDF_DEBUG
#include <iostream>
#endif

#include "pk11pub.h"

//*******************************************************************************

namespace NistSP800_108KDF{

//*******************************************************************************
// Generates three PK11SymKey objects using the KDF_CM_SHA256HMAC_L384() function for key data.
// After calling KDF_CM_SHA256HMAC_L384, the function splits up the output, sets DES parity,
//   and imports the keys into the token.
//
// Careful:  This function currently generates the key data **IN RAM** using calls to NSS sha256.
//           The key data is then "unwrapped" (imported) to the NSS token and then erased from RAM.
//           (This means that a malicious actor on the box could steal the key data.)
//
// Note: Returned key material from the KDF is converted into keys according to the following:
//   * Bytes 0  - 15 : enc/auth key
//   * Bytes 16 - 31 : mac key
//   * Bytes 32 - 47 : kek key
//   We chose this order to conform with the key order used by the PUT KEY command.
//
//*******************************************************************************
void ComputeCardKeys(  PK11SymKey* masterKey,               // Key Derivation Key
                       const BYTE* context,                 // unique data passed to the kdf (kdd)
                       const size_t context_length,         // length of context
                       PK11SymKey** encKey,                 // output parameter: generated enc/auth key
                       PK11SymKey** macKey,                 // output parameter: generated mac key
                       PK11SymKey** kekKey)                 // output parameter: generated kek key
{
    // sanity check output parameters
    if (*encKey != NULL){
        throw std::runtime_error("Output parameter \"encKey\" wasn't initialized to NULL. Overwriting may result in a memory leak.");
    }
    if (*macKey != NULL){
        throw std::runtime_error("Output parameter \"macKey\" wasn't initialized to NULL. Overwriting may result in a memory leak.");
    }
    if (*kekKey != NULL){
        throw std::runtime_error("Output parameter \"kekKey\" wasn't initialized to NULL. Overwriting may result in a memory leak.");
    }

    // allocate space for KDF output
    BYTE kdf_output[KDF_OUTPUT_SIZE_BYTES];

    try{
        // generate 384 bits of key data from the master key
        KDF_CM_SHA256HMAC_L384(masterKey, context, context_length, KDF_LABEL, kdf_output, KDF_OUTPUT_SIZE_BYTES);
    }catch(std::runtime_error& ex){
        std::ostringstream msg;
        msg << "Exception invoking NistSP800_108KDF::KDF_CM_SHA256HMAC_L384: ";
        if (ex.what() == NULL){
            msg << "NULL";
        }else{
            msg << ex.what();
        }
        throw std::runtime_error(msg.str());
    }catch(...){
        throw std::runtime_error("Unknown exception invoking NistSP800_108KDF::KDF_CM_SHA256HMAC_L384.");
    }

    try{
        // get slot from master key
        //   (we need the slot to be able to generate our temp key and unwrap our generated bytes
        PK11SlotInfo* slot = PK11_GetSlotFromKey(masterKey);
        if (slot == NULL){
            throw std::runtime_error("Failed to get slot from masterKey.");
        }
        try{
            // generate a temp key to import the key data with
            PK11SymKey* tmpKey = PK11_TokenKeyGenWithFlags(slot,               // slot handle
                                                           CKM_DES3_KEY_GEN,   // mechanism type
                                                           NULL,               // pointer to params (SECItem structure)
                                                           0,                  // keySize (per documentation in pk11skey.c, must be 0 for fixed key length algorithms)
                                                           0,                  // pointer to keyid (SECItem structure)
                                                           CKF_WRAP | CKF_UNWRAP | CKF_ENCRYPT | CKF_DECRYPT, // opFlags
                                                           PK11_ATTR_PRIVATE | PK11_ATTR_UNEXTRACTABLE | PK11_ATTR_SENSITIVE, // attrFlags (AC: this is my "best guess" as to what flags should be set)
                                                           NULL);              // pointer to wincx (AC: also my "best guess" - per pkix_sample_modules.h line 265, this should always be NULL on non-Windows)
            if (tmpKey == NULL) {
                throw std::runtime_error("Unable to create temp key (for use with importing the key data).");
            }
            try{

                // set parity on each of the 3 generated **16 byte** keys
                set_des_parity(kdf_output + (0 * KEY_DATA_SIZE_BYTES), KEY_DATA_SIZE_BYTES);
                set_des_parity(kdf_output + (1 * KEY_DATA_SIZE_BYTES), KEY_DATA_SIZE_BYTES);
                set_des_parity(kdf_output + (2 * KEY_DATA_SIZE_BYTES), KEY_DATA_SIZE_BYTES);

                try{
                    // copy byte array information into 2-key 3DES PK11 keys on token
                    *encKey = Copy2Key3DESKeyDataToToken(slot, tmpKey, kdf_output + (0 * KEY_DATA_SIZE_BYTES), KEY_DATA_SIZE_BYTES);
                    *macKey = Copy2Key3DESKeyDataToToken(slot, tmpKey, kdf_output + (1 * KEY_DATA_SIZE_BYTES), KEY_DATA_SIZE_BYTES);
                    *kekKey = Copy2Key3DESKeyDataToToken(slot, tmpKey, kdf_output + (2 * KEY_DATA_SIZE_BYTES), KEY_DATA_SIZE_BYTES);
                }catch(...){
                    // free any keys we created before rethrowing
                    if (*encKey != NULL){
                        PK11_FreeSymKey(*encKey);
                        *encKey = NULL;
                    }
                    if (*macKey != NULL){
                        PK11_FreeSymKey(*macKey);
                        *macKey = NULL;
                    }
                    if (*kekKey != NULL){
                        PK11_FreeSymKey(*kekKey);
                        *kekKey = NULL;
                    }

                    throw;
                }

                // clean up
                PK11_FreeSymKey(tmpKey);
                tmpKey = NULL;
            }catch(...){
                // clean up
                PK11_FreeSymKey(tmpKey);
                tmpKey = NULL;

                throw;
            }
            // clean up
            PK11_FreeSlot(slot);
            slot = NULL;
        }catch(...){
            // clean up
            PK11_FreeSlot(slot);
            slot = NULL;

            throw;
        }

        // erase key data from RAM
        memset(kdf_output, 0, KDF_OUTPUT_SIZE_BYTES);
    }catch(...){
        // erase key data from RAM before rethrowing
        memset(kdf_output, 0, KDF_OUTPUT_SIZE_BYTES);

        throw;
    }
}

// uses the specified temporary key to encrypt and then unwrap (decrypt) the specified binary data onto the specified token
// this has the net effect of copying the raw key data to the token
PK11SymKey* Copy2Key3DESKeyDataToToken( PK11SlotInfo* slot,      // slot to unwrap key onto
                                        PK11SymKey* tmpKey,      // temporary key to use (must already be on the slot)
                                        const BYTE* const data,  // pointer to array containing the key data to encrypt and then unwrap (decrypt) on the token
                                        const size_t data_len)   // length of data in above array
{

    // ensure expected input data size
    if (data_len != KEY_DATA_SIZE_BYTES){
        throw std::runtime_error("Invalid data length value (should be 16) (Copy2Key3DESKeyDataToToken).");
    }

    // create encryption context
    SECItem noParams = { siBuffer, NULL, 0 };
    PK11Context* context = PK11_CreateContextBySymKey(CKM_DES3_ECB,   // mechanism type
                                                      CKA_ENCRYPT,    // operation type
                                                      tmpKey,         // symKey to operate on
                                                      &noParams);     // pointer to param (SECItem structure)
    if (context == NULL) {
        throw std::runtime_error("Unable to create context (Copy2Key3DESKeyDataToToken).");
    }
    try{
        BYTE encryptedData[KEY_DATA_SIZE_BYTES + 8];
        BYTE unencryptedData[KEY_DATA_SIZE_BYTES + 8];

        // copy the key data to a new (larger) buffer
        memcpy(unencryptedData, data, KEY_DATA_SIZE_BYTES);

        // copy first DES key (of the two) into the end of the buffer
        //  (key1-key2-key1)
        memcpy(unencryptedData + KEY_DATA_SIZE_BYTES, data, 8);

        try{

            // encrypt key data with the temp key
            int encryptedData_result_len = -1;
            SECStatus result = PK11_CipherOp( context,                      // [in] pointer to PK11Context object
                                              encryptedData,                // [out] pointer to output buffer for encrypted data
                                              &encryptedData_result_len,    // [out] pointer to output buffer length
                                              KEY_DATA_SIZE_BYTES + 8,      // [in] size of output buffer
                                              unencryptedData,              // [in] pointer to input buffer for unencrypted data
                                              KEY_DATA_SIZE_BYTES + 8);     // [in] size of input buffer
            if (result != SECSuccess){
                throw std::runtime_error("Unable to encrypt plaintext key data with temporary key (Copy2Key3DESKeyDataToToken).");
            }
            if (encryptedData_result_len != KEY_DATA_SIZE_BYTES + 8){
                throw std::runtime_error("Invalid output encrypting plaintext key data with temporary key (Copy2Key3DESKeyDataToToken).");
            }

            // now "unwrap" the encrypted key data onto the token with the temporary key
            SECItem wrappeditem;
            wrappeditem.type = siBuffer;
            wrappeditem.data = encryptedData;
            wrappeditem.len = encryptedData_result_len;
            noParams.type = siBuffer;
            noParams.data = NULL;
            noParams.len = 0;
            PK11SymKey* const resultingKey = PK11_UnwrapSymKeyWithFlags(tmpKey,                      // pointer to wrappingKey (PK11SymKey)
                                                                        CKM_DES3_ECB,                // wrapType (CK_MECHANISM_TYPE)
                                                                        &noParams,                   // pointer to param (SECItem struct)
                                                                        &wrappeditem,                // pointer to wrappedKey data (SECItem struct)
                                                                        CKM_DES3_KEY_GEN,            // target (CK_MECHANISM_TYPE)
                                                                        CKA_DECRYPT,                 // operation (CK_ATTRIBUTE_TYPE)
                                                                        KEY_DATA_SIZE_BYTES + 8,     // keySize (int)
                                                                        CKF_SIGN | CKF_WRAP | CKF_UNWRAP | CKF_ENCRYPT | CKF_DECRYPT); // flags (CK_FLAGS)
            if (resultingKey == NULL){
                throw std::runtime_error("Unable to unwrap key onto token (Copy2Key3DESKeyDataToToken).");
            }

            // zeroize unencrypted key data before returning
            memset(unencryptedData, 0, KEY_DATA_SIZE_BYTES + 8);

            // clean up
            PK11_DestroyContext(context, PR_TRUE);

            return resultingKey;
        }catch(...){
            // zeroize unencrypted key data before rethrowing
            memset(unencryptedData, 0, KEY_DATA_SIZE_BYTES + 8);

            throw;
        }

    }catch(...){
        // clean up
        PK11_DestroyContext(context, PR_TRUE);

        throw;
    }
}

//*******************************************************************************
// Key Derivation Function in Counter Mode using PRF = SHA256HMAC (NIST SP 800-108)
//   Calculates 384 bits of diversified output from the provided master key (K_I)
//*******************************************************************************
void KDF_CM_SHA256HMAC_L384(  PK11SymKey* K_I,                     // Key Derivation Key
                              const BYTE* context,                 // unique data passed to the kdf (kdd)
                              const size_t context_length,         // length of context
                              const BYTE label,                    // one BYTE label parameter
                              BYTE* const output,                  // output is a L-bit array of BYTEs
                              const size_t output_length)          // output length must be at least 48 bytes
{
    //unsigned int h_bits = SHA256_LENGTH * 8;      // SHA256_HMAC output size = 256 bits
    //unsigned int h_bytes = SHA256_LENGTH;         // SHA256_HMAC output size = 32 bytes
    //const unsigned int r_bits = 8;                // The counter will be representable in 8 bits
    //unsigned int n = L / h_bits;                  // Number of iterations of the PRF
    //unsigned int L_BYTE_array_length = (int)ceil(L/256.0);

    const BYTE n = 2;                               // ceil(384 / (SHA256LENGTH * 8)) == 2
    const size_t L_BYTE_array_length = 2;           // 384 = 0x0180 hex; 2 byte long representation

    // sanity check that output buffer is large enough to contain 384 bits
    if (output_length < KDF_OUTPUT_SIZE_BYTES){
        throw std::runtime_error("Array \"output\" must be at least 48 bytes in size.");
    }

    // calculate size of temporary buffer 
    size_t HMAC_DATA_INPUT_SIZE = context_length + 3 + L_BYTE_array_length; // Don't change without reviewing code below.
    // prevent integer overflow
    if (HMAC_DATA_INPUT_SIZE < context_length){
        throw std::runtime_error("Input parameter \"context_length\" too large.");
    }
    BYTE* hmac_data_input = new BYTE[HMAC_DATA_INPUT_SIZE];                 // Hash Input = context + 5 BYTES
    
    BYTE K[n * SHA256_LENGTH];                                              // BYTE K[n * h_bytes]; - Buffer to store PRF output
    try{
        const BYTE L_BYTE_array[L_BYTE_array_length] = {0x01, 0x80};        // Array to store L in BYTES

        /* Establish HMAC Input */
        memset(hmac_data_input, 0, HMAC_DATA_INPUT_SIZE);
        hmac_data_input[1] = label;
        hmac_data_input[2] = 0x00;
        memcpy(&hmac_data_input[3], context, context_length);
        memcpy(&hmac_data_input[context_length+3], L_BYTE_array, 2);

        for(BYTE i = 1; i <= n; i++){
            // hmac_data_input = i || label || 0x00 || context || L
            hmac_data_input[0] = i;

#ifdef NISTSP800_108_KDF_DEBUG
            std::cout << "hmac_data_input:\n";
            print_BYTE_array(hmac_data_input, HMAC_DATA_INPUT_SIZE); // 5 bytes added to context
#endif

            SHA256HMAC(K_I, hmac_data_input, HMAC_DATA_INPUT_SIZE, &K[(i - 1) * SHA256_LENGTH]);
        }
        
        // clean up
        delete[] hmac_data_input;
        hmac_data_input = NULL;
    
    // upon exception, clean up before rethrowing
    }catch(...){
        // clean up
        delete[] hmac_data_input;
        hmac_data_input = NULL;

        throw;
    }

#ifdef NISTSP800_108_KDF_DEBUG
    std::cout << "KDF Output (untrimmed):\n";
    print_BYTE_array(K, n * SHA256_LENGTH);
#endif

    // copy result to output buffer, trimming it to 384 bits
    memcpy(output, K, KDF_OUTPUT_SIZE_BYTES);

    // clear K before returning
    memset(K, 0, n * SHA256_LENGTH);
}

//*******************************************************************************

void SHA256HMAC(     PK11SymKey* key,                  // HMAC Secret Key (K_I)
                     const BYTE* input,                // HMAC Input (i||04||00||context||0180)
                     const size_t input_length,        // Input Length
                     BYTE* const output)               // Output Buffer (32 BYTES written)
{
    unsigned int len = 32;
    PK11Context *context = 0;
    SECStatus s;
    SECItem noParams;
    noParams.type = siBuffer;
    noParams.data = 0;
    noParams.len = 0;

    context = PK11_CreateContextBySymKey(CKM_SHA256_HMAC, CKA_SIGN, key, &noParams);
    if (!context) {
        throw std::runtime_error("CreateContextBySymKey failed");
    }
    try{

        s = PK11_DigestBegin(context);
        if (s != SECSuccess) {
            throw std::runtime_error("DigestBegin failed");
        }

        s = PK11_DigestOp(context, input, input_length);
        if (s != SECSuccess) {
            throw std::runtime_error("DigestOp failed");
        }

        s = PK11_DigestFinal(context, output, &len, 32);
        if (s != SECSuccess) {
            throw std::runtime_error("DigestFinal failed");
        }

/* Debug Output */
#ifdef NISTSP800_108_KDF_DEBUG
        std::cout << "********************SHA256HMAC_NSS********************\n";
        std::cout << "\nInput Data:\n";
        print_BYTE_array(input, input_length);
        std::cout << "\nSHA256HMAC_NSS output:\n";
        print_BYTE_array(output, SHA256_LENGTH);
#endif

        PK11_DestroyContext(context, PR_TRUE);
    }catch(...){
        PK11_DestroyContext(context, PR_TRUE);
        throw;
    }
}

//*******************************************************************************
//    DES Parity Functions
//*******************************************************************************

/* DES KEY Parity conversion table. Takes each byte >> 1 as an index, returns
 * that byte with the proper parity bit set*/
const unsigned char parityTable[256] =
  {
  /* Even...0x00,0x02,0x04,0x06,0x08,0x0a,0x0c,0x0e */
  /* E */0x01, 0x02, 0x04, 0x07, 0x08, 0x0b, 0x0d, 0x0e,
  /* Odd....0x10,0x12,0x14,0x16,0x18,0x1a,0x1c,0x1e */
  /* O */0x10, 0x13, 0x15, 0x16, 0x19, 0x1a, 0x1c, 0x1f,
  /* Odd....0x20,0x22,0x24,0x26,0x28,0x2a,0x2c,0x2e */
  /* O */0x20, 0x23, 0x25, 0x26, 0x29, 0x2a, 0x2c, 0x2f,
  /* Even...0x30,0x32,0x34,0x36,0x38,0x3a,0x3c,0x3e */
  /* E */0x31, 0x32, 0x34, 0x37, 0x38, 0x3b, 0x3d, 0x3e,
  /* Odd....0x40,0x42,0x44,0x46,0x48,0x4a,0x4c,0x4e */
  /* O */0x40, 0x43, 0x45, 0x46, 0x49, 0x4a, 0x4c, 0x4f,
  /* Even...0x50,0x52,0x54,0x56,0x58,0x5a,0x5c,0x5e */
  /* E */0x51, 0x52, 0x54, 0x57, 0x58, 0x5b, 0x5d, 0x5e,
  /* Even...0x60,0x62,0x64,0x66,0x68,0x6a,0x6c,0x6e */
  /* E */0x61, 0x62, 0x64, 0x67, 0x68, 0x6b, 0x6d, 0x6e,
  /* Odd....0x70,0x72,0x74,0x76,0x78,0x7a,0x7c,0x7e */
  /* O */0x70, 0x73, 0x75, 0x76, 0x79, 0x7a, 0x7c, 0x7f,
  /* Odd....0x80,0x82,0x84,0x86,0x88,0x8a,0x8c,0x8e */
  /* O */0x80, 0x83, 0x85, 0x86, 0x89, 0x8a, 0x8c, 0x8f,
  /* Even...0x90,0x92,0x94,0x96,0x98,0x9a,0x9c,0x9e */
  /* E */0x91, 0x92, 0x94, 0x97, 0x98, 0x9b, 0x9d, 0x9e,
  /* Even...0xa0,0xa2,0xa4,0xa6,0xa8,0xaa,0xac,0xae */
  /* E */0xa1, 0xa2, 0xa4, 0xa7, 0xa8, 0xab, 0xad, 0xae,
  /* Odd....0xb0,0xb2,0xb4,0xb6,0xb8,0xba,0xbc,0xbe */
  /* O */0xb0, 0xb3, 0xb5, 0xb6, 0xb9, 0xba, 0xbc, 0xbf,
  /* Even...0xc0,0xc2,0xc4,0xc6,0xc8,0xca,0xcc,0xce */
  /* E */0xc1, 0xc2, 0xc4, 0xc7, 0xc8, 0xcb, 0xcd, 0xce,
  /* Odd....0xd0,0xd2,0xd4,0xd6,0xd8,0xda,0xdc,0xde */
  /* O */0xd0, 0xd3, 0xd5, 0xd6, 0xd9, 0xda, 0xdc, 0xdf,
  /* Odd....0xe0,0xe2,0xe4,0xe6,0xe8,0xea,0xec,0xee */
  /* O */0xe0, 0xe3, 0xe5, 0xe6, 0xe9, 0xea, 0xec, 0xef,
  /* Even...0xf0,0xf2,0xf4,0xf6,0xf8,0xfa,0xfc,0xfe */
  /* E */0xf1, 0xf2, 0xf4, 0xf7, 0xf8, 0xfb, 0xfd, 0xfe, };

void set_des_parity(BYTE* const key, const size_t length)
{
    if(length != 2*8){
        throw std::runtime_error("set_des_parity failed: wrong key size");
    }

    for (size_t i=0; i < length; i++)
    {
        key[i] = parityTable[key[i]>>1];
    }
}

//*******************************************************************************
//   BYTE Array Management Functions
//*******************************************************************************
#ifdef NISTSP800_108_KDF_DEBUG
void print_BYTE_array(const BYTE *array2, const size_t length)
{
    for (size_t i = 0; i < length; i++){
        printf("%02x ", array2[i]);
        if((i+1)%16 == 0)
            printf("\n");
    }
    std::cout << std::endl;
}
#endif

//*******************************************************************************
// NistSP800_108KDF Decision-Making Functions
//*******************************************************************************
// Returns true if the new KDF should be used, otherwise false.
bool useNistSP800_108KDF(BYTE nistSP800_108KDFonKeyVersion, BYTE requestedKeyVersion){
    return (requestedKeyVersion >= nistSP800_108KDFonKeyVersion);
}

//*******************************************************************************

} // end namespace NistSP800_108KDF

//*******************************************************************************