crypto.h File Reference

#include "globalplatform/types.h"
#include "globalplatform/library.h"
#include "globalplatform/unicode.h"
#include "globalplatform/error.h"
#include "globalplatform/security.h"

Include dependency graph for crypto.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	GP211_ECC_DOMAIN_PARAMETERS

Functions
OPGP_NO_API OPGP_ERROR_STATUS	calculate_CMAC_aes (PBYTE sMacKey, DWORD keyLength, BYTE *message, DWORD messageLength, PBYTE chainingValue, PBYTE mac)
	Creates a MAC for commands (APDUs) using CMAC AES. This is used by SCP03. The MAC for the message is the first 8 Bytes of mac. The next chainingValue is the full 16 Bytes of mac. Save this value for the next command MAC calculation. More...
OPGP_NO_API OPGP_ERROR_STATUS	calculate_key_check_value (GP211_SECURITY_INFO *secInfo, BYTE keyType, PBYTE keyData, DWORD keyDataLength, BYTE keyCheckValue[3])
OPGP_NO_API OPGP_ERROR_STATUS	encrypt_sensitive_data (GP211_SECURITY_INFO *secInfo, PBYTE data, DWORD dataLength, PBYTE encryptedData, PDWORD encryptedDataLength)
OPGP_NO_API OPGP_ERROR_STATUS	get_key_data_field (GP211_SECURITY_INFO *secInfo, PBYTE keyData, DWORD keyDataLength, BYTE keyType, PBYTE keyDataField, PDWORD keyDataFieldLength, BYTE keyCheckValue[3], BOOL includeKeyCheckValue)
OPGP_NO_API OPGP_ERROR_STATUS	create_session_key_SCP01 (BYTE key[16], BYTE cardChallenge[8], BYTE hostChallenge[8], PBYTE sessionKey)
OPGP_NO_API OPGP_ERROR_STATUS	create_session_key_SCP02 (BYTE key[16], BYTE constant[2], BYTE sequenceCounter[2], PBYTE sessionKey)
OPGP_NO_API OPGP_ERROR_STATUS	calculate_rsa_signature (PBYTE message, DWORD messageLength, OPGP_STRING PEMKeyFileName, char *passPhrase, PBYTE signature, PDWORD signatureLength)
OPGP_NO_API OPGP_ERROR_STATUS	calculate_ecc_signature (PBYTE message, DWORD messageLength, OPGP_STRING PEMKeyFileName, char *passPhrase, PBYTE signature, PDWORD signatureLength)
OPGP_NO_API OPGP_ERROR_STATUS	calculate_signature (PBYTE message, DWORD messageLength, OPGP_STRING PEMKeyFileName, char *passPhrase, PBYTE signature, PDWORD signatureLength)
OPGP_NO_API OPGP_ERROR_STATUS	validate_signature (PBYTE message, DWORD messageLength, OPGP_STRING PEMKeyFileName, char *passPhrase, PBYTE signature, DWORD signatureLength)
OPGP_NO_API OPGP_ERROR_STATUS	calculate_MAC (BYTE sessionKey[16], BYTE *message, DWORD messageLength, BYTE icv[8], BYTE mac[8])
OPGP_NO_API OPGP_ERROR_STATUS	calculate_enc_cbc (BYTE key[16], BYTE *message, DWORD messageLength, BYTE *encryption, DWORD *encryptionLength)
OPGP_NO_API OPGP_ERROR_STATUS	calculate_enc_cbc_SCP02 (BYTE key[16], BYTE *message, DWORD messageLength, BYTE *encryption, DWORD *encryptionLength)
OPGP_NO_API OPGP_ERROR_STATUS	calculate_enc_cbc_SCP03 (BYTE key[32], DWORD keyLength, BYTE *message, DWORD messageLength, PBYTE icv, PBYTE encryption, PDWORD encryptionLength)
OPGP_NO_API OPGP_ERROR_STATUS	calculate_enc_icv_SCP03 (PBYTE key, DWORD keyLength, LONG sessionEncryptionCounter, PBYTE icv, BOOL forResponse)
OPGP_NO_API OPGP_ERROR_STATUS	calculate_enc_ecb_single_des (BYTE key[8], BYTE *message, DWORD messageLength, BYTE *encryption, DWORD *encryptionLength)
OPGP_NO_API OPGP_ERROR_STATUS	calculate_card_cryptogram_SCP01 (BYTE S_ENCSessionKey[16], BYTE cardChallenge[8], BYTE hostChallenge[8], BYTE cardCryptogram[8])
OPGP_NO_API OPGP_ERROR_STATUS	calculate_card_cryptogram_SCP02 (BYTE S_ENCSessionKey[16], BYTE sequenceCounter[2], PBYTE cardChallenge, BYTE hostChallenge[8], BYTE cardCryptogram[8])
OPGP_NO_API OPGP_ERROR_STATUS	calculate_host_cryptogram_SCP01 (BYTE S_ENCSessionKey[16], BYTE cardChallenge[8], BYTE hostChallenge[8], BYTE hostCryptogram[8])
OPGP_NO_API OPGP_ERROR_STATUS	calculate_host_cryptogram_SCP02 (BYTE S_ENCSessionKey[16], BYTE sequenceCounter[2], PBYTE cardChallenge, BYTE hostChallenge[8], BYTE hostCryptogram[8])
OPGP_NO_API OPGP_ERROR_STATUS	create_session_key_SCP03 (BYTE key[32], DWORD keyLength, BYTE derivationConstant, BYTE cardChallenge[8], BYTE hostChallenge[8], PBYTE sessionKey)
OPGP_NO_API OPGP_ERROR_STATUS	calculate_card_challenge_SCP03 (BYTE S_ENC[32], DWORD keyLength, BYTE sequenceCounter[3], PBYTE invokingAID, DWORD invokingAIDLength, BYTE cardChallenge[8])
OPGP_NO_API OPGP_ERROR_STATUS	calculate_card_cryptogram_SCP03 (BYTE S_MACSessionKey[32], DWORD keyLength, BYTE cardChallenge[8], BYTE hostChallenge[8], BYTE cardCryptogram[8])
OPGP_NO_API OPGP_ERROR_STATUS	calculate_host_cryptogram_SCP03 (BYTE S_MACSessionKey[32], DWORD keyLength, BYTE cardChallenge[8], BYTE hostChallenge[8], BYTE hostCryptogram[8])
OPGP_NO_API OPGP_ERROR_STATUS	wrap_command (PBYTE apduCommand, DWORD apduCommandLength, PBYTE wrappedApduCommand, PDWORD wrappedApduCommandLength, GP211_SECURITY_INFO *secInfo)
	Wraps a command, i.e. encrypts and add the MAC to the APDU with the necessary security information according to secInfo. More...
OPGP_NO_API OPGP_ERROR_STATUS	unwrap_command (PBYTE apduCommand, DWORD apduCommandLength, PBYTE responseData, DWORD responseDataLength, PBYTE unwrappedResponseData, PDWORD unwrappedResponseDataLength, GP211_SECURITY_INFO *secInfo)
	Unwraps a response, i.e. decrypt and check the R-MAC of a response APDU with the necessary security information according to secInfo. More...
OPGP_NO_API OPGP_ERROR_STATUS	GP211_check_R_MAC (PBYTE apduCommand, DWORD apduCommandLength, PBYTE responseData, DWORD responseDataLength, PBYTE unwrappedResponseApdu, PDWORD unwrappedResponseApduLength, GP211_SECURITY_INFO *secInfo)
	Checks the R-MAC of an APDU with the necessary security information according to secInfo. More...
OPGP_NO_API OPGP_ERROR_STATUS	calculate_enc_ecb_two_key_triple_des (BYTE key[16], BYTE *message, DWORD messageLength, BYTE *encryption, DWORD *encryptionLength)
OPGP_NO_API OPGP_ERROR_STATUS	validate_receipt (PBYTE validationData, DWORD validationDataLength, BYTE receipt[16], PBYTE receiptKey, DWORD keyLength, BYTE secureChannelProtocol)
OPGP_NO_API OPGP_ERROR_STATUS	validate_receipt_ex (PBYTE validationData, DWORD validationDataLength, PBYTE receipt, DWORD receiptLength, PBYTE receiptKey, DWORD keyLength, BYTE receiptKeyType, OPGP_STRING PEMKeyFileName, char *passPhrase)
OPGP_NO_API OPGP_ERROR_STATUS	calculate_MAC_des_3des (BYTE _3des_key[16], BYTE *message, DWORD messageLength, BYTE initialICV[8], BYTE mac[8])
OPGP_NO_API OPGP_ERROR_STATUS	validate_install_receipt (PBYTE receiptKey, DWORD keyLength, GP211_RECEIPT_DATA receiptData, PBYTE executableLoadFileAID, DWORD executableLoadFileAIDLength, PBYTE applicationAID, DWORD applicationAIDLength, BYTE receiptKeyType, OPGP_STRING PEMKeyFileName, char *passPhrase)
OPGP_NO_API OPGP_ERROR_STATUS	validate_delete_receipt (PBYTE receiptKey, DWORD keyLength, GP211_RECEIPT_DATA receiptData, PBYTE AID, DWORD AIDLength, BYTE receiptKeyType, OPGP_STRING PEMKeyFileName, char *passPhrase)
OPGP_NO_API OPGP_ERROR_STATUS	validate_load_receipt (PBYTE receiptKey, DWORD keyLength, GP211_RECEIPT_DATA receiptData, PBYTE executableLoadFileAID, DWORD executableLoadFileAIDLength, PBYTE securityDomainAID, DWORD securityDomainAIDLength, BYTE receiptKeyType, OPGP_STRING PEMKeyFileName, char *passPhrase)
OPGP_NO_API OPGP_ERROR_STATUS	validate_extradition_receipt (PBYTE receiptKey, DWORD keyLength, GP211_RECEIPT_DATA receiptData, PBYTE oldSecurityDomainAID, DWORD oldSecurityDomainAIDLength, PBYTE newSecurityDomainAID, DWORD newSecurityDomainAIDLength, PBYTE applicationOrExecutableLoadFileAID, DWORD applicationOrExecutableLoadFileAIDLength, BYTE receiptKeyType, OPGP_STRING PEMKeyFileName, char *passPhrase)
OPGP_NO_API OPGP_ERROR_STATUS	validate_registry_update_receipt (PBYTE receiptKey, DWORD keyLength, GP211_RECEIPT_DATA receiptData, PBYTE oldSecurityDomainAID, DWORD oldSecurityDomainAIDLength, PBYTE applicationAID, DWORD applicationAIDLength, PBYTE newSecurityDomainAID, DWORD newSecurityDomainAIDLength, DWORD applicationPrivileges, PBYTE registryUpdateParameters, DWORD registryUpdateParametersLength, BYTE receiptKeyType, OPGP_STRING PEMKeyFileName, char *passPhrase)
OPGP_NO_API OPGP_ERROR_STATUS	read_public_rsa_key (OPGP_STRING PEMKeyFileName, char *passPhrase, PBYTE rsaModulus, PDWORD rsaModulusLength, LONG *rsaExponent)
	Reads a public RSA key from a file. More...
OPGP_NO_API OPGP_ERROR_STATUS	read_certificate_file (OPGP_STRING PEMKeyFileName, char *passPhrase, PBYTE certificateData, PDWORD certificateDataLength)
	Reads a certificate from a PEM or DER file.
OPGP_NO_API BOOL	contains_pem_certificate_header (const BYTE *data, DWORD dataLength)
	Checks whether data contains a PEM CERTIFICATE header.
OPGP_NO_API OPGP_ERROR_STATUS	convert_pem_certificate_list_to_der (const BYTE *pemData, DWORD pemDataLength, PBYTE derData, PDWORD derDataLength)
	Converts one or more PEM CERTIFICATE blocks to concatenated DER certificates.
OPGP_NO_API OPGP_ERROR_STATUS	convert_der_certificate_list_to_pem (const BYTE *derData, DWORD derDataLength, PBYTE pemData, PDWORD pemDataLength)
	Converts one or more concatenated DER X.509 certificates to PEM CERTIFICATE blocks.
OPGP_NO_API OPGP_ERROR_STATUS	prepare_scp11_der_x509_certificate_chain (const BYTE *derData, DWORD derDataLength, PBYTE preparedData, PDWORD preparedDataLength)
	Orders a DER X.509 chain for SCP11 verification and omits a self-issued trust anchor.
OPGP_NO_API OPGP_ERROR_STATUS	extract_scp11_ca_kloc_identifier_from_certificate_chain (const BYTE *certificateChainData, DWORD certificateChainDataLength, PBYTE authorityIdentifier, PDWORD authorityIdentifierLength)
	Extracts the CA-KLOC Identifier used to verify the first SCP11 certificate.
OPGP_NO_API OPGP_ERROR_STATUS	read_public_ecc_key (OPGP_STRING PEMKeyFileName, char *passPhrase, PBYTE eccPublicPoint, PDWORD eccPublicPointLength, PBYTE eccKeyComponentType, PBYTE keyParameterReference, GP211_ECC_DOMAIN_PARAMETERS *domainParameters)
	Reads a public ECC key from a file. More...
OPGP_NO_API OPGP_ERROR_STATUS	read_public_ecc_key_from_der_certificate (const BYTE *certificateData, DWORD certificateDataLength, PBYTE eccPublicPoint, PDWORD eccPublicPointLength, PBYTE eccKeyComponentType, PBYTE keyParameterReference)
	Extracts a public ECC key from a DER encoded X.509 certificate.
OPGP_NO_API OPGP_ERROR_STATUS	generate_ecc_keypair (int curveNid, PBYTE privateKey, PDWORD privateKeyLength, PBYTE publicKey, PDWORD publicKeyLength)
	Generates an ECC key pair for a named OpenSSL curve.
OPGP_NO_API OPGP_ERROR_STATUS	calculate_ecc_shared_secret (int curveNid, PBYTE privateKey, DWORD privateKeyLength, PBYTE peerPublicKey, DWORD peerPublicKeyLength, PBYTE sharedSecret, PDWORD sharedSecretLength)
	Calculates an ECDH shared secret for a named OpenSSL curve.
OPGP_NO_API OPGP_ERROR_STATUS	calculate_sha2_hash (PBYTE message, DWORD messageLength, BYTE hash[64], DWORD hashLength)
	Calculates a SHA-256 hash. More...
OPGP_NO_API OPGP_ERROR_STATUS	calculate_sha1_hash (PBYTE message, DWORD messageLength, BYTE hash[20])
	Calculates a SHA-1 hash. More...
OPGP_NO_API OPGP_ERROR_STATUS	calculate_sm3_hash (PBYTE message, DWORD messageLength, BYTE hash[32])
	Calculates a SM3 hash. More...
OPGP_NO_API OPGP_ERROR_STATUS	calculate_MAC_right_des_3des (BYTE key[16], BYTE *message, DWORD messageLength, BYTE mac[8])
	Calculates a MAC using first DES and 3DES for the final round when the padding is applied. More...
OPGP_NO_API OPGP_ERROR_STATUS	get_random (BYTE *random, int randomLength)

Detailed Description

This file contains internally used cryptographic related functionality.

Function Documentation

calculate_card_challenge_SCP03()

OPGP_NO_API OPGP_ERROR_STATUS calculate_card_challenge_SCP03	(	BYTE	S_ENC[32],
		DWORD	keyLength,
		BYTE	sequenceCounter[3],
		PBYTE	invokingAID,
		DWORD	invokingAIDLength,
		BYTE	cardChallenge[8]
	)

Calculates the card challenge when using pseudo-random challenge generation for SCP03.

Parameters

S_ENC	[in] The static S-ENC Key.
keyLength	[in] The key length in bytes (16, 24 or 32).
sequenceCounter	[in] The sequence counter.
invokingAID	The invoking AID byte buffer.
invokingAIDLength	The length of the invoking AID byte buffer.
cardChallenge	[out] The calculated challenge.

Returns

OPGP_ERROR_STATUS struct with error status OPGP_ERROR_STATUS_SUCCESS if no error occurs, otherwise error code and error message are contained in the OPGP_ERROR_STATUS struct

calculate_card_cryptogram_SCP01()

OPGP_NO_API OPGP_ERROR_STATUS calculate_card_cryptogram_SCP01	(	BYTE	S_ENCSessionKey[16],
		BYTE	cardChallenge[8],
		BYTE	hostChallenge[8],
		BYTE	cardCryptogram[8]
	)

Calculates the card cryptogram for SCP01.

Parameters

S_ENCSessionKey	[in] The S-ENC Session Key for calculating the card cryptogram.
cardChallenge	[in] The card challenge.
hostChallenge	[in] The host challenge.
cardCryptogram	[out] The calculated card cryptogram.

Returns

OPGP_ERROR_STATUS struct with error status OPGP_ERROR_STATUS_SUCCESS if no error occurs, otherwise error code and error message are contained in the OPGP_ERROR_STATUS struct

calculate_card_cryptogram_SCP02()

OPGP_NO_API OPGP_ERROR_STATUS calculate_card_cryptogram_SCP02	(	BYTE	S_ENCSessionKey[16],
		BYTE	sequenceCounter[2],
		PBYTE	cardChallenge,
		BYTE	hostChallenge[8],
		BYTE	cardCryptogram[8]
	)

Calculates the card cryptogram for SCP02.

Parameters

S_ENCSessionKey	[in] The S-ENC Session Key for calculating the card cryptogram.
sequenceCounter	[in] The sequence counter.
cardChallenge	[in] The card challenge.
hostChallenge	[in] The host challenge.
cardCryptogram	[out] The calculated card cryptogram.

Returns

OPGP_ERROR_STATUS struct with error status OPGP_ERROR_STATUS_SUCCESS if no error occurs, otherwise error code and error message are contained in the OPGP_ERROR_STATUS struct

calculate_card_cryptogram_SCP03()

OPGP_NO_API OPGP_ERROR_STATUS calculate_card_cryptogram_SCP03	(	BYTE	S_MACSessionKey[32],
		DWORD	keyLength,
		BYTE	cardChallenge[8],
		BYTE	hostChallenge[8],
		BYTE	cardCryptogram[8]
	)

Calculates the card cryptogram for SCP03.

Parameters

S_MACSessionKey	[in] The S-MAC Session Key for calculating the card cryptogram.
keyLength	[in] The key length in bytes (16, 24 or 32).
cardChallenge	[in] The card challenge.
hostChallenge	[in] The host challenge.
cardCryptogram	[out] The calculated host cryptogram.

Returns

OPGP_ERROR_STATUS struct with error status OPGP_ERROR_STATUS_SUCCESS if no error occurs, otherwise error code and error message are contained in the OPGP_ERROR_STATUS struct

calculate_CMAC_aes()

OPGP_NO_API OPGP_ERROR_STATUS calculate_CMAC_aes	(	PBYTE	sMacKey,
		DWORD	keyLength,
		BYTE *	message,
		DWORD	messageLength,
		PBYTE	chainingValue,
		PBYTE	mac
	)

Creates a MAC for commands (APDUs) using CMAC AES. This is used by SCP03. The MAC for the message is the first 8 Bytes of mac. The next chainingValue is the full 16 Bytes of mac. Save this value for the next command MAC calculation.

Parameters

sMacKey	[in] The S-MAC key (session MAC key) to use for MAC generation.
keyLength	[in] The AES key length in bytes (16, 24, or 32).
message	[in] The message to generate the MAC for.
messageLength	[in] The length of the message.
chainingValue	[in] The chaining value to use for the MAC generation. This is usually the full 16 Byte MAC generated for the last command or 16 bytes 0x00 for the first one (i.e. EXTERNAL AUTHENTICATE).
mac	[out] The full 16 Byte MAC. Append the first 8 Bytes to the message. Save the full 16 Bytes for further MAC generation if needed.

calculate_ecc_signature()

OPGP_NO_API OPGP_ERROR_STATUS calculate_ecc_signature	(	PBYTE	message,
		DWORD	messageLength,
		OPGP_STRING	PEMKeyFileName,
		char *	passPhrase,
		PBYTE	signature,
		PDWORD	signatureLength
	)

Backward compatible wrapper for callers using ECC-specific naming.

calculate_enc_cbc()

OPGP_NO_API OPGP_ERROR_STATUS calculate_enc_cbc	(	BYTE	key[16],
		BYTE *	message,
		DWORD	messageLength,
		BYTE *	encryption,
		DWORD *	encryptionLength
	)

Calculates the encryption of a message in CBC mode. Pads the message with 0x80 and additional 0x00 if message length is not a multiple of 8.

Parameters

key	[in] A 3DES key used to encrypt.
*message	[in] The message to encrypt.
messageLength	[in] The length of the message.
*encryption	[out] The encryption.
*encryptionLength	[out] The length of the encryption.

Returns

OPGP_ERROR_STATUS struct with error status OPGP_ERROR_STATUS_SUCCESS if no error occurs, otherwise error code and error message are contained in the OPGP_ERROR_STATUS struct

calculate_enc_cbc_SCP02()

OPGP_NO_API OPGP_ERROR_STATUS calculate_enc_cbc_SCP02	(	BYTE	key[16],
		BYTE *	message,
		DWORD	messageLength,
		BYTE *	encryption,
		DWORD *	encryptionLength
	)

Calculates the encryption of a message in CBC mode for SCP02. Pads the message with 0x80 and additional 0x00 until message length is a multiple of 8.

Parameters

key	[in] A 3DES key used to encrypt.
*message	[in] The message to encrypt.
messageLength	[in] The length of the message.
*encryption	[out] The encryption.
*encryptionLength	[out] The length of the encryption.

Returns

OPGP_ERROR_STATUS struct with error status OPGP_ERROR_STATUS_SUCCESS if no error occurs, otherwise error code and error message are contained in the OPGP_ERROR_STATUS struct

calculate_enc_ecb_single_des()

OPGP_NO_API OPGP_ERROR_STATUS calculate_enc_ecb_single_des	(	BYTE	key[8],
		BYTE *	message,
		DWORD	messageLength,
		BYTE *	encryption,
		DWORD *	encryptionLength
	)

Calculates the encryption of a message in ECB mode with single DES. Pads the message with 0x80 and additional 0x00 if message length is not a multiple of 8.

Parameters

key	[in] A DES key used to encrypt.
*message	[in] The message to encrypt.
messageLength	[in] The length of the message.
*encryption	[out] The encryption.
*encryptionLength	[out] The length of the encryption.

Returns

OPGP_ERROR_STATUS struct with error status OPGP_ERROR_STATUS_SUCCESS if no error occurs, otherwise error code and error message are contained in the OPGP_ERROR_STATUS struct

calculate_enc_ecb_two_key_triple_des()

OPGP_NO_API OPGP_ERROR_STATUS calculate_enc_ecb_two_key_triple_des	(	BYTE	key[16],
		BYTE *	message,
		DWORD	messageLength,
		BYTE *	encryption,
		DWORD *	encryptionLength
	)

Calculates the encryption of a message in ECB mode with two key triple DES. Pads the message with 0x80 and additional 0x00 if message length is not a multiple of 8.

Parameters

key	[in] A 3DES key used to encrypt.
*message	[in] The message to encrypt.
messageLength	[in] The length of the message.
*encryption	[out] The encryption.
*encryptionLength	[out] The length of the encryption.

Returns

OPGP_ERROR_STATUS struct with error status OPGP_ERROR_STALTUS_SUCCESS if no error occurs, otherwise error code and error message are contained in the OPGP_ERROR_STATUS struct

calculate_enc_icv_SCP03()

OPGP_NO_API OPGP_ERROR_STATUS calculate_enc_icv_SCP03	(	PBYTE	key,
		DWORD	keyLength,
		LONG	sessionEncryptionCounter,
		PBYTE	icv,
		BOOL	forResponse
	)

Calculates the encryption ICV for SCP03 using AES.

Parameters

key	[in] An AES key used to encrypt.
keyLength	[in] The key length. 16, 24 or 32 bytes.
sessionEncryptionCounter	[in] The session encryption counter.
icv	[out] The ICV to use.
forResponse	1 if the calculation is performed for the response.

Returns

OPGP_ERROR_STATUS struct with error status OPGP_ERROR_STATUS_SUCCESS if no error occurs, otherwise error code and error message are contained in the OPGP_ERROR_STATUS struct

calculate_host_cryptogram_SCP01()

OPGP_NO_API OPGP_ERROR_STATUS calculate_host_cryptogram_SCP01	(	BYTE	S_ENCSessionKey[16],
		BYTE	cardChallenge[8],
		BYTE	hostChallenge[8],
		BYTE	hostCryptogram[8]
	)

Calculates the host cryptogram for SCP01.

Parameters

S_ENCSessionKey	[in] The S-ENC Session Key for calculating the card cryptogram.
cardChallenge	[in] The card challenge.
hostChallenge	[in] The host challenge.
hostCryptogram	[out] The calculated host cryptogram.

Returns

OPGP_ERROR_STATUS struct with error status OPGP_ERROR_STATUS_SUCCESS if no error occurs, otherwise error code and error message are contained in the OPGP_ERROR_STATUS struct

calculate_host_cryptogram_SCP02()

OPGP_NO_API OPGP_ERROR_STATUS calculate_host_cryptogram_SCP02	(	BYTE	S_ENCSessionKey[16],
		BYTE	sequenceCounter[2],
		PBYTE	cardChallenge,
		BYTE	hostChallenge[8],
		BYTE	hostCryptogram[8]
	)

Calculates the host cryptogram for SCP02.

Parameters

S_ENCSessionKey	[in] The S-ENC Session Key for calculating the card cryptogram.
sequenceCounter	[in] The sequence counter.
cardChallenge	[in] The card challenge.
hostChallenge	[in] The host challenge.
hostCryptogram	[out] The calculated host cryptogram.

Returns

OPGP_ERROR_STATUS struct with error status OPGP_ERROR_STATUS_SUCCESS if no error occurs, otherwise error code and error message are contained in the OPGP_ERROR_STATUS struct

calculate_host_cryptogram_SCP03()

OPGP_NO_API OPGP_ERROR_STATUS calculate_host_cryptogram_SCP03	(	BYTE	S_MACSessionKey[32],
		DWORD	keyLength,
		BYTE	cardChallenge[8],
		BYTE	hostChallenge[8],
		BYTE	hostCryptogram[8]
	)

Calculates the host cryptogram for SCP03.

Parameters

S_MACSessionKey	[in] The S-MAC Session Key for calculating the card cryptogram.
keyLength	[in] The key length in bytes (16, 24 or 32).
cardChallenge	[in] The card challenge.
hostChallenge	[in] The host challenge.
hostCryptogram	[out] The calculated host cryptogram.

Returns

OPGP_ERROR_STATUS struct with error status OPGP_ERROR_STATUS_SUCCESS if no error occurs, otherwise error code and error message are contained in the OPGP_ERROR_STATUS struct

calculate_key_check_value()

OPGP_NO_API OPGP_ERROR_STATUS calculate_key_check_value	(	GP211_SECURITY_INFO *	secInfo,
		BYTE	keyType,
		PBYTE	keyData,
		DWORD	keyDataLength,
		BYTE	keyCheckValue[3]
	)

Parameters

*secInfo	[in, out] The pointer to the GP211_SECURITY_INFO structure returned by GP211_mutual_authentication().
keyType	[in] The key type. See GP211_KEY_TYPE_AES.
keyData	[in] The key data.
keyDataLength	[in] The key data length.
keyCheckValue	[out] The key check value.

Returns

OPGP_ERROR_STATUS struct with error status OPGP_ERROR_STATUS_SUCCESS if no error occurs, otherwise error code and error message are contained in the OPGP_ERROR_STATUS struct

calculate_MAC()

OPGP_NO_API OPGP_ERROR_STATUS calculate_MAC	(	BYTE	sessionKey[16],
		BYTE *	message,
		DWORD	messageLength,
		BYTE	icv[8],
		BYTE	mac[8]
	)

Calculates a message authentication code. Pads the message always with 0x80 and additional 0x00 until message length is a multiple of 8.

Parameters

sessionKey	[in] A 3DES key used to sign.
*message	[in] The message to authenticate.
messageLength	[in] The message length.
icv	[in] The initial chaining vector.
mac	[out] The calculated MAC.

Returns

OPGP_ERROR_STATUS struct with error status OPGP_ERROR_STATUS_SUCCESS if no error occurs, otherwise error code and error message are contained in the OPGP_ERROR_STATUS struct

calculate_MAC_des_3des()

OPGP_NO_API OPGP_ERROR_STATUS calculate_MAC_des_3des	(	BYTE	_3des_key[16],
		BYTE *	message,
		DWORD	messageLength,
		BYTE	initialICV[8],
		BYTE	mac[8]
	)

Calculates a message authentication code using the left half key of a two key 3DES key and the full key for the final operation. Pads the message always with 0x80 and additional 0x00 until message length is a multiple of 8.

Parameters

_3des_key	[in] A 3DES key used to sign.
*message	[in] The message to authenticate.
messageLength	[in] The message length.
initialICV	[in] The initial chaining vector.
mac	[out] The calculated MAC.

Returns

OPGP_ERROR_STATUS struct with error status OPGP_ERROR_STATUS_SUCCESS if no error occurs, otherwise error code and error message are contained in the OPGP_ERROR_STATUS struct

calculate_MAC_right_des_3des()

OPGP_NO_API OPGP_ERROR_STATUS calculate_MAC_right_des_3des	(	BYTE	key[16],
		BYTE *	message,
		DWORD	messageLength,
		BYTE	mac[8]
	)

Calculates a MAC using first DES and 3DES for the final round when the padding is applied.

Parameters

key	[in] A 3DES key used to sign. For DES the right half of the key is used.
*message	[in] The message to authenticate.
messageLength	[in] The message length.
mac	[out] The calculated MAC.

Returns

OPGP_ERROR_STATUS struct with error status OPGP_ERROR_STATUS_SUCCESS if no error occurs, otherwise error code and error message are contained in the OPGP_ERROR_STATUS struct

calculate_rsa_signature()

OPGP_NO_API OPGP_ERROR_STATUS calculate_rsa_signature	(	PBYTE	message,
		DWORD	messageLength,
		OPGP_STRING	PEMKeyFileName,
		char *	passPhrase,
		PBYTE	signature,
		PDWORD	signatureLength
	)

Backward compatible wrapper for callers using RSA-specific naming.

calculate_sha1_hash()

OPGP_NO_API OPGP_ERROR_STATUS calculate_sha1_hash	(	PBYTE	message,
		DWORD	messageLength,
		BYTE	hash[20]
	)

Calculates a SHA-1 hash.

Parameters

message	[in] The message to generate the hash for.
messageLength	[in] The length of the message buffer.
hash	[out] The calculated hash.

calculate_sha2_hash()

OPGP_NO_API OPGP_ERROR_STATUS calculate_sha2_hash	(	PBYTE	message,
		DWORD	messageLength,
		BYTE	hash[64],
		DWORD	hashLength
	)

Calculates a SHA-256 hash.

Parameters

message	[in] The message to generate the hash for.
messageLength	[in] The length of the message buffer.
hash	[out] The calculated hash.
hashLength	[in] The hash length for SCP03: 32 for AES-128, 48 for AES-192, 64 for AES-256.

calculate_signature()

OPGP_NO_API OPGP_ERROR_STATUS calculate_signature	(	PBYTE	message,
		DWORD	messageLength,
		OPGP_STRING	PEMKeyFileName,
		char *	passPhrase,
		PBYTE	signature,
		PDWORD	signatureLength
	)

Calculates a signature using an RSA or ECC private key from a PEM file. RSA and ECC signature encoding rules are selected automatically from the private key type.

Parameters

message	[in] The data to sign.
messageLength	[in] The length of the message buffer.
PEMKeyFileName	[in] A PEM file name with the private key.
*passPhrase	[in] The passphrase. Must be an ASCII string. May be NULL for unencrypted keys.
signature	[out] The calculated signature buffer.
signatureLength	[in,out] On input: size of signature buffer. On output: actual signature length.

calculate_sm3_hash()

OPGP_NO_API OPGP_ERROR_STATUS calculate_sm3_hash	(	PBYTE	message,
		DWORD	messageLength,
		BYTE	hash[32]
	)

Calculates a SM3 hash.

Parameters

message	[in] The message to generate the hash for.
messageLength	[in] The length of the message buffer.
hash	[out] The calculated hash (32 bytes for SM3).

create_session_key_SCP01()

OPGP_NO_API OPGP_ERROR_STATUS create_session_key_SCP01	(	BYTE	key[16],
		BYTE	cardChallenge[8],
		BYTE	hostChallenge[8],
		PBYTE	sessionKey
	)

Creates the session key for SCP01.

Parameters

key	[in] The Secure Channel Encryption Key or Secure Channel Message Authentication Code Key for calculating the corresponding session key.
cardChallenge	[in] The card challenge.
hostChallenge	[in] The host challenge.
sessionKey	[out] The calculated 3DES session key.

Returns

OPGP_ERROR_STATUS struct with error status OPGP_ERROR_STATUS_SUCCESS if no error occurs, otherwise error code and error message are contained in the OPGP_ERROR_STATUS struct

create_session_key_SCP02()

OPGP_NO_API OPGP_ERROR_STATUS create_session_key_SCP02	(	BYTE	key[16],
		BYTE	constant[2],
		BYTE	sequenceCounter[2],
		PBYTE	sessionKey
	)

Creates the session key for SCP02.

Parameters

key	[in] The Secure Channel Encryption Key or Secure Channel Message Authentication Code Key or Data Encryption Key for calculating the corresponding session key.
constant	[in] The constant for the corresponding session key.
sequenceCounter	[in] The sequence counter.
sessionKey	[out] The calculated 3DES session key.

Returns

OPGP_ERROR_STATUS struct with error status OPGP_ERROR_STATUS_SUCCESS if no error occurs, otherwise error code and error message are contained in the OPGP_ERROR_STATUS struct

create_session_key_SCP03()

OPGP_NO_API OPGP_ERROR_STATUS create_session_key_SCP03	(	BYTE	key[32],
		DWORD	keyLength,
		BYTE	derivationConstant,
		BYTE	cardChallenge[8],
		BYTE	hostChallenge[8],
		PBYTE	sessionKey
	)

Creates an AES-128 session key for SCP03.

Parameters

key	[in] The Secure Channel Encryption Key or Secure Channel Message Authentication Code Key for calculating the corresponding session key.
keyLength	[in] The key length. 16, 24 or 32 bytes.
derivationConstant	[in] The derivation constant, as defined in "Table 4-1: Data derivation constants" of SCP03.
cardChallenge	[in] The card challenge.
hostChallenge	[in] The host challenge.
sessionKey	[out] The calculated AES session key.

Returns

OPGP_ERROR_STATUS struct with error status OPGP_ERROR_STATUS_SUCCESS if no error occurs, otherwise error code and error message are contained in the OPGP_ERROR_STATUS struct

encrypt_sensitive_data()

OPGP_NO_API OPGP_ERROR_STATUS encrypt_sensitive_data	(	GP211_SECURITY_INFO *	secInfo,
		PBYTE	data,
		DWORD	dataLength,
		PBYTE	encryptedData,
		PDWORD	encryptedDataLength
	)

Parameters

*secInfo	[in, out] The pointer to the GP211_SECURITY_INFO structure returned by GP211_mutual_authentication().
data	[in] The data to encrypt.
dataLength	[in] The data length.
encryptedData	[out] The encrypted data. No length checking is done. The buffer must have sufficient size, e.g. the next block size or twice the data size if unsure.
encryptedDataLength	[out] The length of the encrypted data.

Returns

OPGP_ERROR_STATUS struct with error status OPGP_ERROR_STATUS_SUCCESS if no error occurs, otherwise error code and error message are contained in the OPGP_ERROR_STATUS struct

get_random()

OPGP_NO_API OPGP_ERROR_STATUS get_random	(	BYTE *	random,
		int	randomLength
	)

Parameters

*random	[out] The random to generate.
randomLength	[in] The random length to generate.

Returns

OPGP_ERROR_STATUS struct with error status OPGP_ERROR_STATUS_SUCCESS if no error occurs, otherwise error code and error message are contained in the OPGP_ERROR_STATUS struct

GP211_check_R_MAC()

OPGP_NO_API OPGP_ERROR_STATUS GP211_check_R_MAC	(	PBYTE	apduCommand,
		DWORD	apduCommandLength,
		PBYTE	responseApdu,
		DWORD	responseApduLength,
		PBYTE	unwrappedResponseApdu,
		PDWORD	unwrappedResponseApduLength,
		GP211_SECURITY_INFO *	secInfo
	)

Checks the R-MAC of an APDU with the necessary security information according to secInfo.

Parameters

apduCommand	[in] The command APDU.
apduCommandLength	[in] The length of the command APDU.
responseApdu	[in] The response APDU.
responseApduLength	[in] The length of the response APDU.
unwrappedResponseApdu	[out] The buffer for the unwrapped response APDU.
unwrappedResponseApduLength	[in, out] The available and returned modified length of the unwrappedResponseAPDU buffer.
*secInfo	[in] The pointer to the GP211_SECURITY_INFO structure returned by GP211_mutual_authentication().

Returns

OPGP_ERROR_STATUS struct with error status OPGP_ERROR_STATUS_SUCCESS if no error occurs, otherwise error code and error message are contained in the OPGP_ERROR_STATUS struct

read_public_ecc_key()

OPGP_NO_API OPGP_ERROR_STATUS read_public_ecc_key	(	OPGP_STRING	PEMKeyFileName,
		char *	passPhrase,
		PBYTE	eccPublicPoint,
		PDWORD	eccPublicPointLength,
		PBYTE	eccKeyComponentType,
		PBYTE	keyParameterReference,
		GP211_ECC_DOMAIN_PARAMETERS *	domainParameters
	)

Reads a public ECC key from a file.

Parameters

PEMKeyFileName	[in] The key file.
*passPhrase	[in] The passphrase. Must be an ASCII string.
eccPublicPoint	[out] The ECC public point in uncompressed form.
eccPublicPointLength	[inout] The ECC public point length passed in and returned.
eccKeyComponentType	[out] GP211_KEY_TYPE_ECC_PUBLIC_OR_PRIVATE or GP211_KEY_TYPE_ECC_SM2_PUBLIC_OR_PRIVATE.
keyParameterReference	[out] ECC key parameter reference (see GP211_KEY_TYPE_ECC_KEY_PARAMETER_REFERENCE_*).
domainParameters	[out] Optional ECC domain parameters for own-parameter key loading.

read_public_rsa_key()

OPGP_NO_API OPGP_ERROR_STATUS read_public_rsa_key	(	OPGP_STRING	PEMKeyFileName,
		char *	passPhrase,
		PBYTE	rsaModulus,
		PDWORD	rsaModulusLength,
		LONG *	rsaExponent
	)

Reads a public RSA key from a file.

Parameters

PEMKeyFileName	[in] The key file.
*passPhrase	[in] The passphrase. Must be an ASCII string.
rsaModulus	[out] The RSA modulus.
rsaModulusLength	[inout] The RSA modules length passed in and returned.
rsaExponent	[out] The RSA exponent.

unwrap_command()

OPGP_NO_API OPGP_ERROR_STATUS unwrap_command	(	PBYTE	apduCommand,
		DWORD	apduCommandLength,
		PBYTE	responseApdu,
		DWORD	responseApduLength,
		PBYTE	unwrappedResponseApdu,
		PDWORD	unwrappedResponseApduLength,
		GP211_SECURITY_INFO *	secInfo
	)

Unwraps a response, i.e. decrypt and check the R-MAC of a response APDU with the necessary security information according to secInfo.

Parameters

apduCommand	[in] The command APDU.
apduCommandLength	[in] The length of the command APDU.
responseApdu	[in] The response data.
responseApduLength	[in] The length of the response data.
unwrappedResponseApdu	[out] The buffer for the unwrapped response APDU.
unwrappedResponseApduLength	[in, out] The available and returned modified length of the unwrappedResponseAPDU buffer.
*secInfo	[in] The pointer to the GP211_SECURITY_INFO structure returned by GP211_mutual_authentication().

Returns

OPGP_ERROR_STATUS struct with error status OPGP_ERROR_STATUS_SUCCESS if no error occurs, otherwise error code and error message are contained in the OPGP_ERROR_STATUS struct

wrap_command()

OPGP_NO_API OPGP_ERROR_STATUS wrap_command	(	PBYTE	apduCommand,
		DWORD	apduCommandLength,
		PBYTE	wrappedApduCommand,
		PDWORD	wrappedApduCommandLength,
		GP211_SECURITY_INFO *	secInfo
	)

Wraps a command, i.e. encrypts and add the MAC to the APDU with the necessary security information according to secInfo.

Wraps a APDU with the necessary security information according to secInfo. The wrappedapduCommand must be a buffer with enough space for the potential added padding for the encryption and the MAC. The maximum possible extra space to the apduCommandLength is 8 bytes for the MAC plus 7 bytes for padding and one Lc byte in the encryption process.

Parameters

apduCommand	[in] The command APDU.
apduCommandLength	[in] The length of the command APDU.
wrappedApduCommand	[out] The buffer for the wrapped APDU command.
wrappedApduCommandLength	[in, out] The available and returned modified length of the wrappedApduCommand buffer.
*secInfo	[in] The pointer to the GP211_SECURITY_INFO structure returned by GP211_mutual_authentication().

Returns

OPGP_ERROR_STATUS struct with error status OPGP_ERROR_STATUS_SUCCESS if no error occurs, otherwise error code and error message are contained in the OPGP_ERROR_STATUS struct