NXP Reader Library  v17.1.0.2535

SAM commands used for asymmetric ECC key management, signature handling and verification. More...

Collaboration diagram for ECC:

Modules

 Defines
 Definitions for SAM PKI ECC commands.
 

Functions

phStatus_t phhalHw_Sam_Cmd_PKI_GenerateEccKey (phhalHw_Sam_DataParams_t *pDataParams, uint8_t bECC_KeyNo, uint16_t wECC_Set, uint8_t bECC_KeyNoCEK, uint8_t bECC_KeyVCEK, uint8_t bECC_RefNoKUC, uint8_t bECC_KeyNoAEK, uint8_t bECC_KeyVAEK, uint8_t bECC_RefNoCurve, uint8_t **ppECC_xy, uint16_t *pECC_xyLen)
 PKI_GenerateEccKey creates a pair of a public and a private ECC key. More...
 
phStatus_t phhalHw_Sam_Cmd_PKI_ImportEccKey (phhalHw_Sam_DataParams_t *pDataParams, uint8_t bOption, uint8_t bECC_KeyNo, uint16_t wECC_Set, uint8_t bECC_KeyNoCEK, uint8_t bECC_KeyVCEK, uint8_t bECC_RefNoKUC, uint8_t bECC_KeyNoAEK, uint8_t bECC_KeyVAEK, uint16_t wECC_Len, uint8_t *pECC_KeyValue, uint8_t bECC_KeyValueLen, uint8_t bECC_RefNoCurve, uint8_t bCRLFile, uint8_t *pIssuer, uint8_t bIssuerLen)
 The PKI_ImportEccKey imports an ECC private or public key in the Key Storage. More...
 
phStatus_t phhalHw_Sam_Cmd_PKI_ImportEccCurve (phhalHw_Sam_DataParams_t *pDataParams, uint8_t bOption, uint8_t bECC_CurveNo, uint8_t bECC_KeyNoCCK, uint8_t bECC_KeyVCCK, uint8_t bECC_N, uint8_t bECC_M, uint8_t *pECC_Prime, uint8_t *pECC_ParamA, uint8_t *pECC_ParamB, uint8_t *pECC_Px, uint8_t *pECC_Py, uint8_t *pECC_Order)
 The PKI_ImportEccCurve imports a full ECC Curve description in the ECC Curve Storage Table. More...
 
phStatus_t phhalHw_Sam_Cmd_PKI_ExportEccPrivateKey (phhalHw_Sam_DataParams_t *pDataParams, uint8_t bECC_KeyNo, uint16_t *pECC_Set, uint8_t *pECC_KeyNoCEK, uint8_t *pECC_KeyVCEK, uint8_t *pECC_RefNoKUC, uint8_t *pECC_KeyNoAEK, uint8_t *pECC_KeyVAEK, uint16_t *pECC_Len, uint8_t *pECC_RefNoCurve, uint8_t **ppECC_Priv, uint8_t *pECC_PrivLen)
 The PKI_ExportEccPrivateKey exports a private ECC key entry, including the private key. More...
 
phStatus_t phhalHw_Sam_Cmd_PKI_ExportEccPublicKey (phhalHw_Sam_DataParams_t *pDataParams, uint8_t bECC_KeyNo, uint16_t *pECC_Set, uint8_t *pECC_KeyNoCEK, uint8_t *pECC_KeyVCEK, uint8_t *pECC_RefNoKUC, uint8_t *pECC_KeyNoAEK, uint8_t *pECC_KeyVAEK, uint16_t *pECC_Len, uint8_t **ppECC_xy, uint8_t *pECC_xyLen, uint8_t *pCRLFile)
 The PKI_ExportEccPublicKey exports the public part of ECC key. More...
 
phStatus_t phhalHw_Sam_Cmd_PKI_GenerateEccSignature (phhalHw_Sam_DataParams_t *pDataParams, uint8_t bHashingAlg, uint8_t bECC_KeyNo_Sign, uint8_t *pHash, uint8_t bHashLen, uint8_t **ppSignature, uint16_t *pSigLen)
 Generate ECC Signature generates a signature on a hash given as input using a private key stored in the ECC Key Entry. More...
 
phStatus_t phhalHw_Sam_Cmd_PKI_VerifyEccSignature (phhalHw_Sam_DataParams_t *pDataParams, uint8_t bECC_KeyNo, uint8_t bECC_CurveNo, uint8_t bLen, uint8_t *pMessage, uint8_t *pSignature, uint16_t wSignatureLen)
 The PKI_VerifyEccSignature is used to support the originality check architecture. More...
 
phStatus_t phhalHw_Sam_Cmd_PKI_ValidateEccCert (phhalHw_Sam_DataParams_t *pDataParams, uint8_t bCertFormat, uint8_t bECC_KeyNo, uint8_t bECC_CurveNo, uint8_t bECC_Target, uint8_t *pCertificate, uint16_t wCertLen)
 The PKI_ValidateEccCert command supports certificate validation in the context of the following non-exhaustive list of use cases. More...
 

Detailed Description

SAM commands used for asymmetric ECC key management, signature handling and verification.

Function Documentation

◆ phhalHw_Sam_Cmd_PKI_GenerateEccKey()

phStatus_t phhalHw_Sam_Cmd_PKI_GenerateEccKey ( phhalHw_Sam_DataParams_t pDataParams,
uint8_t  bECC_KeyNo,
uint16_t  wECC_Set,
uint8_t  bECC_KeyNoCEK,
uint8_t  bECC_KeyVCEK,
uint8_t  bECC_RefNoKUC,
uint8_t  bECC_KeyNoAEK,
uint8_t  bECC_KeyVAEK,
uint8_t  bECC_RefNoCurve,
uint8_t **  ppECC_xy,
uint16_t pECC_xyLen 
)

PKI_GenerateEccKey creates a pair of a public and a private ECC key.

To make the key usable, Bit 0 of ECC_SET must be unset (that is disable key entry is false). ECC_SET Bit 1 must be set, indicating a private key entry.

Returns
Status code
Return values
PH_ERR_SUCCESSOperation successful.
PH_ERR_INVALID_DATA_PARAMSpDataParams is NULL.
PH_ERR_INVALID_PARAMETERpECC_xy is NULL
OtherDepending on implementation and underlaying component.
Parameters
[in]pDataParams[In] Pointer to this layer's parameter structure.
[in]bECC_KeyNo[In] The key reference number of the ECC key entry to be update.
  • NVM key: 0x00 - 0x0F
  • RAM key: 0xE0 - 0xE3
[in]wECC_Set[In] Configuration settings of the key entry.
[in]bECC_KeyNoCEK[In] Key reference number of change entry key.
  • 0xFE : No Restrictions
  • 0xFF : Entry Locked
  • 0x00 - 0x7F: Restricted to specific permanent KST Key Entry
[in]bECC_KeyVCEK[In] Key version of change entry key.
[in]bECC_RefNoKUC[In] Reference number of key usage counter.
[in]bECC_KeyNoAEK[In] Key reference number of access entry key.
  • 0xFE : No Restrictions
  • 0xFF : Entry Locked
  • 0x00 - 0x7F: Restricted to specific permanent KST Key Entry
[in]bECC_KeyVAEK[In] Key version of access entry key.
[in]bECC_RefNoCurve[In] Reference of ECC Curve.
[out]ppECC_xy[Out] Public key point coordinate.
[out]pECC_xyLen[Out] Length of bytes available in ppECC_xy buffer.

◆ phhalHw_Sam_Cmd_PKI_ImportEccKey()

phStatus_t phhalHw_Sam_Cmd_PKI_ImportEccKey ( phhalHw_Sam_DataParams_t pDataParams,
uint8_t  bOption,
uint8_t  bECC_KeyNo,
uint16_t  wECC_Set,
uint8_t  bECC_KeyNoCEK,
uint8_t  bECC_KeyVCEK,
uint8_t  bECC_RefNoKUC,
uint8_t  bECC_KeyNoAEK,
uint8_t  bECC_KeyVAEK,
uint16_t  wECC_Len,
uint8_t pECC_KeyValue,
uint8_t  bECC_KeyValueLen,
uint8_t  bECC_RefNoCurve,
uint8_t  bCRLFile,
uint8_t pIssuer,
uint8_t  bIssuerLen 
)

The PKI_ImportEccKey imports an ECC private or public key in the Key Storage.

The command can also be used to only update the key settings (that is ECC_SET, ECC_KeyNoCEK, ECC_KeyVCEK, ECC_RefNoKUC, ECC_KeyNoAEK and ECC_KeyVAEK and (optionally for public keys) CRLFile and/or Issuer). This can be done for example to temporarily disable a key entry. This is indicated by P1.

Returns
Status code
Return values
PH_ERR_SUCCESSOperation successful.
PH_ERR_INVALID_DATA_PARAMSpDataParams is NULL.
PH_ERR_INVALID_PARAMETERpECC_xy is NULL
OtherDepending on implementation and underlaying component.
Parameters
[in]pDataParams[In] Pointer to this layer's parameter structure.
[in]bOption[In] Option for P1 information byte.
[in]bECC_KeyNo[In] The key reference number of the ECC key entry to be update.
  • NVM key: 0x00 - 0x0F
  • RAM key: 0xE0 - 0xE3
[in]wECC_Set[In] Configuration settings of the key entry.
[in]bECC_KeyNoCEK[In] Key reference number of change entry key.
  • 0xFE : No Restrictions
  • 0xFF : Entry Locked
  • 0x00 - 0x7F: Restricted to specific permanent KST Key Entry
[in]bECC_KeyVCEK[In] Key version of change entry key.
[in]bECC_RefNoKUC[In] Reference number of key usage counter.
[in]bECC_KeyNoAEK[In] Key reference number of access entry key.
  • 0xFE : No Restrictions
  • 0xFF : Entry Locked
  • 0x00 - 0x7F: Restricted to specific permanent KST Key Entry
[in]bECC_KeyVAEK[In] Key version of access entry key.
[in]wECC_Len[In] ECC bit field size in bytes.
[in]pECC_KeyValue[In] Private or Public key information.
  • Exchanged if P1 = 0x00 and ECC_SET Bit 1 is not set, Public key (ECC_xy) point coordinates should be provided.
  • Exchanged if P1 = 0x00 and ECC_SET Bit 1 is set, Private key (ECC_priv) scalar should be provided.
[in]bECC_KeyValueLen[In] Length of bytes available in pECC_KeyValue buffer.
[in]bECC_RefNoCurve[In] Reference of ECC Curve. Exchanged if P1 = 0x00 and ECC_SET Bit 1 is set
[out]bCRLFile[Out] CRL File. Exchanged if ECC_SET Bit 12 is set and value will be from 00 - 0F
[in]pIssuer[In] Trusted issuer name. Exchanged if ECC_SET Bit 12 is set
[in]bIssuerLen[In] Length of bytes available in pIssuer buffer.

◆ phhalHw_Sam_Cmd_PKI_ImportEccCurve()

phStatus_t phhalHw_Sam_Cmd_PKI_ImportEccCurve ( phhalHw_Sam_DataParams_t pDataParams,
uint8_t  bOption,
uint8_t  bECC_CurveNo,
uint8_t  bECC_KeyNoCCK,
uint8_t  bECC_KeyVCCK,
uint8_t  bECC_N,
uint8_t  bECC_M,
uint8_t pECC_Prime,
uint8_t pECC_ParamA,
uint8_t pECC_ParamB,
uint8_t pECC_Px,
uint8_t pECC_Py,
uint8_t pECC_Order 
)

The PKI_ImportEccCurve imports a full ECC Curve description in the ECC Curve Storage Table.

The command can also be used to only update the curve settings (that is ECC_KeyNoCCK and ECC_KeyVCCK). This is indicated by P1.

Returns
Status code
Return values
PH_ERR_SUCCESSOperation successful.
PH_ERR_INVALID_DATA_PARAMSpDataParams is NULL.
PH_ERR_INVALID_PARAMETERpECC_Prime, pECC_ParamA, pECC_ParamB, pECC_Px, pECC_Py and pECC_Order are NULL
OtherDepending on implementation and underlaying component.
Parameters
[in]pDataParams[In] Pointer to this layer's parameter structure.
[in]bOption[In] Option for P1 information byte.
[in]bECC_CurveNo[In] Curve reference number of the ECC curve entry to update (00h to 03h).
[in]bECC_KeyNoCCK[In] Key reference number to change the curve entry.
  • 0xFE : No Restrictions
  • 0xFF : Entry Locked
  • 0x00 - 0x7F: Restricted to specific permanent KST Key Entry
[in]bECC_KeyVCCK[In] Key version to change curve entry.
[in]bECC_N[In] Size of the field in bytes. Ranges from 16 to 32 bytes.
[in]bECC_M[In] Size of the order in bytes. Ranges from 16 to 32 bytes.
[in]pECC_Prime[In] Prime, field definition: ECC_N bytes.
[in]pECC_ParamA[In] Curve parameter (a): ECC_N bytes.
[in]pECC_ParamB[In] Curve parameter (b): ECC_N bytes.
[in]pECC_Px[In] x-coordinate of base point: ECC_N bytes.
[in]pECC_Py[In] y-coordinate of base point: ECC_N bytes.
[in]pECC_Order[In] Order of base point: ECC_M bytes.

◆ phhalHw_Sam_Cmd_PKI_ExportEccPrivateKey()

phStatus_t phhalHw_Sam_Cmd_PKI_ExportEccPrivateKey ( phhalHw_Sam_DataParams_t pDataParams,
uint8_t  bECC_KeyNo,
uint16_t pECC_Set,
uint8_t pECC_KeyNoCEK,
uint8_t pECC_KeyVCEK,
uint8_t pECC_RefNoKUC,
uint8_t pECC_KeyNoAEK,
uint8_t pECC_KeyVAEK,
uint16_t pECC_Len,
uint8_t pECC_RefNoCurve,
uint8_t **  ppECC_Priv,
uint8_t pECC_PrivLen 
)

The PKI_ExportEccPrivateKey exports a private ECC key entry, including the private key.

Returns
Status code
Return values
PH_ERR_SUCCESSOperation successful.
PH_ERR_INVALID_DATA_PARAMSpDataParams is NULL.
PH_ERR_INVALID_PARAMETERpECC_Set, pECC_KeyNoCEK, pECC_KeyVCEK, pECC_RefNoKUC, pECC_KeyNoAEK, pECC_KeyVAEK pECC_Len, pECC_RefNoCurve, and pECC_PrivLen are NULL
OtherDepending on implementation and underlaying component.
Parameters
[in]pDataParams[In] Pointer to this layer's parameter structure.
[in]bECC_KeyNo[In] The key reference number (ECC_KeyNo) of the ECC key entry to be exported (00h to 07h).
[out]pECC_Set[Out] Configuration settings of the key entry.
[out]pECC_KeyNoCEK[Out] Key reference number of change entry key.
  • 0xFE : No Restrictions
  • 0xFF : Entry Locked
  • 0x00 - 0x7F: Restricted to specific permanent KST Key Entry
[out]pECC_KeyVCEK[Out] Key version of change entry key.
[out]pECC_RefNoKUC[Out] Reference number of key usage counter.
[out]pECC_KeyNoAEK[Out] Key reference number of access entry key.
  • 0xFE : No Access Restrictions
  • 0x00 - 0x7F: Restricted to specific permanent KST Key Entry
[out]pECC_KeyVAEK[Out] Key version of access entry key.
[out]pECC_Len[Out] ECC bit field size in bytes.
[in]pECC_RefNoCurve[In] Reference of ECC Curve.
[out]ppECC_Priv[Out] Private key scalar. Ranges from 16 - 80 bytes.
[out]pECC_PrivLen[Out] Length of bytes available in ppECC_Priv buffer.

◆ phhalHw_Sam_Cmd_PKI_ExportEccPublicKey()

phStatus_t phhalHw_Sam_Cmd_PKI_ExportEccPublicKey ( phhalHw_Sam_DataParams_t pDataParams,
uint8_t  bECC_KeyNo,
uint16_t pECC_Set,
uint8_t pECC_KeyNoCEK,
uint8_t pECC_KeyVCEK,
uint8_t pECC_RefNoKUC,
uint8_t pECC_KeyNoAEK,
uint8_t pECC_KeyVAEK,
uint16_t pECC_Len,
uint8_t **  ppECC_xy,
uint8_t pECC_xyLen,
uint8_t pCRLFile 
)

The PKI_ExportEccPublicKey exports the public part of ECC key.

  • If a private key entry is targeted, the public key is computed by the SAM on the fly.
  • If a public key entry is targeted, the CRLFile number is returned, if any CRLFile is associated with the targeted key entry. If the targeted key entry is associated with a trusted Issuer, this is never returned as it is only stored hashed internally in the SAM.
Returns
Status code
Return values
PH_ERR_SUCCESSOperation successful.
PH_ERR_INVALID_DATA_PARAMSpDataParams is NULL.
PH_ERR_INVALID_PARAMETERpECC_Set, pECC_KeyNoCEK, pECC_KeyVCEK, pECC_RefNoKUC, pECC_KeyNoAEK, pECC_KeyVAEK pECC_Len, pCRLFile and pECC_xyLen are NULL
OtherDepending on implementation and underlaying component.
Parameters
[in]pDataParams[In] Pointer to this layer's parameter structure.
[in]bECC_KeyNo[In] The key reference number (ECC_KeyNo) of the ECC key entry to be exported (00h to 07h).
[out]pECC_Set[Out] Configuration settings of the key entry.
[out]pECC_KeyNoCEK[Out] Key reference number of change entry key.
  • 0xFE : No Restrictions
  • 0xFF : Entry Locked
  • 0x00 - 0x7F: Restricted to specific permanent KST Key Entry
[out]pECC_KeyVCEK[Out] Key version of change entry key.
[out]pECC_RefNoKUC[Out] Reference number of key usage counter.
[out]pECC_KeyNoAEK[Out] Key reference number of access entry key.
  • 0xFE : No Access Restrictions
  • 0x00 - 0x7F: Restricted to specific permanent KST Key Entry
[out]pECC_KeyVAEK[Out] Key version of access entry key.
[out]pECC_Len[Out] ECC bit field size in bytes.
[out]ppECC_xy[Out] Public key point coordinate. Ranges from 33 - 65 bytes.
[out]pECC_xyLen[Out] Length of bytes available in ppECC_xy buffer.
[out]pCRLFile[Out] CRL File.
  • Exchanged if ECC_SET Bit 12 is set and value will be from 00 - 0F
  • Will be 0xFF otherwise

◆ phhalHw_Sam_Cmd_PKI_GenerateEccSignature()

phStatus_t phhalHw_Sam_Cmd_PKI_GenerateEccSignature ( phhalHw_Sam_DataParams_t pDataParams,
uint8_t  bHashingAlg,
uint8_t  bECC_KeyNo_Sign,
uint8_t pHash,
uint8_t  bHashLen,
uint8_t **  ppSignature,
uint16_t pSigLen 
)

Generate ECC Signature generates a signature on a hash given as input using a private key stored in the ECC Key Entry.

The signature is immediately returned in the response as the concatenation of r and s. This response has a length of 2 * ECC_Len of the targeted ECC Key Entry, i.e. twice the curve size.

Returns
Status code
Return values
PH_ERR_SUCCESSOperation successful.
PH_ERR_INVALID_DATA_PARAMSpDataParams is NULL.
PH_ERR_INVALID_PARAMETERpHash and pSigLen are NULL
OtherDepending on implementation and underlaying component.
Parameters
[in]pDataParams[In] Pointer to this layer's parameter structure.
[in]bHashingAlg[In] Hashing algorithm selection (for padding MGFs and digital signature).
[in]bECC_KeyNo_Sign[In] The key reference number of the ECC key entry to be used for signature generation.
  • NVM key: 0x00 - 0x0F
  • RAM key: 0xE0 - 0xE3
[in]pHash[In] Hash message to be signed.
[in]bHashLen[In] Length of bytes available in pHash buffer.
[in]ppSignature[In] Generated signature (r, s) with an actual length of 2 * ECC_Len of the targeted ECC key entry.
[in]pSigLen[In] Length of bytes available in ppSignature buffer.

◆ phhalHw_Sam_Cmd_PKI_VerifyEccSignature()

phStatus_t phhalHw_Sam_Cmd_PKI_VerifyEccSignature ( phhalHw_Sam_DataParams_t pDataParams,
uint8_t  bECC_KeyNo,
uint8_t  bECC_CurveNo,
uint8_t  bLen,
uint8_t pMessage,
uint8_t pSignature,
uint16_t  wSignatureLen 
)

The PKI_VerifyEccSignature is used to support the originality check architecture.

The originality check allows verification of the genuineness of NXP chips after manufacturing. The command verifies the correctness of an ECC signature (for example: NXPOriginalitySignature) obtained from the product to verify. The signature is computed according to Elliptic Curve DSA (ECDSA). In case of originality checking, the PKI_VerifyEccSignature cryptographic parameters, such as the input message (M), the selected ECC curve and the required public key depend on the type of product for which the verification is performed.

Returns
Status code
Return values
PH_ERR_SUCCESSOperation successful.
PH_ERR_INVALID_DATA_PARAMSpDataParams is NULL.
PH_ERR_INVALID_PARAMETERpMessage and pSignature are NULL
OtherDepending on implementation and underlaying component.
Parameters
[in]pDataParams[In] Pointer to this layer's parameter structure.
[in]bECC_KeyNo[In] The key reference number of the ECC key entry to be used for signature verification (00h to 07h).
[in]bECC_CurveNo[In] The curve reference number of the ECC curve entry to be used for signature verification (00h to 03h).
[in]bLen[In] Length in bytes of the message to verify.
[in]pMessage[In] Signed input data.
[in]pSignature[In] The ECC digital signature where N is 2 * ECC_Len of ECC_KeyNo key entry.
[in]wSignatureLen[In] Length of bytes available in pSignature buffer.

◆ phhalHw_Sam_Cmd_PKI_ValidateEccCert()

phStatus_t phhalHw_Sam_Cmd_PKI_ValidateEccCert ( phhalHw_Sam_DataParams_t pDataParams,
uint8_t  bCertFormat,
uint8_t  bECC_KeyNo,
uint8_t  bECC_CurveNo,
uint8_t  bECC_Target,
uint8_t pCertificate,
uint16_t  wCertLen 
)

The PKI_ValidateEccCert command supports certificate validation in the context of the following non-exhaustive list of use cases.

  • ECC-based Card-Unilateral Authentication supporting the MIFARE DUOX ISOInternalAuthenticate
  • EV charging protocol supporting the MIFARE DUOX VDE_ECDSA_Sign
  • Secure Dynamic Messaging, i.e. the SUN-feature, with ECDSA signature as supported by MIFARE DUOX
  • Transaction Signature with ECDSA signature as supported by MIFARE DUOX
Returns
Status code
Return values
PH_ERR_SUCCESSOperation successful.
PH_ERR_INVALID_DATA_PARAMSpDataParams is NULL.
PH_ERR_INVALID_PARAMETERpCertificate is NULL
OtherDepending on implementation and underlaying component.
Parameters
[in]pDataParams[In] Pointer to this layer's parameter structure.
[in]bCertFormat[In] Format of the Certificate. This will be used for P1 parameter information
[in]bECC_KeyNo[In] The key reference number of the ECC key entry to be used for signature verification.
  • NVM key: 0x00 - 0x0F
  • RAM key: 0xE0 - 0xE3
[in]bECC_CurveNo[In] Curve reference number of the ECC curve entry to update (00h to 03h).
[in]bECC_Target[In] ECC key entry targeted to store the extracted public key.
  • NVM key: 0x00 - 0x0F
  • RAM key: 0xE0 - 0xE3
[in]pCertificate[In] Certificate to be validated
[in]wCertLen[In] Length of bytes available in pCertificate buffer.