CardCreateContainer function
The CardCreateContainer function creates a new key container that is identified by the container index that the bContainerIndex argument specifies.
For applications in which the card does not support on-card key generation or if it is desired to archive the keys, the key material can be supplied with the call by specifying in flags that the card is to import the supplied key material.
Syntax
DWORD WINAPI CardCreateContainer(
_In_ PCARD_DATA pCardData,
_In_ BYTE bContainerIndex,
_In_ DWORD dwFlags ,
_In_ DWORD dwKeySpec ,
_In_ DWORD dwKeySize,
_In_ PBYTE 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.
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. These index numbers are assigned by the Base CSP/KSP. 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 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 call 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 a wrong value for bContainerIndex is passed (invalid or nonexistent), an SCARD_E_NO_KEY_CONTAINER return value is expected.
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 specifies 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 tries 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) |