tlsprf.c File Reference

#include "precomp.h"

Include dependency graph for tlsprf.c:

Go to the source code of this file.

Macros
#define	SYMCRYPT_TLS_MAX_LABEL_AND_SEED_SIZE   (SYMCRYPT_TLS_MAX_LABEL_SIZE + SYMCRYPT_TLS_MAX_SEED_SIZE)
#define	SYMCRYPT_TLS_1_1_CHUNK_SIZE   80

Functions
SYMCRYPT_ERROR SYMCRYPT_CALL	SymCryptTlsPrf1_1ExpandKey (_Out_ PSYMCRYPT_TLSPRF1_1_EXPANDED_KEY pExpandedKey, _In_reads_(cbKey) PCBYTE pbKey, SIZE_T cbKey)
SYMCRYPT_ERROR SYMCRYPT_CALL	SymCryptTlsPrf1_2ExpandKey (_Out_ PSYMCRYPT_TLSPRF1_2_EXPANDED_KEY pExpandedKey, _In_ PCSYMCRYPT_MAC macAlgorithm, _In_reads_(cbKey) PCBYTE pbKey, SIZE_T cbKey)
VOID SYMCRYPT_CALL	SymCryptTlsPrfMac (_In_ PCSYMCRYPT_MAC pMacAlgorithm, _In_ PCSYMCRYPT_MAC_EXPANDED_KEY pMacExpandedKey, _In_reads_(cbAi) PCBYTE pbAi, _In_ SIZE_T cbAi, _In_reads_opt_(cbSeed) PCBYTE pbSeed, _In_ SIZE_T cbSeed, _Out_ PBYTE pbResult)
VOID SYMCRYPT_CALL	SymCryptTlsPrfPHash (_In_ PCSYMCRYPT_MAC pMacAlgorithm, _In_ PCSYMCRYPT_MAC_EXPANDED_KEY pMacExpandedKey, _In_reads_(cbSeed) PCBYTE pbSeed, _In_ SIZE_T cbSeed, _In_reads_opt_(cbAiIn) PCBYTE pbAiIn, _In_ SIZE_T cbAiIn, _Out_writes_(cbResult) PBYTE pbResult, SIZE_T cbResult, _Out_writes_opt_(cbAiOut) PBYTE pbAiOut, SIZE_T cbAiOut)
SYMCRYPT_ERROR SYMCRYPT_CALL	SymCryptTlsPrf1_1Derive (_In_ PCSYMCRYPT_TLSPRF1_1_EXPANDED_KEY pExpandedKey, _In_reads_opt_(cbLabel) PCBYTE pbLabel, _In_ SIZE_T cbLabel, _In_reads_(cbSeed) PCBYTE pbSeed, _In_ SIZE_T cbSeed, _Out_writes_(cbResult) PBYTE pbResult, SIZE_T cbResult)
SYMCRYPT_ERROR SYMCRYPT_CALL	SymCryptTlsPrf1_2Derive (_In_ PCSYMCRYPT_TLSPRF1_2_EXPANDED_KEY pExpandedKey, _In_reads_opt_(cbLabel) PCBYTE pbLabel, _In_ SIZE_T cbLabel, _In_reads_(cbSeed) PCBYTE pbSeed, _In_ SIZE_T cbSeed, _Out_writes_(cbResult) PBYTE pbResult, SIZE_T cbResult)
SYMCRYPT_ERROR SYMCRYPT_CALL	SymCryptTlsPrf1_1 (_In_reads_(cbKey) PCBYTE pbKey, _In_ SIZE_T cbKey, _In_reads_opt_(cbLabel) PCBYTE pbLabel, _In_ SIZE_T cbLabel, _In_reads_(cbSeed) PCBYTE pbSeed, _In_ SIZE_T cbSeed, _Out_writes_(cbResult) PBYTE pbResult, SIZE_T cbResult)
SYMCRYPT_ERROR SYMCRYPT_CALL	SymCryptTlsPrf1_2 (_In_ PCSYMCRYPT_MAC pMacAlgorithm, _In_reads_(cbKey) PCBYTE pbKey, _In_ SIZE_T cbKey, _In_reads_opt_(cbLabel) PCBYTE pbLabel, _In_ SIZE_T cbLabel, _In_reads_(cbSeed) PCBYTE pbSeed, _In_ SIZE_T cbSeed, _Out_writes_(cbResult) PBYTE pbResult, SIZE_T cbResult)

Macro Definition Documentation

SYMCRYPT_TLS_1_1_CHUNK_SIZE

#define SYMCRYPT_TLS_1_1_CHUNK_SIZE   80

Definition at line 23 of file tlsprf.c.

SYMCRYPT_TLS_MAX_LABEL_AND_SEED_SIZE

#define SYMCRYPT_TLS_MAX_LABEL_AND_SEED_SIZE   (SYMCRYPT_TLS_MAX_LABEL_SIZE + SYMCRYPT_TLS_MAX_SEED_SIZE)

Definition at line 19 of file tlsprf.c.

Function Documentation

SymCryptTlsPrf1_1()

SYMCRYPT_ERROR SYMCRYPT_CALL SymCryptTlsPrf1_1	(	_In_reads_(cbKey) PCBYTE	pbKey,
		_In_ SIZE_T	cbKey,
		_In_reads_opt_(cbLabel) PCBYTE	pbLabel,
		_In_ SIZE_T	cbLabel,
		_In_reads_(cbSeed) PCBYTE	pbSeed,
		_In_ SIZE_T	cbSeed,
		_Out_writes_(cbResult) PBYTE	pbResult,
		SIZE_T	cbResult
	)

Definition at line 484 of file tlsprf.c.

{
    SYMCRYPT_ERROR scError = SYMCRYPT_NO_ERROR;
    SYMCRYPT_TLSPRF1_1_EXPANDED_KEY key;
 
    // Create the expanded key
    scError = SymCryptTlsPrf1_1ExpandKey(&key, pbKey, cbKey);
    if (scError != SYMCRYPT_NO_ERROR)
    {
        goto cleanup;
    }
 
    // Derive the key
    scError = SymCryptTlsPrf1_1Derive(
        &key,
        pbLabel,
        cbLabel,
        pbSeed,
        cbSeed,
        pbResult,
        cbResult);
    if (scError != SYMCRYPT_NO_ERROR)
    {
        goto cleanup;
    }
 
cleanup:
    SymCryptWipeKnownSize(&key, sizeof(key));
 
    return scError;
}

SymCryptTlsPrf1_1Derive()

SYMCRYPT_ERROR SYMCRYPT_CALL SymCryptTlsPrf1_1Derive	(	_In_ PCSYMCRYPT_TLSPRF1_1_EXPANDED_KEY	pExpandedKey,
		_In_reads_opt_(cbLabel) PCBYTE	pbLabel,
		_In_ SIZE_T	cbLabel,
		_In_reads_(cbSeed) PCBYTE	pbSeed,
		_In_ SIZE_T	cbSeed,
		_Out_writes_(cbResult) PBYTE	pbResult,
		SIZE_T	cbResult
	)

Definition at line 299 of file tlsprf.c.

{
    SYMCRYPT_ERROR scError = SYMCRYPT_NO_ERROR;
 
    SYMCRYPT_ALIGN BYTE    rbLabelAndSeed[SYMCRYPT_TLS_MAX_LABEL_AND_SEED_SIZE];
                   SIZE_T  cbLabelAndSeed = 0;
 
    SYMCRYPT_ALIGN BYTE    rbAiMd5[SYMCRYPT_HMAC_MD5_RESULT_SIZE];
    SYMCRYPT_ALIGN BYTE    rbPartialResultMd5[SYMCRYPT_TLS_1_1_CHUNK_SIZE];
 
    SYMCRYPT_ALIGN BYTE    rbAiSha1[SYMCRYPT_HMAC_SHA1_RESULT_SIZE];
    SYMCRYPT_ALIGN BYTE    rbPartialResultSha1[SYMCRYPT_TLS_1_1_CHUNK_SIZE];
 
                   BYTE *  pbTmp = pbResult;
                   SIZE_T  cbBytesToWrite = cbResult;
 
    // Size checks
    if ((cbLabel > SYMCRYPT_TLS_MAX_LABEL_SIZE) || (cbSeed > SYMCRYPT_TLS_MAX_SEED_SIZE))
    {
        scError = SYMCRYPT_WRONG_DATA_SIZE;
        goto cleanup;
    }
 
    // Concatenating the label and the seed
    pbTmp = rbLabelAndSeed;
    if( cbLabel > 0 )
    {
        memcpy(pbTmp, pbLabel, cbLabel);
        pbTmp += cbLabel;
    }
    memcpy(pbTmp, pbSeed, cbSeed);
    cbLabelAndSeed = cbLabel + cbSeed;
 
    // Build A(1)'s
    SymCryptTlsPrfMac(
        SymCryptHmacMd5Algorithm,
        (PCSYMCRYPT_MAC_EXPANDED_KEY)&pExpandedKey->macMd5Key,
        rbLabelAndSeed,         // This is A(0)
        cbLabelAndSeed,
        NULL,                   // No "seed" part for A(i)'s
        0,
        rbAiMd5);
 
    SymCryptTlsPrfMac(
        SymCryptHmacSha1Algorithm,
        (PCSYMCRYPT_MAC_EXPANDED_KEY)&pExpandedKey->macSha1Key,
        rbLabelAndSeed,         // This is A(0)
        cbLabelAndSeed,
        NULL,                   // No "seed" part for A(i)'s
        0,
        rbAiSha1);
 
    // Calculate the output
    pbTmp = pbResult;
    while (cbBytesToWrite > 0)
    {
        // Calculate the two P_Hashes up to SYMCRYPT_TLS_1_1_CHUNK_SIZE bytes
 
        // P_MD5
        SymCryptTlsPrfPHash(
            SymCryptHmacMd5Algorithm,
            (PCSYMCRYPT_MAC_EXPANDED_KEY)&pExpandedKey->macMd5Key,
            rbLabelAndSeed,
            cbLabelAndSeed,
            rbAiMd5,
            SYMCRYPT_HMAC_MD5_RESULT_SIZE,
            rbPartialResultMd5,
            SYMCRYPT_MIN(cbBytesToWrite, SYMCRYPT_TLS_1_1_CHUNK_SIZE),
            rbAiMd5,
            SYMCRYPT_HMAC_MD5_RESULT_SIZE);
 
        // P_SHA1
        SymCryptTlsPrfPHash(
            SymCryptHmacSha1Algorithm,
            (PCSYMCRYPT_MAC_EXPANDED_KEY)&pExpandedKey->macSha1Key,
            rbLabelAndSeed,
            cbLabelAndSeed,
            rbAiSha1,
            SYMCRYPT_HMAC_SHA1_RESULT_SIZE,
            rbPartialResultSha1,
            SYMCRYPT_MIN(cbBytesToWrite, SYMCRYPT_TLS_1_1_CHUNK_SIZE),
            rbAiSha1,
            SYMCRYPT_HMAC_SHA1_RESULT_SIZE);
 
        // XOR the two into the output
        SymCryptXorBytes(
            rbPartialResultMd5,
            rbPartialResultSha1,
            pbTmp,
            SYMCRYPT_MIN(cbBytesToWrite, SYMCRYPT_TLS_1_1_CHUNK_SIZE));
 
        if (cbBytesToWrite <= SYMCRYPT_TLS_1_1_CHUNK_SIZE)
        {
            break;
        }
 
        cbBytesToWrite -= SYMCRYPT_TLS_1_1_CHUNK_SIZE;
        pbTmp += SYMCRYPT_TLS_1_1_CHUNK_SIZE;
 
    }
 
cleanup:
    SymCryptWipeKnownSize(rbLabelAndSeed, sizeof(rbLabelAndSeed));
    SymCryptWipeKnownSize(rbAiMd5, sizeof(rbAiMd5));
    SymCryptWipeKnownSize(rbPartialResultMd5, sizeof(rbPartialResultMd5));
    SymCryptWipeKnownSize(rbAiSha1, sizeof(rbAiSha1));
    SymCryptWipeKnownSize(rbPartialResultSha1, sizeof(rbPartialResultSha1));
 
    return scError;
}

Referenced by SymCryptTlsPrf1_1().

SymCryptTlsPrf1_1ExpandKey()

SYMCRYPT_ERROR SYMCRYPT_CALL SymCryptTlsPrf1_1ExpandKey	(	_Out_ PSYMCRYPT_TLSPRF1_1_EXPANDED_KEY	pExpandedKey,
		_In_reads_(cbKey) PCBYTE	pbKey,
		SIZE_T	cbKey
	)

Definition at line 58 of file tlsprf.c.

{
    SYMCRYPT_ERROR  scError = SYMCRYPT_NO_ERROR;
 
    SIZE_T cbKeySize;
    SIZE_T cbHalfSecret;
    SIZE_T cbOdd;
 
    // Calculating the two halves
    cbHalfSecret = cbKey / 2;
    cbOdd = cbKey % 2;
    cbKeySize = cbHalfSecret + cbOdd;
 
    //
    //     The bytes of the key material are split as following:
    //     cbOdd == 0   =>   cbKeySize == cbHalfSecret
    //
    //          ********************************************
    //          <----cbHalfSecret----><----cbHalfSecret---->
    //          <----cbKeySize-------><----cbKeySize------->
    //
    //
    //     cbOdd == 1   =>   cbKeySize == cbHalfSecret + 1
    //
    //          **********************$**********************
    //          <----cbHalfSecret----> <----cbHalfSecret---->
    //          <----cbKeySize-------->
    //                                <----cbKeySize-------->
    //
    //      Note that the middle byte of the key input might be
    //      read twice (when the key length is odd). This violates
    //      the standard rule that input data should only be read
    //      once. In this case, we do this for the following reasons:
    //      -   Avoiding the dual-read is difficult; we'd have to buffer
    //          an arbitrary-size input, and SymCrypt avoids memory
    //          allocations for symmetric algorithms.
    //      -   The dual-reading of inputs is a problem when the
    //          memory is double-mapped to a different (less trusted)
    //          security context. (E.g. a kernel-mode operation on
    //          memory that is also mapped into a user address space.)
    //          This PRF is used by TLS in LSA where that situation
    //          does not occur.
    //      -   This is used for TLS 1.0 and TLS 1.1, both of which
    //          are on the deprecation path.
    //      -   In the dual-read attack, the input is typically provided
    //          by the attacker, and then changed whilst the code is
    //          accessing it. But if the attacker is providing the input,
    //          she could just as well have provided an even-length key
    //          input that provides full freedom for choosing both HMAC
    //          keys; there is simply no reason to try and perform the
    //          dual-read attack.
    //      -   Even if the dual-read problem were to occur, it does not
    //          seem to help an attacker in any way.
 
    // MD5 Key Expansion
    scError = SymCryptHmacMd5ExpandKey(&pExpandedKey->macMd5Key, pbKey, cbKeySize);
    if (scError != SYMCRYPT_NO_ERROR)
    {
        goto cleanup;
    }
 
    // SHA1 Key Expansion
    scError = SymCryptHmacSha1ExpandKey(&pExpandedKey->macSha1Key, pbKey + cbHalfSecret, cbKeySize);
    if (scError != SYMCRYPT_NO_ERROR)
    {
        SymCryptWipeKnownSize(&pExpandedKey->macMd5Key, sizeof(pExpandedKey->macMd5Key));
 
        goto cleanup;
    }
 
cleanup:
    return scError;
}

Referenced by SymCryptTlsPrf1_1().

SymCryptTlsPrf1_2()

SYMCRYPT_ERROR SYMCRYPT_CALL SymCryptTlsPrf1_2	(	_In_ PCSYMCRYPT_MAC	pMacAlgorithm,
		_In_reads_(cbKey) PCBYTE	pbKey,
		_In_ SIZE_T	cbKey,
		_In_reads_opt_(cbLabel) PCBYTE	pbLabel,
		_In_ SIZE_T	cbLabel,
		_In_reads_(cbSeed) PCBYTE	pbSeed,
		_In_ SIZE_T	cbSeed,
		_Out_writes_(cbResult) PBYTE	pbResult,
		SIZE_T	cbResult
	)

Definition at line 530 of file tlsprf.c.

{
    SYMCRYPT_ERROR scError = SYMCRYPT_NO_ERROR;
    SYMCRYPT_TLSPRF1_2_EXPANDED_KEY key;
 
    // Create the expanded key
    scError = SymCryptTlsPrf1_2ExpandKey(&key, pMacAlgorithm, pbKey, cbKey);
    if (scError != SYMCRYPT_NO_ERROR)
    {
        goto cleanup;
    }
 
    // Derive the key
    scError = SymCryptTlsPrf1_2Derive(
        &key,
        pbLabel,
        cbLabel,
        pbSeed,
        cbSeed,
        pbResult,
        cbResult);
    if (scError != SYMCRYPT_NO_ERROR)
    {
        goto cleanup;
    }
 
cleanup:
    SymCryptWipeKnownSize(&key, sizeof(key));
 
    return scError;
}

SymCryptTlsPrf1_2Derive()

SYMCRYPT_ERROR SYMCRYPT_CALL SymCryptTlsPrf1_2Derive	(	_In_ PCSYMCRYPT_TLSPRF1_2_EXPANDED_KEY	pExpandedKey,
		_In_reads_opt_(cbLabel) PCBYTE	pbLabel,
		_In_ SIZE_T	cbLabel,
		_In_reads_(cbSeed) PCBYTE	pbSeed,
		_In_ SIZE_T	cbSeed,
		_Out_writes_(cbResult) PBYTE	pbResult,
		SIZE_T	cbResult
	)

Definition at line 426 of file tlsprf.c.

{
    SYMCRYPT_ERROR scError = SYMCRYPT_NO_ERROR;
 
    SYMCRYPT_ALIGN BYTE    rbLabelAndSeed[SYMCRYPT_TLS_MAX_LABEL_AND_SEED_SIZE];
                   BYTE *  pbTmp;
 
    // Size checks
    if ((cbLabel > SYMCRYPT_TLS_MAX_LABEL_SIZE) || (cbSeed > SYMCRYPT_TLS_MAX_SEED_SIZE))
    {
        scError = SYMCRYPT_WRONG_DATA_SIZE;
        goto cleanup;
    }
 
    // Concatenating the label and the seed
    pbTmp = rbLabelAndSeed;
    if( cbLabel > 0 )
    {
        memcpy(pbTmp, pbLabel, cbLabel);
        pbTmp += cbLabel;
    }
    memcpy(pbTmp, pbSeed, cbSeed);
 
    //
    // According to RFC 2104 (HMAC),  hash the secret if its length
    // exceeds the basic compression block length. This is taken
    // care by the specific HMAC inside SymCryptTlsPrfPHash.
    //
    SymCryptTlsPrfPHash(
        pExpandedKey->macAlg,
        &pExpandedKey->macKey,
        rbLabelAndSeed,
        cbLabel + cbSeed,
        NULL,
        0,
        pbResult,
        cbResult,
        NULL,
        0);
 
cleanup:
    SymCryptWipeKnownSize(rbLabelAndSeed, sizeof(rbLabelAndSeed));
 
    return scError;
}

Referenced by SymCryptTlsPrf1_2().

SymCryptTlsPrf1_2ExpandKey()

SYMCRYPT_ERROR SYMCRYPT_CALL SymCryptTlsPrf1_2ExpandKey	(	_Out_ PSYMCRYPT_TLSPRF1_2_EXPANDED_KEY	pExpandedKey,
		_In_ PCSYMCRYPT_MAC	macAlgorithm,
		_In_reads_(cbKey) PCBYTE	pbKey,
		SIZE_T	cbKey
	)

Definition at line 137 of file tlsprf.c.

{
    SYMCRYPT_ASSERT( macAlgorithm->expandedKeySize <= sizeof( pExpandedKey->macKey ) );
 
    pExpandedKey->macAlg = macAlgorithm;
    return macAlgorithm->expandKeyFunc( &pExpandedKey->macKey, pbKey, cbKey );
}

Referenced by SymCryptTlsPrf1_2().

SymCryptTlsPrfMac()

VOID SYMCRYPT_CALL SymCryptTlsPrfMac	(	_In_ PCSYMCRYPT_MAC	pMacAlgorithm,
		_In_ PCSYMCRYPT_MAC_EXPANDED_KEY	pMacExpandedKey,
		_In_reads_(cbAi) PCBYTE	pbAi,
		_In_ SIZE_T	cbAi,
		_In_reads_opt_(cbSeed) PCBYTE	pbSeed,
		_In_ SIZE_T	cbSeed,
		_Out_ PBYTE	pbResult
	)

Definition at line 160 of file tlsprf.c.

{
    SYMCRYPT_MAC_STATE macState;
 
    pMacAlgorithm->initFunc( &macState, pMacExpandedKey );
    pMacAlgorithm->appendFunc(&macState, pbAi, cbAi);
 
    if (cbSeed > 0)
    {
        pMacAlgorithm->appendFunc( &macState, pbSeed, cbSeed );
    }
 
    pMacAlgorithm->resultFunc( &macState, pbResult );
 
    // No need to wipe the state. The resultFunc wipes it.
}

Referenced by SymCryptTlsPrf1_1Derive(), and SymCryptTlsPrfPHash().

SymCryptTlsPrfPHash()

VOID SYMCRYPT_CALL SymCryptTlsPrfPHash	(	_In_ PCSYMCRYPT_MAC	pMacAlgorithm,
		_In_ PCSYMCRYPT_MAC_EXPANDED_KEY	pMacExpandedKey,
		_In_reads_(cbSeed) PCBYTE	pbSeed,
		_In_ SIZE_T	cbSeed,
		_In_reads_opt_(cbAiIn) PCBYTE	pbAiIn,
		_In_ SIZE_T	cbAiIn,
		_Out_writes_(cbResult) PBYTE	pbResult,
		SIZE_T	cbResult,
		_Out_writes_opt_(cbAiOut) PBYTE	pbAiOut,
		SIZE_T	cbAiOut
	)

Definition at line 204 of file tlsprf.c.

{
    SYMCRYPT_ALIGN BYTE    rbAi[SYMCRYPT_MAC_MAX_RESULT_SIZE];
    SYMCRYPT_ALIGN BYTE    rbPartialResult[SYMCRYPT_MAC_MAX_RESULT_SIZE];
                   BYTE *  pbTmp = pbResult;
 
    SIZE_T  cbMacResultSize = pMacAlgorithm->resultSize;
    SIZE_T  cbBytesToWrite = cbResult;
 
    if (cbAiIn == 0)
    {
        // Build A(1)
        SymCryptTlsPrfMac(
            pMacAlgorithm,
            pMacExpandedKey,
            pbSeed,         // This is A(0)
            cbSeed,
            NULL,           // No "seed" part for A(i)'s
            0,
            rbAi);
    }
    else
    {
        // Get the previous Ai
        memcpy(rbAi, pbAiIn, SYMCRYPT_MIN(SYMCRYPT_MAC_MAX_RESULT_SIZE, cbAiIn));
    }
 
    while (cbBytesToWrite > 0)
    {
        // Build HMAC( secret, A(i) + seed)
        SymCryptTlsPrfMac(
            pMacAlgorithm,
            pMacExpandedKey,
            rbAi,          // this is A(i)
            cbMacResultSize,
            pbSeed,             // the "seed" part
            cbSeed,
            rbPartialResult);
 
        // Store it in the output buffer
        memcpy(pbTmp, rbPartialResult, SYMCRYPT_MIN(cbBytesToWrite, cbMacResultSize));
 
        // Build A(i+1)
        SymCryptTlsPrfMac(
            pMacAlgorithm,
            pMacExpandedKey,
            rbAi,         // This is A(i)
            cbMacResultSize,
            NULL,              // No "seed" part for A(i)'s
            0,
            rbAi);
 
        if (cbBytesToWrite <= cbMacResultSize)
        {
            break;
        }
 
        pbTmp += cbMacResultSize;
        cbBytesToWrite -= cbMacResultSize;
    }
 
    // Store the next A(i) if needed
    if (cbAiOut > 0)
    {
        memcpy(pbAiOut, rbAi, SYMCRYPT_MIN(cbAiOut,cbMacResultSize));
    }
 
    SymCryptWipeKnownSize(rbAi, sizeof(rbAi));
    SymCryptWipeKnownSize(rbPartialResult, sizeof(rbPartialResult));
}

Referenced by SymCryptTlsPrf1_1Derive(), and SymCryptTlsPrf1_2Derive().