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

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... | |
SAM commands used for asymmetric ECC key management, signature handling and verification.
| 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.
| PH_ERR_SUCCESS | Operation successful. |
| PH_ERR_INVALID_DATA_PARAMS | pDataParams is NULL. |
| PH_ERR_INVALID_PARAMETER | pECC_xy is NULL |
| Other | Depending on implementation and underlaying component. |
| [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.
|
| [in] | wECC_Set | [In] Configuration settings of the key entry. |
| [in] | bECC_KeyNoCEK | [In] Key reference number of change entry key.
|
| [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.
|
| [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. |
| 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.
| PH_ERR_SUCCESS | Operation successful. |
| PH_ERR_INVALID_DATA_PARAMS | pDataParams is NULL. |
| PH_ERR_INVALID_PARAMETER | pECC_xy is NULL |
| Other | Depending on implementation and underlaying component. |
| [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.
|
| [in] | wECC_Set | [In] Configuration settings of the key entry. |
| [in] | bECC_KeyNoCEK | [In] Key reference number of change entry key.
|
| [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.
|
| [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.
|
| [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. |
| 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.
| PH_ERR_SUCCESS | Operation successful. |
| PH_ERR_INVALID_DATA_PARAMS | pDataParams is NULL. |
| PH_ERR_INVALID_PARAMETER | pECC_Prime, pECC_ParamA, pECC_ParamB, pECC_Px, pECC_Py and pECC_Order are NULL |
| Other | Depending on implementation and underlaying component. |
| [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.
|
| [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. |
| 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.
| PH_ERR_SUCCESS | Operation successful. |
| PH_ERR_INVALID_DATA_PARAMS | pDataParams is NULL. |
| PH_ERR_INVALID_PARAMETER | pECC_Set, pECC_KeyNoCEK, pECC_KeyVCEK, pECC_RefNoKUC, pECC_KeyNoAEK, pECC_KeyVAEK pECC_Len, pECC_RefNoCurve, and pECC_PrivLen are NULL |
| Other | Depending on implementation and underlaying component. |
| [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.
|
| [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.
|
| [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. |
| 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.
| PH_ERR_SUCCESS | Operation successful. |
| PH_ERR_INVALID_DATA_PARAMS | pDataParams is NULL. |
| PH_ERR_INVALID_PARAMETER | pECC_Set, pECC_KeyNoCEK, pECC_KeyVCEK, pECC_RefNoKUC, pECC_KeyNoAEK, pECC_KeyVAEK pECC_Len, pCRLFile and pECC_xyLen are NULL |
| Other | Depending on implementation and underlaying component. |
| [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.
|
| [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.
|
| [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.
|
| 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.
| PH_ERR_SUCCESS | Operation successful. |
| PH_ERR_INVALID_DATA_PARAMS | pDataParams is NULL. |
| PH_ERR_INVALID_PARAMETER | pHash and pSigLen are NULL |
| Other | Depending on implementation and underlaying component. |
| [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.
|
| [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. |
| 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.
| PH_ERR_SUCCESS | Operation successful. |
| PH_ERR_INVALID_DATA_PARAMS | pDataParams is NULL. |
| PH_ERR_INVALID_PARAMETER | pMessage and pSignature are NULL |
| Other | Depending on implementation and underlaying component. |
| [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. |
| 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.
| PH_ERR_SUCCESS | Operation successful. |
| PH_ERR_INVALID_DATA_PARAMS | pDataParams is NULL. |
| PH_ERR_INVALID_PARAMETER | pCertificate is NULL |
| Other | Depending on implementation and underlaying component. |
| [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.
|
| [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.
|
| [in] | pCertificate | [In] Certificate to be validated |
| [in] | wCertLen | [In] Length of bytes available in pCertificate buffer. |