PAL cryptographic - platform. This file contains cryptographic APIs that need to be implemented in the platform layer. More...

#include "pal.h"

Functions
palStatus_t	pal_plat_initCrypto (void)
	Initiate the Crypto library. More...

palStatus_t	pal_plat_cleanupCrypto (void)
	Free resources for the Crypto library. More...

palStatus_t	pal_plat_initAes (palAesHandle_t *aes)
	Initialize an AES context. More...

palStatus_t	pal_plat_freeAes (palAesHandle_t *aes)
	Free an AES context. More...

palStatus_t	pal_plat_setAesKey (palAesHandle_t aes, const unsigned char *key, uint32_t keybits, palAesKeyType_t keyTarget)
	Set an AES key context for encryption or decryption. More...

palStatus_t	pal_plat_aesCTR (palAesHandle_t aes, const unsigned char input, unsigned char output, size_t inLen, unsigned char iv[16], bool zeroOffset)
	Use AES-CTR encryption or decryption on a buffer. More...

palStatus_t	pal_plat_aesECB (palAesHandle_t aes, const unsigned char input[PAL_CRYPT_BLOCK_SIZE], unsigned char output[PAL_CRYPT_BLOCK_SIZE], palAesMode_t mode)
	Use AES-ECB encryption or decryption on a block. More...

palStatus_t	pal_plat_sha256 (const unsigned char input, size_t inLen, unsigned char output)
	Process SHA-256 over the input buffer. More...

palStatus_t	pal_plat_x509Initiate (palX509Handle_t *x509)
	Initialize a certificate chain context. More...

palStatus_t	pal_plat_x509CertParse (palX509Handle_t x509, const unsigned char *input, size_t inLen)
	Parse one or more certificates and add them to the chained list. More...

palStatus_t	pal_plat_x509CertGetAttribute (palX509Handle_t x509Cert, palX509Attr_t attr, void output, size_t outLenBytes, size_t actualOutLenBytes)
	Get attributes from the parsed certificate. More...

palStatus_t	pal_plat_x509CertVerifyExtended (palX509Handle_t x509Cert, palX509Handle_t x509CertChain, int32_t *verifyResult)
	Verify one or more X.509 DER formatted certificates. More...

palStatus_t	pal_plat_x509CertCheckExtendedKeyUsage (palX509Handle_t x509Cert, palExtKeyUsage_t usage)

palStatus_t	pal_plat_x509Free (palX509Handle_t *x509)
	Deallocate all certificate data. More...

palStatus_t	pal_plat_mdInit (palMDHandle_t *md, palMDType_t mdType)
	Initialize an message digest (MD) context and set up the required data according to the given algorithm. More...

palStatus_t	pal_plat_mdUpdate (palMDHandle_t md, const unsigned char *input, size_t inLen)
	Generic message digest (MD) process buffer. More...

palStatus_t	pal_plat_mdGetOutputSize (palMDHandle_t md, size_t *bufferSize)
	Generic message digest (MD) output buffer size getter. More...

palStatus_t	pal_plat_mdFinal (palMDHandle_t md, unsigned char *output)
	Generic message digest (MD) final digest. More...

palStatus_t	pal_plat_mdFree (palMDHandle_t *md)
	Free and clear the message digest (MD) context. More...

palStatus_t	pal_plat_verifySignature (palX509Handle_t x509, palMDType_t mdType, const unsigned char hash, size_t hashLen, const unsigned char sig, size_t sigLen)
	Verify the signature. More...

palStatus_t	pal_plat_ASN1GetTag (unsigned char *position, const unsigned char end, size_t *len, uint8_t tag)
	Check for a specific tag. Updates the pointer to immediately after the tag and length. More...

palStatus_t	pal_plat_CCMInit (palCCMHandle_t *ctx)
	Initialize a CCM context. More...

palStatus_t	pal_plat_CCMFree (palCCMHandle_t *ctx)
	Destroy a CCM context. More...

palStatus_t	pal_plat_CCMSetKey (palCCMHandle_t ctx, palCipherID_t id, const unsigned char *key, unsigned int keybits)
	Set the CCM key. More...

palStatus_t	pal_plat_CCMDecrypt (palCCMHandle_t ctx, unsigned char input, size_t inLen, unsigned char iv, size_t ivLen, unsigned char add, size_t addLen, unsigned char tag, size_t tagLen, unsigned char *output)
	Apply authenticated CCM decryption on a buffer. More...

palStatus_t	pal_plat_CCMEncrypt (palCCMHandle_t ctx, unsigned char input, size_t inLen, unsigned char iv, size_t ivLen, unsigned char add, size_t addLen, unsigned char output, unsigned char *tag, size_t tagLen)
	Apply CCM encryption on a buffer. More...

palStatus_t	pal_plat_CtrDRBGInit (palCtrDrbgCtxHandle_t *ctx)
	Initializes a Counter mode Deterministic Random Byte Generation (CTR-DRBG) context. More...

palStatus_t	pal_plat_CtrDRBGFree (palCtrDrbgCtxHandle_t *ctx)
	Destroys a Counter mode Deterministic Random Byte Generation (CTR-DRBG) context. More...

palStatus_t	pal_plat_CtrDRBGIsSeeded (palCtrDrbgCtxHandle_t ctx)
	Check whether a Counter mode Deterministic Random Byte Generator (CTR-DRBG) context is seeded. More...

palStatus_t	pal_plat_CtrDRBGSeed (palCtrDrbgCtxHandle_t ctx, const void *seed, size_t len)
	Set the initial seed for a Counter mode Deterministic Random Byte Generation (CTR-DRBG) context. More...

palStatus_t	pal_plat_CtrDRBGGenerate (palCtrDrbgCtxHandle_t ctx, unsigned char *out, size_t len)
	Generate a random value using a Counter mode Deterministic Random Byte Generation (CTR-DRBG) context. More...

palStatus_t	pal_plat_CtrDRBGGenerateWithAdditional (palCtrDrbgCtxHandle_t ctx, unsigned char out, size_t len, unsigned char additional, size_t additionalLen)
	Generate a random value with additional input using a Counter mode Deterministic Random Byte Generation (CTR-DRBG) context. More...

palStatus_t	pal_plat_mdHmacSha256 (const unsigned char key, size_t keyLenInBytes, const unsigned char input, size_t inputLenInBytes, unsigned char output, size_t outputLenInBytes)
	Apply a one-shot Message Digest HMAC cipher. More...

palStatus_t	pal_plat_ECCheckKey (palCurveHandle_t grp, palECKeyHandle_t key, uint32_t type, bool *verified)
	Check that a private or public key is a valid key and the public key is on this curve. More...

palStatus_t	pal_plat_ECKeyNew (palECKeyHandle_t *key)
	Allocate key context and initialize a key pair as an invalid pair. More...

palStatus_t	pal_plat_ECKeyFree (palECKeyHandle_t *key)
	Free the components of a key pair. More...

palStatus_t	pal_plat_newKeyHandle (palKeyHandle_t *keyHandle, size_t key_size)
	Initializes a handle to key according to its size. More...

palStatus_t	pal_plat_freeKeyHandle (palKeyHandle_t *keyHandle)
	frees a a key handle. More...

palStatus_t	pal_plat_parseECPrivateKeyFromDER (const unsigned char *prvDERKey, size_t keyLen, palECKeyHandle_t key)
	Parse a DER encoded private key. More...

palStatus_t	pal_plat_parseECPublicKeyFromDER (const unsigned char *pubDERKey, size_t keyLen, palECKeyHandle_t key)
	Parse a DER encoded public key. More...

palStatus_t	pal_plat_parseECPrivateKeyFromHandle (const palKeyHandle_t prvKeyHandle, palECKeyHandle_t ECKeyHandle)
	Parse a private key. More...

palStatus_t	pal_plat_parseECPublicKeyFromHandle (const palKeyHandle_t pubKeyHandle, palECKeyHandle_t ECKeyHandle)
	Parse a public key. More...

palStatus_t	pal_plat_writePrivateKeyToDer (palECKeyHandle_t key, unsigned char derBuffer, size_t bufferSize, size_t actualSize)
	Encode the given private key from the key handle to the DER buffer. More...

palStatus_t	pal_plat_writePublicKeyToDer (palECKeyHandle_t key, unsigned char derBuffer, size_t bufferSize, size_t actualSize)
	Encode the given public key from the key handle to the DER buffer. More...

palStatus_t	pal_plat_ECKeyGenerateKey (palGroupIndex_t grpID, palECKeyHandle_t key)
	Generate a curve ID for a keypair. More...

palStatus_t	pal_plat_ECKeyGetCurve (palECKeyHandle_t key, palGroupIndex_t *grpID)
	Retrieve the curve ID, if it exists, from the given key. More...

palStatus_t	pal_plat_x509CSRInit (palx509CSRHandle_t *x509CSR)
	Allocate and initialize the X.509 certificate signing request (CSR) context. More...

palStatus_t	pal_plat_x509CSRSetSubject (palx509CSRHandle_t x509CSR, const char *subjectName)
	Set the subject name for a certificate signing request (CSR). The subject name should contain a comma-separated list of OIDs and values. More...

palStatus_t	pal_plat_x509CSRSetMD (palx509CSRHandle_t x509CSR, palMDType_t mdType)
	Set the message digest (MD) algorithm to use for the signature. More...

palStatus_t	pal_plat_x509CSRSetKey (palx509CSRHandle_t x509CSR, palECKeyHandle_t pubKey, palECKeyHandle_t prvKey)
	Set the key for a CSR. More...

palStatus_t	pal_plat_x509CSRSetKeyUsage (palx509CSRHandle_t x509CSR, uint32_t keyUsage)
	Set flags for key usage extension. More...

palStatus_t	pal_plat_x509CSRSetExtendedKeyUsage (palx509CSRHandle_t x509CSR, uint32_t extKeyUsage)
	Set flags for extended key usage extension. More...

palStatus_t	pal_plat_x509CSRSetExtension (palx509CSRHandle_t x509CSR, const char oid, size_t oidLen, const unsigned char value, size_t valueLen)
	Generic function to add to the CSR. More...

palStatus_t	pal_plat_x509CSRWriteDER (palx509CSRHandle_t x509CSR, unsigned char derBuf, size_t derBufLen, size_t actualDerLen)
	Write a CSR to a DER structure. More...

palStatus_t	pal_plat_x509CSRFromCertWriteDER (palX509Handle_t x509Cert, palx509CSRHandle_t x509CSR, unsigned char derBuf, size_t derBufLen, size_t actualDerBufLen)
	Write a CSR from a given X.509 Certificate. More...

palStatus_t	pal_plat_x509CertGetHTBS (palX509Handle_t x509Cert, palMDType_t hash_type, unsigned char output, size_t outLenBytes, size_t actualOutLenBytes)
	Calculate the hash of the To Be Signed (TBS) part of an X.509 certificate. More...

palStatus_t	pal_plat_x509CSRFree (palx509CSRHandle_t *x509CSR)
	Free the X.509 CSR context. More...

palStatus_t	pal_plat_ECDHComputeKey (const palCurveHandle_t grp, const palECKeyHandle_t peerPublicKey, const palECKeyHandle_t privateKey, palECKeyHandle_t outKey)
	Compute a shared secret. More...

palStatus_t	pal_plat_ECDHKeyAgreement (const uint8_t derPeerPublicKey, size_t derPeerPublicKeySize, const palECKeyHandle_t privateKeyHandle, unsigned char rawSharedSecretOut, size_t rawSharedSecretMaxSize, size_t *rawSharedSecretActSizeOut)
	Compute the raw shared secret using elliptic curve Diffie�Hellman. More...

palStatus_t	pal_plat_ECDSASign (palCurveHandle_t grp, palMDType_t mdType, palECKeyHandle_t prvKey, unsigned char dgst, uint32_t dgstLen, unsigned char sig, size_t *sigLen)
	Compute the ECDSA signature of a previously hashed message. More...

palStatus_t	pal_plat_ECDSAVerify (palECKeyHandle_t pubKey, unsigned char dgst, uint32_t dgstLen, unsigned char sig, size_t sigLen, bool *verified)
	Verify the ECDSA signature of a previously hashed message. More...

palStatus_t	pal_plat_convertRawSignatureToDer (const unsigned char rawSignature, size_t rawSignatureSize, unsigned char derSignatureOut, size_t derSignatureMaxSize, size_t *derSignatureActSizeOut)
	Convert ECDSA signature in RAW format to DER format. More...

palStatus_t	pal_plat_asymmetricSign (const palECKeyHandle_t privateKeyHandle, palMDType_t mdType, const unsigned char hash, size_t hashSize, unsigned char outSignature, size_t maxSignatureSize, size_t *actualOutSignatureSize)
	Compute the ECDSA raw signature of a previously hashed message. More...

palStatus_t	pal_plat_asymmetricVerify (const palECKeyHandle_t publicKeyHanlde, palMDType_t mdType, const unsigned char hash, size_t hashSize, const unsigned char signature, size_t signatureSize)
	Verify the ECDSA raw signature of a previously hashed message. More...

palStatus_t	pal_plat_ECGroupFree (palCurveHandle_t *grp)
	Free the components of an ECP group. More...

palStatus_t	pal_plat_ECGroupInitAndLoad (palCurveHandle_t *grp, palGroupIndex_t index)
	Initialize an ECP group and set it using well-known domain parameters. More...

Detailed Description

PAL cryptographic - platform. This file contains cryptographic APIs that need to be implemented in the platform layer.

Function Documentation

palStatus_t pal_plat_aesCTR	(	palAesHandle_t	aes,
		const unsigned char *	input,
		unsigned char *	output,
		size_t	inLen,
		unsigned char	iv[16],
		bool	zeroOffset
	)

Use AES-CTR encryption or decryption on a buffer.

Parameters

[in]	aes	The AES context.
[in]	input	The input data buffer.
[out]	output	The output data buffer.
[in]	inLen	The length of the input data in bytes.
[in]	iv	The initialization vector for AES-CTR.
[in]	zeroOffset	Send offset value zero to platform function.

Note: Due to the nature of CTR you should use the same key schedule for both encryption and decryption. So before calling this function you MUST call pal_setAesKey() with the key target PAL_KEY_TARGET_ENCRYPTION to set the key.

Returns: PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.

palStatus_t pal_plat_aesECB	(	palAesHandle_t	aes,
		const unsigned char	input[PAL_CRYPT_BLOCK_SIZE],
		unsigned char	output[PAL_CRYPT_BLOCK_SIZE],
		palAesMode_t	mode
	)

Use AES-ECB encryption or decryption on a block.

Parameters

[in]	aes	The AES context.
[in]	input	A 16-byte input block.
[out]	output	A 16-byte output block.
[in]	mode	Choose between encryption (PAL_AES_ENCRYPT) or decryption (PAL_AES_DECRYPT).

Returns: PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.

palStatus_t pal_plat_ASN1GetTag	(	unsigned char **	position,
		const unsigned char *	end,
		size_t *	len,
		uint8_t	tag
	)

Check for a specific tag. Updates the pointer to immediately after the tag and length.

Parameters

[in,out]	position	The initial position in the ASN.1 data.
[in]	end	The end of data.
[out]	len	The tag length in bytes.
[in]	tag	The expected tag.

Returns: PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.

palStatus_t pal_plat_asymmetricSign	(	const palECKeyHandle_t	privateKeyHandle,
		palMDType_t	mdType,
		const unsigned char *	hash,
		size_t	hashSize,
		unsigned char *	outSignature,
		size_t	maxSignatureSize,
		size_t *	actualOutSignatureSize
	)

Compute the ECDSA raw signature of a previously hashed message.

The function supports keys with PAL_ECP_DP_SECP256R1 curve only.

Parameters

[in]	privateKeyHandle	The private signing key handle.
[in]	mdType	The MD algorithm to be used.
[in]	hash	The message hash.
[in]	hashSize	The size of the message buffer in bytes.

palStatus_t pal_plat_asymmetricVerify	(	const palECKeyHandle_t	publicKeyHanlde,
		palMDType_t	mdType,
		const unsigned char *	hash,
		size_t	hashSize,
		const unsigned char *	signature,
		size_t	signatureSize
	)

Verify the ECDSA raw signature of a previously hashed message.

Parameters

[in]	publicKeyHanlde	The public key for verification.
[in]	mdType	The MD algorithm to be used.
[in]	hash	The message hash.
[in]	hashSize	The size of the message buffer in bytes.
[in]	signature	The raw signature.
[in]	signatureSize	The size of the computed signature in bytes.

Returns: PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.

palStatus_t pal_plat_CCMDecrypt	(	palCCMHandle_t	ctx,
		unsigned char *	input,
		size_t	inLen,
		unsigned char *	iv,
		size_t	ivLen,
		unsigned char *	add,
		size_t	addLen,
		unsigned char *	tag,
		size_t	tagLen,
		unsigned char *	output
	)

Apply authenticated CCM decryption on a buffer.

Parameters

[in]	ctx	The CCM context.
[in]	input	A buffer holding the input data.
[in]	inLen	The length of the input data in bytes.
[in]	iv	The initialization vector.
[in]	ivLen	The length of the IV in bytes.
[in]	add	Additional data.
[in]	addLen	The length of the additional data in bytes.
[in]	tag	A buffer holding the tag.
[in]	tagLen	The length of the tag in bytes.
[out]	output	A buffer for holding the output data.

Returns: PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.

palStatus_t pal_plat_CCMEncrypt	(	palCCMHandle_t	ctx,
		unsigned char *	input,
		size_t	inLen,
		unsigned char *	iv,
		size_t	ivLen,
		unsigned char *	add,
		size_t	addLen,
		unsigned char *	output,
		unsigned char *	tag,
		size_t	tagLen
	)

Apply CCM encryption on a buffer.

Parameters

[in]	ctx	The CCM context.
[in]	input	A buffer holding the input data.
[in]	inLen	The length of the input data in bytes.
[in]	iv	The initialization vector.
[in]	ivLen	The length of the IV in bytes.
[in]	add	Additional data.
[in]	addLen	The length of additional data in bytes.
[out]	output	A buffer for holding the output data, must be at least 'inLen' bytes wide.
[out]	tag	A buffer for holding the tag.
[out]	tagLen	The length of the tag to generate in bytes.

Returns: PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.

palStatus_t pal_plat_CCMFree ( palCCMHandle_t * ctx )

Destroy a CCM context.

Parameters

[in] ctx The CCM context to destroy.

Returns: PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.

palStatus_t pal_plat_CCMInit ( palCCMHandle_t * ctx )

Initialize a CCM context.

Parameters

[in] ctx The CCM context to be initialized.

Returns: PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.

palStatus_t pal_plat_CCMSetKey	(	palCCMHandle_t	ctx,
		palCipherID_t	id,
		const unsigned char *	key,
		unsigned int	keybits
	)

Set the CCM key.

Parameters

[in]	ctx	The CCM context.
[in]	id	The cipher to use (a 128-bit block cipher).
[in]	key	The encryption key.
[in]	keybits	The key size in bits. Must be acceptable by the cipher.

Returns: PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.

palStatus_t pal_plat_cleanupCrypto ( void )

Free resources for the Crypto library.

Note: This function must be called in the general PAL cleanup function.

Returns: PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.

palStatus_t pal_plat_convertRawSignatureToDer	(	const unsigned char *	rawSignature,
		size_t	rawSignatureSize,
		unsigned char *	derSignatureOut,
		size_t	derSignatureMaxSize,
		size_t *	derSignatureActSizeOut
	)

Convert ECDSA signature in RAW format to DER format.

Parameters

[in]	rawSignature	The RAW signature buffer.
[in]	rawSignatureSize	The RAW signature buffer size in bytes.
[out]	derSignatureOut	A buffer to hold the converted DER signature.
[in]	derSignatureMaxSize	The size of the DER signature buffer.
[out]	derSignatureActSizeOut	The actual size of the converted DER signature.

Returns: PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.

palStatus_t pal_plat_CtrDRBGFree ( palCtrDrbgCtxHandle_t * ctx )

Destroys a Counter mode Deterministic Random Byte Generation (CTR-DRBG) context.

Parameters

[in] ctx The CTR-DRBG context to destroy.

Returns: PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.

palStatus_t pal_plat_CtrDRBGGenerate	(	palCtrDrbgCtxHandle_t	ctx,
		unsigned char *	out,
		size_t	len
	)

Generate a random value using a Counter mode Deterministic Random Byte Generation (CTR-DRBG) context.

Parameters

[in]	ctx	The CTR-DRBG context.
[in]	out	The buffer to fill.
[in]	len	The length of the buffer in bytes.

Returns: PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.

palStatus_t pal_plat_CtrDRBGGenerateWithAdditional	(	palCtrDrbgCtxHandle_t	ctx,
		unsigned char *	out,
		size_t	len,
		unsigned char *	additional,
		size_t	additionalLen
	)

Generate a random value with additional input using a Counter mode Deterministic Random Byte Generation (CTR-DRBG) context.

Parameters

[in]	ctx	The CTR-DRBG context.
[in]	out	The buffer to fill.
[in]	len	The length of the buffer in bytes.
[in]	additional	Additional data to update with.
[in]	additionalLen	Length of additional data in bytes.

Returns: PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.

palStatus_t pal_plat_CtrDRBGInit ( palCtrDrbgCtxHandle_t * ctx )

Initializes a Counter mode Deterministic Random Byte Generation (CTR-DRBG) context.

Parameters

[in] ctx The CTR-DRBG context to be initialized.

Returns: PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.

palStatus_t pal_plat_CtrDRBGIsSeeded ( palCtrDrbgCtxHandle_t ctx )

Check whether a Counter mode Deterministic Random Byte Generator (CTR-DRBG) context is seeded.

Calls to pal_plat_CtrDRBGGenerate() only succeed when the context is seeded.

Parameters

[in] ctx The CTR-DRBG context to be checked.

Returns: PAL_SUCCESS if the CTR-DRBG is seeded.; PAL_ERR_CTR_DRBG_NOT_SEEDED if the CTR-DRBG is not yet seeded, meaning calls to pal_plat_CtrDRBGGenerate() will fail.; Any other negative value indicating a specific error code in case of failure.

palStatus_t pal_plat_CtrDRBGSeed	(	palCtrDrbgCtxHandle_t	ctx,
		const void *	seed,
		size_t	len
	)

Set the initial seed for a Counter mode Deterministic Random Byte Generation (CTR-DRBG) context.

Parameters

[in]	ctx	The CTR-DRBG context to be seeded.
[in]	seed	The seed data.
[in]	len	The seed data length in bytes.

Returns: PAL_SUCCESS on success, negative value indicating a specific error code in case of failure.

palStatus_t pal_plat_ECCheckKey	(	palCurveHandle_t	grp,
		palECKeyHandle_t	key,
		uint32_t	type,
		bool *	verified
	)

Check that a private or public key is a valid key and the public key is on this curve.

Parameters

[in]	grp	The curve the point should belong to.
[in]	key	A pointer to the struct that holds the keys to check.
[in]	type	Determines whether to check the private key (PAL_CHECK_PRIVATE_KEY), public key (PAL_CHECK_PUBLIC_KEY), or both (PAL_CHECK_BOTH_KEYS).
[out]	verified	The result of the verification.

Note: The key can contain only private or public key or both.

Returns: PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.

palStatus_t pal_plat_ECDHComputeKey	(	const palCurveHandle_t	grp,
		const palECKeyHandle_t	peerPublicKey,
		const palECKeyHandle_t	privateKey,
		palECKeyHandle_t	outKey
	)

Compute a shared secret.

Parameters

[in]	grp	The ECP group.
[in]	peerPublicKey	The public key from a peer.
[in]	privateKey	The private key.
[out]	outKey	The shared secret.

Returns: PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.

palStatus_t pal_plat_ECDHKeyAgreement	(	const uint8_t *	derPeerPublicKey,
		size_t	derPeerPublicKeySize,
		const palECKeyHandle_t	privateKeyHandle,
		unsigned char *	rawSharedSecretOut,
		size_t	rawSharedSecretMaxSize,
		size_t *	rawSharedSecretActSizeOut
	)

Compute the raw shared secret using elliptic curve Diffie�Hellman.

Parameters

[in]	derPeerPublicKey	The DER public key from a peer.
[in]	derPeerPublicKeySize	The size of the DER public key from a peer.
[in]	privateKeyHandle	The private key handle.

palStatus_t pal_plat_ECDSASign	(	palCurveHandle_t	grp,
		palMDType_t	mdType,
		palECKeyHandle_t	prvKey,
		unsigned char *	dgst,
		uint32_t	dgstLen,
		unsigned char *	sig,
		size_t *	sigLen
	)

Compute the ECDSA signature of a previously hashed message.

Parameters

[in]	grp	The ECP group.
[in]	prvKey	The private signing key-
[in]	dgst	The message hash.
[in]	dgstLen	The length of the message buffer in bytes.
[out]	sig	A buffer to hold the computed signature.
[out]	sigLen	The length of the computed signature in bytes.

Returns: PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.

palStatus_t pal_plat_ECDSAVerify	(	palECKeyHandle_t	pubKey,
		unsigned char *	dgst,
		uint32_t	dgstLen,
		unsigned char *	sig,
		size_t	sigLen,
		bool *	verified
	)

Verify the ECDSA signature of a previously hashed message.

Parameters

[in]	pubKey	The public key for verification.
[in]	dgst	The message hash.
[in]	dgstLen	The length of the message buffer in bytes.
[in]	sign	The signature.
[in]	sig	A buffer to hold the computed signature.
[in]	sigLen	The length of the computed signature in bytes.
[out]	verified	The boolean to hold the verification result.

Returns: PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.

palStatus_t pal_plat_ECGroupFree ( palCurveHandle_t * grp )

Free the components of an ECP group.

Parameters

[in] grp The group to free.

Returns: PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.

palStatus_t pal_plat_ECGroupInitAndLoad	(	palCurveHandle_t *	grp,
		palGroupIndex_t	index
	)

Initialize an ECP group and set it using well-known domain parameters.

Parameters

[in]	grp	The destination group.
[in]	index	The index in the list of well-known domain parameters.

Returns: PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.

palStatus_t pal_plat_ECKeyFree ( palECKeyHandle_t * key )

Free the components of a key pair.

Parameters

[in] key The key pair to free.

Returns: PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.

palStatus_t pal_plat_ECKeyGenerateKey	(	palGroupIndex_t	grpID,
		palECKeyHandle_t	key
	)

Generate a curve ID for a keypair.

Parameters

[in]	grpID	The generated curve ID.
[in]	key	A handle to the destination keypair.

Note: The key parameter must be first allocated by pal_ECKeyNew().

Returns: PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.

palStatus_t pal_plat_ECKeyGetCurve	(	palECKeyHandle_t	key,
		palGroupIndex_t *	grpID
	)

Retrieve the curve ID, if it exists, from the given key.

Parameters

[in]	key	The key from which to retrieve the curve ID.
[out]	grpID	The curve ID for the given key. In case of error, this pointer contains "PAL_ECP_DP_NONE".

Returns: PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.

palStatus_t pal_plat_ECKeyNew ( palECKeyHandle_t * key )

Allocate key context and initialize a key pair as an invalid pair.

Parameters

[in] key The key pair context to initialize

Returns: PAL_SUCCESS on success, negative value indicating a specific error code in case of failure.

palStatus_t pal_plat_freeAes ( palAesHandle_t * aes )

Free an AES context.

Parameters

[in,out] aes The AES context to be deallocated.

Returns: PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.

palStatus_t pal_plat_freeKeyHandle ( palKeyHandle_t * keyHandle )

frees a a key handle.

Parameters

[in] keyHandle A handle for the key

Returns: PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.

palStatus_t pal_plat_initAes ( palAesHandle_t * aes )

Initialize an AES context.

Parameters

[in,out] aes The AES context to be initialized.

Returns: PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.

palStatus_t pal_plat_initCrypto ( void )

Initiate the Crypto library.

Initialization is not required for some crypto libraries. In such cases, the implementation may be empty.

Note: This function must be called in the general PAL initializtion function.

Returns: PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.

palStatus_t pal_plat_mdFinal	(	palMDHandle_t	md,
		unsigned char *	output
	)

Generic message digest (MD) final digest.

Parameters

[in]	md	The MD context.
[in]	output	The generic message digest checksum result.

Returns: PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.

palStatus_t pal_plat_mdFree ( palMDHandle_t * md )

Free and clear the message digest (MD) context.

Parameters

[in,out] md The MD context to be freed.

Returns: PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.

palStatus_t pal_plat_mdGetOutputSize	(	palMDHandle_t	md,
		size_t *	bufferSize
	)

Generic message digest (MD) output buffer size getter.

Parameters

[in]	md	The MD context.
[out]	bufferSize	A pointer to hold the output size of the `pal_mdFinal()` for the given handle.

Note: You SHOULD call this function before calling pal_mdFinal().

Returns: PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.

palStatus_t pal_plat_mdHmacSha256	(	const unsigned char *	key,
		size_t	keyLenInBytes,
		const unsigned char *	input,
		size_t	inputLenInBytes,
		unsigned char *	output,
		size_t *	outputLenInBytes
	)

Apply a one-shot Message Digest HMAC cipher.

Parameters

[in]	key	The encryption key.
[in]	keyLenInBytes	The key size in bytes.
[in]	input	A buffer for the input data.
[in]	inputLenInBytes	The input data length in bytes.
[out]	output	The generic HMAC result.
[out]	outputLenInBytes	Size of the HMAC result in bytes. Optional.

Note: Expects output to be 32 bytes long

Returns: PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.

palStatus_t pal_plat_mdInit	(	palMDHandle_t *	md,
		palMDType_t	mdType
	)

Initialize an message digest (MD) context and set up the required data according to the given algorithm.

Parameters

[in,out]	md	The MD context to be initialized.
[in]	mdType	The MD algorithm.

Returns: PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.

palStatus_t pal_plat_mdUpdate	(	palMDHandle_t	md,
		const unsigned char *	input,
		size_t	inLen
	)

Generic message digest (MD) process buffer.

Parameters

[in]	md	The MD context.
[in]	input	A buffer holding the input data.
[in]	inLen	The length of the input data in bytes.

Returns: PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.

palStatus_t pal_plat_newKeyHandle	(	palKeyHandle_t *	keyHandle,
		size_t	key_size
	)

Initializes a handle to key according to its size.

Parameters

[in]	keyHandle	A handle for the key
[in]	key_size	size of the key.

Returns: PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.

palStatus_t pal_plat_parseECPrivateKeyFromDER	(	const unsigned char *	prvDERKey,
		size_t	keyLen,
		palECKeyHandle_t	key
	)

Parse a DER encoded private key.

Parameters

[in]	prvDERKey	A buffer that holds the DER encoded private key.
[in]	keyLen	The key length in bytes.
[out]	key	A handle for the context that holds the parsed key.

Returns: PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.

palStatus_t pal_plat_parseECPrivateKeyFromHandle	(	const palKeyHandle_t	prvKeyHandle,
		palECKeyHandle_t	ECKeyHandle
	)

Parse a private key.

Parameters

[in]	prvKeyHandle	A palKey_t object - either a PSA handle or a buffer and size of private key
[out]	ECKeyHandle	A handle for the context that holds the parsed private key.

Returns: PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.

palStatus_t pal_plat_parseECPublicKeyFromDER	(	const unsigned char *	pubDERKey,
		size_t	keyLen,
		palECKeyHandle_t	key
	)

Parse a DER encoded public key.

Parameters

[in]	pubDERKey	A buffer that holds the DER encoded public key.
[in]	keyLen	The key length in bytes.
[out]	key	A handle for the context that holds the parsed key.

Returns: PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.

palStatus_t pal_plat_parseECPublicKeyFromHandle	(	const palKeyHandle_t	pubKeyHandle,
		palECKeyHandle_t	ECKeyHandle
	)

Parse a public key.

Parameters

[in]	pubKeyHandle	A palKey_t object - either a PSA handle or a buffer and size of public key
[out]	ECKeyHandle	A handle for the context that holds the parsed public key.

Returns: PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.

palStatus_t pal_plat_setAesKey	(	palAesHandle_t	aes,
		const unsigned char *	key,
		uint32_t	keybits,
		palAesKeyType_t	keyTarget
	)

Set an AES key context for encryption or decryption.

Parameters

[in]	aes	The AES context.
[in]	key	AES key.
[in]	keybits	The size of the key in bits.
[in]	keyTarget	The key target, either encryption or decryption.

Returns: PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.

palStatus_t pal_plat_sha256	(	const unsigned char *	input,
		size_t	inLen,
		unsigned char *	output
	)

Process SHA-256 over the input buffer.

Parameters

[in]	input	A buffer for the input data.
[in]	inLen	The length of the input data in bytes.
[out]	output	SHA-256 checksum result.

Returns: PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.

palStatus_t pal_plat_verifySignature	(	palX509Handle_t	x509,
		palMDType_t	mdType,
		const unsigned char *	hash,
		size_t	hashLen,
		const unsigned char *	sig,
		size_t	sigLen
	)

Verify the signature.

Parameters

[in]	x509	The certificate context that holds the PK data.
[in]	mdType	The MD algorithm used.
[in]	hash	The hash of the message to sign.
[in]	hashLen	The hash length in bytes.
[in]	sig	The signature to verify.
[in]	sigLen	The signature length in bytes.

Returns: PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.

palStatus_t pal_plat_writePrivateKeyToDer	(	palECKeyHandle_t	key,
		unsigned char *	derBuffer,
		size_t	bufferSize,
		size_t *	actualSize
	)

Encode the given private key from the key handle to the DER buffer.

Parameters

[in]	key	A handle to the private key.
[out]	derBuffer	A buffer to hold the result of the DER encoding.
[in]	bufferSize	The size of the allocated buffer in bytes.
[out]	actualSize	The actual size of the written data in bytes.

Returns: PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.

palStatus_t pal_plat_writePublicKeyToDer	(	palECKeyHandle_t	key,
		unsigned char *	derBuffer,
		size_t	bufferSize,
		size_t *	actualSize
	)

Encode the given public key from the key handle to the DER buffer.

Parameters

[in]	key	A handle to the public key.
[out]	derBuffer	A buffer to hold the result of the DER encoding.
[in]	bufferSize	The size of the allocated buffer in bytes.
[out]	actualSize	The actual size of the written data in bytes.

Returns: PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.

palStatus_t pal_plat_x509CertCheckExtendedKeyUsage	(	palX509Handle_t	x509Cert,
		palExtKeyUsage_t	usage
	)

Check usage of certificate against extended-key-usage extension

Parameters

[in]	x509Cert	A handle holding the parsed certificate.
[in]	option	Intended usage (e.g.: PAL_X509_EXT_KU_CLIENT_AUTH)

Returns: PAL_SUCCESS if this use of the certificate is allowed, PAL_ERR_CERT_CHECK_EXTENDED_KEY_USAGE_FAILED if not or PAL_ERR_X509_UNKNOWN_OID if the given usage is unknown or not supported.

palStatus_t pal_plat_x509CertGetAttribute	(	palX509Handle_t	x509Cert,
		palX509Attr_t	attr,
		void *	output,
		size_t	outLenBytes,
		size_t *	actualOutLenBytes
	)

Get attributes from the parsed certificate.

Parameters

[in]	x509Cert	The parsed certificate.
[in]	attr	The required attribute.
[out]	output	A buffer to hold the attribute value.
[in]	outLenBytes	The size of the allocated buffer in bytes.
[out]	actualOutLenBytes	The actual size of the attribute in bytes.

Returns: PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.

palStatus_t pal_plat_x509CertGetHTBS	(	palX509Handle_t	x509Cert,
		palMDType_t	hash_type,
		unsigned char *	output,
		size_t	outLenBytes,
		size_t *	actualOutLenBytes
	)

Calculate the hash of the To Be Signed (TBS) part of an X.509 certificate.

This function may be used to validate a certificate signature. To do so, use this function to retrieve the hash, then verify the signature using the hash, the public key and the signature of the X.509

Parameters

[in]	x509Cert	Handle to the certificate to hash the TBS.
[in]	hash_type	The hash type. Currently only PAL_SHA256 supported
[out]	output	Pointer to a buffer that will contain the hash digest. This buffer must be at least the size of the digest. When `hash_type` is PAL_SHA256, then buffer pointed to by output must be at least 32 bytes.
[in]	outLenBytes	The size of the buffer pointed to by output in bytes. Must be at least the size of the digest.
[out]	actualOutLenBytes	Size of the digest copied to output in bytes. In case of success, will always be the length of the hash digest.

Returns: PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.

palStatus_t pal_plat_x509CertParse	(	palX509Handle_t	x509,
		const unsigned char *	input,
		size_t	inLen
	)

Parse one or more certificates and add them to the chained list.

Parameters

[in]	x509	The start of the chain.
[in]	input	A buffer holding the certificate data in PEM or DER format.
[in]	inLen	The size of the input buffer in bytes.

Returns: PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.

palStatus_t pal_plat_x509CertVerifyExtended	(	palX509Handle_t	x509Cert,
		palX509Handle_t	x509CertChain,
		int32_t *	verifyResult
	)

Verify one or more X.509 DER formatted certificates.

Parameters

[in]	x509Cert	A handle holding the parsed certificate.
[in]	x509CertChain	The start of the chain to verify the X.509 DER certificate with. This is optional.
[out]	verifyResult	Bitmask of errors that cause the failure. This value is relevant ONLY in case that the return value of the function is `PAL_ERR_X509_CERT_VERIFY_FAILED`.

Note: In case a platform doesn't support multiple errors for certificate verification, please return PAL_ERR_X509_CERT_VERIFY_FAILED and the reason should be specified in the verifyResult

Returns: PAL_SUCCESS on success.; PAL_ERR_X509_CERT_VERIFY_FAILED in case of failure.

palStatus_t pal_plat_x509CSRFree ( palx509CSRHandle_t * x509CSR )

Free the X.509 CSR context.

Parameters

[in] x509CSR The CSR context to free.

Returns: PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.

palStatus_t pal_plat_x509CSRFromCertWriteDER	(	palX509Handle_t	x509Cert,
		palx509CSRHandle_t	x509CSR,
		unsigned char *	derBuf,
		size_t	derBufLen,
		size_t *	actualDerBufLen
	)

Write a CSR from a given X.509 Certificate.

Parameters

[in]	x509Cert	The parsed X.509 certificate.
[in,out]	x509CSR	A valid handle to a CSR that has already been initialized with at least private key.
[out]	derBuf	A buffer to write to.
[out]	derBufLen	The buffer length in bytes.
[out]	actualDerBufLen	The actual length of the written data in bytes.

Returns: PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.

palStatus_t pal_plat_x509CSRInit ( palx509CSRHandle_t * x509CSR )

Allocate and initialize the X.509 certificate signing request (CSR) context.

Parameters

[in] x509CSR The CSR context to allocate and initialize.

Returns: PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.

palStatus_t pal_plat_x509CSRSetExtendedKeyUsage	(	palx509CSRHandle_t	x509CSR,
		uint32_t	extKeyUsage
	)

Set flags for extended key usage extension.

Parameters

[in]	x509CSR	The CSR context to use.
[in]	extKeyUsage	The extended key usage flags, should be taken from `palExtKeyUsage_t`.

Returns: PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.

palStatus_t pal_plat_x509CSRSetExtension	(	palx509CSRHandle_t	x509CSR,
		const char *	oid,
		size_t	oidLen,
		const unsigned char *	value,
		size_t	valueLen
	)

Generic function to add to the CSR.

Parameters

[in]	x509CSR	The CSR context to use.
[in]	oid	The OID of the extension.
[in]	oidLen	The OID length in bytes.
[in]	value	The value of the extension OCTET STRING.
[in]	valueLen	The value length in bytes.

Returns: PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.

palStatus_t pal_plat_x509CSRSetKey	(	palx509CSRHandle_t	x509CSR,
		palECKeyHandle_t	pubKey,
		palECKeyHandle_t	prvKey
	)

Set the key for a CSR.

Parameters

[in]	x509CSR	The CSR context to use.
[in]	pubKey	The public key to include. To use a keypair handle, see the note.
[in]	prvKey	The public key to sign with.

Note: To use a keypair, please send it as pubKey and NULL as prvKey.

Returns: PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.

palStatus_t pal_plat_x509CSRSetKeyUsage	(	palx509CSRHandle_t	x509CSR,
		uint32_t	keyUsage
	)

Set flags for key usage extension.

Parameters

[in]	x509CSR	The CSR context to use.
[in]	keyUsage	The key usage flags. See `palKeyUsage_t` for options.

Returns: PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.

palStatus_t pal_plat_x509CSRSetMD	(	palx509CSRHandle_t	x509CSR,
		palMDType_t	mdType
	)

Set the message digest (MD) algorithm to use for the signature.

Parameters

[in]	x509CSR	The CSR context to use.
[in]	mdType	The MD algorithm to use.

Returns: PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.

palStatus_t pal_plat_x509CSRSetSubject	(	palx509CSRHandle_t	x509CSR,
		const char *	subjectName
	)

Set the subject name for a certificate signing request (CSR). The subject name should contain a comma-separated list of OIDs and values.

Parameters

[in]	x509CSR	The CSR context to use.
[in]	subjectName	The subject name to set.

Returns: PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.

palStatus_t pal_plat_x509CSRWriteDER	(	palx509CSRHandle_t	x509CSR,
		unsigned char *	derBuf,
		size_t	derBufLen,
		size_t *	actualDerLen
	)

Write a CSR to a DER structure.

Parameters

[in]	x509CSR	The CSR context to use.
[in]	derBuf	A buffer to write to.
[in]	derBufLen	The buffer length in bytes.
[in]	actualDerLen	The actual length of the written data in bytes.

Returns: PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.

palStatus_t pal_plat_x509Free ( palX509Handle_t * x509 )

Deallocate all certificate data.

Parameters

[in,out] x509 The certificate chain to free.

Returns: PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.

palStatus_t pal_plat_x509Initiate ( palX509Handle_t * x509 )

Initialize a certificate chain context.

Parameters

[in,out] x509 The certificate chain to initialize.

Returns: PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.

Documentation

Functions

Detailed Description

Function Documentation