10.3. A71CH Legacy API

10.3.1. Introduction

The A71CH Legacy API encapsulates the APDU calls supported by the A71CH security module. The standard A71CH security module supports the following functionality:

  • Secure storage, generation, insertion or deletion of ECC key pairs (ECC NIST P-256).

  • Secure storage, insertion or deletion of ECC public keys.

  • Signature generation and verification (ECDSA)

  • Shared secret calculation for Key Agreement (ECDH or ECDH-E)

  • Secure storage and use of monotonic counters (32 bits each)

  • Secure storage, insertion or deletion of symmetric keys (128 bits); symmetric keys can be concatenated to form longer keys

  • Retrieval of unique chip ID.

  • HKDF using the symmetric secrets as key, Extract & Expand or Expand only.

  • HMAC SHA256 calculation

  • Freezing of credentials (= OTP behavior)

  • An optional secure channel with the host MCU (conform Global Platform SCP03).

The Debug Mode variant of the A71CH security module, which can be ordered on evaluation kits, supports the following additional functionality:

  • A set of debug commands to facilitate integration of the A71CH in a host application.

  • Possibility to permanently disable these debug commands

Note

In the remainder of this document the A71CH Legacy API is simply called A71CH API

10.3.2. A71CH API

The A71CH API is made up of four parts:

  • A71CH specific functionality (.../hostlib/inc/a71ch_api.h)

    • Crypto Derive API deals with deriving secrets, hmacs etc. from stored secrets

    • Ecc Key API deals with ECC crypto building blocks as ECDSA signing and verification and ECDH

    • Module API deals with functions not related to stored crypto credentials

    • Secure Storage (SST) API deals with storing, retrieving, erasing and locking credentials

  • Data link communication functionality (sm_connect.c)

  • Secure channel functionality (ax_scp.h). The implementation resides in ax_scp.c and scp_a7x.c.

  • A71CH Debug Mode variant functionality (a71_debug.c)

10.3.3. SW structure

10.3.3.1. OpenSSL

The following picture illustrates the Host Library in the context of the Host SW with OpenSSL

../_images/A71CH_HostLib_SW_Layers_OpenSSL.svg

10.3.3.2. mbed TLS

The following picture illustrates the Host Library in the context of the Host SW with mbed TLS

../_images/A71CH_HostLib_SW_Layers_mbedTLS.svg

10.3.4. API details

10.3.4.1. Module API

Description

Wrap module centric APDU functionality of the A71CH

Functions

U16 A71_GetCredentialInfo(U8 *map, U16 *mapLen)

Get credential info from Module (in raw format)

Parameters
  • [inout] map:

  • [inout] mapLen:

Return Value
  • ::SW_OK: Upon successful execution

U16 A71_GetModuleInfo(U16 *selectResponse, U8 *debugOn, U8 *restrictedKpIdx, U8 *transportLockState, U8 *scpState, U8 *injectLockState, U16 *gpStorageSize)

Get info on Module

Parameters
  • [out] selectResponse: Encodes applet revision and whether Debug Mode is available

  • [out] debugOn: Equals 0x01 when the Debug Mode is available

  • [out] restrictedKpIdx: Either the index of the restricted keypair or A71CH_NO_RESTRICTED_KP

  • [out] transportLockState: The value retieved is one of A71CH_TRANSPORT_LOCK_STATE_LOCKED, A71CH_TRANSPORT_LOCK_STATE_UNLOCKED or A71CH_TRANSPORT_LOCK_STATE_ALLOW_LOCK

  • [out] scpState: The value retrieved is on of A71CH_SCP_MANDATORY, A71CH_SCP_NOT_SET_UP or A71CH_SCP_KEYS_SET

  • [out] injectLockState: The value retrieved is one of A71CH_INJECT_LOCK_STATE_LOCKED or A71CH_INJECT_LOCK_STATE_UNLOCKED

  • [out] gpStorageSize: Total storage size (in byte) of the General Purpose data store

Return Value
  • ::SW_OK: Upon successful execution

U16 A71_GetUniqueID(U8 *uid, U16 *uidLen)

Get Unique Identifier from the Secure Module

Parameters
  • [inout] uid: IN: buffer to contain uid; OUT: uid retrieved from Secure Module

  • [inout] uidLen: IN: Size of buffer provided (at least A71CH_MODULE_UNIQUE_ID_LEN byte); OUT: length of retrieved unique identifier (expected to be A71CH_MODULE_UNIQUE_ID_LEN byte)

Return Value
  • ::SW_OK: Upon successful execution

  • ::ERR_WRONG_RESPONSE: In case an identifier with a length different from A71CH_MODULE_UNIQUE_ID_LEN was retrieved

U16 A71_GetCertUid(U8 *certUid, U16 *certUidLen)

Get cert uid from the Secure Module. The cert uid is a subset of the Secure Module Unique Identifier

Parameters
  • [inout] certUid: IN: buffer to contain cert uid; OUT: cert uid retrieved from Secure Module

  • [inout] certUidLen: IN: Size of buffer provided (at least A71CH_MODULE_CERT_UID_LEN byte); OUT: length of retrieved unique identifier (expected to be A71CH_MODULE_CERT_UID_LEN byte)

Return Value
  • ::SW_OK: Upon successful execution

  • ::ERR_WRONG_RESPONSE: In case the Secure Module Unique Identifier (i.e. the base uid) did not have the expected length

U16 A71_GetUnlockChallenge(U8 *challenge, U16 *challengeLen)

Get Unlock challenge from the Secure Module

Parameters
  • [inout] challenge: IN: buffer to contain challenge; OUT: challenge retrieved from Secure Module

  • [inout] challengeLen: IN: Size of buffer provided (at least A71CH_MODULE_UNLOCK_CHALLENGE_LEN byte); OUT: length of retrieved unique identifier (must be A71CH_MODULE_UNLOCK_CHALLENGE_LEN byte)

Return Value
  • ::SW_OK: Upon successful execution

  • ::ERR_WRONG_RESPONSE: In case an identifier with a length different from A71CH_MODULE_UNLOCK_CHALLENGE_LEN was retrieved

U16 A71_GetKeyPairChallenge(U8 *challenge, U16 *challengeLen)

Get Unlock challenge for a Keypair

Parameters
  • [inout] challenge: IN: buffer to contain challenge; OUT: challenge retrieved from Secure Module

  • [inout] challengeLen: IN: Size of buffer provided (at least A71CH_MODULE_UNLOCK_CHALLENGE_LEN byte); OUT: length of retrieved unique identifier (must be A71CH_MODULE_UNLOCK_CHALLENGE_LEN byte)

Return Value
  • ::SW_OK: Upon successful execution

  • ::ERR_WRONG_RESPONSE: In case an identifier with a length different from A71CH_MODULE_UNLOCK_CHALLENGE_LEN was retrieved

U16 A71_GetPublicKeyChallenge(U8 *challenge, U16 *challengeLen)

Get Unlock challenge for a Public Key

Parameters
  • [inout] challenge: IN: buffer to contain challenge; OUT: challenge retrieved from Secure Module

  • [inout] challengeLen: IN: Size of buffer provided (at least A71CH_MODULE_UNLOCK_CHALLENGE_LEN byte); OUT: length of retrieved unique identifier (must be A71CH_MODULE_UNLOCK_CHALLENGE_LEN byte)

Return Value
  • ::SW_OK: Upon successful execution

  • ::ERR_WRONG_RESPONSE: In case an identifier with a length different from A71CH_MODULE_UNLOCK_CHALLENGE_LEN was retrieved

U16 A71_GetRandom(U8 *random, U8 randomLen)

Retrieves a random byte array of size randomLen from the Secure Module. The maximum amount of data that can be retrieved depends on whether an authenticated channel (SCP03) has been set up. In case SCP03 has been set up, this (worst-case) maximum is A71CH_SCP03_MAX_PAYLOAD_SIZE

Parameters
  • [inout] random: IN: buffer to contain random value (at least of size randomLen); OUT: retrieved random data

  • [in] randomLen: Amount of byte to retrieve

Return Value
  • ::SW_OK: Upon successful execution

U16 A71_CreateClientHelloRandom(U8 *clientHello, U8 clientHelloLen)

Updates a 32 byte random value inside the A71CH and returns this value to the caller.

Post

A71CH is in a state it will accept A71_PskDeriveMasterSecret or A71_EcdhPskDeriveMasterSecret as an API call.

Parameters
  • [inout] clientHello: IN: buffer to contain random value (at least of size randomLen); OUT: retrieved random data

  • [in] clientHelloLen: Amount of byte to retrieve (must be equal to AX_TLS_PSK_HELLO_RANDOM_LEN)

Return Value
  • ::SW_OK: Upon successful execution

U16 A71_GetRestrictedKeyPairInfo(U8 *idx, U16 *nBlocks, U8 *blockInfo, U16 *blockInfoLen)

Get the index of the restricted key pair (idx) together with the number of modifiable blocks (nBlocks) in the locked GP storage area that is associated with the restricted key pair. Detailed info on block offset and block length is contained in the blockInfo byte array. Per block 2 bytes indicate the offset into GP storage and two bytes indicate the length of the modifiable block.

Parameters
  • [out] idx: Index of restricted key pair. A71CH_NO_RESTRICTED_KP in case there is no restricted key pair

  • [out] nBlocks: Number of modifiable blocks

  • [inout] blockInfo: IN: Storage to contain blockInfo; OUT: Raw info on block offset and block lenght per block.

  • [inout] blockInfoLen: IN: Size of blockInfo (in byte); OUT: effective size of blockInfo

Return Value
  • ::SW_OK: Upon successful execution

U16 A71_GetSha256(U8 *data, U16 dataLen, U8 *sha, U16 *shaLen)

Calculates the SHA256 value of the data provided as input.

Parameters
  • [in] data: Data buffer for which the SHA256 must be calculated

  • [in] dataLen: The length of data passed as argument

  • [inout] sha: IN: caller passes a buffer of at least 32 byte; OUT: contains the calculated SHA256

  • [inout] shaLen: IN: length of the sha buffer passed; OUT: because SHA256 is used this is 32 byte exact

Return Value
  • ::SW_OK: Upon successful execution

U16 A71_Sha256Init(void)

Initialise multistep SHA256.

Return Value
  • ::SW_OK: Upon successful execution

U16 A71_Sha256Update(U8 *data, U16 dataLen)

Update the data for calulating SHA256 value (in multistep).

Parameters
  • [in] data: Data buffer for which the SHA256 must be calculated

  • [in] dataLen: The length of data passed as argument

Return Value
  • ::SW_OK: Upon successful execution

U16 A71_Sha256Final(U8 *sha, U16 *shaLen)

calulating SHA256 value (in multistep).

Parameters
  • [inout] sha: IN: caller passes a buffer of at least 32 byte; OUT: contains the calculated SHA256

  • [inout] shaLen: IN: length of the sha buffer passed; OUT: because SHA256 is used this is 32 byte exact

Return Value
  • ::SW_OK: Upon successful execution

U16 A71_InjectLock()

This function disables - at device level - the ability to

  • Set symmetric keys without prior wrapping

  • Erase symmetric keys

  • Set ECC key pairs (private key part) without prior wrapping

  • Set ECC public key without prior wrapping

Return Value
  • ::SW_OK: Upon successful execution

U16 A71_LockModule()

This function locks the module (typically to protect the module during transport to production facilities). When the A71CH is locked the functionality is reduced to the following subset:

  • A71_GetUniqueID

  • A71_GetUnlockChallenge

  • A71_UnlockModule

  • A71_GetModuleInfo

Return Value
  • ::SW_OK: Upon successful execution

U16 A71_UnlockModule(U8 *code, U16 codeLen)

This function unlocks the module provided the correct code is provided as input argument. The A71CH can only be unlocked once: if the device is already unlocked, the device cannot be locked or unlocked again (it will remain unlocked).

The unlock code is calculated as follows:

  • Request a challenge from A71CH using A71_GetUnlockChallenge.

  • Decrypt the challenge in ECB mode using the appropriate configuration key value (the same as stored at index A71CH_CFG_KEY_IDX_MODULE_LOCK).

  • The decrypted value is the unlock code

    Parameters
    • [in] code: Value of unlock code

    • [in] codeLen: Length of unlock code (must be 16)

    Return Value
    • ::SW_OK: Upon successful execution

U16 A71_SetTlsLabel(const U8 *label, U16 labelLen)

Sets the label that is used when calling A71_EcdhPskDeriveMasterSecret or A71_PskDeriveMasterSecret. Calling this function is optional. By default the label used by the A71CH is 'master secret’ (no quotes) as applicable for TLS 1.2. The maximum size of the label that can be set is 24 byte.

Parameters
  • [in] label: Value to be stored and used as ‘label’ in TLS 1.2 protocol

  • [in] labelLen: Length of label (less than or equal to A71CH_TLS_MAX_LABEL)

Return Value
  • ::SW_OK: Upon successful execution

U16 A71_EccVerifyWithKey(const U8 *pKeyData, U16 keyDataLen, const U8 *pHash, U16 hashLen, const U8 *pSignature, U16 signatureLen, U8 *pResult)

Verifies whether pSignature is the signature of pHash using pKeyData as the verifying public key.

As opposed to function A71_EccVerify the public key value is passed as an argument to the A71CH.

Parameters
  • [in] pKeyData: Public key passed as byte array in ANSI X9.62 uncompressed format

  • [in] keyDataLen: Length of public key passed as argument

  • [in] pHash: Pointer to the provided hash (or any other bytestring).

  • [in] hashLen: Length of the provided hash.

  • [in] pSignature: Pointer to the provided signature.

  • [in] signatureLen: Length of the provided signature.

  • [out] pResult: Pointer to the computed result of the verification. Points to a value of 0x01 in case of successful verification

Return Value
  • ::SW_OK: Upon successful execution

10.3.4.2. Ecc Key API

Description

Wrap the ECC cryptographic functionality of the A71CH.

Functions

U16 A71_GenerateEccKeyPair(SST_Index_t index)

Generates an ECC keypair at storage location index.

Pre

INJECTION_LOCKED has not been set

Parameters
  • [in] index: Storage index of the keypair to be created.

Return Value
  • ::SW_OK: Upon successful execution

U16 A71_GenerateEccKeyPairWithChallenge(SST_Index_t index, const U8 *configKey, U16 configKeyLen)

Generates an ECC keypair at storage location index. This function must be called instead of A71_GenerateEccKeyPair in case INJECTION_LOCKED was set.

To use this function the value of the Key Pair configuration key must be known on the host. If this is not the case use A71_GenerateEccKeyPairWithCode instead.

Parameters
  • [in] index: Storage index of the keypair to be created.

  • [in] configKey: Value of Key Pair configuration key. This value has a high level of confidentiality and may not be available to the Host.

  • [in] configKeyLen: Length of Key Pair configuration key

Return Value
  • ::SW_OK: Upon successful execution

U16 A71_GenerateEccKeyPairWithCode(SST_Index_t index, const U8 *code, U16 codeLen)

Generates an ECC keypair at storage location index. This function must be called instead of A71_GenerateEccKeyPair in case INJECTION_LOCKED was set.

The assumption is the value of the Key Pair configuration key is not known on the host. If this does not apply use A71_GenerateEccKeyPairWithChallenge instead.

The code is calculated as follows:

  • Request a challenge from A71CH using A71_GetUnlockChallenge.

  • Decrypt the challenge in ECB mode using the appropriate configuration key value (the same as stored at index ::A71XX_CFG_KEY_IDX_PRIVATE_KEYS).

  • The decrypted value is the value of code

Parameters
  • [in] index: Storage index of the keypair to be created.

  • [in] code: Value of unlock code.

  • [in] codeLen: Length of unlock code (must be 16)

Return Value
  • ::SW_OK: Upon successful execution

U16 A71_EccSign(SST_Index_t index, const U8 *pHash, U16 hashLen, U8 *pSignature, U16 *pSignatureLen)

Signs the hash pHash using the keypair at the indicated index.

Parameters
  • [in] index: Storage index of the keypair (private key) to be used.

  • [in] pHash: Pointer to the provided hash (or any other bytestring).

  • [in] hashLen: Length of the provided hash.

  • [inout] pSignature: Pointer to the computed signature.

  • [inout] pSignatureLen: Pointer to the length of the computed signature.

Return Value
  • ::SW_OK: Upon successful execution

U16 A71_EccNormalizedAsnSign(SST_Index_t index, const U8 *pHash, U16 hashLen, U8 *pSignature, U16 *pSignatureLen)

Signs the hash pHash using the keypair at the indicated index.

The integer representation of the ECDSA signatures’ r and s component is modified to be in line with ASN.1 (Ensuring an integer value is always encoded in the smallest possible number of octets)

Parameters
  • [in] index: Storage index of the keypair (private key) to be used.

  • [in] pHash: Pointer to the provided hash (or any other bytestring).

  • [in] hashLen: Length of the provided hash.

  • [inout] pSignature: Pointer to the computed signature.

  • [inout] pSignatureLen: Pointer to the length of the computed signature.

Return Value
  • ::SW_OK: Upon successful execution

U16 A71_EccRestrictedSign(SST_Index_t index, const U8 *updateBytes, U16 updateBytesLen, U8 *invocationCount)

Patches a predetermined fixed size memory region in GP storage with the byte array updateBytes Creates a signed certificate - in place in GP storage - using a predetermined block of GP storage data

Parameters
  • [in] index: Storage index of the keypair (private key) to be used.

  • [in] updateBytes: Byte array to be written into GP storage

  • [in] updateBytesLen: Length of the provided byte array (updateBytes).

  • [out] invocationCount: Amount of times the underlying APDU has been called succesfully.

Return Value
  • ::SW_OK: Upon successful execution

U16 A71_EccVerify(SST_Index_t index, const U8 *pHash, U16 hashLen, const U8 *pSignature, U16 signatureLen, U8 *pResult)

Verifies whether pSignature is the signature of pHash using the public key stored under index as the verifying public key.

The index refers to an instance of the PUBLIC_KEY secure storage class on the A71CH.

Note

The public key of an ECC key pair cannot be used for a verify operation.

Note

A71_EccVerifyWithKey allows to pass the value of the public key rather than use a stored public key.

Parameters
  • [in] index: Storage index of the key used for the verification.

  • [in] pHash: Pointer to the provided hash (or any other bytestring).

  • [in] hashLen: Length of the provided hash (pHash).

  • [in] pSignature: Pointer to the provided signature.

  • [in] signatureLen: Length of the provided signature (pSignature)

  • [out] pResult: Pointer to the computed result of the verification. Points to a value of 0x01 in case of successful verification

Return Value
  • ::SW_OK: Upon successful execution

U16 A71_EcdhGetSharedSecret(U8 index, const U8 *pOtherPublicKey, U16 otherPublicKeyLen, U8 *pSharedSecret, U16 *pSharedSecretLen)

Generates and retrieves a shared secret ECC point pSharedSecret using the private key stored at index and a public key pOtherPublicKey passed as argument.

Parameters
  • [in] index: to the key pair (private key to be used)

  • [in] pOtherPublicKey: Pointer to the given public key.

  • [in] otherPublicKeyLen: Length of the given public key.

  • [inout] pSharedSecret: Pointer to the computed shared secret.

  • [inout] pSharedSecretLen: Pointer to the length of the computed shared secret.

Return Value
  • ::SW_OK: Upon successful execution

10.3.4.3. Crypto Derive API

Description

Wrap the key derivation functionality of the A71CH.

Functions

U16 A71_HkdfExpandSymKey(SST_Index_t index, U8 nBlock, const U8 *info, U16 infoLen, U8 *derivedData, U16 derivedDataLen)

The HMAC Key Derivation function derives a key from a stored secret using SHA256 as hash function according to [RFC5869]. Only the expand step will be executed.

The secret is stored in the SYM key store. It can be either 16, 32, 48 or 64 byte long. The Most Significant part of the secret resides in the storage location with the lowest index. The subsequent parts reside in the next storage locations. The nBlock parameter is equal to the length of the secret divided by 16. A secret with length 64 can only start at Index 0 of the SYM key store: a secret can not be stored wrapped around in the SYM key store.

Note

infoLen must be smaller than 254 byte.

Parameters
  • [in] index: Index of the SYM key store containing the MSB part of the pre-shared secret

  • [in] nBlock: Amount of blocks, equivalent to the pre-shared secret length when multiplied by 16

  • [in] info: Context and application specific information used in expand step

  • [in] infoLen: The length of the info data passed as argument

  • [inout] derivedData: IN: caller passes a buffer of at least derivedDataLen; OUT: contains the calculated derived data

  • [in] derivedDataLen: IN: length of the requested derivedData. Must be smaller than 256 byte.

Return Value
  • ::SW_OK: Successfull execution

U16 A71_HkdfSymKey(SST_Index_t index, U8 nBlock, const U8 *salt, U16 saltLen, const U8 *info, U16 infoLen, U8 *derivedData, U16 derivedDataLen)

The HMAC Key Derivation function derives a key from a stored secret using SHA256 as hash function according to [RFC5869]. Both the extract and expand steps will be executed.

In case a zero length salt value is passed as argument, this function is equivalent to A71_HkdfExpandSymKey: i.e. the extract step is skipped. To enforce the usage of the default salt value (a Bytestring of 32 zeroes) the caller must explicitly pass this default salt value as argument to this function.

The secret is stored in the SYM key store. It can be either 16, 32, 48 or 64 byte long. The Most Significant part of the secret resides in the storage location with the lowest index. The subsequent parts reside in the next storage locations. The nBlock parameter is equal to the length of the secret divided by 16. A secret with length 64 can only start at Index 0 of the SYM key store: a secret can not be stored wrapped around in the SYM key store.

Note

The sum of saltLen and infoLen must be smaller than 254 byte.

Parameters
  • [in] index: Index of the SYM key store containing the MSB part of the pre-shared secret

  • [in] nBlock: Amount of blocks, equivalent to the pre-shared secret length when multiplied by 16

  • [in] salt: Salt data used in extract step

  • [in] saltLen: The length of the salt data passed as argument

  • [in] info: Context and application specific information used in expand step

  • [in] infoLen: The length of the info data passed as argument

  • [inout] derivedData: IN: caller passes a buffer of at least derivedDataLen; OUT: contains the calculated derived data

  • [in] derivedDataLen: IN: length of the requested derivedData. Must be smaller than 256 byte.

Return Value
  • ::SW_OK: Successfull execution

U16 A71_PskDeriveMasterSecret(SST_Index_t index, U8 nBlock, const U8 *serverHelloRnd, U16 serverHelloRndLen, U8 *masterSecret)

This function calculates the PRF according to TLS1.2 [RFC5246]. The pre-master secret is formed - based upon a pre-shared secret (PSK) stored in the secure module - according to [RFC4279].

The pre-shared secret is stored in the SYM key store. It can be either 16, 32, 48 or 64 byte long. The Most Significant part of the pre-shared secret resides in the storage location with the lowest index. The subsequent parts reside in the next storage locations. The nBlock parameter is equal to the length of the PSK divided by 16.

A PSK cannot be stored wrapped around in the SYM key store.

The PRF creating the masterSecret also takes as parameter the concatentation of label (“master_secret”), ClientHello.random and ServerHello.random. This function only takes ServerHello.random as parameter: ClientHello.random has already been set by a call to A71_CreateClientHelloRandom, the value of the label (default is “master_secret”) can be overruled by a call to A71_SetTlsLabel.

Pre

This call must be preceded by a call to A71_CreateClientHelloRandom, no other A71CH API call (implying an APDU exchange between Host and A71CH) may be executed in between the invocation of A71_CreateClientHelloRandom and A71_PskDeriveMasterSecret

Parameters
  • [in] index: Index of the SYM key store containing the MSB part of the pre-shared secret

  • [in] nBlock: Amount of blocks, equivalent to the pre-shared secret length when multiplied by 16

  • [in] serverHelloRnd: ServerHello.random (concatenated with values already contained in A71CH)

  • [in] serverHelloRndLen: The length of serverHelloRnd passed as an argument

  • [inout] masterSecret: IN: caller passes a buffer of at least 48 byte; OUT: contains the calculated master Secret, TLS 1.2 mandates this to be 48 byte exact

Return Value
  • ::SW_OK: Successfull execution

U16 A71_EcdhPskDeriveMasterSecret(SST_Index_t indexKp, const U8 *publicKey, U16 publicKeyLen, SST_Index_t index, U8 nBlock, const U8 *serverHelloRnd, U16 serverHelloRndLen, U8 *masterSecret)

This function calculates the PRF according to TLS1.2 [RFC5246]. The pre-master secret is formed - based upon a pre-shared secret (PSK) stored in the secure module and on an ECDH calculation - according to [RFC5489].

The pre-shared secret is stored in the SYM key store. It can be either 16, 32, 48 or 64 byte long. The Most Significant part of the pre-shared secret resides in the storage location with the lowest index. The subsequent parts reside in the next storage locations. The nBlock parameter is equal to the length of the PSK divided by 16.

A PSK cannot be stored wrapped around in the SYM key store.

The PRF creating the masterSecret also takes as parameter the concatentation of label (“master_secret”), ClientHello.random and ServerHello.random. This function only takes ServerHello.random as parameter: ClientHello.random has already been set by a call to A71_CreateClientHelloRandom, the value of the label (default is “master_secret”) can be overruled by a call to A71_SetTlsLabel.

Pre

This call must be preceded by a call to A71_CreateClientHelloRandom, no other A71CH API call (implying an APDU exchange between Host and A71CH) may be executed in between the invocation of A71_CreateClientHelloRandom and A71_EcdhPskDeriveMasterSecret

Parameters
  • [in] indexKp: Index of the ECC keypair whose private key is used in the ECDH operation

  • [in] publicKey: Value of the public key to be used in ECDH operation

  • [in] publicKeyLen: Length of publicKey in byte

  • [in] index: Index of the SYM key store containing the MSB part of the pre-shared secret

  • [in] nBlock: Amount of blocks, equivalent to the pre-shared secret length when multiplied by 16

  • [in] serverHelloRnd: ServerHello.random (concatenated with values already contained in A71CH)

  • [in] serverHelloRndLen: The length of serverHelloRnd passed as an argument

  • [inout] masterSecret: IN: caller passes a buffer of at least 48 byte; OUT: contains the calculated master Secret, TLS 1.2 mandates this to be 48 byte exact

Return Value
  • ::SW_OK: Successfull execution

U16 A71_GetHmacSha256(SST_Index_t index, U8 nBlock, const U8 *data, U16 dataLen, U8 *hmac, U16 *hmacLen)

Calculates the HMAC on data using SHA256 as Hash Function according to [RFC2104]. The secret is stored in the SYM key store. It can be either 16, 32, 48 or 64 byte long. The Most Significant part of the secret resides in the storage location with the lowest index. The subsequent parts reside in the next storage locations. The nBlock parameter is equal to the length of the secret divided by 16. A secret with length 64 can only start at Index 0 of the SYM key store: a secret can not be stored wrapped around in the SYM key store.

Parameters
  • [in] index: Index of the SYM key store containing the MSB part of the pre-shared secret

  • [in] nBlock: Amount of blocks, equivalent to the pre-shared secret length when multiplied by 16

  • [in] data: Data buffer for which the HMAC-SHA256 must be calculated

  • [in] dataLen: The length of data passed as argument

  • [inout] hmac: IN: caller passes a buffer of at least 32 byte; OUT: contains the calculated hmac

  • [inout] hmacLen: IN: length of the hmac buffer passed; OUT: because SHA256 is used this is 32 byte exact

Return Value
  • ::SW_OK: Successfull execution

U16 A71_HmacSha256Init(SST_Index_t index, U8 nBlock)

Initialise multistep HMACSHA256.

Parameters
  • [in] index: Index of the SYM key store containing the MSB part of the pre-shared secret

  • [in] nBlock: Amount of blocks, equivalent to the pre-shared secret length when multiplied by 16

Return Value
  • ::SW_OK: Upon successful execution

U16 A71_HmacSha256Update(SST_Index_t index, U8 nBlock, U8 *data, U16 dataLen)

Update the data for calulating HMACSHA256 value (in multistep).

Parameters
  • [in] index: Index of the SYM key store containing the MSB part of the pre-shared secret

  • [in] nBlock: Amount of blocks, equivalent to the pre-shared secret length when multiplied by 16

  • [in] data: Data buffer for which the HMACSHA256 must be calculated

  • [in] dataLen: The length of data passed as argument

Return Value
  • ::SW_OK: Upon successful execution

U16 A71_HmacSha256Final(SST_Index_t index, U8 nBlock, U8 *hmac, U16 *hmacLen)

calulating HMACSHA256 value (in multistep).

Parameters
  • [in] index: Index of the SYM key store containing the MSB part of the pre-shared secret

  • [in] nBlock: Amount of blocks, equivalent to the pre-shared secret length when multiplied by 16

  • [inout] hmac: IN: caller passes a buffer of at least 32 byte; OUT: contains the calculated HMACSHA256

  • [inout] hmacLen: IN: length of the sha buffer passed; OUT: because HMACSHA256 is used this is 32 byte exact

Return Value
  • ::SW_OK: Upon successful execution

10.3.4.4. Secure Storage (SST) API

Description

Wrap the secure storage functionality of the A71CH.

Functions

U16 A71_SetEccKeyPair(SST_Index_t index, const U8 *publicKey, U16 publicKeyLen, const U8 *privateKey, U16 privateKeyLen)

Sets an ECC Key pair at storage location index with the provided values for public and private key. The private key can optionally be RFC3944 wrapped. Whether wrapping is applied or not is implicit in the length of the private key.

Parameters
  • [in] index: Storage index of the keypair to be created.

  • [in] publicKey: Pointer to the byte array containing the public key. The public key must be in ANSI X9.62 uncompressed format (including the leading 0x04 byte).

  • [in] publicKeyLen: Length of the public key (65 byte)

  • [in] privateKey: Pointer to the byte array containing the private key. The private key may be RFC3394 wrapped using the config key stored at index A71CH_CFG_KEY_IDX_PRIVATE_KEYS

  • [in] privateKeyLen: Length of the private key (either 32 byte for keys in plain format or 40 byte for keys in RFC3944 wrapped format)

Return Value
  • ::SW_OK: Upon successful execution

U16 A71_GetPublicKeyEccKeyPair(SST_Index_t index, U8 *publicKey, U16 *publicKeyLen)

Retrieves the ECC Public Key - from a key pair - from the storage location index into the provided buffer. The public key retrieved is in ANSI X9.62 uncompressed format (including the leading 0x04 byte).

Parameters
  • [in] index: Storage index of the key pair

  • [inout] publicKey: IN: buffer to contain public key byte array; OUT: public key

  • [inout] publicKeyLen: IN: size of provided buffer; OUT: Length of the retrieved public key

Return Value
  • ::SW_OK: Upon successful execution

  • ::ERR_BUF_TOO_SMALL: publicKey buffer is too small

U16 A71_GetEccKeyPairUsage(SST_Index_t index, U8 *restricted, U16 *usedCnt, U16 *maxUseCnt)

Retrieve the usage counter (i.e. how much times the key pair has been used so far to sign) and the maximum usage counter. If the key pair is NOT restricted, usage counter and maximum usage counter will be set to 0 and the restricted parameter will be 0 (otherwise it is 1)

Parameters
  • [in] index: Storage index of the key pair

  • [out] restricted: 0 when the key pair on index is not restricted; 1 if it is restricted. A restricted key pair is a key pair that can only be used to sign a dedicated area in GP storage.

  • [out] usedCnt: Number of times the key pair on index has been used to sign (assuming it is a restricted key pair)

  • [out] maxUseCnt: Indicates the maximum amount of signing operations associated with the key pair at index. In case the value is zero, there is no limit on the amount of signing operations.

U16 A71_FreezeEccKeyPair(SST_Index_t index)

Freezes an ECC key pair at storage location index. This means that the key pair can no longer be erased or its value changed.

Pre

INJECTION_LOCKED has not been set

Parameters
  • [in] index: Storage index of the key pair to be frozen.

Return Value
  • ::SW_OK: Upon successful execution

U16 A71_FreezeEccKeyPairWithChallenge(SST_Index_t index, U8 *configKey, U16 configKeyLen)

Freezes an ECC key pair at storage location index. This means that the key pair can no longer be erased or its value changed. This function must be called instead of A71_FreezeEccKeyPair in case INJECTION_LOCKED was set

The assumption is the value of the Key Pair configuration key is known on the host. If this does not apply use A71_FreezeEccKeyPairWithCode instead.

Parameters
  • [in] index: Storage index of the key pair to be frozen.

  • [in] configKey: Value of Key Pair configuration key. This value has a high level of confidentiality and may not be available to the Host.

  • [in] configKeyLen: Length of Key Pair configuration key

Return Value
  • ::SW_OK: Upon successful execution

U16 A71_FreezeEccKeyPairWithCode(SST_Index_t index, U8 *code, U16 codeLen)

Freezes an ECC key pair at storage location index provided the correct code value is passed as argument. Freezing the key pair means that it can no longer be erased or its value changed. This function must be called instead of A71_FreezeEccKeyPair in case INJECTION_LOCKED was set.

The assumption is the value of the Key Pair configuration key is not known on the host. If this does not apply use A71_FreezeEccKeyPairWithChallenge instead.

The code is calculated as follows:

  • Request a challenge from A71CH using A71_GetUnlockChallenge.

  • Decrypt the challenge in ECB mode using the appropriate configuration key value (the same as stored at index A71CH_CFG_KEY_IDX_PRIVATE_KEYS).

  • The decrypted value is the value of code

    Parameters
    • [in] index: Storage index of the key pair to be frozen.

    • [in] code: Value of unlock code

    • [in] codeLen: Length of unlock code (must be 16)

    Return Value
    • ::SW_OK: Upon successful execution

U16 A71_EraseEccKeyPair(SST_Index_t index)

Erases an ECC key pair at storage location index. This means that the key pair can no longer be used before a new value is set.

Pre

INJECTION_LOCKED has not been set

Parameters
  • [in] index: Storage index of the key pair to be frozen.

Return Value
  • ::SW_OK: Upon successful execution

U16 A71_EraseEccKeyPairWithChallenge(SST_Index_t index, U8 *configKey, U16 configKeyLen)

Erases an ECC key pair at storage location index. This means that the key pair can no longer be used before a new value is set. This function must be called instead of A71_EraseEccKeyPair in case INJECTION_LOCKED was set.

The assumption is the value of the Key Pair configuration key is known on the host. If this does not apply use A71_EraseEccKeyPairWithCode instead.

Parameters
  • [in] index: Storage index of the key pair to be frozen.

  • [in] configKey: Value of Key Pair configuration key. This value has a high level of confidentiality and may not be available to the Host.

  • [in] configKeyLen: Length of Key Pair configuration key

Return Value
  • ::SW_OK: Upon successful execution

U16 A71_EraseEccKeyPairWithCode(SST_Index_t index, U8 *code, U16 codeLen)

Erases an ECC key pair at storage location index. This means that the key pair can no longer be used before a new value is set. This function must be called instead of A71_EraseEccKeyPair in case INJECTION_LOCKED was set.

The assumption is the value of the Key Pair configuration key is not known on the host. If this does not apply use A71_EraseEccKeyPairWithChallenge instead.

The code is calculated as follows:

  • Request a challenge from A71CH using A71_GetUnlockChallenge.

  • Decrypt the challenge in ECB mode using the appropriate configuration key value (the same as stored at index A71CH_CFG_KEY_IDX_PRIVATE_KEYS).

  • The decrypted value is the value of code

    Parameters
    • [in] index: Storage index of the key pair to be frozen.

    • [in] code: Value of unlock code

    • [in] codeLen: Length of unlock code (must be 16)

    Return Value
    • ::SW_OK: Upon successful execution

U16 A71_SetEccPublicKey(SST_Index_t index, const U8 *publicKey, U16 publicKeyLen)

Sets an ECC Public Key at storage location index with the provided value for public key either in plain ANSI X9.62 uncompressed format or wrapped. Whether RFC3944 wrapping is applied or not is implicit in the length of the public key. In case RFC3944 wrapping is applied the first byte of the public key (the one indicating the public key format) is removed before applying wrapping.

Parameters
  • [in] index: Storage index of the public key to be set.

  • [in] publicKey: Pointer to the byte array containing the public key. The public key may be RFC3394 wrapped using the config key stored at index A71CH_CFG_KEY_IDX_PUBLIC_KEYS

  • [in] publicKeyLen: Length of the public key (either 65 byte for keys in plain format or 72 byte for keys in RFC3944 wrapped format)

Return Value
  • ::SW_OK: Upon successful execution

U16 A71_GetEccPublicKey(SST_Index_t index, U8 *publicKey, U16 *publicKeyLen)

Retrieves the ECC Public Key from the storage location index into the provided buffer. The public key is in ANSI X9.62 uncompressed format (including the leading 0x04 byte).

Parameters
  • [in] index: Storage index of the public key to be retrieved.

  • [inout] publicKey: IN: buffer to contain public key byte array; OUT: public key

  • [inout] publicKeyLen: IN: size of provided buffer; OUT: Length of the retrieved public key

Return Value
  • ::SW_OK: Upon successful execution

  • ::ERR_BUF_TOO_SMALL: publicKey buffer is too small

U16 A71_FreezeEccPublicKeyWithChallenge(SST_Index_t index, U8 *configKey, U16 configKeyLen)

Freezes an ECC public key at storage location index. This means that the public key can no longer be erased or its value changed. This function must be called instead of A71_FreezeEccPublicKey in case INJECTION_LOCKED was set.

The assumption is the value of the Public Key configuration key is known on the host. If this does not apply use A71_FreezeEccPublicKeyWithCode instead.

Parameters
  • [in] index: Storage index of the public key to be frozen.

  • [in] configKey: Value of Public Key Pair key. This value has a high level of confidentiality and may not be available to the Host.

  • [in] configKeyLen: Length of Public Key configuration key

Return Value
  • ::SW_OK: Upon successful execution

U16 A71_FreezeEccPublicKeyWithCode(SST_Index_t index, U8 *code, U16 codeLen)

Freezes an ECC public key at storage location index provided the correct code value is passed as argument. Freezing the public key means that it can no longer be erased or its value changed. This function must be called instead of A71_FreezeEccPublicKey in case INJECTION_LOCKED was set.

The assumption is the value of the Public Key configuration key is not known on the host. If this does not apply use A71_FreezeEccPublicKeyWithChallenge instead.

The code is calculated as follows:

  • Request a challenge from A71CH using A71_GetUnlockChallenge.

  • Decrypt the challenge in ECB mode using the appropriate configuration key value (the same as stored at index A71CH_CFG_KEY_IDX_PUBLIC_KEYS).

  • The decrypted value is the value of code

    Parameters
    • [in] index: Storage index of the key pair to be frozen.

    • [in] code: Value of unlock code

    • [in] codeLen: Length of unlock code (must be 16)

    Return Value
    • ::SW_OK: Upon successful execution

U16 A71_FreezeEccPublicKey(SST_Index_t index)

Freezes an ECC public key at storage location index. This means that the public key can no longer be erased or its value changed.

Parameters
  • [in] index: Storage index of the public key to be frozen.

Return Value
  • ::SW_OK: Upon successful execution

U16 A71_EraseEccPublicKey(SST_Index_t index)

Erases an ECC public key at storage location index. This means that the public key can no longer be used before a new value is set.

Pre

INJECTION_LOCKED has not been set

Parameters
  • [in] index: Storage index of the public key to be frozen.

Return Value
  • ::SW_OK: Upon successful execution

U16 A71_EraseEccPublicKeyWithChallenge(SST_Index_t index, U8 *configKey, U16 configKeyLen)

Erases an ECC public key at storage location index. This means that the public key can no longer be used before a new value is set. This function must be called instead of A71_EraseEccPublicKey in case INJECTION_LOCKED was set.

The assumption is the value of the Public Key configuration key is known on the host. If this does not apply use A71_EraseEccPublicKeyWithCode instead.

Parameters
  • [in] index: Storage index of the public key to be frozen.

  • [in] configKey: Value of Public Key Pair key. This value has a high level of confidentiality and may not be available to the Host.

  • [in] configKeyLen: Length of Public Key configuration key

Return Value
  • ::SW_OK: Upon successful execution

U16 A71_EraseEccPublicKeyWithCode(SST_Index_t index, U8 *code, U16 codeLen)

Erases an ECC public key at storage location index. This means that the public key can no longer be used before a new value is set. This function must be called instead of A71_EraseEccPublicKey in case INJECTION_LOCKED was set.

The assumption is the value of the Public Key configuration key is not known on the host. If this does not apply use A71_EraseEccPublicKeyWithChallenge instead.

The code is calculated as follows:

  • Request a challenge from A71CH using A71_GetUnlockChallenge.

  • Decrypt the challenge in ECB mode using the appropriate configuration key value (the same as stored at index A71CH_CFG_KEY_IDX_PUBLIC_KEYS).

  • The decrypted value is the value of code

    Parameters
    • [in] index: Storage index of the key pair to be frozen.

    • [in] code: Value of unlock code

    • [in] codeLen: Length of unlock code (must be 16)

    Return Value
    • ::SW_OK: Upon successful execution

U16 A71_SetSymKey(SST_Index_t index, const U8 *key, U16 keyLen)

Sets a symmetric key at storage location index with the key value. The key locations indexed are the same as the one referenced by A71_SetRfc3394WrappedAesKey

Parameters
  • [in] index: Storage index of the symmetric key to be set.

  • [in] key: Pointer to the byte array containing the symmetric key

  • [in] keyLen: Length of the symmetric key (must be 16)

Return Value
  • ::SW_OK: Upon successful execution

U16 A71_SetRfc3394WrappedAesKey(SST_Index_t index, const U8 *key, U16 keyLen)

Sets an RFC3394 wrapped AES key in secure storage. The key value being set, must be wrapped with the value already stored at index. The key locations indexed are the same as the one referenced by A71_SetSymKey

Parameters
  • [in] index: index of the key to be set. At the same time the index of the wrapping key.

  • [in] key: Pointer to the supplied key data.

  • [in] keyLen: Length of the supplied key data.

Return Value
  • ::SW_OK: Upon successful execution

U16 A71_FreezeSymKey(SST_Index_t index)

Freezes a symmetric key at storage location index. This means the value of the key at the specified index can no longer be changed.

Parameters
  • [in] index: Storage index of the symmetric key to be frozen.

Return Value
  • ::SW_OK: Upon successful execution

U16 A71_EraseSymKey(SST_Index_t index)

Erases the symmetric key at storage location index. This means the value of the key at the specified index is cleared. The value must be set anew before the key can be used.

Parameters
  • [in] index: Storage index of the symmetric key to be set.

Return Value
  • ::SW_OK: Upon successful execution

U16 A71_IncrementCounter(SST_Index_t index)

Increments the monotonic counter at storage location index by one.

Parameters
  • [in] index: Storage index of the counter.

Return Value
  • ::SW_OK: Upon successful execution

U16 A71_SetCounter(SST_Index_t index, U32 value)

Sets the value of the monotonic counter at storage location ‘index’ with the value passed as parameter.

Parameters
  • [in] index: Storage index of the counter.

  • [in] value: Counter value to be set

Return Value
  • ::SW_OK: Upon successful execution

U16 A71_GetCounter(SST_Index_t index, U32 *pValue)

Gets the value of the monotonic counter at storage location ‘index’.

Parameters
  • [in] index: Storage index of the counter.

  • [out] pValue: Counter value retrieved

Return Value
  • ::SW_OK: Upon successful execution

U16 A71_DbgEraseCounter(SST_Index_t index)

Sets the value of the monotonic counter at storage location ‘index’ to zero.

Note

Only available when the applet is in Debug Mode.

Parameters
  • [in] index: Storage index of the counter.

Return Value
  • ::SW_OK: Upon successful execution

U16 A71_SetGpData(U16 dataOffset, const U8 *data, U16 dataLen)

Sets a data chunk of General Purpose storage in the security module. Depending on the size of the chunk, this requires one or more APDU exchanges with the security module.

Pre

The addressed General Purpose storage is not locked.

Note

In case part of the addressed General Purpose storage is locked, only part of the provided data will have been written most likely leading to an inconsistent data set stored in General Purpose storage.

Parameters
  • [in] dataOffset: Offset for the data in the GP Storage.

  • [in] data: IN: buffer containing data to write

  • [in] dataLen: Amount of data to write

Return Value
  • ::SW_OK: Upon successful execution

U16 A71_SetGpDataWithLockCheck(U16 dataOffset, const U8 *data, U16 dataLen)

Sets a data chunk of General Purpose storage in the security module. Depending on the size of the chunk, this requires one or more APDU exchanges with the security module.

Pre

The addressed General Purpose storage is not locked.

Note

In case more than one apdu is required, this function first validates that each of the chunks of the addressed General Purpose storage is not locked, and only in that case try to write the provided data using A71_SetGpData()

Parameters
  • [in] dataOffset: Offset for the data in the GP Storage.

  • [in] data: IN: buffer containing data to write

  • [in] dataLen: Amount of data to write

Return Value
  • ::SW_OK: Upon successful execution

U16 A71_GetGpData(U16 dataOffset, U8 *data, U16 dataLen)

Retrieve a chunk of data from general purpose (GP) storage.

Parameters
  • [in] dataOffset: Offset for the data in the GP Storage.

  • [inout] data: IN: buffer to contain data; OUT: retrieved data

  • [in] dataLen: Amount of data to retrieve

Return Value
  • ::SW_OK: Upon successful execution

U16 A71_FreezeGpData(U16 dataOffset, U16 dataLen)

Mark a chunk in GP storage as frozen (meaning further modification of the GP storage area is disallowed). Both the dataOffset and dataLen must be aligned on A71CH_GP_STORAGE_GRANULARITY

Parameters
  • [in] dataOffset: Offset for the data in the GP Storage.

  • [in] dataLen: Amount of data to freeze

Return Value
  • ::SW_OK: Upon successful execution

U16 A71_SetConfigKey(SST_Index_t index, const U8 *key, U16 keyLen)

Sets a config key at storage location index with the key value. The key locations indexed are the same as the one referenced by A71_SetRfc3394WrappedConfigKey

Parameters
  • [in] index: Storage index of the config key to be set.

  • [in] key: Pointer to the byte array containing the config key

  • [in] keyLen: Length of the config key (must be 16)

Return Value
  • ::SW_OK: Upon successful execution

U16 A71_SetRfc3394WrappedConfigKey(SST_Index_t index, const U8 *key, U16 keyLen)

Sets an RFC3394 wrapped config key in secure storage. The key value being set, must be wrapped with the value already stored at the index. The key locations indexed are the same as the one referenced by A71_SetConfigKey

Parameters
  • [in] index: index of the key to be set. At the same time the index of the wrapping key.

  • [in] key: Pointer to the supplied key data.

  • [in] keyLen: Length of the supplied key data.

Return Value
  • ::SW_OK: Upon successful execution

10.3.4.5. sm_connect.c

Description

Implementation of basic communication functionality between Host and A71CH. (This file was renamed from a71ch_com.c into sm_connect.c.)

Functions

U16 SM_RjctConnect(void **conn_ctx, const char *connectString, SmCommState_t *commState, U8 *atr, U16 *atrLen)
U16 SM_I2CConnect(void **conn_ctx, SmCommState_t *commState, U8 *atr, U16 *atrLen, const char *pConnString)
U16 SM_Connect(void *conn_ctx, SmCommState_t *commState, U8 *atr, U16 *atrLen)

Establishes the communication with the Security Module (SM) at the link level and selects the A71CH applet on the SM. The physical communication layer used (e.g. I2C) is determined at compilation time.

Parameters
  • [inout] commState:

  • [inout] atr:

  • [inout] atrLen:

Return Value
  • ::SW_OK: Upon successful execution

U16 SM_Close(void *conn_ctx, U8 mode)

Closes the communication with the Security Module A new connection can be established by calling SM_Connect

Parameters
  • [in] mode: Specific information that may be required on the link layer

Return Value
  • ::SW_OK: Upon successful execution

U16 SM_SendAPDU(U8 *cmd, U16 cmdLen, U8 *resp, U16 *respLen)

Sends the command APDU to the Secure Module and retrieves the response APDU. The latter consists of the concatenation of the response data (possibly none) and the status word (2 bytes).

The command APDU and response APDU are not interpreted by the host library.

The command/response APDU sizes must lay within the APDU size limitations

Parameters
  • [in] cmd: command APDU

  • [in] cmdLen: length (in byte) of cmd

  • [inout] resp: response APDU (response data || response status word)

  • [inout] respLen: IN: Length of resp buffer (resp) provided; OUT: effective length of response retrieved.

Return Value
  • ::SW_OK: Upon successful execution

10.3.4.6. ax_scp.c

Description

Set up the SCP03 communication channel.

Functions

U16 SCP_HostLocal_GetSessionState(ChannelId_t channelId, Scp03SessionState_t *pSession)

Copy the session state into pSession. Caller must allocate memory of pSession.

Parameters
  • [in] channelId: Either ::AX_HOST_CHANNEL or ::AX_ADMIN_CHANNEL. Must be ::AX_HOST_CHANNEL in case of A71CH.

  • [inout] pSession: IN: pointer to allocated ::Scp03SessionState_t structure; OUT: retrieved state

Return Value
  • ::SW_OK: Upon successful execution

  • ::SCP_UNDEFINED_CHANNEL_ID: In case an undefined ::ChannelId_t type was passed as parameter

U16 SCP_GetScpSessionState(Scp03SessionState_t *scp03state)

Retrieve the SCP03 session state of the host - secure module channel from the Host Library.

Return

::SW_OK

Parameters
  • [inout] scp03state: IN: pointer to allocated structure; OUT: datastructure contains SCP03 session state

void SCP_SetScpSessionState(Scp03SessionState_t *scp03state)

Sets SCP03 session state of the host - secure module channel of the Host Library. Can be used in a scenario where e.g. the bootloader has established the SCP03 link between host and secure module and the Host OS must re-establish the communication with the secure module without breaking the SCP03 session.

Parameters
  • [in] scp03state: IN: SCP03 session state

U16 SCP_GP_ExternalAuthenticate(ChannelId_t channelId, U8 *hostCryptogram)
U16 SCP_GP_InitializeUpdate(ChannelId_t channelId, U8 *hostChallenge, U16 hostChallengeLen, U8 *keyDivData, U16 *pKeyDivDataLen, U8 *keyInfo, U16 *pKeyInfoLen, U8 *cardChallenge, U16 *pCardChallengeLen, U8 *cardCryptoGram, U16 *pCardCryptoGramLen, U8 *seqCounter, U16 *pSeqCounterLen)
U16 SCP_GP_PutKeys(U8 keyVersion, U8 *keyEnc, U8 *keyMac, U8 *keyDek, U8 *currentKeyDek, U16 keyBytes)

Persistently stores the provided SCP03 base key set in the security module.

This method must be called once before the Host - Secure Module SCP channel can be established.

Return

::SW_OK upon success

Parameters
  • [in] keyVersion:

  • [in] keyEnc: SCP03 channel encryption base key

  • [in] keyMac: SCP03 authentication base key

  • [in] keyDek: SCP03 data encryption base key

  • [in] currentKeyDek: Value of the data encryption base key already stored in secure module, may be NULL in case no key is currently stored.

  • [in] keyBytes: Length (in byte) of the keys being set. Typically 16 (corresponding to 128 bits)

U16 SCP_Authenticate(U8 *keyEnc, U8 *keyMac, U8 *keyDek, U16 keyBytes, U8 *sCounter, U16 *sCounterLen)

Performs an SCP03 authentication with the SM and - when successful - computes the SCP03 session keys and initializes the current Session state.

Parameters
  • [in] keyEnc: SCP03 channel encryption base key (aka static key) (16 bytes)

  • [in] keyMac: SCP03 authentication base key (aka static key) (16 bytes)

  • [in] keyDek: SCP03 data encryption base key (aka static key) (16 bytes)

  • [in] keyBytes: Must be 16

  • [inout] sCounter: SCP03 sequence counter (3 bytes)

  • [inout] sCounterLen:

10.3.4.7. scp_a7x.c

Description

Conditionally apply SCP03 channel encryption (This file was renamed from scp.c into scp_a7x.c.)

10.3.4.8. a71_debug.c

Description

Wrap Debug Mode specific APDU’s of A71CH.

Functions

U16 A71_DbgReset(void)

Resets the Secure Module to the initial state.

Return Value
  • ::SW_OK: Upon successful execution

U16 A71_DbgDisableDebug(void)

Permanently disables the Debug API.

Return Value
  • ::SW_OK: Upon successful execution

U16 A71_DbgGetFreePersistentMemory(S16 *freeMem)

Reports the available persistent memory in the Security Module.

Return Value
  • ::SW_OK: Upon successful execution

U16 A71_DbgGetFreeTransientMemory(S16 *freeMem)

Reports the available transient memory in the Security Module.

Return Value
  • ::SW_OK: Upon successful execution

U16 A71_DbgReflect(U8 *sndBuf, U16 sndBufLen, U8 *rcvBuf, U16 *rcvBufLen)

Invokes data reflection APDU (facilitates link testing). No check of data payload returned

Return

Parameters
  • [in] sndBuf:

  • [in] sndBufLen:

  • [inout] rcvBuf:

  • [inout] rcvBufLen: