Cryptographic Provider

The Cryptographic Provider provides fundamental cryptographic services such as random number generation, authentication, and digital signature generation.

Access Control Rules

Before it calls any Cryptographic Provider function, the client application must first establish a security context with the Cryptographic Provider Provider Module by:

• Calling the discovery function, gscBsiGetCryptoProperties(), to return a CRYPTOAcr structure defining the access control rules for a CP service.

• Establishing the security context according to the retrieved ACR using the gscBsiUtilAcquireContext() function.

Function Summary

Access Control

Challenge

SKI

PKI

Function Details

gscBsiGetChallenge()

Retrieves a randomly generated challenge from the specified applet. Use this function only for strong key management requirements when you do not want the External Authentication key exposed in clear text. It is the first step for a strong authentication of the application to the card. The client application should then return the encrypted challenge to the card through a call to the gscBsiUtilAcquireContext() function. For further information about strong authentication, see Access Control Rules.

Syntax:

BSI_RETURN gscBsiGetChallenge(
IN BSI_CARD_HANDLE hCard,
IN BSI_BYTE_PTR uszAID,
IN BSI_ULONG unAIDLen,
INOUT BSI_BYTE_PTR uszChallenge,
INOUT BSI_ULONG_PTR unChallengeLen);

Parameters:

Returns:

BSI_OK
BSI_BAD_AID
BSI_BAD_HANDLE
BSI_BAD_PARAM
BSI_CARD_REMOVED
BSI_INSUFFICIENT_BUFFER
BSI_NO_CARDSERVICE
BSI_SC_LOCKED
BSI_UNKNOWN_ERROR

gscBsiGetCryptoProperties()

Retrieves the access control rules and private cryptographic key length managed by the Cryptographic Provider Module.

Syntax:

BSI_RETURN gscBsiGetCryptoProperties(
IN BSI_CARD_HANDLE hCard,
IN BSI_BYTE_PTR uszAID,
IN BSI_ULONG unAIDLen,
INOUT BSI_CRYPTO_ACR_PTR strctCRYPTOacr,
INOUT BSI_ULONG_PTR punKeyLen);

Parameters:

Returns:

BSI_OK
BSI_BAD_AID
BSI_BAD_HANDLE
BSI_BAD_PARAM
BSI_CARD_REMOVED
BSI_NO_CARDSERVICE
BSI_SC_LOCKED
BSI_UNKNOWN_ERROR

gscBsiPkiCompute()

Performs a private key computation on a message digest using the private key associated with the specified PKI applet.

Syntax:

BSI_RETURN gscBsiPkiCompute(
IN BSI_CARD_HANDLE hCard,
IN BSI_BYTE_PTR uszAID,
IN BSI_ULONG unAIDLen,
IN BSI_BYTE ucAlgoID,
IN BSI_BYTE_PTR uszMessage,
IN BSI_ULONG unMessageLen,
INOUT BSI_BYTE_PTR uszResult,
INOUT BSI_ULONG_PTR unResultLen);

Parameters:

Returns:

BSI_OK
BSI_ACCESS_DENIED
BSI_BAD_AID
BSI_BAD_ALGO_ID
BSI_BAD_HANDLE
BSI_BAD_PARAM
BSI_CARD_REMOVED
BSI_INSUFFICIENT_BUFFER
BSI_NO_CARDSERVICES
BSI_SC_LOCKED
BSI_UNKNOWN_ERROR

gscBsiPkiGetCertificate()

Reads a certificate from the card.

Syntax:

BSI_RETURN CALLBACK gscBsiPkiGetCertificate(
IN BSI_CARD_HANDLE hCard,
IN BSI_BYTE_PTR uszAID,
IN BSI_ULONG unAIDLen,
OUT BSI_BYTE_PTR uszCertificate,
INOUT BSI_ULONG_PTR unCertificateLen);

Parameters:

Returns:

BSI_OK
BSI_ACCESS_DENIED
BSI_BAD_AID
BSI_BAD_HANDLE
BSI_BAD_PARAM
BSI_CARD_REMOVED
BSI_INSUFFICIENT_BUFFER
BSI_NO_CARDSERVICE
BSI_READ_ERROR
BSI_SC_LOCKED
BSI_UNKNOWN_ERROR

gscBsiSkiInternalAuthenticate()

Computes a symmetric key cryptography authenticator in response to a challenge generated by the client application.

Syntax:

BSI_RETURN gscBsiSkiInternalAuthenticate(
IN BSI_CARD_HANDLE hCard,
IN BSI_BYTE_PTR uszAID,
IN BSI_ULONG unAIDLen,
IN BSI_BYTE ucAlgoID,
IN BSI_BYTE_PTR uszChallenge,
IN BSI_ULONG unChallengeLen,
OUT BSI_BYTE_PTR uszCryptogram,
INOUT BSI_ULONG_PTR unCryptogramLen);

Parameters:

Returns:

BSI_OK
BSI_ACCESS_DENIED
BSI_BAD_AID
BSI_BAD_ALGO_ID
BSI_BAD_HANDLE
BSI_BAD_PARAM
BSI_CARD_REMOVED
BSI_INSUFFICIENT_BUFFER
BSI_NO_CARDSERVICE
BSI_SC_LOCKED
BSI_TERMINAL_AUTH
BSI_UNKNOWN_ERROR