CARD_DERIVE_KEY structure

  • Article

This topic is not current. For the most current information about the Smart Card API, see Smart Card Minidriver Specification.

The CARD_DERIVE_KEY structure contains the key derivation function (KDF) that the CardDeriveKey function uses to derive a session key and receives the derived key on output.

Syntax

typedef struct _CARD_DERIVE_KEY {
  DWORD   dwVersion;
  DWORD   dwFlags;
  LPCWSTR pwszKDF;
  BYTE    bSecretAgreementIndex;
  PVOID   pParameterList;
  PUCHAR  pbDerivedKey;
  DWORD   cbDerivedKey;
} CARD_DERIVE_KEY, *PCARD_DERIVE_KEY;

Members

dwVersion

The version number of this structure, defined in Cardmod.h by the CARD_DERIVE_KEY_VERSION constant. The current version number is 1.

dwFlags

If CARD_BUFFER_SIZE_ONLY is specified, the smart card module returns only the size of the resulting key in the cbDerivedKey member and is not required to return the key in the pbDerivedKey member.

pwszKDF

A pointer to a null-terminated Unicode string that contains an object identifier (OID). The OID identifies the KDF that derives the key. The pwszKDF member can be one of the following strings.

Value Meaning
BCRYPT_KDF_HASH
L"HASH"
 Use the hash key derivation function. The parameters identified by the pParameterList parameter can contain the following parameters.
KDF_HASH_ALGORITHM
KDF_SECRET_PREPEND
KDF_SECRET_APPEND
BCRYPT_KDF_HMAC
L"HMAC"
 Use the Hash-Based Message Authentication Code (HMAC) key derivation function. The parameters identified by the pParameterList parameter can or must contain the following parameters.
KDF_HASH_ALGORITHM The default algorithm is SHA1.
KDF_HMAC_KEY
KDF_SECRET_PREPEND
KDF_SECRET_APPEND
BCRYPT_KDF_TLS_PRF
L"TLS_PRF"
 Use the transport layer security (TLS) pseudo-random function (PRF) key derivation function. The parameters identified by the pParameterList parameter can or must contain the following parameters.
KDF_TLS_PRF_LABEL
KDF_TLS_PRF_SEED

bSecretAgreementIndex

The index of the key container that holds the secret agreement. The CardDeriveKey function creates the session key from this agreement.

pParameterList

A pointer to a BCryptBufferDesc structure that contains the KDF parameters. This member is optional and can be NULL if it is not needed.

pbDerivedKey

The address of a buffer that receives the key. The cbDerivedKey member contains the size of this buffer. The buffer should be allocated by the CardDeriveKey function by calling the PFN_CSP_ALLOC function, and is freed by the smart card key storage provider (KSP).

cbDerivedKey

The size, in bytes, of the pbDerivedKey buffer.

Requirements
Minimum supported client
 Windows Vista [desktop apps only]
Minimum supported server
 Windows Server 2008 [desktop apps only]
Header
Cardmod.h