Key​Derivation​Parameters Key​Derivation​Parameters Key​Derivation​Parameters Class

Definition

Represents parameters used when deriving a key.

public sealed class KeyDerivationParameters : IKeyDerivationParameters, IKeyDerivationParameters2public sealed class KeyDerivationParameters : IKeyDerivationParameters, IKeyDerivationParameters2Public NotInheritable Class KeyDerivationParameters Implements IKeyDerivationParameters, IKeyDerivationParameters2
Attributes
Windows 10 requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Remarks

You do not have to create an instance of the class to use the methods. Instead, use the class name followed by the dot operator (.), followed by the method name.

Properties

Capi1KdfTargetAlgorithm Capi1KdfTargetAlgorithm Capi1KdfTargetAlgorithm

Gets or sets the Capi1KdfTargetAlgorithm.

public Capi1KdfTargetAlgorithm Capi1KdfTargetAlgorithm { get; set; }public Capi1KdfTargetAlgorithm Capi1KdfTargetAlgorithm { get; set; }Public ReadWrite Property Capi1KdfTargetAlgorithm As Capi1KdfTargetAlgorithm
Attributes

IterationCount IterationCount IterationCount

Retrieves the number of iterations used to derive the key. For more information, see BuildForPbkdf2.

public unsigned short IterationCount { get; }public uint IterationCount { get; }Public ReadOnly Property IterationCount As uint
Value
uint uint uint

Iteration count.

Attributes

Remarks

The number of iterations is specified in the BuildForPbkdf2 method.

KdfGenericBinary KdfGenericBinary KdfGenericBinary

Gets or sets the parameters used by the key derivation algorithm.

public IBuffer KdfGenericBinary { get; set; }public IBuffer KdfGenericBinary { get; set; }Public ReadWrite Property KdfGenericBinary As IBuffer
Value
IBuffer IBuffer IBuffer

Buffer that contains the parameters.

Attributes

Methods

BuildForCapi1Kdf(Capi1KdfTargetAlgorithm) BuildForCapi1Kdf(Capi1KdfTargetAlgorithm) BuildForCapi1Kdf(Capi1KdfTargetAlgorithm)

Creates a KeyDerivationParameters object for use in the target algorithm.

public static KeyDerivationParameters BuildForCapi1Kdf(Capi1KdfTargetAlgorithm capi1KdfTargetAlgorithm)public static KeyDerivationParameters BuildForCapi1Kdf(Capi1KdfTargetAlgorithm capi1KdfTargetAlgorithm)Public Static Function BuildForCapi1Kdf(capi1KdfTargetAlgorithm As Capi1KdfTargetAlgorithm) As KeyDerivationParameters
Parameters
capi1KdfTargetAlgorithm
Capi1KdfTargetAlgorithm Capi1KdfTargetAlgorithm Capi1KdfTargetAlgorithm

The target algorithm.

Returns

Refers to the parameters used during key derivation.

Attributes

BuildForPbkdf2(IBuffer, UInt32) BuildForPbkdf2(IBuffer, UInt32) BuildForPbkdf2(IBuffer, UInt32)

Creates a KeyDerivationParameters object for use in the password-based key derivation function 2 (PBKDF2).

public static KeyDerivationParameters BuildForPbkdf2(IBuffer pbkdf2Salt, UInt32 iterationCount)public static KeyDerivationParameters BuildForPbkdf2(IBuffer pbkdf2Salt, UInt32 iterationCount)Public Static Function BuildForPbkdf2(pbkdf2Salt As IBuffer, iterationCount As UInt32) As KeyDerivationParameters
Parameters
pbkdf2Salt
IBuffer IBuffer IBuffer

The salt, a random or pseudorandom value to be combined with the password in multiple iterations. A salt is used to increase entropy above what can be obtained from using a password alone.

iterationCount
System.UInt32 System.UInt32 System.UInt32

Number of iterations to be used to derive a key.

Returns

Refers to the parameters used during key derivation.

Attributes

Remarks

You can use the following algorithm names with the OpenAlgorithm function to open a PBKDF2 algorithm provider:

Examples

public String SampleDeriveFromPbkdf(
    String strAlgName,
    UInt32 targetSize)
{
    // Open the specified algorithm.
    KeyDerivationAlgorithmProvider objKdfProv = KeyDerivationAlgorithmProvider.OpenAlgorithm(strAlgName);

    // Create a buffer that contains the secret used during derivation.
    String strSecret = "MyPassword";
    IBuffer buffSecret = CryptographicBuffer.ConvertStringToBinary(strSecret, BinaryStringEncoding.Utf8);

    // Create a random salt value.
    IBuffer buffSalt = CryptographicBuffer.GenerateRandom(32);

    // Specify the number of iterations to be used during derivation.
    UInt32 iterationCount = 10000;

    // Create the derivation parameters.
    KeyDerivationParameters pbkdf2Params = KeyDerivationParameters.BuildForPbkdf2(buffSalt, iterationCount);

    // Create a key from the secret value.
    CryptographicKey keyOriginal = objKdfProv.CreateKey(buffSecret);

    // Derive a key based on the original key and the derivation parameters.
    IBuffer keyDerived = CryptographicEngine.DeriveKeyMaterial(
        keyOriginal,
        pbkdf2Params,
        targetSize);

    // Encode the key to a hexadecimal value (for display)
    String strKeyHex = CryptographicBuffer.EncodeToHexString(keyDerived);

    // Return the encoded string
    return strKeyHex;
}

BuildForSP800108(IBuffer, IBuffer) BuildForSP800108(IBuffer, IBuffer) BuildForSP800108(IBuffer, IBuffer)

Creates a KeyDerivationParameters object for use in a counter mode, hash-based message authentication code (HMAC) key derivation function.

public static KeyDerivationParameters BuildForSP800108(IBuffer label, IBuffer context)public static KeyDerivationParameters BuildForSP800108(IBuffer label, IBuffer context)Public Static Function BuildForSP800108(label As IBuffer, context As IBuffer) As KeyDerivationParameters
Parameters
label
IBuffer IBuffer IBuffer

Buffer that specifies the purpose for the derived keying material.

context
IBuffer IBuffer IBuffer

Buffer that specifies information related to the derived keying material. For example, the context can identify the parties who are deriving the keying material and, optionally, a nonce known by the parties.

Returns

Refers to the parameters used during key derivation.

Attributes

Remarks

You can use the following algorithm names with the OpenAlgorithm function to open a SP800108 KDF algorithm provider:

Examples

public void SampleDeriveFromSP800108()
{
    // Create a string that contains the algorithm name.
    String strAlgName = KeyDerivationAlgorithmNames.Sp800108CtrHmacSha256;

    // Open the specified algorithm.
    KeyDerivationAlgorithmProvider objKdfProv = KeyDerivationAlgorithmProvider.OpenAlgorithm(strAlgName);

    // Specify the requested size, in bytes, of the derived key. 
    UInt32 targetSize = 32;

    // Create a buffer that contains the label value.
    String strPurpose = "Purpose";
    IBuffer buffLabel = CryptographicBuffer.ConvertStringToBinary(strPurpose, BinaryStringEncoding.Utf8);

    // Create a buffer that contains the context value.
    byte[] Nonce = { 1, 1, 0, 0, 0, 0, 0, 0};
    IBuffer buffContext = CryptographicBuffer.CreateFromByteArray(Nonce);

    // Create the derivation parameters.
    KeyDerivationParameters kdf800108Params = KeyDerivationParameters.BuildForSP800108(buffLabel, buffContext);

    // Create a secret value.
    IBuffer buffSecret = CryptographicBuffer.GenerateRandom(32);

    // Create a key from the secret value.
    CryptographicKey keyOriginal = objKdfProv.CreateKey(buffSecret);

    // Derive a key based on the original key and the derivation parameters.
    IBuffer keyDerived = CryptographicEngine.DeriveKeyMaterial(
        keyOriginal,
        kdf800108Params,
        targetSize);

    // Encode the key to a hexadecimal value (for display)
    String strKeyHex = CryptographicBuffer.EncodeToHexString(keyDerived);
}

BuildForSP80056a(IBuffer, IBuffer, IBuffer, IBuffer, IBuffer) BuildForSP80056a(IBuffer, IBuffer, IBuffer, IBuffer, IBuffer) BuildForSP80056a(IBuffer, IBuffer, IBuffer, IBuffer, IBuffer)

Creates a KeyDerivationParameters object for use in the SP800-56A key derivation function.

public static KeyDerivationParameters BuildForSP80056a(IBuffer algorithmId, IBuffer partyUInfo, IBuffer partyVInfo, IBuffer suppPubInfo, IBuffer suppPrivInfo)public static KeyDerivationParameters BuildForSP80056a(IBuffer algorithmId, IBuffer partyUInfo, IBuffer partyVInfo, IBuffer suppPubInfo, IBuffer suppPrivInfo)Public Static Function BuildForSP80056a(algorithmId As IBuffer, partyUInfo As IBuffer, partyVInfo As IBuffer, suppPubInfo As IBuffer, suppPrivInfo As IBuffer) As KeyDerivationParameters
Parameters
algorithmId
IBuffer IBuffer IBuffer

Specifies the intended purpose of the derived key.

partyUInfo
IBuffer IBuffer IBuffer

Contains public information contributed by the initiator.

partyVInfo
IBuffer IBuffer IBuffer

Contains public information contributed by the responder.

suppPubInfo
IBuffer IBuffer IBuffer

Contains public information known to both initiator and responder.

suppPrivInfo
IBuffer IBuffer IBuffer

Contains private information known to both initiator and responder, such as a shared secret.

Returns

Refers to the parameters used during key derivation.

Attributes

Remarks

You can use the following algorithm names with the OpenAlgorithm function to open a SP80056a KDF algorithm provider:

Examples

!code-csharp[

public void SampleDeriveFromSP80056a()
{
    // Create a string that contains the algorithm name.
    String strAlgName = KeyDerivationAlgorithmNames.Sp80056aConcatSha512;

    // Open the specified algorithm.
    KeyDerivationAlgorithmProvider objKdfProv = KeyDerivationAlgorithmProvider.OpenAlgorithm(strAlgName);

    // Specify the requested size, in bytes, of the derived key. 
    UInt32 targetSize = 32;

    // Create a buffer that contains the secret to be used during derivation.
    IBuffer buffSecret = CryptographicBuffer.GenerateRandom(32);

    // Create a buffer that contains the intended purpose of the derived key.
    String strAlgId = "Purpose";
    IBuffer buffAlgId = CryptographicBuffer.ConvertStringToBinary(strAlgId, BinaryStringEncoding.Utf8);

    // Create a buffer that contains public information contributed by the initiator.
    String strPartyUInfo = "Initiator public info";
    IBuffer buffPartyUInfo = CryptographicBuffer.ConvertStringToBinary(strPartyUInfo, BinaryStringEncoding.Utf8);

    // Create a buffer that contains public information contributed by the responder.
    String strPartyVInfo = "Responder public info";
    IBuffer buffPartyVInfo = CryptographicBuffer.ConvertStringToBinary(strPartyVInfo, BinaryStringEncoding.Utf8);

    // Create a buffer that contains public information known to both parties.
    String strSuppPubInfo = "Two party public info";
    IBuffer buffSuppPubInfo = CryptographicBuffer.ConvertStringToBinary(strSuppPubInfo, BinaryStringEncoding.Utf8);

    // Create a buffer that contains a shared private secret.
    IBuffer buffSuppPrivInfo = CryptographicBuffer.GenerateRandom(32);

    // Create the derivation parameters.
    KeyDerivationParameters kdf80056AParamsEx = KeyDerivationParameters.BuildForSP80056a(
        buffAlgId,
        buffPartyUInfo,
        buffPartyVInfo,
        buffSuppPubInfo,
        buffSuppPrivInfo);

    // Create a key from the secret value.
    CryptographicKey keyOriginal = objKdfProv.CreateKey(buffSecret);

    // Derive a key based on the original key and the derivation parameters.
    IBuffer keyDerived = CryptographicEngine.DeriveKeyMaterial(
        keyOriginal,
        kdf80056AParamsEx,
        targetSize);

    // Encode the key to a hexadecimal value (for display)
    String strKeyHex = CryptographicBuffer.EncodeToHexString(keyDerived);
}

]