mcuxClKey_Functions

Defines all functions of mcuxClKey. More...

Functions
mcuxClKey_Status_t	mcuxClKey_init (mcuxClSession_Handle_t session, mcuxClKey_Handle_t key, mcuxClKey_Type_t type, const uint8_t *pKeyData, uint32_t keyDataLength)
	Initializes a key handle.
void	mcuxClKey_linkKeyPair (mcuxClSession_Handle_t session, mcuxClKey_Handle_t privKey, mcuxClKey_Handle_t pubKey)
	Establishes a key pair link between a private and public key handle.
mcuxClKey_Status_t	mcuxClKey_setEncoding (mcuxClSession_Handle_t session, mcuxClKey_Handle_t key, mcuxClKey_Encoding_t encoding, const uint8_t *pAuxData, uint32_t auxDataLength)
	Configures the encoding mechanism for the given key handle.
mcuxClKey_Status_t	mcuxClKey_loadCopro (mcuxClSession_Handle_t session, mcuxClKey_Handle_t key, uint32_t loadOptions)
	Load key into destination key slot of a coprocessor.
mcuxClKey_Status_t	mcuxClKey_flush (mcuxClSession_Handle_t session, mcuxClKey_Handle_t key)
	Flush key from destination which can be a key slot of coprocessor or memory buffer.
mcuxClKey_Status_t	mcuxClKey_generate_keypair (mcuxClSession_Handle_t session, mcuxClKey_Generation_t generation, mcuxClKey_Handle_t privKey, mcuxClKey_Handle_t pubKey)
	Key-pair generation function.
mcuxClKey_Status_t	mcuxClKey_agreement (mcuxClSession_Handle_t session, mcuxClKey_Agreement_t agreement, mcuxClKey_Handle_t key, mcuxClKey_Handle_t otherKey, mcuxClKey_Agreement_AdditionalInput_t additionalInputs[], uint32_t numberOfInputs, uint8_t *pOut, uint32_t *const pOutLength)
	Key agreement function.
mcuxClKey_Status_t	mcuxClKey_encode (mcuxClSession_Handle_t session, mcuxClKey_Encoding_t encoding, mcuxClKey_Handle_t encodedKey, mcuxClKey_Type_t type, const uint8_t *pPlainKeyData, uint32_t plainKeyDataLength, const uint8_t *pAuxData, uint32_t auxDataLength, uint8_t *pEncodedKeyData, uint32_t *const pEncodedKeyDataLength)
	Key descriptor initialization function including applying a encoding mechanism.
mcuxClKey_Status_t	mcuxClKey_recode (mcuxClSession_Handle_t session, mcuxClKey_Handle_t encodedKey, mcuxClKey_Encoding_t encoding, mcuxClKey_Handle_t recodedKey, const uint8_t *pAuxData, uint32_t auxDataLength, uint8_t *pEncodedKeyData, uint32_t *const pEncodedKeyDataLength)
	Key recoding (re-encoding) function to apply a new encoding to key material.
mcuxClKey_Status_t	mcuxClKey_validate (mcuxClSession_Handle_t session, mcuxClKey_Validation_t validation, mcuxClKey_Handle_t key)
	Key validation function.

Detailed Description

Defines all functions of mcuxClKey.

Function Documentation

mcuxClKey_init()

mcuxClKey_Status_t mcuxClKey_init	(	mcuxClSession_Handle_t	session,
		mcuxClKey_Handle_t	key,
		mcuxClKey_Type_t	type,
		const uint8_t *	pKeyData,
		uint32_t	keyDataLength )

Initializes a key handle.

Initializes a key handle with default encoding values.

Parameters

	session	Session handle to provide session dependent information
	key	Key handle that will be initialized (word-aligned)
	type	Define which key type shall be initialized
[in]	pKeyData	Pointer to the source data of the key. This can be a pointer to a plain key, any supported encoded key, a share or a key blob. The encoding mechanism defines the purpose of this parameter.
	keyDataLength	Length of the provided key data pKeyData

Returns

An error code that can be any error code in MCUXCLKEY_STATUS_, see individual documentation for more information

Return values

MCUXCLKEY_STATUS_FAILURE	Key initialization failed
MCUXCLKEY_STATUS_OK	on successful operation

Examples

mcuxClAeadModes_Ccm_Aes128_Multipart_example.c, mcuxClAeadModes_Ccm_Aes128_Oneshot_Nist1_example.c, mcuxClAeadModes_Ccm_Aes128_Oneshot_Nist2_example.c, mcuxClAeadModes_Ccm_Aes128_Oneshot_PreloadedKey_example.c, mcuxClAeadModes_Gcm_Aes128_Multipart_example.c, mcuxClAeadModes_Gcm_Aes128_Oneshot_LongNonce_example.c, mcuxClAeadModes_Gcm_Aes128_Oneshot_example.c, mcuxClCipherModes_Cbc_Aes128_Multipart_KeyRfc3394Encoding_example.c, mcuxClCipherModes_Cbc_Aes128_Multipart_PaddingISO_example.c, mcuxClCipherModes_Cbc_Aes128_Multipart_PaddingZero_Dma_NonBlocking_example.c, mcuxClCipherModes_Cbc_Aes128_Multipart_PaddingZero_example.c, mcuxClCipherModes_Cbc_Aes128_Multipart_example.c, mcuxClCipherModes_Cbc_Aes128_Oneshot_Dma_NonBlocking_example.c, mcuxClCipherModes_Cbc_Aes128_Oneshot_PaddingISO_example.c, mcuxClCipherModes_Cbc_Aes128_Oneshot_PaddingZero_example.c, mcuxClCipherModes_Cbc_Aes128_Oneshot_example.c, mcuxClCipherModes_Ctr_Aes128_Multipart_Dma_NonBlocking_example.c, mcuxClCipherModes_Ctr_Aes128_Multipart_example.c, mcuxClCipherModes_Ctr_Aes128_Oneshot_Dma_NonBlocking_example.c, mcuxClCipherModes_Ctr_Aes128_Oneshot_example.c, mcuxClCipherModes_Ecb_Aes128_Multipart_PaddingISO_example.c, mcuxClCipherModes_Ecb_Aes128_Multipart_PaddingZero_Dma_NonBlocking_MultipleProcess_example.c, mcuxClCipherModes_Ecb_Aes128_Multipart_PaddingZero_Dma_NonBlocking_example.c, mcuxClCipherModes_Ecb_Aes128_Multipart_PaddingZero_example.c, mcuxClCipherModes_Ecb_Aes128_Multipart_example.c, mcuxClCipherModes_Ecb_Aes128_Oneshot_Dma_NonBlocking_example.c, mcuxClCipherModes_Ecb_Aes128_Oneshot_PaddingISO_example.c, mcuxClCipherModes_Ecb_Aes128_Oneshot_PaddingPKCS7_example.c, mcuxClCipherModes_Ecb_Aes128_Oneshot_PaddingZero_example.c, mcuxClCipherModes_Ecb_Aes128_Oneshot_PreloadedKey_example.c, mcuxClCipherModes_Ecb_Aes128_Oneshot_example.c, mcuxClEcc_ECDH_KeyAgreement_NIST_P256_example.c, mcuxClEcc_ECDSA_FixedKeys_NIST_P256_example.c, mcuxClEcc_ECDSA_GeneratedKeys_NIST_P256_example.c, mcuxClEcc_ECDSA_VerifyOnly_NIST_P256_example.c, mcuxClEcc_EdDSA_Ed25519_example.c, mcuxClEcc_EdDSA_Ed25519ctx_example.c, mcuxClEcc_EdDSA_Ed25519ph_example.c, mcuxClEcc_EdDSA_GenerateSignature_Ed25519_example.c, mcuxClEcc_MontDH_Curve25519_example.c, mcuxClEcc_MontDH_Curve448_example.c, mcuxClEcc_WeierECC_CustomEccWeierType_BN256_example.c, mcuxClEcc_Weier_KeyValidation_PrivateKey_example.c, mcuxClEcc_Weier_KeyValidation_PublicKey_example.c, mcuxClFfdh_KeyAgreement_ffdhe2048_example.c, mcuxClFfdh_KeyAgreement_ffdhe3072_example.c, mcuxClFfdh_KeyAgreement_ffdhe4096_example.c, mcuxClFfdh_KeyAgreement_ffdhe6144_example.c, mcuxClFfdh_KeyAgreement_ffdhe8192_example.c, mcuxClHmac_Sw_Multipart_example.c, mcuxClHmac_Sw_Oneshot_example.c, mcuxClKey_Load_Flush_Sgi_example.c, mcuxClKey_Rewrap_Rfc3394_Sgi_example.c, mcuxClKey_Unwrap_Rfc3394_Sgi_example.c, mcuxClKey_WrapAndLoad_Rfc3394_Sgi_example.c, mcuxClKey_Wrap_Rfc3394_Sgi_kwkAlreadyLoaded_example.c, mcuxClMacModes_Cmac_Aes128_Compute_Dma_NonBlocking_example.c, mcuxClMacModes_Cmac_Aes128_Compute_PreloadedKey_example.c, mcuxClMacModes_Cmac_Aes128_Compute_example.c, mcuxClMacModes_Cmac_Aes128_Multipart_Dma_NonBlocking_example.c, mcuxClMacModes_Cmac_Aes128_Multipart_example.c, mcuxClMacModes_Cmac_Aes256_Compute_example.c, mcuxClRsa_KeyGeneration_example.c, mcuxClRsa_Signature_RSASSA_PSS_example.c, and mcuxClSession_cleanupOnError_example.c.

mcuxClKey_linkKeyPair()

void mcuxClKey_linkKeyPair	(	mcuxClSession_Handle_t	session,
		mcuxClKey_Handle_t	privKey,
		mcuxClKey_Handle_t	pubKey )

Establishes a key pair link between a private and public key handle.

Parameters

session	Session handle to provide session dependent information
privKey	Key handle of private key (word-aligned)
pubKey	Key handle of public key (word-aligned)

Return values

void

mcuxClKey_setEncoding()

mcuxClKey_Status_t mcuxClKey_setEncoding	(	mcuxClSession_Handle_t	session,
		mcuxClKey_Handle_t	key,
		mcuxClKey_Encoding_t	encoding,
		const uint8_t *	pAuxData,
		uint32_t	auxDataLength )

Configures the encoding mechanism for the given key handle.

This function shall be used when the key material of a key handle is already encoded. mcuxClKey_init must be called to initialize the key handle first.

Parameters

	session	Session handle to provide session dependent information
	key	Key handle that will be configured (word-aligned)
	encoding	Define the encoding and flush mechanism that shall be used with this key
[in]	pAuxData	Auxiliary data needed for the given key encoding.
	auxDataLength	Number of bytes available in the pAuxData buffer.

Returns

An error code that can be any error code in MCUXCLKEY_STATUS_, see individual documentation for more information

Return values

MCUXCLKEY_STATUS_ERROR	on unsuccessful operation
MCUXCLKEY_STATUS_OK	on successful operation

Examples

mcuxClCipherModes_Cbc_Aes128_Multipart_KeyRfc3394Encoding_example.c, mcuxClKey_Rewrap_Rfc3394_Sgi_example.c, and mcuxClKey_Unwrap_Rfc3394_Sgi_example.c.

mcuxClKey_loadCopro()

mcuxClKey_Status_t mcuxClKey_loadCopro	(	mcuxClSession_Handle_t	session,
		mcuxClKey_Handle_t	key,
		uint32_t	loadOptions )

Load key into destination key slot of a coprocessor.

Parameters

session	Session handle to provide session dependent information
key	Key handle that provides of the key to be loaded (word-aligned)
loadOptions	Provide the destination key slot in the hardware and associated options. The key slot must be available in the coprocessor that fits the key type. The slot shall be a provided constant in MCUXCLKEY_LOADOPTION_SLOT_. Additional options in MCUXCLKEY_LOADOPTION_ can be provided.

Return values

MCUXCLSGI_STATUS_UNWRAP_ERROR

Error during RFC3394 Key Unwrap detected. An SGI reset or FULL_FLUSH needs to be performed.

Attention

If the given key handle contains an RFC3394 wrapped key, this operation will unwrap the key material. This can potentially lead to a MCUXCLSGI_STATUS_UNWRAP_ERROR.

Examples

mcuxClAeadModes_Ccm_Aes128_Oneshot_PreloadedKey_example.c, mcuxClCipherModes_Cbc_Aes128_Multipart_KeyRfc3394Encoding_example.c, mcuxClCipherModes_Ecb_Aes128_Oneshot_PreloadedKey_example.c, mcuxClKey_Load_Flush_Sgi_example.c, mcuxClKey_Rewrap_Rfc3394_Sgi_example.c, mcuxClKey_Unwrap_Rfc3394_Sgi_example.c, mcuxClKey_WrapAndLoad_Rfc3394_Sgi_example.c, mcuxClKey_Wrap_Rfc3394_Sgi_kwkAlreadyLoaded_example.c, and mcuxClMacModes_Cmac_Aes128_Compute_PreloadedKey_example.c.

mcuxClKey_flush()

mcuxClKey_Status_t mcuxClKey_flush	(	mcuxClSession_Handle_t	session,
		mcuxClKey_Handle_t	key )

Flush key from destination which can be a key slot of coprocessor or memory buffer.

Parameters

session	Session handle to provide session dependent information
key	Key handle that provides information to flush the key from its location (word-aligned)

Returns

An error code that can be any error code in MCUXCLKEY_STATUS_, see individual documentation for more information

Return values

MCUXCLKEY_STATUS_OK	on successful operation
MCUXCLKEY_STATUS_FAULT_ATTACK	if a fault is detected

Examples

mcuxClAeadModes_Ccm_Aes128_Oneshot_PreloadedKey_example.c, mcuxClCipherModes_Cbc_Aes128_Multipart_KeyRfc3394Encoding_example.c, mcuxClCipherModes_Ecb_Aes128_Oneshot_PreloadedKey_example.c, mcuxClKey_Load_Flush_Sgi_example.c, mcuxClKey_Rewrap_Rfc3394_Sgi_example.c, mcuxClKey_Unwrap_Rfc3394_Sgi_example.c, mcuxClKey_WrapAndLoad_Rfc3394_Sgi_example.c, mcuxClKey_Wrap_Rfc3394_Sgi_kwkAlreadyLoaded_example.c, and mcuxClMacModes_Cmac_Aes128_Compute_PreloadedKey_example.c.

mcuxClKey_generate_keypair()

mcuxClKey_Status_t mcuxClKey_generate_keypair	(	mcuxClSession_Handle_t	session,
		mcuxClKey_Generation_t	generation,
		mcuxClKey_Handle_t	privKey,
		mcuxClKey_Handle_t	pubKey )

Key-pair generation function.

This function can be used to perform a key-pair generation operation. The generated keys are linked with each other using mcuxClKey_linkKeyPair.

Note: the key handles privKey and pubKey must already be initialized and contain a proper key type (matching to the generation algorithm), encoding mechanism and enough space for key data buffers.

Parameters

[in]	session	Handle for the current CL session.
[in]	generation	Key generation algorithm that determines the key data stored in privKey and pubKey.
	privKey	Key handle for the private key (word-aligned).
	pubKey	Key handle for the public key (word-aligned).

Returns

Status of the mcuxClKey_generate_keypair operation.

Return values

MCUXCLKEY_STATUS_OK	Key generation operation executed successfully.
MCUXCLKEY_STATUS_INVALID_INPUT	The input parameters are not valid.
MCUXCLKEY_STATUS_ERROR	An error occurred during the execution.
MCUXCLKEY_STATUS_FAILURE	The key generation failed. RSA-specific: this occurs in case the key generation exceeds the limit of iterations to generate a prime.
MCUXCLKEY_STATUS_FAULT_ATTACK	An error occurred during the execution.

Attention

This function uses DRBG and PRNG which have to be initialized prior to calling the function.

Examples

mcuxClEcc_ECDSA_GeneratedKeys_NIST_P256_example.c, mcuxClEcc_EdDSA_Ed25519_example.c, mcuxClEcc_EdDSA_Ed25519ctx_example.c, mcuxClEcc_EdDSA_Ed25519ph_example.c, mcuxClEcc_EdDSA_GenerateSignature_Ed25519_example.c, mcuxClEcc_MontDH_Curve25519_example.c, mcuxClEcc_MontDH_Curve448_example.c, mcuxClEcc_WeierECC_CustomEccWeierType_BN256_example.c, and mcuxClRsa_KeyGeneration_example.c.

mcuxClKey_agreement()

mcuxClKey_Status_t mcuxClKey_agreement	(	mcuxClSession_Handle_t	session,
		mcuxClKey_Agreement_t	agreement,
		mcuxClKey_Handle_t	key,
		mcuxClKey_Handle_t	otherKey,
		mcuxClKey_Agreement_AdditionalInput_t	additionalInputs[],
		uint32_t	numberOfInputs,
		uint8_t *	pOut,
		uint32_t *const	pOutLength )

Key agreement function.

This function can be used to perform a Diffie-Hellman-like key agreement operation.

Parameters

	session	Handle for the current CL session.
	agreement	Key agreement algorithm that determines the value of pOut.
	key	First key to be used for the agreement operation (word-aligned).
	otherKey	Other key to be used for the agreement operation (word-aligned).
	additionalInputs	Additional input needed for the agreement operation.
	numberOfInputs	Number of the additional inputs needed for the agreement operation.
[out]	pOut	Pointer to a memory location to store the agreed key.
[out]	pOutLength	Will be incremented by the number of bytes written to pOut.

Returns

status

Examples

mcuxClEcc_ECDH_KeyAgreement_NIST_P256_example.c, mcuxClEcc_MontDH_Curve25519_example.c, mcuxClEcc_MontDH_Curve448_example.c, mcuxClFfdh_KeyAgreement_ffdhe2048_example.c, mcuxClFfdh_KeyAgreement_ffdhe3072_example.c, mcuxClFfdh_KeyAgreement_ffdhe4096_example.c, mcuxClFfdh_KeyAgreement_ffdhe6144_example.c, and mcuxClFfdh_KeyAgreement_ffdhe8192_example.c.

mcuxClKey_encode()

mcuxClKey_Status_t mcuxClKey_encode	(	mcuxClSession_Handle_t	session,
		mcuxClKey_Encoding_t	encoding,
		mcuxClKey_Handle_t	encodedKey,
		mcuxClKey_Type_t	type,
		const uint8_t *	pPlainKeyData,
		uint32_t	plainKeyDataLength,
		const uint8_t *	pAuxData,
		uint32_t	auxDataLength,
		uint8_t *	pEncodedKeyData,
		uint32_t *const	pEncodedKeyDataLength )

Key descriptor initialization function including applying a encoding mechanism.

This function performs the initialization of a Key descriptor. In addition the given encoding mechanism gets applied to the given raw key data.

Parameters

	session	Handle for the current CL session.
	encoding	Encoding mechanism to be applied to the given pPlainKeyData.
	encodedKey	Key to be initialized and encoded (word-aligned).
	type	Type of the key.
[in]	pPlainKeyData	Plain raw key data.
	plainKeyDataLength	Number of bytes available in the pPlainKeyData.
[in]	pAuxData	Auxiliary data needed for the given key encoding.
	auxDataLength	Number of bytes available in the pAuxData buffer.
[out]	pEncodedKeyData	Encoded raw key data (after applying encoding to the pPlainKeyData)
[out]	pEncodedKeyDataLength	Incremented with the number of bytes written at pEncodedKeyData.

Returns

status

Examples

mcuxClKey_WrapAndLoad_Rfc3394_Sgi_example.c, and mcuxClKey_Wrap_Rfc3394_Sgi_kwkAlreadyLoaded_example.c.

mcuxClKey_recode()

mcuxClKey_Status_t mcuxClKey_recode	(	mcuxClSession_Handle_t	session,
		mcuxClKey_Handle_t	encodedKey,
		mcuxClKey_Encoding_t	encoding,
		mcuxClKey_Handle_t	recodedKey,
		const uint8_t *	pAuxData,
		uint32_t	auxDataLength,
		uint8_t *	pEncodedKeyData,
		uint32_t *const	pEncodedKeyDataLength )

Key recoding (re-encoding) function to apply a new encoding to key material.

This function performs the initialization of the key descriptor recodedKey. In addition, it decodes the key material of the given encodedKey and recodes (re-encoded) the plain material with the given encoding to finalize the init of the recodedKey.

In-place recoding is not supported.

Parameters

	session	Handle for the current CL session.
[in]	encodedKey	Input key associated with the material to be recoded. This key object is used as const input (word-aligned).
	encoding	Encoding mechanism to be applied to the plain key material of the given encodedKey.
	recodedKey	Output key handle containing the recoded key. Must point to an uninitialized key handle, in-place recoding is not supported (word-aligned).
[in]	pAuxData	Auxiliary data needed for the given key encoding.
	auxDataLength	Number of bytes available in the pAuxData buffer.
[out]	pEncodedKeyData	Recoded key data (after applying encoding to the decoded key data associated with encodedKey).
[out]	pEncodedKeyDataLength	Incremented with the number of bytes written to pEncodedKeyData.

Returns

status

Examples

mcuxClKey_Rewrap_Rfc3394_Sgi_example.c.

mcuxClKey_validate()

mcuxClKey_Status_t mcuxClKey_validate	(	mcuxClSession_Handle_t	session,
		mcuxClKey_Validation_t	validation,
		mcuxClKey_Handle_t	key )

Key validation function.

This function validates a key.

Parameters

[in]	session	Handle for the current CL session.
[in]	validation	Key validation type.
[in]	key	Key handle for the key to be validated (word-aligned).

Return values

MCUXCLKEY_STATUS_VALIDATION_PASSED	Key validation successful
MCUXCLKEY_STATUS_VALIDATION_FAILED	Key validation failed

Examples

mcuxClEcc_Weier_KeyValidation_PrivateKey_example.c, and mcuxClEcc_Weier_KeyValidation_PublicKey_example.c.