Merged PR 11087190: SSKDF implementation

## Description:
SSKDF implementation and unit tests.
 
## Admin Checklist:
- [x] You have updated documentation in symcrypt.h to reflect any changes in behavior
- [x] You have updated CHANGELOG.md to reflect any changes in behavior
- [x] You have updated symcryptunittest to exercise any new functionality
- [x] If you have introduced any symbols in symcrypt.h you have updated production and test dynamic export symbols (exports.ver / exports.def / symcrypt.src) and tested the updated dynamic modules with symcryptunittest
- [x] If you have introduced functionality that varies based on CPU features, you have manually tested with and without relevant features
- [X] If you have made significant changes to a particular algorithm, you have checked that performance numbers reported by symcryptunittest are in line with expectations
- [X] If you have added new algorithms/modes, you have updated the status indicator text for the associated modules if necessary

Related work items: #51795170

Author: mamckee

CHANGELOG.md

@@ -4,6 +4,7 @@ New changes will be listed here as they are developed. The version number is det
 prior to the creation of a new release, based on the changes contained in that release.
 
 - Internal self-test changes to support FIPS 140-3 certification
+- Add SSKDF implementation
 
 # Version 103.4.3
 

inc/symcrypt.h

@@ -5494,10 +5494,9 @@ SymCryptSskdfMacDerive(
 // Parameters:
 //    - pExpandedSalt       :   Pointer to a SYMCRYPT_SSKDF_MAC_EXPANDED_SALT structure that is
 //                              initialized by a prior call to SymCryptSskdfMacExpandSalt.
-//    - cbMacOutputSize     :   Output size used by the MAC algorithm for intermediate computations.
-//                              Set to 0 for MACs that don't support variable output sizes, or to use
-//                              the default output size. The default output size for KMAC128 is 32 bytes,
-//                              and KMAC256 is 64 bytes.
+//    - cbMacOutputSize     :   Output size used by the MAC algorithm for intermediate computations. Must not be
+//                              greater than 64 bytes. Set to 0 for MACs that don't support variable output sizes,
+//                              or to use the default output size. The default output size when KMAC is used is cbResult.
 //    - pbSecret, cbSecret  :   Buffer containing the shared secret.
 //    - pbInfo, cbInfo      :   Buffer containing the fixed info.
 //    - pbResult, cbResult  :   Buffer to store the derived key. Exactly cbResult bytes of output will be generated.
@@ -5541,15 +5540,20 @@ SymCryptSskdfHash(
 //
 // Parameters:
 //    - hashAlgorithm       :   Hash algorithm that will be used in the key derivation.
-//    - cbMacOutputSize     :   Output size used by the hash algorithm for intermediate computations.
+//    - cbHashOutputSize    :   Output size used by the hash algorithm for intermediate computations.
 //                              Set to 0 for hashes that don't support variable output sizes, or to use
-//                              the default output size.
+//                              the default output size. Currently, no allowed hash algorithms support
+//                              variable output sizes, so this should always be set to 0.
 //    - pbSecret, cbSecret  :   Buffer containing the shared secret.
 //    - pbInfo, cbInfo      :   Buffer containing the fixed info.
 //    - pbResult, cbResult  :   Buffer to store the derived key. Exactly cbResult bytes of output will be generated.
 //                              Must not exceed 2^{32} - 1 times the result size of hashAlgorithm.
 //
 
+VOID
+SYMCRYPT_CALL
+SymCryptSskdfSelfTest(void);
+
 //==========================================================================
 //   RNG ALGORITHMS
 //==========================================================================

inc/symcrypt_internal.h

@@ -1501,6 +1501,7 @@ typedef SYMCRYPT_ERROR (SYMCRYPT_CALL * PSYMCRYPT_MAC_EXPAND_KEY)
 typedef VOID (SYMCRYPT_CALL * PSYMCRYPT_MAC_INIT)     ( PVOID pState,  PCVOID pExpandedKey );
 typedef VOID (SYMCRYPT_CALL * PSYMCRYPT_MAC_APPEND)( PVOID pState, PCBYTE pbData, SIZE_T cbData );
 typedef VOID (SYMCRYPT_CALL * PSYMCRYPT_MAC_RESULT)  ( PVOID pState, PVOID pbResult );
+typedef VOID (SYMCRYPT_CALL * PSYMCRYPT_MAC_RESULT_EX)  ( PVOID pState, PVOID pbResult, SIZE_T cbResult );
 
 typedef struct _SYMCRYPT_MAC
 {

lib/CMakeLists.txt

@@ -111,6 +111,8 @@ set(SOURCES_COMMON
     ssh_kdf.c
     ssh_kdf_sha256.c
     ssh_kdf_sha512.c
+    sskdf.c
+    sskdf_selftest.c
     tlsCbcVerify.c
     tlsprf_selftest.c
     tlsprf.c

lib/sskdf.c

@@ -0,0 +1,266 @@
+//
+// sskdf.c
+//
+// Copyright (c) Microsoft Corporation. Licensed under the MIT license.
+//
+
+//
+// This module implements Single-Step KDF as specified in SP800-56C section 4.
+//
+
+#include "precomp.h"
+
+//
+// See the symcrypt.h file for documentation on what the various functions do.
+//
+
+
+#define SYMCRYPT_SSKDF_KMAC_128_DEFAULT_SALT_SIZE (164)
+#define SYMCRYPT_SSKDF_KMAC_256_DEFAULT_SALT_SIZE (132)
+#define SYMCRYPT_SSKDF_DEFAULT_SALT_MAX SYMCRYPT_SSKDF_KMAC_128_DEFAULT_SALT_SIZE
+
+
+static const BYTE   pbKmacCustomizationString[3] = { 'K', 'D', 'F' };
+
+SYMCRYPT_ERROR
+SYMCRYPT_CALL
+SymCryptSskdfMacExpandSalt(
+    _Out_                   PSYMCRYPT_SSKDF_MAC_EXPANDED_SALT   pExpandedSalt,
+    _In_                    PCSYMCRYPT_MAC                      macAlgorithm,
+    _In_reads_opt_(cbSalt)  PCBYTE                              pbSalt,
+                            SIZE_T                              cbSalt)
+{
+    SYMCRYPT_ERROR scError = SYMCRYPT_NO_ERROR;
+
+    const BYTE pbSaltDefault[SYMCRYPT_SSKDF_DEFAULT_SALT_MAX] = { 0 };
+
+    SYMCRYPT_ASSERT( macAlgorithm->expandedKeySize <= sizeof( pExpandedSalt->macKey ) );
+
+    pExpandedSalt->macAlg = macAlgorithm;
+
+    if ( pbSalt == NULL )
+    {
+        if ( macAlgorithm == SymCryptKmac128Algorithm )
+        {
+            cbSalt = SYMCRYPT_SSKDF_KMAC_128_DEFAULT_SALT_SIZE;
+        }
+        else if ( macAlgorithm == SymCryptKmac256Algorithm )
+        {
+            cbSalt = SYMCRYPT_SSKDF_KMAC_256_DEFAULT_SALT_SIZE;
+        }
+        else
+        {
+            cbSalt = SymCryptHashInputBlockSize( *(macAlgorithm->ppHashAlgorithm) );
+        }
+
+        pbSalt = pbSaltDefault;
+    }
+
+    if ( macAlgorithm == SymCryptKmac128Algorithm )
+    {
+        scError = SymCryptKmac128ExpandKeyEx(
+            &pExpandedSalt->macKey.kmac128Key,
+            pbSalt,
+            cbSalt,
+            pbKmacCustomizationString,
+            sizeof( pbKmacCustomizationString ) );
+    }
+    else if ( macAlgorithm == SymCryptKmac256Algorithm )
+    {
+        scError = SymCryptKmac256ExpandKeyEx(
+            &pExpandedSalt->macKey.kmac256Key,
+            pbSalt,
+            cbSalt,
+            pbKmacCustomizationString,
+            sizeof( pbKmacCustomizationString ) );
+    }
+    else
+    {
+        scError = macAlgorithm->expandKeyFunc( &pExpandedSalt->macKey, pbSalt, cbSalt );
+    }
+
+    return scError;
+}
+
+SYMCRYPT_ERROR
+SYMCRYPT_CALL
+SymCryptSskdfMacDerive(
+    _In_                    PCSYMCRYPT_SSKDF_MAC_EXPANDED_SALT  pExpandedSalt,
+                            SIZE_T                              cbMacOutputSize,
+    _In_reads_(cbSecret)    PCBYTE                              pbSecret,
+                            SIZE_T                              cbSecret,
+    _In_reads_opt_(cbInfo)  PCBYTE                              pbInfo,
+                            SIZE_T                              cbInfo,
+    _Out_writes_(cbResult)  PBYTE                               pbResult,
+                            SIZE_T                              cbResult)
+{
+    SYMCRYPT_ERROR scError = SYMCRYPT_NO_ERROR;
+    SYMCRYPT_MAC_STATE state;
+    PCSYMCRYPT_MAC pMacAlgorithm = pExpandedSalt->macAlg;
+    PSYMCRYPT_MAC_RESULT_EX resultFuncEx = NULL;
+
+    SYMCRYPT_ALIGN BYTE rbPartialResult[SYMCRYPT_MAC_MAX_RESULT_SIZE];
+    PBYTE pbCurr = pbResult;
+
+    SIZE_T cbMacResultSize = pMacAlgorithm->resultSize;
+    SIZE_T cbBlock;
+    UINT32 cntr = 1;
+    BYTE ctrBuf[4];
+
+    if ( cbMacOutputSize > 64 )
+    {
+        scError = SYMCRYPT_INVALID_ARGUMENT;
+        goto cleanup;
+    }
+
+    if ( pMacAlgorithm == SymCryptKmac128Algorithm )
+    {
+        cbMacResultSize = cbMacOutputSize;
+        resultFuncEx = SymCryptKmac128ResultEx;
+    }
+    else if ( pMacAlgorithm == SymCryptKmac256Algorithm )
+    {
+        cbMacResultSize = cbMacOutputSize;
+        resultFuncEx = SymCryptKmac256ResultEx;
+    }
+    else if ( cbMacOutputSize > 0 && cbMacOutputSize != pMacAlgorithm->resultSize )
+    {
+        scError = SYMCRYPT_INVALID_ARGUMENT;
+        goto cleanup;
+    }
+
+    while ( cbResult > 0 )
+    {
+        SYMCRYPT_STORE_MSBFIRST32( ctrBuf, cntr );
+
+        // Calculate K(i) = H(counter || Z || FixedInfo)
+        pMacAlgorithm->initFunc( &state, &pExpandedSalt->macKey );
+        pMacAlgorithm->appendFunc( &state, ctrBuf, sizeof( ctrBuf ) );
+        pMacAlgorithm->appendFunc( &state, pbSecret, cbSecret );
+        pMacAlgorithm->appendFunc( &state, pbInfo, cbInfo );
+
+        cbBlock = SYMCRYPT_MIN( cbResult, cbMacResultSize );
+
+        if ( resultFuncEx != NULL )
+        {
+            if ( cbMacOutputSize > 0 )
+            {
+                resultFuncEx( &state, rbPartialResult, cbMacOutputSize );
+            }
+            else
+            {
+                // If the output size is not specified, calculate the full result
+                resultFuncEx( &state, pbResult, cbResult );
+                break;
+            }
+        }
+        else
+        {
+            pMacAlgorithm->resultFunc( &state, rbPartialResult );
+        }
+
+        // Store the result in the output buffer
+        memcpy( pbCurr, rbPartialResult, cbBlock );
+
+        // Update counters
+        cntr++;
+        pbCurr += cbBlock;
+        cbResult -= cbBlock;
+    }
+
+cleanup:
+
+    SymCryptWipeKnownSize( &rbPartialResult[0], sizeof( rbPartialResult ) );
+
+    return scError;
+}
+
+SYMCRYPT_ERROR
+SYMCRYPT_CALL
+SymCryptSskdfMac(
+    _In_                    PCSYMCRYPT_MAC  macAlgorithm,
+                            SIZE_T          cbMacOutputSize,
+    _In_reads_(cbSecret)    PCBYTE          pbSecret,
+                            SIZE_T          cbSecret,
+    _In_reads_opt_(cbSalt)  PCBYTE          pbSalt,
+                            SIZE_T          cbSalt,
+    _In_reads_opt_(cbInfo)  PCBYTE          pbInfo,
+                            SIZE_T          cbInfo,
+    _Out_writes_(cbResult)  PBYTE           pbResult,
+                            SIZE_T          cbResult)
+{
+    SYMCRYPT_ERROR scError = SYMCRYPT_NO_ERROR;
+    SYMCRYPT_SSKDF_MAC_EXPANDED_SALT expandedSalt;
+
+    scError = SymCryptSskdfMacExpandSalt( &expandedSalt, macAlgorithm, pbSalt, cbSalt );
+
+    if ( scError != SYMCRYPT_NO_ERROR )
+    {
+        goto cleanup;
+    }
+
+    scError = SymCryptSskdfMacDerive(
+        &expandedSalt,
+        cbMacOutputSize,
+        pbSecret,
+        cbSecret,
+        pbInfo,
+        cbInfo,
+        pbResult,
+        cbResult );
+
+cleanup:
+
+    SymCryptWipeKnownSize( &expandedSalt, sizeof( expandedSalt ) );
+
+    return scError;
+}
+
+SYMCRYPT_ERROR
+SYMCRYPT_CALL
+SymCryptSskdfHash(
+    _In_                    PCSYMCRYPT_HASH hashAlgorithm,
+                            SIZE_T          cbHashOutputSize,
+    _In_reads_(cbSecret)    PCBYTE          pbSecret,
+                            SIZE_T          cbSecret,
+    _In_reads_opt_(cbInfo)  PCBYTE          pbInfo,
+                            SIZE_T          cbInfo,
+    _Out_writes_(cbResult)  PBYTE           pbResult,
+                            SIZE_T          cbResult)
+{
+    SYMCRYPT_HASH_STATE state;
+
+    PBYTE pbCurr = pbResult;
+
+    SIZE_T cbHashResultSize = hashAlgorithm->resultSize;
+    SIZE_T cbPartialResult;
+    UINT32 cntr = 1;
+    BYTE ctrBuf[4];
+
+    if ( cbHashOutputSize > 64 ||
+         cbHashOutputSize > 0 && cbHashOutputSize != hashAlgorithm->resultSize )
+    {
+        return SYMCRYPT_INVALID_ARGUMENT;
+    }
+
+    while ( cbResult > 0 )
+    {
+        SYMCRYPT_STORE_MSBFIRST32( ctrBuf, cntr );
+
+        cbPartialResult = SYMCRYPT_MIN( cbResult, cbHashResultSize );
+
+        // Calculate K(i) = H(counter || Z || FixedInfo)
+        SymCryptHashInit( hashAlgorithm, &state );
+        SymCryptHashAppend( hashAlgorithm, &state, ctrBuf, sizeof( ctrBuf ) );
+        SymCryptHashAppend( hashAlgorithm, &state, pbSecret, cbSecret );
+        SymCryptHashAppend( hashAlgorithm, &state, pbInfo, cbInfo );
+        SymCryptHashResult( hashAlgorithm, &state, pbCurr, cbPartialResult );
+
+        // Update counters
+        cntr++;
+        pbCurr += cbPartialResult;
+        cbResult -= cbPartialResult;
+    }
+
+    return SYMCRYPT_NO_ERROR;
+}

lib/sskdf_selftest.c

@@ -0,0 +1,34 @@
+//
+// sskdf_selftest.c
+//
+// Copyright (c) Microsoft Corporation. Licensed under the MIT license.
+//
+
+#include "precomp.h"
+
+static const BYTE pbResult[] =
+{
+    0x30, 0xe5, 0x3e, 0x4c, 0xf6, 0xb1, 0xa5, 0x42, 0x5d, 0xc6, 0x4c, 0xe6, 0x15, 0x7f, 0x5f, 0xa6
+};
+
+VOID
+SYMCRYPT_CALL
+SymCryptSskdfSelfTest(void)
+{
+    SYMCRYPT_ALIGN BYTE rbResult[sizeof(pbResult)];
+
+    SymCryptSskdfMac(
+        SymCryptHmacSha512Algorithm,
+        0,
+        &SymCryptTestKey32[0], 16,
+        &SymCryptTestKey32[16], 16,
+        &SymCryptTestMsg16[0], 16,
+        rbResult, sizeof(pbResult));
+
+    SymCryptInjectError(rbResult, sizeof(pbResult));
+
+    if (memcmp(rbResult, pbResult, sizeof(pbResult)) != 0)
+    {
+        SymCryptFatal('sskd');
+    }
+}

lib/symcrypt.vcxproj

@@ -141,6 +141,8 @@
     <ClCompile Include="ssh_kdf.c" />
     <ClCompile Include="ssh_kdf_sha256.c" />
     <ClCompile Include="ssh_kdf_sha512.c" />
+    <ClCompile Include="sskdf.c" />
+    <ClCompile Include="sskdf_selftest.c" />
     <ClCompile Include="tlsCbcVerify.c" />
     <ClCompile Include="tlsprf.c" />
     <ClCompile Include="tlsprf_selftest.c" />

modules/linux/common/exports.ver

@@ -554,4 +554,9 @@ VERSION_103.4
       SymCryptXtsAesEncryptWith128bTweak;
       SymCryptXtsAesExpandKeyEx;
       SymCryptXtsAesKeyCopy;
+      SymCryptSskdfMacExpandSalt;
+      SymCryptSskdfMacDerive;
+      SymCryptSskdfMac;
+      SymCryptSskdfHash;
+      SymCryptSskdfSelfTest;
 } VERSION_103.2;

modules/linux/common/module.c

@@ -63,6 +63,8 @@ VOID __attribute__((constructor)) SymCryptModuleMain(void)
         SymCryptSshKdfSha256SelfTest();
         SymCryptSshKdfSha512SelfTest();
 
+        SymCryptSskdfSelfTest();
+
         SymCryptHmacSha3_256Selftest();
 
         g_SymCryptFipsSelftestsPerformed |= SYMCRYPT_SELFTEST_ALGORITHM_STARTUP;