CARD_DERIVE_KEY Structure

The CARD_DERIVE_KEY structure specifies 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

Send comments about this topic to Microsoft

Build date: 3/5/2009