SAM commands used for asymmetric key management, signature handling and symmetric key updates based on PKI. More...

Collaboration diagram for Public Key Infrastructure:

Macros
#define	PHHAL_HW_SAMAV2_CMD_PKI_GENERATE_KEY_PAIR_LC_MIN 0x0A
	Minimun Length of data of PKI_GenerateKeyPair.

#define	PHHAL_HW_SAMAV2_CMD_PKI_SEND_SIGNATURE_LE_VALUE 0x00
	Length of data(LE) for the response of PKI_SendSignature.

#define	PHHAL_HW_SAMAV2_CMD_PKI_UPDATE_KEY_ENTRIES_LC_MIN 0x02
	Minimun Length of data of PKI_UpdateKeyEntries.

#define	PHHAL_HW_SAMAV2_CMD_PKI_UPDATE_KEY_ENTRIES_LC_MAX 0xC0
	Maximun Length of data of PKI_UpdateKeyEntries.

#define	PHHAL_HW_SAMAV2_CMD_PKI_IMPORT_KEY_LC_MIN 0x0E
	Minimun Length of data of PKI_ImportKey.

#define	PHHAL_HW_SAMAV2_CMD_BIG_ENDIAN 0x00
	Big Endian.

#define	PHHAL_HW_SAMAV2_CMD_LITTLE_ENDIAN 0x01
	Little Endian.

#define	PHHAL_HW_SAMAV2_CMD_HASH_MESSAGE_LENGTH_20 0x14
	20-bytes long hashed message

#define	PHHAL_HW_SAMAV2_CMD_HASH_MESSAGE_LENGTH_28 0x1C
	28-bytes long hashed message

#define	PHHAL_HW_SAMAV2_CMD_HASH_MESSAGE_LENGTH_32 0x20
	32-bytes long hashed message

#define	PHHAL_HW_SAMAV2_CMD_PKI_GENERATE_HASH_OPTION_FIRST_FRAME 0x04
	Option mask for a decipher with given input length.

Functions
phStatus_t	phhalHw_SamAV2_Cmd_PKI_GenerateKeyPair (phhalHw_SamAV2_DataParams_t pDataParams, uint8_t bOption, uint8_t bPKI_KeyNo, uint16_t wPKI_Set, uint8_t bPKI_KeyNoCEK, uint8_t bPKI_KeyVCEK, uint8_t bPKI_RefNoKUC, uint16_t wPKI_NLen, uint16_t wPKI_eLen, uint8_t pPKI_e)
	Create an RSA key pair. More...

phStatus_t	phhalHw_SamAV2_Cmd_PKI_ImportKey (phhalHw_SamAV2_DataParams_t pDataParams, uint8_t bOption, uint8_t bPKI_KeyNo, uint16_t wPKI_Set, uint8_t bPKI_KeyNoCEK, uint8_t bPKI_KeyVCEK, uint8_t bPKI_RefNoKUC, uint16_t wPKI_NLen, uint16_t wPKI_eLen, uint16_t wPKI_PLen, uint16_t wPKI_QLen, uint8_t pPKI_N, uint8_t pPKI_e, uint8_t pPKI_P, uint8_t pPKI_Q, uint8_t pPKI_dP, uint8_t pPKI_dQ, uint8_t pPKI_iPQ)
	Import a public or private RSA key. More...

phStatus_t	phhalHw_SamAV2_Cmd_PKI_ExportPrivateKey (phhalHw_SamAV2_DataParams_t pDataParams, uint16_t wOption, uint8_t bPKI_KeyNo, uint8_t ppRxBuffer, uint16_t pRxLength)
	Export the public and the private part of an RSA key pair. More...

phStatus_t	phhalHw_SamAV2_Cmd_PKI_ExportPublicKey (phhalHw_SamAV2_DataParams_t pDataParams, uint16_t wOption, uint8_t bPKI_KeyNo, uint8_t ppRxBuffer, uint16_t pRxLength)
	Export the public part of an RSA key pair. More...

phStatus_t	phhalHw_SamAV2_Cmd_PKI_UpdateKeyEntries (phhalHw_SamAV2_DataParams_t pDataParams, uint8_t bNoOfKeyEntries, uint8_t bHashingAlg, uint8_t bPKI_KeyNo_Enc, uint8_t bPKI_KeyNo_Sign, uint8_t pKeyFrame, uint16_t wKeyFrameLength)
	Change up to 3 symmetric key entries by using PKI. More...

phStatus_t	phhalHw_SamAV2_Cmd_PKI_GenerateHash (phhalHw_SamAV2_DataParams_t pDataParams, uint16_t wOption, uint8_t bHashingAlg, uint32_t dwMsgLength, uint8_t pTxBuffer, uint16_t wTxLength, uint8_t pHash, uint8_t pHashLength)
	Generate Hash dataframe from Data. More...

phStatus_t	phhalHw_SamAV2_Cmd_PKI_GenerateSignature (phhalHw_SamAV2_DataParams_t pDataParams, uint8_t bHashingAlg, uint8_t bPKI_KeyNo, uint8_t pHashMsgData, uint8_t bHashMsgLength)
	Generate a signature with a given RSA key entry. More...

phStatus_t	phhalHw_SamAV2_Cmd_PKI_SendSignature (phhalHw_SamAV2_DataParams_t pDataParams, uint8_t ppRxBuffer, uint16_t pRxLength)
	Get a previously generated signature. More...

phStatus_t	phhalHw_SamAV2_Cmd_PKI_VerifySignature (phhalHw_SamAV2_DataParams_t pDataParams, uint8_t bPKI_KeyNo, uint8_t bHashingAlg, uint8_t pHashData, uint8_t bHashDataLength, uint8_t *pSignature, uint16_t wSignatureLength)
	Verify a hash / signature pair with a given RSA key. More...

Sam AV2 command code for Sam Public Key Infrastructure feature.
#define	PHHAL_HW_SAMAV2_CMD_PKI_GENERATE_KEY_PAIR_INS 0x15
	CMD Byte for PKI_GenerateKeyPair command.

#define	PHHAL_HW_SAMAV2_CMD_PKI_IMPORT_KEY_INS 0x19
	CMD Byte for PKI_ImportKey command.

#define	PHHAL_HW_SAMAV2_CMD_PKI_EXPORT_PRIVATE_KEY_INS 0x1F
	CMD Byte for PKI_ExportPrivateKey command.

#define	PHHAL_HW_SAMAV2_CMD_PKI_EXPORT_PUBLIC_KEY_INS 0x18
	CMD Byte for PKI_ExportPublicKey command.

#define	PHHAL_HW_SAMAV2_CMD_PKI_UPDATE_KEY_ENTRIES_INS 0x1D
	CMD Byte for PKI_UpdateKeyEntries command.

#define	PHHAL_HW_SAMAV2_CMD_PKI_GENERATE_HASH_INS 0x17
	CMD Byte for PKI_GenerateHash command.

#define	PHHAL_HW_SAMAV2_CMD_PKI_GENERATE_SIGNATURE_INS 0x16
	CMD Byte for PKI_GenerateSignature command.

#define	PHHAL_HW_SAMAV2_CMD_PKI_SEND_SIGNATURE_INS 0x1A
	CMD Byte for PKI_SendSignature command.

#define	PHHAL_HW_SAMAV2_CMD_PKI_VERIFY_SIGNATURE_INS 0x1B
	CMD Byte for PKI_VerifySignature command.

Option macros for Sam AV2 Public Key Infrastructure hash algorithms.
#define	PHHAL_HW_SAMAV2_CMD_HASH_ALGO_SHA_1 0x00
	SHA-1 hashing algorithm.

#define	PHHAL_HW_SAMAV2_CMD_HASH_ALGO_SHA_224 0x01
	SHA-224 hashing algorithm.

#define	PHHAL_HW_SAMAV2_CMD_HASH_ALGO_SHA_256 0x02
	SHA-256 hashing algorithm.

Option macros for Sam AV2 Public Key Infrastructure GenerateKeyPair command.
#define	PHHAL_HW_SAMAV2_CMD_PKI_GENERATE_KEY_PAIR_DEFAULT 0x00
	Default option mask for PKI_GenerateKeyPair.

#define	PHHAL_HW_SAMAV2_CMD_PKI_GENERATE_KEY_PAIR_FIXED_E 0x01
	Option mask for a key generation with a given exponent e.

#define	PHHAL_HW_SAMAV2_CMD_PKI_GENERATE_KEY_PAIR_RANDOM_E 0x00
	Option mask for a key generation with a randomly selected exponent e.

Option macros for Sam AV2 Public Key Infrastructure ImportKey command.
#define	PHHAL_HW_SAMAV2_CMD_PKI_IMPORT_KEY_DEFAULT 0x00
	Default option mask for PKI_ImportKey.

#define	PHHAL_HW_SAMAV2_CMD_PKI_IMPORT_KEY_SETTINGS_ONLY 0x01
	Option mask for importing the key settings only.

#define	PHHAL_HW_SAMAV2_CMD_PKI_IMPORT_KEY_KEY_ENTRY 0x00
	Option mask for importing a complete key entry.

Option macros for Sam AV2 Public Key Infrastructure UpdateKeyEntries command.
#define	PHHAL_HW_SAMAV2_CMD_PKI_ONE_KEY_ENTRY 0x01
	One key entry.

#define	PHHAL_HW_SAMAV2_CMD_PKI_TWO_KEY_ENTRIES 0x02
	Two key entry.

#define	PHHAL_HW_SAMAV2_CMD_PKI_THREE_KEY_ENTRIES 0x03
	Three key entry.

Detailed Description

SAM commands used for asymmetric key management, signature handling and symmetric key updates based on PKI.

Function Documentation

◆ phhalHw_SamAV2_Cmd_PKI_GenerateKeyPair()

phStatus_t phhalHw_SamAV2_Cmd_PKI_GenerateKeyPair	(	phhalHw_SamAV2_DataParams_t *	pDataParams,
		uint8_t	bOption,
		uint8_t	bPKI_KeyNo,
		uint16_t	wPKI_Set,
		uint8_t	bPKI_KeyNoCEK,
		uint8_t	bPKI_KeyVCEK,
		uint8_t	bPKI_RefNoKUC,
		uint16_t	wPKI_NLen,
		uint16_t	wPKI_eLen,
		uint8_t *	pPKI_e
	)

Create an RSA key pair.

This command is only available in AV2.

Returns: Status code

Return values

PH_ERR_SUCCESS	Operation successful.
Other	Depending on implementation and underlaying component.

Parameters

[in]	pDataParams	[In] Pointer to this layer's parameter structure.
[in]	bOption	[In] Option for key generation: PHHAL_HW_SAMAV2_CMD_PKI_GENERATE_KEY_PAIR_DEFAULT PHHAL_HW_SAMAV2_CMD_PKI_GENERATE_KEY_PAIR_FIXED_E PHHAL_HW_SAMAV2_CMD_PKI_GENERATE_KEY_PAIR_RANDOM_E
[in]	bPKI_KeyNo	[In] Reference number of the key entry where the created key should be stored (00h to 01h).
[in]	wPKI_Set	[In] Configuration settings of the created key entry.
[in]	bPKI_KeyNoCEK	[In] Reference number to the change key of the created key entry.
[in]	bPKI_KeyVCEK	[In] Version of the change key of the created key entry.
[in]	bPKI_RefNoKUC	[In] Reference number to the KUC of the created key entry.
[in]	wPKI_NLen	[In] Length of the modulus N (multiple of 8 and in [32;256]).
[in]	wPKI_eLen	[In] Length of the exponent e (multiple of 4 and in [4;256]).
[in]	pPKI_e	[In] Buffer containing the fixed exponent e.

◆ phhalHw_SamAV2_Cmd_PKI_ImportKey()

phStatus_t phhalHw_SamAV2_Cmd_PKI_ImportKey	(	phhalHw_SamAV2_DataParams_t *	pDataParams,
		uint8_t	bOption,
		uint8_t	bPKI_KeyNo,
		uint16_t	wPKI_Set,
		uint8_t	bPKI_KeyNoCEK,
		uint8_t	bPKI_KeyVCEK,
		uint8_t	bPKI_RefNoKUC,
		uint16_t	wPKI_NLen,
		uint16_t	wPKI_eLen,
		uint16_t	wPKI_PLen,
		uint16_t	wPKI_QLen,
		uint8_t *	pPKI_N,
		uint8_t *	pPKI_e,
		uint8_t *	pPKI_P,
		uint8_t *	pPKI_Q,
		uint8_t *	pPKI_dP,
		uint8_t *	pPKI_dQ,
		uint8_t *	pPKI_iPQ
	)

Import a public or private RSA key.

Returns: Status code

Return values

PH_ERR_SUCCESS	Operation successful.
Other	Depending on implementation and underlaying component.

Parameters

[in]	pDataParams	[In] Pointer to this layer's parameter structure.
[in]	bOption	[In] Option parameter: PHHAL_HW_SAMAV2_CMD_PKI_IMPORT_KEY_DEFAULT PHHAL_HW_SAMAV2_CMD_PKI_IMPORT_KEY_SETTINGS_ONLY PHHAL_HW_SAMAV2_CMD_PKI_IMPORT_KEY_KEY_ENTRY
[in]	bPKI_KeyNo	[In] Number of the key entry to be imported (00h to 02h).
[in]	wPKI_Set	[In] Configuration settings of the imported key entry. It indicates wheter a private of public key shall be imported.
[in]	bPKI_KeyNoCEK	[In] Reference number to the change key of the imported key entry.
[in]	bPKI_KeyVCEK	[In] Version of the change key of the imported key entry.
[in]	bPKI_RefNoKUC	[In] Reference number to the KUC of the created key entry.
[in]	wPKI_NLen	[In] Length of Modulus N (multiple of 8 and in [32;256]).
[in]	wPKI_eLen	[In] Length of exponent e (multiple of 4 and in [4;256]).
[in]	wPKI_PLen	[In] Length of prime P. Only used if bPublicOnly = 00h.
[in]	wPKI_QLen	[In] Length of prime Q. Only used if bPublicOnly = 00h.
[in]	pPKI_N	[In] Modulus N.
[in]	pPKI_e	[In] Exponent e.
[in]	pPKI_P	[In] Prime P.
[in]	pPKI_Q	[In] Prime Q.
[in]	pPKI_dP	[In] Parameter dP padded up to a length of wPKI_PLen.
[in]	pPKI_dQ	[In] Parameter dQ padded up to a length of wPKI_QLen.
[in]	pPKI_iPQ	[In] Inverse P(-1) mod Q padded up to a length of wPKI_QLen.

◆ phhalHw_SamAV2_Cmd_PKI_ExportPrivateKey()

phStatus_t phhalHw_SamAV2_Cmd_PKI_ExportPrivateKey	(	phhalHw_SamAV2_DataParams_t *	pDataParams,
		uint16_t	wOption,
		uint8_t	bPKI_KeyNo,
		uint8_t **	ppRxBuffer,
		uint16_t *	pRxLength
	)

Export the public and the private part of an RSA key pair.

This command is only available in AV2.

Returns: Status code

Return values

PH_ERR_SUCCESS	Operation successful, command completed.
PH_ERR_SUCCESS_CHAINING	Operation successful, chaining ongoing.
Other	Depending on implementation and underlaying component.

Parameters

[in]	pDataParams	[In] Pointer to this layer's parameter structure.
[in]	wOption	[In] Option parameter: PH_EXCHANGE_DEFAULT (for receiving the first part of data) PH_EXCHANGE_RXCHAINING (for receiving the final part of data).
[in]	bPKI_KeyNo	[In] Reference number of the key entry to be exported (00h to 01h).
[out]	ppRxBuffer	[Out] Pointer to received data
[out]	pRxLength	[Out] Length of received data.

◆ phhalHw_SamAV2_Cmd_PKI_ExportPublicKey()

phStatus_t phhalHw_SamAV2_Cmd_PKI_ExportPublicKey	(	phhalHw_SamAV2_DataParams_t *	pDataParams,
		uint16_t	wOption,
		uint8_t	bPKI_KeyNo,
		uint8_t **	ppRxBuffer,
		uint16_t *	pRxLength
	)

Export the public part of an RSA key pair.

This command is only available in AV2.

Returns: Status code

Return values

PH_ERR_SUCCESS	Operation successful, command completed.
PH_ERR_SUCCESS_CHAINING	Operation successful, chaining ongoing.
Other	Depending on implementation and underlaying component.

Parameters

[in]	pDataParams	[In] Pointer to this layer's parameter structure.
[in]	wOption	[In] Option parameter: PH_EXCHANGE_DEFAULT (for receiving the first part of data) PH_EXCHANGE_RXCHAINING (for receiving the final part of data).
[in]	bPKI_KeyNo	[In] Reference number of the key entry to be exported (00h to 02h).
[out]	ppRxBuffer	[Out] Pointer to received data
[out]	pRxLength	[Out] Length of received data.

◆ phhalHw_SamAV2_Cmd_PKI_UpdateKeyEntries()

phStatus_t phhalHw_SamAV2_Cmd_PKI_UpdateKeyEntries	(	phhalHw_SamAV2_DataParams_t *	pDataParams,
		uint8_t	bNoOfKeyEntries,
		uint8_t	bHashingAlg,
		uint8_t	bPKI_KeyNo_Enc,
		uint8_t	bPKI_KeyNo_Sign,
		uint8_t *	pKeyFrame,
		uint16_t	wKeyFrameLength
	)

Change up to 3 symmetric key entries by using PKI.

Returns: Status code

Return values

PH_ERR_SUCCESS	Operation successful.
Other	Depending on implementation and underlaying component.

Parameters

[in]	pDataParams	[In] Pointer to this layer's parameter structure.
[in]	bNoOfKeyEntries	[In] Number of symmetric key entries to update. PHHAL_HW_SAMAV2_CMD_PKI_ONE_KEY_ENTRY PHHAL_HW_SAMAV2_CMD_PKI_TWO_KEY_ENTRIES PHHAL_HW_SAMAV2_CMD_PKI_THREE_KEY_ENTRIES
[in]	bHashingAlg	[In] Hashing algorithm to be used for signature verification `00`: SHA-1 `01`: SHA-224 `11`: SHA-256 `10`: RFU
[in]	bPKI_KeyNo_Enc	[In] Reference number of the private RSA key entry to be used for decryption (00h to 01h).
[in]	bPKI_KeyNo_Sign	[In] Reference number of the public key entry to be used for signature verification (00h to 02h).
[in]	pKeyFrame	[In] Buffer containing the RSA encrypted key entries and the signature.
[in]	wKeyFrameLength	[In] Key frame length.

◆ phhalHw_SamAV2_Cmd_PKI_GenerateHash()

phStatus_t phhalHw_SamAV2_Cmd_PKI_GenerateHash	(	phhalHw_SamAV2_DataParams_t *	pDataParams,
		uint16_t	wOption,
		uint8_t	bHashingAlg,
		uint32_t	dwMsgLength,
		uint8_t *	pTxBuffer,
		uint16_t	wTxLength,
		uint8_t *	pHash,
		uint8_t *	pHashLength
	)

Generate Hash dataframe from Data.

Returns: Status code

Return values

PH_ERR_SUCCESS	Operation successful, command completed.
PH_ERR_SUCCESS_CHAINING	Operation successful, chaining ongoing.
Other	Depending on implementation and underlaying component.

Parameters

[in]	pDataParams	[In] Pointer to this layer's parameter structure.
[in]	wOption	[In] Option parameter: Local buffering is implemented by the flags PH_EXCHANGE_BUFFER_FIRST PH_EXCHANGE_BUFFER_CONT PH_EXCHANGE_BUFFER_LAST (the command is sent to the SAM) PH_EXCHANGE_TXCHAINING (The LFI is set to AFh if the flag) On the first frame of the command chain the flag PHHAL_HW_SAMAV2_CMD_PKI_GENERATE_HASH_OPTION_FIRST_FRAME has to be set to force the appending of the length of the overall message.
[in]	bHashingAlg	[In] Hashing algorithm to be used for signature verification `00`: SHA-1 `01`: SHA-224 `11`: SHA-256 `10`: RFU
[in]	dwMsgLength	[In] Overall message length.
[in]	pTxBuffer	[In] Message chunk to be hashed.
[in]	wTxLength	[In] Length of message chunk.
[out]	pHash	[Out] Buffer containing the hash after sending the last message chunk. The buffer has to be 32 bytes long.
[out]	pHashLength	[Out] Amount of valid data in hash buffer.

◆ phhalHw_SamAV2_Cmd_PKI_GenerateSignature()

phStatus_t phhalHw_SamAV2_Cmd_PKI_GenerateSignature	(	phhalHw_SamAV2_DataParams_t *	pDataParams,
		uint8_t	bHashingAlg,
		uint8_t	bPKI_KeyNo,
		uint8_t *	pHashMsgData,
		uint8_t	bHashMsgLength
	)

Generate a signature with a given RSA key entry.

Returns: Status code

Return values

PH_ERR_SUCCESS	Operation successful.
Other	Depending on implementation and underlaying component.

Parameters

[in]	pDataParams	[In] Pointer to this layer's parameter structure.
[in]	bHashingAlg	[In] Hashing algorithm to be used for signature verification `00`: SHA-1 `01`: SHA-224 `11`: SHA-256 `10`: RFU
[in]	bPKI_KeyNo	[In] Number of the key entry to be used for signing (00h to 01h).
[in]	pHashMsgData	[In] Hash message to be signed.
[in]	bHashMsgLength	[In] Hash message length.

◆ phhalHw_SamAV2_Cmd_PKI_SendSignature()

phStatus_t phhalHw_SamAV2_Cmd_PKI_SendSignature	(	phhalHw_SamAV2_DataParams_t *	pDataParams,
		uint8_t **	ppRxBuffer,
		uint16_t *	pRxLength
	)

Get a previously generated signature.

This command is only available in AV2.

Returns: Status code

Return values

PH_ERR_SUCCESS	Operation successful.
Other	Depending on implementation and underlaying component.

Parameters

[in]	pDataParams	[In] Pointer to this layer's parameter structure.
[out]	ppRxBuffer	[Out] Pointer to received data
[out]	pRxLength	[Out] Length of received data.

◆ phhalHw_SamAV2_Cmd_PKI_VerifySignature()

phStatus_t phhalHw_SamAV2_Cmd_PKI_VerifySignature	(	phhalHw_SamAV2_DataParams_t *	pDataParams,
		uint8_t	bPKI_KeyNo,
		uint8_t	bHashingAlg,
		uint8_t *	pHashData,
		uint8_t	bHashDataLength,
		uint8_t *	pSignature,
		uint16_t	wSignatureLength
	)

Verify a hash / signature pair with a given RSA key.

Returns: Status code

Return values

PH_ERR_SUCCESS	Operation successful.
Other	Depending on implementation and underlaying component.

Parameters

[in]	pDataParams	[In] Pointer to this layer's parameter structure.
[in]	bPKI_KeyNo	[In] Number of the key entry to be used for verification (00h to 02h).
[in]	bHashingAlg	[In] Hashing algorithm to be used for signature verification `00`: SHA-1 `01`: SHA-224 `11`: SHA-256 `10`: RFU
[in]	pHashData	[In] Hash data.
[in]	bHashDataLength	[In] Hash data length.
[in]	pSignature	[In] RSA digital signature.
[in]	wSignatureLength	[In] RSA digital signature length.

Macros

Functions

Sam AV2 command code for Sam Public Key Infrastructure feature.

Option macros for Sam AV2 Public Key Infrastructure hash algorithms.

Option macros for Sam AV2 Public Key Infrastructure GenerateKeyPair command.

Option macros for Sam AV2 Public Key Infrastructure ImportKey command.

Option macros for Sam AV2 Public Key Infrastructure UpdateKeyEntries command.

Detailed Description

Function Documentation

◆ phhalHw_SamAV2_Cmd_PKI_GenerateKeyPair()

◆ phhalHw_SamAV2_Cmd_PKI_ImportKey()

◆ phhalHw_SamAV2_Cmd_PKI_ExportPrivateKey()

◆ phhalHw_SamAV2_Cmd_PKI_ExportPublicKey()

◆ phhalHw_SamAV2_Cmd_PKI_UpdateKeyEntries()

◆ phhalHw_SamAV2_Cmd_PKI_GenerateHash()

◆ phhalHw_SamAV2_Cmd_PKI_GenerateSignature()

◆ phhalHw_SamAV2_Cmd_PKI_SendSignature()

◆ phhalHw_SamAV2_Cmd_PKI_VerifySignature()