CardImportSessionKey function

Article
11/21/2017

The CardImportSessionKey function imports a temporary session key to the card. The session key is encrypted with a key exchange key, and the function returns a handle of the imported session key to the caller.

Syntax

DWORD WINAPI CardImportSessionKey(
  _In_  PCARD_DATA pCardData,
  _In_  BYTE       bContainerIndex,
  _In_  VOID       *pPaddingInfo,
  _In_  LPCWSTR    pwszBlobType,
  _In_  LPCWSTR    pwszAlgId,
  _Out_ LPCWSTR    phKey,
  _In_  PBYTE      pbInput,
  _In_  DWORD      cbInput,
  _In_  DWORD      dwFlags
);

Parameters

pCardData [in]
Context information for the call. For more information, see CardAcquireContext.
bContainerIndex [in]
Index number for the container that is used to decrypt the key material in pbInput. This index value must identify an RSA key container. ECC keys cannot be used for this decryption operation.
pPaddingInfo [in]
A pointer to a structure that contains padding information. The type of structure to which this parameter points depends on the value of the dwFlags parameter.
pwszBlobType [in]
A pointer to a null-terminated Unicode string. This string identifies the type of BLOB in the pbInput buffer.
pwszAlgId [in]
A pointer to a null-terminated Unicode string. This string identifies algorithm of the key inside encrypted data. For more information, see the description of CP_ENUM_ALGORITHMS in CardGetProperty.
phKey [out]
A pointer to a CARD_KEY_HANDLE that receives the handle of the imported key. This handle is used in subsequent functions that require the key, such as CardProcessEncryptedData. The handle must be released when it is no longer needed by calling CardDestroyKey.
pbInput [in]
A byte pointer to the buffer that contains the key BLOB to be imported. The cbInput contains the size of this buffer. The pwszBlobType parameter specifies the type of key BLOB that this buffer contains. Everything should be encrypted with the exception of the BLOB header, if it is present.
cbInput [in]
IThe size, in bytes, of the key BLOB in the pbInput buffer.
dwFlags [in]
Index number for the container that is used to decrypt the key material in pbInput. This index value must identify an RSA key container. ECC keys cannot be used for this decryption operation.

Return value

Zero on success; otherwise, nonzero.

Remarks

If the card minidriver does not support the import of temporary symmetric keys, the function should return SCARD_E_UNSUPPORTED_FEATURE.

The following table describes the string values that are valid for the pwszBlobType parameter.

String value	Description
"KeyDataBlob"	The pbInput parameter is a pointer to a buffer that contains a BCRYPT_KEY_DATA_BLOB_HEADER structure. The key BLOB data immediately follows the BCRYPT_KEY_DATA_BLOB_HEADER structure in the buffer.

If pwszBlobType contains an invalid or undefined value, the function should return SCARD_E_INVALID_PARAMETER. For legacy applications and cards that use the minidriver interface for secure key injection, the minidriver can accept proprietary BLOB types.

If pwszAlgId contains an invalid or undefined value, the function should return SCARD_E_INVALID_PARAMETER. If the pwszAlgId value is defined but not supported, the function should return SCARD_E_UNSUPPORTED_FEATURE. For legacy cards, the minidriver can support other algorithms.

When the function returns, the phKey parameter should contain a handle to the imported key. If the parameter does not contain a valid pointer, the function should return SCARD_E_INVALID_PARAMETER. The key is expected to be valid until either CardDestroyKey is called or the card is removed from the reader.

The flags in the following table can be set in the dwFlags parameter.

Flag value	Description
CARD_PADDING_NONE	No padding was used. The pPaddingInfo parameter is not used.
CARD_PADDING_PKCS1	The data was padded with a random number when the data was encrypted. The pPaddingInfo parameter is not used.
CARD_PADDING_OAEP	The OAEP scheme was used when the data was encrypted. The pPaddingInfo parameter is a pointer to a BCRYPT_OAEP_PADDING_INFO structure.

Note Only one flag can be set in the dwFlags parameter.

If dwFlags contains an invalid or undefined value, the function should return SCARD_E_INVALID_PARAMETER. If dwFlags contains a value that is defined but not supported, the function should return SCARD_E_UNSUPPORTED_FEATURE.

Only users can create symmetric keys. If an administrator attempts to import a symmetric key, the function should return SCARD_W_SECURITY_VIOLATION.

Error checking is performed based on the order of cost. The minidriver should perform all parameter verification first without communicating to the card. Error conditions that would result in a return of SCARD_E_UNSUPPORTED_FEATURE must be checked first.

Requirements

Target platform	Desktop
Header	Cardmod.h (include Cardmod.h)