CardSetContainerProperty function

Article
11/21/2017

This function sets the properties on containers. The two container properties are supported are CCP_PIN_IDENTIFIER and CP_ASSOCIATED_ECDH_KEY.

Syntax

DWORD WINAPI CardSetContainerProperty(
  _In_ PCARD_DATA pCardData,
  _In_ BYTE       bContainerIndex,
  _In_ LPWSTR     wszProperty,
  _In_ PBYTE      pbData,
  _In_ DWORD      cbDataLen,
  _In_ DWORD      dwFlags
);

Parameters

pCardData [in]
Context information for the call. For more information, see CardAcquireContext.
bContainerIndex [in]
Index to a key container on the card.
wszProperty [in]
An LPWSTR that indicates which property is requested.
pbData [in]
Byte pointer to data buffer that contains the data.
cbDataLen [in]
Length of the data buffer pointed to by pbData.
dwFlags [in]
Reserved. Set to 0.

Return value

Zero on success; nonzero on failure.

Remarks

CardSetContainerProperty should check the dwFlags value. If this is nonzero, it should fail and return SCARD_E_INVALID_PARAMETER.

If an unsupported wszProperty is passed to CardSetContainerProperty, it should fail and return SCARD_E_INVALID_PARAMETER or SCARD_E_UNSUPPORTED_FEATURE.

Note Any minidriver can choose to define and support optional custom properties that are not defined in this specification.

If CardSetContainerProperty is called with a nonexistent bContainerIndex parameter, it should return an SCARD_E_NO_KEY_CONTAINER error.

The format of pbData is different depending on the wszProperty parameter that is passed to the function. The following table is a list of the different types that pbData takes depending on wszProperty (the structures are serialized as byte arrays).

wszProperty	pbData
CCP_PIN_IDENTIFIER	In this situation, pbData contains a DWORD that describes the PIN identifier to the PIN that is associated with this container. Although this function is not consumed by the Base CSP/KSP, the following are some guidelines for this function: When a new key is created on the card, the user PIN must be authenticated and the new key container is associated with ROLE_USER. This function is used to update the PIN property if needed. The PIN identifier can be updated only by using the user PIN or the administrator PIN. The administrator PIN cannot be associated with a key container. If the user PIN is currently authenticated and this function is called to associate the key container with, for example, PIN #3, PIN #3 must be authenticated to use this key. If the key container already has a PIN associated with it, ROLE_USER or the associated object PIN can be used to change the associated PIN.
CCP_ASSOCIATED_ECDH_KEY	CCP_ASSOCIATED_ECDH_KEY In this situation, pbData points to a container index for the ECDH key of an ECDSA key container. This creates an association between an ECDSA key and an ECDH key for logon.

CCP_PIN_IDENTIFIER

In this situation, pbData contains a DWORD that describes the PIN identifier to the PIN that is associated with this container.

Although this function is not consumed by the Base CSP/KSP, the following are some guidelines for this function:

When a new key is created on the card, the user PIN must be authenticated and the new key container is associated with ROLE_USER. This function is used to update the PIN property if needed.
The PIN identifier can be updated only by using the user PIN or the administrator PIN.
The administrator PIN cannot be associated with a key container.
If the user PIN is currently authenticated and this function is called to associate the key container with, for example, PIN #3, PIN #3 must be authenticated to use this key.

If the key container already has a PIN associated with it, ROLE_USER or the associated object PIN can be used to change the associated PIN.

CCP_ASSOCIATED_ECDH_KEY

CCP_ASSOCIATED_ECDH_KEY In this situation, pbData points to a container index for the ECDH key of an ECDSA key container. This creates an association between an ECDSA key and an ECDH key for logon.

Requirements

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

Send comments about this topic to Microsoft

Share via