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
10.3.3.2. mbed TLS¶
The following picture illustrates the Host Library in the context of the Host SW with mbed TLS
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 theblockInfo
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 ofpHash
usingpKeyData
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 ofpHash
using the public key stored underindex
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 atindex
and a public keypOtherPublicKey
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 onindex
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 onindex
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 atindex
. 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 setThe 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
anddataLen
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
intosm_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) ofcmd
[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 ofpSession
.- 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
intoscp_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
: