CardDeriveKey function

The key derivation structure represents the majority of the required changes for FIPS 140-2 compliance for smart cards. It holds the requested key derivation function (KDF) and the associated input. The KDFs are defined in the “CNG Reference” documentation on MSDN. For RSA-only card minidrivers, this entry point is not defined and is set to NULL in the CARD_DATA structure that is returned from CardAcquireContext

Syntax


DWORD WINAPI CardDeriveKey(
  _In_     PCARD_DATA pCardData,
  _Inout_  PCARD_DERIVE_KEY pAgreementInfo
);

Parameters

pCardData [in]

Context information for the call. For more information, see CardAcquireContext.

pAgreementInfo [in, out]

On input, contains information that is related to the request for a derived key. On output, contains information that is related to the response for a derived key.

Return value

Zero on success; otherwise, nonzero.

Remarks

The pAgreementInfo parameter is formatted as a CARD_DERIVE_KEY structure.


#define CARD_DERIVE_KEY_VERSION_2 2

#define CARD_RETURN_KEY_HANDLE 0x1000000

typedef struct _CARD_DERIVE_KEY
{
    DWORD             dwVersion;

    // If CARD_BUFFER_SIZE_ONLY is passed then the card module
    // should return only the size of the resulting key in
    // cbDerivedKey
    DWORD             dwFlags;
    LPWSTR            pwszKDF;
    BYTE              bSecretAgreementIndex;

    PVOID             pParameterList;

    PBYTE             pbDerivedKey;
    DWORD             cbDerivedKey;

    // The following parameter can be used by the card to determine
    // key derivation material and to pass back a symmetric key
    // handle
    // as a result of the key derivation algorithm
    LPWSTR            pwszAlgId;
    DWORD             dwKeyLen;
    CARD_KEY_HANDLE   hKey;
} CARD_DERIVE_KEY, *PCARD_DERIVE_KEY;

If the dwVersion member is set to CARD_DERIVE_KEY_VERSION_2 and the CARD_RETURN_KEY_HANDLE flag is set in dwFlags, the minidriver should return a key handle in the hKey member instead of returning the key material through the pbDerivedKey and cbDerivedKey members.

On input, the following members must be set in the pAgreementInfo parameter and verified by the CardDeriveKey function.

dwVersion

Represents the revision of the CardDeriveKey functionality. The current version is 2. The current version is defined by CARD_DERIVE_KEY_VERSION.

dwFlags

Required to be zero, KDF_USE_SECRET_AS_HMAC _KEY_FLAG, CARD_RETURN_KEY_HANDLE, or CARD_BUFFER_SIZE_ONLY.

pwszKDF

A string that indicates the KDF to be used. This is set to the KDF that the client requests. These KDFs are defined in Bcrypt.h. The following is a list of possible KDFs:

BCRYPT_KDF_HASH
		BCRYPT_KDF_HMAC
		BCRYPT_KDF_TLS_PRF
		BCRYPT_KDF_SP80056A_CONCAT

For detailed information, see the “CNG Reference” documentation on MSDN. If a card minidriver does not implement the requested KDF, SCARD_E_INVALID_PARAMETER should be returned.

pParameterList

Contains the optional list of parameters to the key derivation algorithm. Type and number of parameters are determined and must be compatible by the key derivation function that the pwszKDF parameter selects. For information about acceptable parameters for a KDF, see CNG Reference.

If a card minidriver does not recognize one of the parameters or that parameter is invalid for the specified KDF, SCARD_E_INVALID_PARAMETER should be returned.

For hash-based KDFs, such as BCRYPT_KDF_HASH or BCRYPT_KDF_HMAC, the KDF_HASH_ALGORITHM may be NULL. In this situation, the minidriver must use a default hash algorithm. We recommend that the minidriver use the SHA-1 algorithm as documented in the CNG documentation for the NCryptDerivekey function.

dwAlgId

A value that identifies the algorithm to be used to derive the key. Possible values are as follows:

  • CARD_3DES_112_ALGORITHM
  • CARD_3DES_ALGORITHM
  • CARD_AES_ALGORITHM
dwkeyLen

Length, in bits, of the derived key. The possible values should not differ from the values that the CARD_KEY_SIZES structure returned when CardGetAlgorithmProperty is called for CP_CARD_KEYSIZES of the desired algorithm.

On output, the following members of the pAgreementInfo parameter must be set on a successful call.

TermDescription

pbDerivedKey

This is the buffer that contains the binary data of the derived key. The caller is responsible for calling the appropriate memory management function to allocate and deallocate this buffer.

To obtain the size of the required buffer for key derivation, the caller calls CardDeriveKey with CARD_BUFFER_SIZE_ONLY set in dwFlags. In this situation, the minidriver must return the size of the buffer in cbDerivedKey.

cbDerivedKey

Specifies the maximum length, in bytes, of the pbDerivedKey buffer.

hKey

When the dwVersion member is set to CARD_DERIVE_KEY_VERSION_2 and the CARD_RETURN_KEY_HANDLE flag is set in the dwFlags member, the minidriver should return a key handle in the hKey member instead of returning the key material in the pbDerivedKey and cbDerivedKey members.

 

If the dwFlags member is set to CARD_BUFFER_SIZE_ONLY, the minidriver must return the required size of the buffer in the cbDerivedKey member. The caller must use this data to allocate a buffer for the derived key, which is passed in through the pbDerivedKey member on subsequent calls to CardDeriveKey.

Requirements

Header

Cardmod.h (include Cardmod.h)

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft