CardCreateContainerEx function
The CardCreateContainerEx function creates a new key container that the container index identifies and the bContainerIndex parameter specifies. The function associates the key container with the PIN that the PinId parameter specified.
This function is useful if the card-edge does not allow for changing the key attributes after the key container is created. This function replaces the need to call CardSetContainerProperty to set the CCP_PIN_IDENTIFIER property CardCreateContainer is called.
Syntax
DWORD WINAPI CardCreateContainerEx(
_In_ PCARD_DATA pCardData,
_In_ BYTE bContainerIndex,
_In_ DWORD dwFlags ,
_In_ DWORD dwKeySpec ,
_In_ DWORD dwKeySize,
_In_ PBYTE pbKeyData,
_In_ PIN_ID pbKeyData
);
Parameters
pCardData [in]
Context information for the call. For more information, see CardAcquireContext.
bContainerIndex [in]
Index number for this container.
dwFlags [in]
Key container creation flags. Set to one of the following.
CARD_CREATE_CONTAINER_KEY_GEN
CARD_CREATE_CONTAINER_KEY_IMPORT
dwKeySpec [in]
Key type specifier. Set to one of the following for ECC keys.
AT_ECDHE_P256
AT_ECDHE_P384
AT_ECDHE_P521
AT_ECDSA_P256
AT_ECDSA_P384
AT_ECDSA_P521
The AT_SIGNATURE or AT_KEYEXCHANGE types specify RSA keys and are usable on dual-mode cards.
dwKeySize [in]
The size, in bits, of the key material. This value must be zero for ECC keys when the key is generated in the card. For RSA keys, this must specify the key bit length.
pbKeyData [in]
If dwFlags is set to CARD_CREATE_CONTAINER_KEY_IMPORT, a pointer to the passed key material, or else ignored for CARD_CREATE_CONTAINER_KEY_GEN.
pbKeyData [in]
PIN Identifier for the container.
Return value
Zero on success; otherwise, nonzero.
Remarks
Containers are referenced in the interface between the Base CSP/KSP and the card minidriver by index number. The Base CSP/KSP assigns these index numbers. Therefore, the Base CSP/KSP maintains a map file that is named mscp\Map on the card. This file lists the CAPI/CNG GUIDs for the containers that were used to this point on the card.
For a new container, the Base CSP/KSP selects the next container or a previously vacated one. A container can be vacated by setting the GUID information in the mscp\Map file to zero for that index.
The card minidriver can support both the CARD_CREATE_CONTAINER_KEY_GEN and CARD_CREATE_CONTAINER_KEY_IMPORT parameters, but must support at least one of these parameters.
If CARD_CREATE_CONTAINER_KEY_GEN or CARD_CREATE_CONTAINER_KEY_IMPORT is passed and the card does not support that feature, the function should return SCARD_E_UNSUPPORTED_FEATURE.
If the target container already exists, it is overwritten by the new one. The new container always contains a valid key if the call succeeds. The two methods of creating a new container are through random key generation and importing existing key data. If an invalid or nonexistent value for bContainerIndex is passed in the call, the function should return SCARD_E_NO_KEY_CONTAINER.
Imported key material is passed in a “private key BLOB,” which is typically returned from CryptExportKey. See Base Provider Key BLOBs for further information. RSA keys comply with the CAPI key BLOB format.
If the card supports the key type that dwKeySpec specified but dwKeySize is invalid or unsupported, the card minidriver should reject the operation and return either SCARD_E_INVALID_PARAMETER or SCARD_E_UNSUPPORTED_FEATURE.
If dwKeySpec is invalid or undefined, the function should return a value of SCARD_E_INVALID_PARAMETER. If the dwKeySpec value is defined but not supported, the function should return a value of SCARD_E_UNSUPPORTED_FEATURE.
Only users can create containers. Both administrators and users should be able to obtain information and delete containers. If an administrator attempts to create a container, the SCARD_W_SECURITY_VIOLATION error should be returned.
Error checking is performed based on the order of cost. The minidriver should perform all parameter verification first without communicating to the card. This would include the validation of the pbKeyData and dwKeySize parameters. 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) |