CardGetProperty function

  • Article

The CardGetProperty function is modeled after the query functions of CAPI for keys. It takes a LPWSTR that indicates which parameter is being requested. The function returns data in the pbData parameter.

Syntax

DWORD WINAPI CardGetProperty(
  _In_      PCARD_DATA pCardData,
  _In_      LPWSTR     wszProperty,
  _Out_opt_ PBYTE      pbData,
  _In_      DWORD      cbData,
  _Out_     PDWORD     pdwDataLen,
  _In_      DWORD      dwFlags
);

Parameters

  • pCardData [in]
    Context information for the call. For more information, see CardAcquireContext.

  • wszProperty [in]
    The name of the requested property.

  • pbData [out, optional]
    Byte pointer to data buffer to receive the data.

  • cbData [in]
    Length of input the buffer.

  • pdwDataLen [out]
    Pointer to a DWORD value receiving the actual data length.

  • dwFlags [in]
    Flags for the operation.

Return value

Zero on success; nonzero on failure.

Remarks

CardGetProperty should check the dwFlags value. Unless dwFlags is specified for the property and the value is nonzero, it should fail and return SCARD_E_INVALID_PARAMETER.

If an unsupported wszProperty is passed to CardGetProperty, it should fail and return SCARD_E_INVALID_PARAMETER or SCARD_E_UNSUPPORTED_FEATURE. Implementing all the following properties is mandatory unless explicitly stated otherwise. 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 that is to be returned, CardGetProperty should return ERROR_INSUFFICIENT_BUFFER.

Note  Careful attention must be taken when returning CP_READ_ONLY_CARD as true. When this property is returned as true, all write operations to the card are blocked at the Base CSP layer.

 

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 type pbData value
CP_CARD_FREE_SPACE 
typedef struct _CARD_FREE_SPACE_INFO
{
    DWORD     dwVersion;
    DWORD     dwBytesAvailable;
    DWORD     dwKeyContainersAvailable;
    DWORD     dwMaxKeyContainers;
) CARD_FREE_SPACE_INFO, *PCARD_FREE_SPACE_INFO;
CP_CARD_CAPABILITIES 
typedef struct _CARD_CAPABILITIES
{
    DWORD     dwVersion;
    BOOL      fCertificateCompression;
    BOOL      fKeyGen;
)
CARD_CAPABILITIES, *PCARD_CAPABILITIES;

CP_CARD_KEYSIZES

The dwFlags parameter indicates key type to be queried. This is one of the AT_* defined values, such as AT_SIGNATURE or AT_ECDSA_P256.

typedef struct _CARD_KEY_SIZES
{
    DWORD     dwVersion;
    DWORD     dwMinimumBitlen;
    DWORD     dwDefaultBitlen;
    DWORD     dwMaximumBitlen;
    DWORD     dwIncrementalBitlen;
)
CARD_KEY_SIZES, *PCARD_KEY_SIZES;

A card minidriver that supports read-only cards may support more key types than what the specific read only card has been provisioned with. In this case the call may succeed and return a corresponding CARD_KEY_SIZES structure for the supported key spec.

CP_CARD_READ_ONLY

 BOOL

If True, all write operations are blocked at the Base CSP layer.

This flag also affects the data cache. If the card indicates that it is read-only, the Base CSP/KSP does not write to the cardcf file.

CP_CARD_CACHE_MODE

 DWORD 
#define CP_CACHE_MODE_GLOBAL_CACHE      1
#define CP_CACHE_MODE_SESSION_ONLY      2
#define CP_CACHE_MODE_NO_CACHE          3

CP_SUPPORTS_WIN_X509_ENROLLMENT

 BOOL

Indicates whether Windows PKI should be allowed to write or renew certificates on the card. This should be used to avoid unexpected results because of a lack of support for multiple PINs in Windows PKI enrollment client.

CP_CARD_GUID

 BYTE[]

In this situation, pbData is a buffer that contains a unique GUID for the card. This value must exactly match the GUID in the “cardid” file.

CP_CARD_SERIAL_NO

 BYTE[]

In this situation, pbData is a buffer that contains a serial number for the card. The format of the serial number is opaque to the Base CSP and is intended for other applications that query the card minidriver directly. This is an optional property that may be supported by the card.

CP_CARD_PIN_INFO

 PIN_INFO

In this situation, pbData is a PIN_INFO structure that contains information about the PIN. The dwFlags parameter contains the identifier of the PIN to return.

CP_CARD_LIST_PINS

 PIN_SET

In this situation, pbData contains a PIN_SET that indicates by a bit-mask what entities the card currently uses.

CP_CARD_AUTHENTICATED_STATE

 PIN_SET

In this situation, pbData contains a PIN_SET that indicates by a bit-mask what entities the card currently authenticates.

This is an optional property that may be supported by the card.

CP_CARD_PIN_STRENGTH_VERIFY

In this situation, pbData contains a bitmask of one or more of the following values:

  • CARD_PIN_STRENGTH_PLAINTEXT – Card can accept a plaintext PIN for authentication.
  • CARD_PIN_STRENGTH_SESSION_PIN – Card can generate a session PIN that can be used for subsequent authentications.
  • The dwFlags parameter contains the identifier of the PIN to return.

The following points apply to PIN strength:

  • Currently the PIN strength is ignored for EmptyPinType and ChallengeResponsePinType
  • Even if CARD_PIN_STRENGTH_SESSION_PIN is set for a PIN, the plaintext PIN must also be accepted for authentication. This is because trusted processes in Windows may use the plaintext PIN.

CP_KEY_IMPORT_SUPPORT

 DWORD

In this situation, pbData is a DWORD value. This value is a bitmask that describes the types of key import which the card supports.

#define     CARD_KEY_IMPORT_PLAIN_TEXT        0x1
#define     CARD_KEY_IMPORT_RSA_KEYEST        0x2
#define     CARD_KEY_IMPORT_ECC_KEYEST        0x4
#define     CARD_KEY_IMPORT_SHARED_SYMMETRIC  0x8

CP_ENUM_ALGORITHMS

 LPWSTR

In this situation, pbData contains a multistring value that describes the algorithms that the minidriver supports. The dwFlags parameter for this operation should contain one of the following values that define the type of algorithm enumeration to perform:

#define     CARD_CIPHER_OPERATION       0x1 // Symmetric operations
#define     CARD_ASYMMETRIC_OPERATION   0x2 // Asymmetric operations

This property is defined in version 7 and later versions of this specification.

Note  This property is read-only. 3DES_112 is for the situation in which the first and third keys are the same.
 

CP_PADDING_SCHEMES

 DWORD

In this situation, pbData contains a DWORD value. This value is a bitmask that describes the types of padding that the card supports for RSA cryptographic operations. The dwFlags parameter controls the cipher operation to which the query pertains. For more information, see the CP_ENUM_ALGORITHMS property value that was previously described.

For asymmetric keys, the return type contains the bitmask with the following padding schemes:

#define CARD_PADDING_PKCS1        0x00000002
#define CARD_PADDING_PSS          0x00000004
#define CARD_PADDING_OAEP         0x00000008

For symmetric keys, only one flag is defined that indicates whether the message was padded up to the next block size. If the message is a multiple of the block size, no padding is needed:

#define     CARD_BLOCK_PADDING          0x1

This property is defined in version 7 and later versions of this specification.

Note  This property is read-only. For symmetric key padding, only support for PKCS#5 padding will exist.
 

CP_CHAINING_MODES

 LPWSTR

In this situation, pbData contains a multistring value that describes the types of chaining modes that the card supports for symmetric key operations. Currently, the only supported chaining mode is cipher block chaining (CBC):

#define  CARD_CHAIN_MODE_CBC   L”ChainingModeCBC”

 

Requirements

Target platform

 Desktop

Header

 Cardmod.h (include Cardmod.h)

 

 

Send comments about this topic to Microsoft