CardDeriveKey function

The CardDeriveKey function provides information about a derived key, in compliance with the Federal Information Processing Standards (FIPS) publication 140-2 for smart cards.

When a call is made to the CardDeriveKey function, the pCardData parameter is set to the CARD_DATA structure that contains a pointer to the key derivation function (KDF). The KDFs are defined in a set of Cryptographic Next Generation (CNG) topics on MSDN. See CNG Reference for more information. For card minidrivers that only work with the hardware-based cryptographic algorithm called RSA, 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.

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

Send comments about this topic to Microsoft