MDEncryptData function

Article
11/21/2017

The MDEncryptData function uses a key handle to encrypt data with a symmetric key. The data is encrypted in a format that the smart card supports.

Syntax

DWORD WINAPI MDEncryptData(
  _In_  PCARD_DATA           pCardData,
  _In_  CARD_KEY_HANDLE      hKey,
  _In_  LPCWSTR              pwszSecureFunction,
  _In_  PBYTE                pbInput,
  _In_  DWORD                cbInput,
  _In_  DWORD                dwFlags,
  _Out_ PCARD_ENCRYPTED_DATA *ppEncryptedData,
  _Out_ PDWORD               pcEncryptedData
);

Parameters

pCardData [in]
Context information for the call. For more information, see CardAcquireContext.
hKey [in]
The handle of the cryptographic key that is used to encrypt the data.
pwszSecureFunction [in]
A pointer to a null-terminated Unicode string that contains the name of the data structure to be encrypted.
pbInput [in]
A byte pointer to the buffer that contains the data.
cbInput [in]
The length, in bytes, of the data buffer.
dwFlags [in]
A set of flags that specify options for the encryption operation. Currently, only one flag is supported.
ppEncryptedData [out]
A pointer to an array of CARD_ENCRYPTED_DATA structures. The buffer that contains the array is allocated by the minidriver and returned to the calling application
pcEncryptedData [out]
A pointer to a value that contains the number of returned encrypted data BLOBs.

Return value

Zero on success; otherwise, nonzero.

Remarks

If the card minidriver does not support encrypting data for secure transmission, the function should return SCARD_E_UNSUPPORTED_FEATURE.

The dwFlags parameter is used to specify flag settings for optional parameters for the encryption operation. Currently, the only allowed flag is CARD_BLOCK_PADDING, which specifies that the encrypted data should be padded by using PKCS #5. For more information, see the description of CP_PADDING_SCHEMES in CardGetProperty.

If dwFlags contains an invalid or undefined value, the function should return SCARD_E_INVALID_PARAMETER.

If an unsupported pwszSecureFunction value is passed to MDEncryptData, the function should return SCARD_E_INVALID_PARAMETER.

Note The minidriver may choose to define and support optional custom secure functions that are not defined in the specification.

The format of pbInput depends on the value of the pwszSecureFunction parameter. The following table describes the different supported values for pwszSecureFunction along with the corresponding format for pbInput:

pwszSecureFunction value	pbInput value
CSF_IMPORT_KEYPAIR	The data contains a structure of type CARD_IMPORT_KEYPAIR.
CSF_CHANGE_AUTHENTICATOR	The data contains a structure of type CARD_CHANGE_AUTHENTICATOR.
CSF_AUTHENTICATE	The data contains a structure of type CARD_AUTHENTICATE.

The function should allocate an array of CARD_ENCRYPTED_DATA structures and return them in the ppEncryptedData pointer.

This function can be called only when CARD_SECURE_KEY_INJECTION_NO_CARD_MODE is passed to CardAcquireContext.

If the appropriate properties are not set on the hKey key handle before the call to MDEncryptData, the function should return SCARD_E_INVALID_PARAMETER.

Requirements

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

Send comments about this topic to Microsoft

Share via