CardSignData function

  • Article

The CardSignData function signs a block of unpadded data. This entry either performs padding on the card or pads the data by using the PFN_CSP_PAD_DATA callback. All card minidrivers must support this entry point.

Syntax

DWORD WINAPI CardSignData(
  _In_ PCARD_DATA         pCardData,
       PCARD_SIGNING_INFO pInfo
);

Parameters

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

  • pInfo
    Structure that contains data to be signed, which is allocated by the Base CSP/KSP.

Return value

Zero on success; otherwise, nonzero.

Remarks

The Base CSP/KSP performs the hashing operation on the data before passing it to CardSignData for signature.

The pInfo parameter is formatted as a CARD_SIGNING_INFO structure, which is defined in Cardmod.h.

#define CARD_PADDING_INFO_PRESENT 0x40000000
#define CARD_BUFFER_SIZE_ONLY     0x20000000
#define CARD_PADDING_NONE         0x00000001
#define CARD_PADDING_PKCS1        0x00000002
#define CARD_PADDING_PSS          0x00000004

// CARD_SIGNING_INFO_BASIC_VERSION is provided for those                    
// applications do not intend to support passing in the                     
// pPaddingInfo structure                                                  
#define CARD_SIGNING_INFO_BASIC_VERSION 1                                  
// Function: CardSignData
//
// Purpose: Sign input data using a specified key
//

#define CARD_SIGNING_INFO_CURRENT_VERSION 2
typedef struct _CARD_SIGNING_INFO
{
    DWORD  dwVersion;

    BYTE   bContainerIndex;

    // See dwKeySpec constants
    DWORD  dwKeySpec;

    // If CARD_BUFFER_SIZE_ONLY flag is present then the card
    // module should return only the size of the resulting
    // key in cbSignedData
    DWORD  dwSigningFlags;

    // If the aiHashAlg is non zero, then it specifies the algorithm
    // to use when padding the data using PKCS
    ALG_ID aiHashAlg;

    // This is the buffer and length that the caller expects to be signed.
    // Signed version is allocated a buffer and put in cb/pbSignedData.
    // That should be freed using PFN_CSP_FREE callback.
    PBYTE  pbData;
    DWORD  cbData;

    PBYTE  pbSignedData;
    DWORD  cbSignedData;

    // The following parameters are new in version 2 of the
    // CARD_SIGNING_INFO structure.
    // If CARD_PADDING_INFO_PRESENT is set in dwSigningFlags then
    // pPaddingInfo will point to the BCRYPT_PADDING_INFO structure
    // defined by dwPaddingType. Currently supported values are
    // CARD_PADDING_PKCS1, CARD_PADDING_PSS and CARD_PADDING_NONE
    LPVOID pPaddingInfo;
    DWORD  dwPaddingType;

} CARD_SIGNING_INFO, *PCARD_SIGNING_INFO;

The dwSigningFlags member takes the same flag values as CryptSignHash, for example, CRYPT_NOHASHOID.

When the structure version is CARD_SIGNING_INFO_BASIC_VERSION, the minidriver should do only PKCS1 padding and use the value in aiHashAlg.

When the structure version is CARD_SIGNING_INFO_CURRENT_VERSION, there are two possibilities, depending on dwSigningFlags:

  • When CARD_PADDING_INFO_PRESENT is not set in dwSigningFlags, the minidriver should do only PKCS1 padding and use the value in aiHashAlg.
  • When CARD_PADDING_INFO_PRESENT is set in dwSigningFlags, the minidriver should get the padding algorithm from dwPaddingType, get padding parameters from pPaddingInfo, and ignore the value set in aiHashAlg.

If dwPaddingType is CARD_PADDING_PKCS1, pPaddingInfo should point to a BCRYPT_PKCS1_PADDING_INFO structure. If dwPaddingType is set to CARD_PADDING_PSS, pPaddingInfo should point to a BCRYPT_PSS_PADDING_INFO structure.

The aiHashAlg member takes those values allowed by ALG_ID from the HASH algorithm class. For a list of algorithm ID, see “ALG_ID” on MSDN.

For maximum interoperability with applications, we recommend that the following algorithm identifiers be supported for the aiHashAlg member:

  • CALG_TLS1PRF
  • CALG_MAC
  • CALG_SHA_256
  • CALG_SHA_384
  • CALG_SHA_512
  • CALG_HASH_REPLACE_OWF
  • CALG_MD2
  • CALG_MD4
  • CALG_MD5
  • CALG_SHA
  • CALG_SHA1
  • CALG_HUGHES_MD5
  • CALG_HMAC
  • CALG_SSL3_SHAMD5

If the aiHashAlg member is nonzero, it specifies the hash algorithm’s object identifier (OID) that is encoded in the PKCS padding. This padding is added to the hashed data to which the pbData parameter pointed. The card itself can add this padding, or the minidriver can request this padding to be added by using the PFN_CSP_PAD_DATA function.

The algorithm identifier that the pszAlgId member specified in pPaddingInfo takes those values that are allowed by CNG for hash algorithm identifier. For a complete list of algorithm identifiers, see CNG Algorithm Identifiers.

For maximum interoperability with applications, we recommend that only the following algorithm identifiers be supported for pszAlgId:

  • BCRYPT_MD2_ALGORITHM
  • BCRYPT_MD4_ALGORITHM
  • BCRYPT_MD5_ALGORITHM
  • BCRYPT_SHA1_ALGORITHM
  • BCRYPT_SHA256_ALGORITHM
  • BCRYPT_SHA384_ALGORITHM
  • BCRYPT_SHA512_ALGORITHM

Algorithms that the card does not support should result in CardSignData returning SCARD_E_UNSUPPORED_FEATURE.

When an invalid or nonexistent bContainerIndex is passed in the CARD_SIGNING_INFO structure, an SCARD_E_NO_KEY_CONTAINER error code should be returned.

When an invalid value for dwKeySpec is passed (see either CardCreateContainer or CardCreateContainerEx), SCARD_E_INVALID_PARAMETER should be returned. When the value for dwKeySpec is valid but not supported, SCARD_E_UNSUPPORTED_FEATURE must be returned.

Note  If the card does not support on-card padding, the card minidrivers are not required to inspect the parameters. It is expected that they call into padding callback function (pfnCspPadData) under normal operating conditions.

 

We recommend supporting the CARD_BUFFER_SIZE_ONLY flag, but this is optional. If supported, it helps reduce the amount of traffic to the card.

Card minidrivers that advertise that they are compatible with Version 5 must support both CARD_SIGNING_INFO_BASIC_VERSION and CARD_SIGNING_INFO_CURRENT_VERSION versions.

If the dwVersion member of the CARD_SIGNING_INFO structure has a value that is less than CARD_SIGNING_INFO_CURRENT_VERSION and the dwVersion member of pCardData is set to CARD_DATA_CURRENT_VERSION, this function should return ERROR_REVISION_MISMATCH. In other words, if the minidriver is loaded for the latest version, CARD_SIGNING_INFO must have the latest version of the structure as well.

The input data to be signed is passed in little-endian format.

Requirements

Target platform

 Desktop

Header

 Cardmod.h (include Cardmod.h)

 

 

Send comments about this topic to Microsoft