CardGetContainerProperty function

Article
11/21/2017

The CardGetContainerProperty function is modeled after the query functions of CAPI for keys. It takes a LPWSTR that indicates which parameter is being requested. Then it returns data written into the pbData parameter.

Syntax

DWORD WINAPI CardGetContainerProperty(
  _In_      PCARD_DATA pCardData,
  _In_      BYTE       bContainerIndex,
  _In_      LPWSTR     wszProperty,
  _Out_opt_ PBYTE      pbData,
  _In_      DWORD      cbData,
  _Out_     PBYTE      pdwDataLen
);

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 [out, optional]
Byte pointer to data buffer to receive the data.
cbData [in]
Length of input buffer.
pdwDataLen [out]
A pointer to a DWORD receiving the actual length of the data returned.

Return value

Zero on success; nonzero on failure.

Remarks

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

If an unsupported wszProperty is passed, the call should fail and return SCARD_E_INVALID_PARAMETER. Any minidriver can choose to define and support optional custom properties that are not defined in this specification.

If cbData is less than the length of the buffer to be returned, CardGetContainerProperty should return ERROR_INSUFFICIENT_BUFFER.

If CardGetContainerProperty is called with a nonexistent bContainerIndex parameter, it should return the 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_CONTAINER_INFO

wszProperty	pbData
CCP_CONTAINER_INFO	`typedef struct _CONTAINER_INFO { DWORD dwVersion; DWORD dwReserved; DWORD cbSigPublicKey; PBYTE pbSigPublicKey; DWORD cbKeyExPublicKey; PBYTE pbKeyExPublicKey; ) CONTAINER_INFO, PCONTAINER_INFO;` CardGetContainerProperty* allocates memory for pbKeyExPublicKey and pbSigPublicKey that the caller must free by calling PFN_CSP_FREE.
CCP_PIN_IDENTIFIER	CCP_PIN_IDENTIFIER In this situation, pbData contains a PIN_ID that describes the PIN identifier of the PIN that is associated with this container.
CCP_ASSOCIATED_ECDH_KEY	CCP_ASSOCIATED_ECDH_KEY This property requests the return of the corresponding ECDH key container index for an ECDSA key that was used during logon. The return value in pbData is a container index of the associated ECDH key.

typedef struct _CONTAINER_INFO
{
    DWORD      dwVersion;
    DWORD      dwReserved;

    DWORD      cbSigPublicKey;
    PBYTE      pbSigPublicKey;

    DWORD      cbKeyExPublicKey;
    PBYTE      pbKeyExPublicKey;
)
CONTAINER_INFO, *PCONTAINER_INFO;

CardGetContainerProperty allocates memory for pbKeyExPublicKey and pbSigPublicKey that the caller must free by calling PFN_CSP_FREE.

CCP_PIN_IDENTIFIER

CCP_PIN_IDENTIFIER In this situation, pbData contains a PIN_ID that describes the PIN identifier of the PIN that is associated with this container.

CCP_ASSOCIATED_ECDH_KEY

CCP_ASSOCIATED_ECDH_KEY This property requests the return of the corresponding ECDH key container index for an ECDSA key that was used during logon. The return value in pbData is a container index of the associated ECDH key.

Requirements

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

Send comments about this topic to Microsoft

Share via