PAL cryptographic. This file contains cryptographic APIs and is part of the PAL service API. More...

Data Structures
struct	palCryptoBuffer
	Crypto buffer structure. More...

Macros
#define	PAL_ASN1_CLASS_BITS 0xC0

#define	PAL_ASN1_TAG_BITS 0x1F

#define	PAL_CRYPT_BLOCK_SIZE 16

#define	PAL_SHA256_SIZE 32

#define	PAL_ECDSA_SECP256R1_SIGNATURE_RAW_SIZE 64

#define	PAL_SECP256R1_MAX_PUB_KEY_RAW_SIZE 65

#define	PAL_ECDSA_SECP256R1_SIGNATURE_DER_SIZE 74

#define	PAL_EC_SECP256R1_MAX_PUB_KEY_DER_SIZE 91

#define	PAL_SECP256R1_RAW_KEY_AGREEMENT_SIZE 32

Typedefs
typedef uintptr_t	palAesHandle_t

typedef uintptr_t	palX509Handle_t

typedef uintptr_t	palMDHandle_t

typedef uintptr_t	palCCMHandle_t

typedef uintptr_t	palCMACHandle_t

typedef uintptr_t	palCtrDrbgCtxHandle_t

typedef uintptr_t	palCurveHandle_t

typedef uintptr_t	palGroupIDHandle_t

typedef uintptr_t	palECKeyHandle_t

typedef uintptr_t	palSignatureHandle_t

typedef uintptr_t	palx509CSRHandle_t

typedef uintptr_t	palKeyHandle_t

typedef enum palAesKeyType	palAesKeyType_t
	Key types to be set to the AES engine. More...

typedef enum palMDType	palMDType_t
	Message digest algorithms supported by PAL. More...

typedef enum palAesMode	palAesMode_t
	AES mode for ECB encryption and decryption. More...

typedef enum palASNTag	palASNTag_t
	The enum tags supported by PAL for ASN.1. More...

typedef enum palFormat	palFormat_t

typedef enum palCipherID	palCipherID_t

typedef enum palGroupIndex	palGroupIndex_t
	Supported curves. More...

typedef enum palKeyUsage	palKeyUsage_t
	Key usage options. More...

typedef enum palExtKeyUsage	palExtKeyUsage_t
	Extended key usage options. More...

typedef enum palKeyToCheck	palKeyToCheck_t
	Key check options. More...

typedef enum palX509Attr	palX509Attr_t
	Attributes to be retrieved from the X.509 certificate. More...

typedef struct palCryptoBuffer	palCryptoBuffer_t
	Crypto buffer structure. More...

Enumerations
enum	palAesKeyType { PAL_KEY_TARGET_ENCRYPTION, PAL_KEY_TARGET_DECRYPTION }
	Key types to be set to the AES engine. More...

enum	palMDType { PAL_SHA256 }
	Message digest algorithms supported by PAL. More...

enum	palAesMode { PAL_AES_ENCRYPT, PAL_AES_DECRYPT }
	AES mode for ECB encryption and decryption. More...

enum	palASNTag { PAL_ASN1_BOOLEAN = 0x01, PAL_ASN1_INTEGER = 0x02, PAL_ASN1_BIT_STRING = 0x03, PAL_ASN1_OCTET_STRING = 0x04, PAL_ASN1_NULL = 0x05, PAL_ASN1_OID = 0x06, PAL_ASN1_UTF8_STRING = 0x0C, PAL_ASN1_SEQUENCE = 0x10, PAL_ASN1_SET = 0x11, PAL_ASN1_PRINTABLE_STRING = 0x13, PAL_ASN1_T61_STRING = 0x14, PAL_ASN1_IA5_STRING = 0x16, PAL_ASN1_UTC_TIME = 0x17, PAL_ASN1_GENERALIZED_TIME = 0x18, PAL_ASN1_UNIVERSAL_STRING = 0x1C, PAL_ASN1_BMP_STRING = 0x1E, PAL_ASN1_PRIMITIVE = 0x00, PAL_ASN1_CONSTRUCTED = 0x20, PAL_ASN1_CONTEXT_SPECIFIC = 0x80 }
	The enum tags supported by PAL for ASN.1. More...

enum	palFormat { PAL_POINT_CONVERSION_UNCOMPRESSED }

enum	palCipherID { PAL_CIPHER_ID_AES }

enum	palGroupIndex { PAL_ECP_DP_NONE, PAL_ECP_DP_SECP256R1 }
	Supported curves. More...

enum	palKeyUsage { PAL_X509_KU_DIGITAL_SIGNATURE = 0x1, PAL_X509_KU_NON_REPUDIATION = 0x2, PAL_X509_KU_KEY_CERT_SIGN = 0x4, PAL_X509_KU_KEY_AGREEMENT = 0x8 }
	Key usage options. More...

enum	palExtKeyUsage { PAL_X509_EXT_KU_ANY = (1 << 0), PAL_X509_EXT_KU_SERVER_AUTH = (1 << 1), PAL_X509_EXT_KU_CLIENT_AUTH = (1 << 2), PAL_X509_EXT_KU_CODE_SIGNING = (1 << 3), PAL_X509_EXT_KU_EMAIL_PROTECTION = (1 << 4), PAL_X509_EXT_KU_TIME_STAMPING = (1 << 8), PAL_X509_EXT_KU_OCSP_SIGNING = (1 << 9) }
	Extended key usage options. More...

enum	palKeyToCheck { PAL_CHECK_PRIVATE_KEY = 0x01, PAL_CHECK_PUBLIC_KEY = 0x10, PAL_CHECK_BOTH_KEYS = 0x11 }
	Key check options. More...

enum	palX509Attr { PAL_X509_ISSUER_ATTR, PAL_X509_SUBJECT_ATTR, PAL_X509_CN_ATTR, PAL_X509_OU_ATTR, PAL_X509_VALID_FROM, PAL_X509_VALID_TO, PAL_X509_CERT_ID_ATTR, PAL_X509_SIGNATUR_ATTR, PAL_X509_L_ATTR }
	Attributes to be retrieved from the X.509 certificate. More...

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

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

palStatus_t	pal_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_aesCTR (palAesHandle_t aes, const unsigned char input, unsigned char output, size_t inLen, unsigned char iv[16])
	Use AES-CTR encryption or decryption on a buffer. More...

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

palStatus_t	pal_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_sha256 (const unsigned char *input, size_t inLen, unsigned char output[PAL_SHA256_SIZE])
	Run a SHA-256 operation on the input data. More...

palStatus_t	pal_x509Initiate (palX509Handle_t *x509Cert)
	Initialize a certificate chain context. More...

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

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

palStatus_t	pal_x509CertVerify (palX509Handle_t x509Cert, palX509Handle_t x509CertChain)
	Verify one or more DER encoded X.509 certificates. More...

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

palStatus_t	pal_x509CertCheckExtendedKeyUsage (palX509Handle_t x509Cert, palExtKeyUsage_t usage)

palStatus_t	pal_x509Free (palX509Handle_t *x509Cert)
	Deallocate all certificate data. More...

palStatus_t	pal_mdInit (palMDHandle_t *md, palMDType_t mdType)
	Initialize the Message Digest (MD) context and set it up according to the given algorithm. More...

palStatus_t	pal_mdUpdate (palMDHandle_t md, const unsigned char *input, size_t inLen)
	Apply an Message Digest (MD) process on a buffer. More...

palStatus_t	pal_mdGetOutputSize (palMDHandle_t md, size_t *bufferSize)
	Get the length of the Message Digest (MD) output. More...

palStatus_t	pal_mdFinal (palMDHandle_t md, unsigned char *output)
	Calculate the final Message Digest (MD). More...

palStatus_t	pal_mdFree (palMDHandle_t *md)
	Free and clear a Message Digest (MD) context. More...

palStatus_t	pal_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_ASN1GetTag (unsigned char *position, const unsigned char end, size_t *len, uint8_t tag)
	Check for a tag in ASN.1 data. More...

palStatus_t	pal_CCMInit (palCCMHandle_t *ctx)

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

palStatus_t	pal_CCMSetKey (palCCMHandle_t ctx, const unsigned char *key, uint32_t keybits, palCipherID_t id)
	Encrypt a CCM context using a set key. More...

palStatus_t	pal_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)
	Use authenticated decryption on a CCM buffer . More...

palStatus_t	pal_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)
	Encrypt a CCM buffer. More...

palStatus_t	pal_CtrDRBGInit (palCtrDrbgCtxHandle_t ctx, const void seed, size_t len)
	Initialize a Counter mode Deterministic Random Byte Generator (CTR-DRBG) context with a given seed. More...

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

palStatus_t	pal_CtrDRBGGenerate (palCtrDrbgCtxHandle_t ctx, unsigned char *out, size_t len)
	Generate a pseudo random number using the Counter mode Deterministic Random Byte Generator (CTR-DRBG). More...

palStatus_t	pal_CtrDRBGFree (palCtrDrbgCtxHandle_t *ctx)
	Destroy a Counter mode Deterministic Random Byte Generator (CTR-DRBG) context. More...

palStatus_t	pal_cipherCMAC (const unsigned char key, size_t keyLenInBits, const unsigned char input, size_t inputLenInBytes, unsigned char *output)
	Apply a one-shot CMAC cipher. More...

palStatus_t	pal_CMACStart (palCMACHandle_t ctx, const unsigned char key, size_t keyLenBits, palCipherID_t cipherID)
	Start an iterative CMAC cipher. More...

palStatus_t	pal_CMACUpdate (palCMACHandle_t ctx, const unsigned char *input, size_t inLen)
	Update an iterative CMAC cipher. More...

palStatus_t	pal_CMACFinish (palCMACHandle_t ctx, unsigned char output, size_t *outLen)
	Finish an iterative CMAC cipher. More...

palStatus_t	pal_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_ECCheckKey (palCurveHandle_t grp, palECKeyHandle_t key, uint32_t type, bool *verified)
	Check that the private key, public key, or both are valid and that the public key is on the curve. More...

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

palStatus_t	pal_ECKeyFree (palECKeyHandle_t *key)
	Release a private or public key context from memory. More...

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

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

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

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

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

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

palStatus_t	pal_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_asymmetricSign (const palECKeyHandle_t privateKeyHanlde, palMDType_t mdType, const unsigned char hash, size_t hashSize, unsigned char outSignature, size_t maxSignatureSize, size_t *actualOutSignatureSize)
	Compute the Elliptic Curve Digital Signature Algorithm (ECDSA) raw signature of a previously hashed message. More...

palStatus_t	pal_asymmetricVerify (const palECKeyHandle_t publicKeyHanlde, palMDType_t mdType, const unsigned char hash, size_t hashSize, const unsigned char signature, size_t signatureSize)
	Verify the Elliptic Curve Digital Signature Algorithm (ECDSA) raw signature of a previously hashed message. More...

palStatus_t	pal_writePrivateKeyWithHandle (const palKeyHandle_t prvKeyHandle, palECKeyHandle_t ECKeyHandle)
	Write a private key from a key handle. More...

palStatus_t	pal_writePublicKeyWithHandle (const palKeyHandle_t pubKeyHandle, palECKeyHandle_t ECKeyHandle)
	Write a public key from a key handle. More...

palStatus_t	pal_writePrivateKeyToDer (palECKeyHandle_t key, unsigned char derBuffer, size_t bufferSize, size_t actualSize)
	DER encode a private key from a key handle. More...

palStatus_t	pal_writePublicKeyToDer (palECKeyHandle_t key, unsigned char derBuffer, size_t bufferSize, size_t actualSize)
	DER encode a public key from a key handle. More...

palStatus_t	pal_ECKeyGenerateKey (palGroupIndex_t grpID, palECKeyHandle_t key)
	Generate a key pair for a given Elliptic Curve. More...

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

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

palStatus_t	pal_ECGroupFree (palCurveHandle_t *grp)
	Free the ECP group context. More...

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

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

palStatus_t	pal_x509CSRSetMD (palx509CSRHandle_t x509CSR, palMDType_t mdType)

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

palStatus_t	pal_x509CSRSetKeyUsage (palx509CSRHandle_t x509CSR, uint32_t keyUsage)
	Set the key usage extension flags for a CSR context. More...

palStatus_t	pal_x509CSRSetExtendedKeyUsage (palx509CSRHandle_t x509CSR, uint32_t extKeyUsage)
	Set the extended key usage flags. More...

palStatus_t	pal_x509CSRSetExtension (palx509CSRHandle_t x509CSR, const char oid, size_t oidLen, const unsigned char value, size_t valueLen)
	Generic function to extend a CSR context. More...

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

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

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

palStatus_t	pal_ECDHComputeKey (const palCurveHandle_t grp, const palECKeyHandle_t peerPublicKey, const palECKeyHandle_t privateKey, palECKeyHandle_t outKey)
	Compute the shared secret using elliptic curve Diffie–Hellman. More...

palStatus_t	pal_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_ECDSASign (palCurveHandle_t grp, palMDType_t mdType, palECKeyHandle_t prvKey, unsigned char dgst, uint32_t dgstLen, unsigned char sig, size_t *sigLen)
	Compute the Elliptic Curve Digital Signature Algorithm (ECDSA) signature of a previously hashed message. More...

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

palStatus_t	pal_x509CertGetHTBS (palX509Handle_t x509Cert, palMDType_t hash_type, unsigned char output, size_t outLenBytes, size_t actualOutLenBytes)
	Calculate the hash of the part of an X.509 certificate that is to be signed. More...

Detailed Description

PAL cryptographic. This file contains cryptographic APIs and is part of the PAL service API.

It contains a variety of cryptographic APIs, such as:

AES-CTR
AES-DRBG
CMAC
Message Digest

Macro Definition Documentation

#define PAL_ASN1_CLASS_BITS 0xC0

#define PAL_ASN1_TAG_BITS 0x1F

#define PAL_CRYPT_BLOCK_SIZE 16

#define PAL_EC_SECP256R1_MAX_PUB_KEY_DER_SIZE 91

#define PAL_ECDSA_SECP256R1_SIGNATURE_DER_SIZE 74

#define PAL_ECDSA_SECP256R1_SIGNATURE_RAW_SIZE 64

#define PAL_SECP256R1_MAX_PUB_KEY_RAW_SIZE 65

#define PAL_SECP256R1_RAW_KEY_AGREEMENT_SIZE 32

#define PAL_SHA256_SIZE 32

Typedef Documentation

typedef uintptr_t palAesHandle_t

typedef enum palAesKeyType palAesKeyType_t

Key types to be set to the AES engine.

typedef enum palAesMode palAesMode_t

AES mode for ECB encryption and decryption.

typedef enum palASNTag palASNTag_t

The enum tags supported by PAL for ASN.1.

typedef uintptr_t palCCMHandle_t

typedef enum palCipherID palCipherID_t

typedef uintptr_t palCMACHandle_t

typedef struct palCryptoBuffer palCryptoBuffer_t

Crypto buffer structure.

typedef uintptr_t palCtrDrbgCtxHandle_t

typedef uintptr_t palCurveHandle_t

typedef uintptr_t palECKeyHandle_t

typedef enum palExtKeyUsage palExtKeyUsage_t

Extended key usage options.

typedef enum palFormat palFormat_t

typedef uintptr_t palGroupIDHandle_t

typedef enum palGroupIndex palGroupIndex_t

Supported curves.

typedef uintptr_t palKeyHandle_t

typedef enum palKeyToCheck palKeyToCheck_t

Key check options.

typedef enum palKeyUsage palKeyUsage_t

Key usage options.

typedef uintptr_t palMDHandle_t

typedef enum palMDType palMDType_t

Message digest algorithms supported by PAL.

typedef uintptr_t palSignatureHandle_t

typedef enum palX509Attr palX509Attr_t

Attributes to be retrieved from the X.509 certificate.

typedef uintptr_t palx509CSRHandle_t

typedef uintptr_t palX509Handle_t

Enumeration Type Documentation

enum palAesKeyType

Key types to be set to the AES engine.

Enumerator
PAL_KEY_TARGET_ENCRYPTION
PAL_KEY_TARGET_DECRYPTION

enum palAesMode

AES mode for ECB encryption and decryption.

Enumerator
PAL_AES_ENCRYPT
PAL_AES_DECRYPT

enum palASNTag

The enum tags supported by PAL for ASN.1.

Enumerator
PAL_ASN1_BOOLEAN
PAL_ASN1_INTEGER
PAL_ASN1_BIT_STRING
PAL_ASN1_OCTET_STRING
PAL_ASN1_NULL
PAL_ASN1_OID
PAL_ASN1_UTF8_STRING
PAL_ASN1_SEQUENCE
PAL_ASN1_SET
PAL_ASN1_PRINTABLE_STRING
PAL_ASN1_T61_STRING
PAL_ASN1_IA5_STRING
PAL_ASN1_UTC_TIME
PAL_ASN1_GENERALIZED_TIME
PAL_ASN1_UNIVERSAL_STRING
PAL_ASN1_BMP_STRING
PAL_ASN1_PRIMITIVE
PAL_ASN1_CONSTRUCTED
PAL_ASN1_CONTEXT_SPECIFIC

enum palCipherID

Enumerator
PAL_CIPHER_ID_AES

enum palExtKeyUsage

Extended key usage options.

Enumerator
PAL_X509_EXT_KU_ANY
PAL_X509_EXT_KU_SERVER_AUTH
PAL_X509_EXT_KU_CLIENT_AUTH
PAL_X509_EXT_KU_CODE_SIGNING
PAL_X509_EXT_KU_EMAIL_PROTECTION
PAL_X509_EXT_KU_TIME_STAMPING
PAL_X509_EXT_KU_OCSP_SIGNING

enum palFormat

Enumerator
PAL_POINT_CONVERSION_UNCOMPRESSED

enum palGroupIndex

Supported curves.

Enumerator
PAL_ECP_DP_NONE
PAL_ECP_DP_SECP256R1

enum palKeyToCheck

Key check options.

Enumerator
PAL_CHECK_PRIVATE_KEY
PAL_CHECK_PUBLIC_KEY
PAL_CHECK_BOTH_KEYS

enum palKeyUsage

Key usage options.

Enumerator
PAL_X509_KU_DIGITAL_SIGNATURE
PAL_X509_KU_NON_REPUDIATION
PAL_X509_KU_KEY_CERT_SIGN
PAL_X509_KU_KEY_AGREEMENT

enum palMDType

Message digest algorithms supported by PAL.

Enumerator
PAL_SHA256

enum palX509Attr

Attributes to be retrieved from the X.509 certificate.

Enumerator
PAL_X509_ISSUER_ATTR
PAL_X509_SUBJECT_ATTR
PAL_X509_CN_ATTR
PAL_X509_OU_ATTR
PAL_X509_VALID_FROM
PAL_X509_VALID_TO
PAL_X509_CERT_ID_ATTR
PAL_X509_SIGNATUR_ATTR
PAL_X509_L_ATTR

Function Documentation

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

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 input data buffer length in bytes.
[in]	iv	The initialization vector for AES-CTR.

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 set the key by calling pal_setAesKey() with key target PAL_KEY_TARGET_ENCRYPTION.

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

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

Use AES-CTR encryption or decryption with zero offset on a buffer.

Parameters

[in]	aes	The AES context.
[in]	input	The input data buffer.
[out]	output	The output data buffer.
[in]	inLen	The input data length in bytes.
[in]	iv	The initialization vector for AES-CTR.

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 set the key by calling pal_setAesKey() with key target PAL_KEY_TARGET_ENCRYPTION.

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

palStatus_t pal_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	Defines whether to encrypt or decrypt. Set as `PAL_AES_ENCRYPT` for encryption or `PAL_AES_DECRYPT` for decryption.

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

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

Check for a tag in ASN.1 data.

The function updates the pointer position to immediately after the tag and its length.

Parameters

[in,out]	position	The 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_asymmetricSign	(	const palECKeyHandle_t	privateKeyHanlde,
		palMDType_t	mdType,
		const unsigned char *	hash,
		size_t	hashSize,
		unsigned char *	outSignature,
		size_t	maxSignatureSize,
		size_t *	actualOutSignatureSize
	)

Compute the Elliptic Curve Digital Signature Algorithm (ECDSA) raw signature of a previously hashed message.

The function supports keys with PAL_ECP_DP_SECP256R1 curve only.

Parameters

[in]	privateKeyHanlde	A parsed private key.
[in]	mdType	The MD algorithm to be used.
[in]	hash	The message hash.
[in]	hashSize	The size of the message buffer.

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

Verify the Elliptic Curve Digital Signature Algorithm (ECDSA) raw signature of a previously hashed message.

The function supports keys with PAL_ECP_DP_SECP256R1 curve only.

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]	signature	The raw signature.
[in]	signatureSize	The size of the signature.

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

palStatus_t pal_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
	)

Use authenticated decryption on a CCM buffer .

Parameters

[in]	ctx	The CCM context to be initialized.
[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 initialization vector 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.
[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_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
	)

Encrypt a CCM buffer.

Parameters

[in]	ctx	The CCM context to be initialized.
[in]	input	A buffer holding the input data.
[in]	inLen	The length of the input data.
[in]	iv	The initialization vector.
[in]	ivLen	The length of the initialization vector in bytes.
[in]	add	Additional data.
[in]	addLen	The length of additional data.
[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_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_CCMInit ( palCCMHandle_t * ctx )

Initialize the 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_CCMSetKey	(	palCCMHandle_t	ctx,
		const unsigned char *	key,
		uint32_t	keybits,
		palCipherID_t	id
	)

Encrypt a CCM context using a set key.

Parameters

[in]	ctx	The CCM context to be initialized.
[in]	id	The 128-bit block cipher to use.
[in]	key	The encryption key.
[in]	keybits	The key size in bits. The size 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_cipherCMAC	(	const unsigned char *	key,
		size_t	keyLenInBits,
		const unsigned char *	input,
		size_t	inputLenInBytes,
		unsigned char *	output
	)

Apply a one-shot CMAC cipher.

Parameters

[in]	ctx	The CMAC context to initialize.
[in]	key	The encryption key.
[in]	keyLenInBits	The key size in bits.
[in]	input	A buffer for the input data.
[in]	inputLenInBytes	The length of the input data in bytes.
[out]	output	The generic CMAC result.

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

palStatus_t pal_CMACFinish	(	palCMACHandle_t *	ctx,
		unsigned char *	output,
		size_t *	outLen
	)

Finish an iterative CMAC cipher.

Parameters

[in]	ctx	The CMAC context.
[out]	output	A buffer for the output data.
[out]	outLen	The length of the output data in bytes.

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

palStatus_t pal_CMACStart	(	palCMACHandle_t *	ctx,
		const unsigned char *	key,
		size_t	keyLenBits,
		palCipherID_t	cipherID
	)

Start an iterative CMAC cipher.

Parameters

[in]	ctx	The CMAC context.
[in]	key	The CMAC key.
[in]	keyLenBits	The key size in bits.
[in]	cipherID	A buffer for the input data.

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

palStatus_t pal_CMACUpdate	(	palCMACHandle_t	ctx,
		const unsigned char *	input,
		size_t	inLen
	)

Update an iterative CMAC cipher.

Parameters

[in]	ctx	The CMAC context.
[in]	input	A buffer for the input data.
[in]	inLen	The length of the input data.

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

palStatus_t pal_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_CtrDRBGFree ( palCtrDrbgCtxHandle_t * ctx )

Destroy a Counter mode Deterministic Random Byte Generator (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_CtrDRBGGenerate	(	palCtrDrbgCtxHandle_t	ctx,
		unsigned char *	out,
		size_t	len
	)

Generate a pseudo random number using the Counter mode Deterministic Random Byte Generator (CTR-DRBG).

Parameters

[in]	ctx	The CTR-DRBG context.
[out]	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_CtrDRBGInit	(	palCtrDrbgCtxHandle_t *	ctx,
		const void *	seed,
		size_t	len
	)

Initialize a Counter mode Deterministic Random Byte Generator (CTR-DRBG) context with a given seed.

Parameters

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

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

palStatus_t pal_CtrDRBGIsSeeded ( palCtrDrbgCtxHandle_t ctx )

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

Calls to pal_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_CtrDRBGGenerate() will fail.; Any other negative value indicating a specific error code in case of failure.

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

Check that the private key, public key, or both are valid and that the public key is on the curve.

Parameters

[in]	grp	The curve or group that the point should belong to.
[in]	key	A pointer to a struct holding the raw data of the keys to check.
[in]	type	Determines whether to check the private key, public key or both should be checked. See `palKeyToCheck_t` for values.
[out]	verified	The result of 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_ECDHComputeKey	(	const palCurveHandle_t	grp,
		const palECKeyHandle_t	peerPublicKey,
		const palECKeyHandle_t	privateKey,
		palECKeyHandle_t	outKey
	)

Compute the shared secret using elliptic curve Diffie–Hellman.

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_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_ECDSASign	(	palCurveHandle_t	grp,
		palMDType_t	mdType,
		palECKeyHandle_t	prvKey,
		unsigned char *	dgst,
		uint32_t	dgstLen,
		unsigned char *	sig,
		size_t *	sigLen
	)

Compute the Elliptic Curve Digital Signature Algorithm (ECDSA) signature of a previously hashed message.

Parameters

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

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

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

Verify the Elliptic Curve Digital Signature Algorithm (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]	sign	The signature.
[in]	sig	A buffer to hold the computed signature.
[in]	sigLen	The length of the computed signature.
[out]	verified	A 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_ECGroupFree ( palCurveHandle_t * grp )

Free the ECP group context.

Parameters

[in] grp The curve or group to free.

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

palStatus_t pal_ECGroupInitAndLoad	(	palCurveHandle_t *	grp,
		palGroupIndex_t	index
	)

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

Parameters

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

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

palStatus_t pal_ECKeyFree ( palECKeyHandle_t * key )

Release a private or public key context from memory.

Parameters

[in] key A handle for the key context to be freed.

Note: This function should be called before calling pal_ECKeyGenerateKey().

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

palStatus_t pal_ECKeyGenerateKey	(	palGroupIndex_t	grpID,
		palECKeyHandle_t	key
	)

Generate a key pair for a given Elliptic Curve.

Parameters

[in]	grpID	The ECP group identifier.
[in,out]	key	The destination handle for the key pair .

Note: pal_ECKeyNew() should be called before calling pal_ECKeyGenerateKey()

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

palStatus_t pal_ECKeyGetCurve	(	palECKeyHandle_t	key,
		palGroupIndex_t *	grpID
	)

Retrieve the curve ID if it exists in the given key.

Parameters

[in]	key	The key where the curve is retrieved from.
[out]	grpID	The group 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_ECKeyNew ( palECKeyHandle_t * key )

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

Parameters

[in] key The key to initialize.

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

palStatus_t pal_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_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_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_mdFinal	(	palMDHandle_t	md,
		unsigned char *	output
	)

Calculate the final Message Digest (MD).

Parameters

[in]	md	The MD context.
[out]	output	The checksum result of the MD.

Note: pal_mdGetOutputSize() should be called before calling pal_mdFinal() to get the needed size for the output.

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

palStatus_t pal_mdFree ( palMDHandle_t * md )

Free and clear a 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_mdGetOutputSize	(	palMDHandle_t	md,
		size_t *	bufferSize
	)

Get the length of the Message Digest (MD) output.

Parameters

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

Note: This function should be called before calling pal_mdFinal().

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

palStatus_t pal_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	Optional. Size of the HMAC result. If not given, the default is 32 bytes.

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

palStatus_t pal_mdInit	(	palMDHandle_t *	md,
		palMDType_t	mdType
	)

Initialize the Message Digest (MD) context and set it up according to the given algorithm.

Parameters

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

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

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

Apply an Message Digest (MD) process on a 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_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_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_parseECPrivateKeyFromHandle	(	const palKeyHandle_t	prvKeyHandle,
		palECKeyHandle_t	ECKeyHandle
	)

Parse a private key.

Parameters

[in]	prvKeyHandle	A palKey_t object - either a PSA private key 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_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_parseECPublicKeyFromHandle	(	const palKeyHandle_t	pubKeyHandle,
		palECKeyHandle_t	ECKeyHandle
	)

Parse a public key.

Parameters

[in]	pubKeyHandle	A palKey_t object - either a PSA public key handle or a buffer and the size of a 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_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	The 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_sha256	(	const unsigned char *	input,
		size_t	inLen,
		unsigned char	output[PAL_SHA256_SIZE]
	)

Run a SHA-256 operation on the input data.

Parameters

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

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

palStatus_t pal_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.

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

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

DER encode a private key from a key handle.

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.
[out]	actualSize	The actual size of the written data.

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

palStatus_t pal_writePrivateKeyWithHandle	(	const palKeyHandle_t	prvKeyHandle,
		palECKeyHandle_t	ECKeyHandle
	)

Write a private key from a key handle.

Parameters

[in]	prvKeyHandle	A handle to the private key.
[in]	ECKeyHandle	A handle to EC Key handle.

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

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

DER encode a public key from a key handle.

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_writePublicKeyWithHandle	(	const palKeyHandle_t	pubKeyHandle,
		palECKeyHandle_t	ECKeyHandle
	)

Write a public key from a key handle.

Parameters

[in]	prvKeyHandle	A handle to the public key.
[in]	ECKeyHandle	A handle to EC Key handle.

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

palStatus_t pal_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_x509CertGetAttribute	(	palX509Handle_t	x509Cert,
		palX509Attr_t	attr,
		void *	output,
		size_t	outLenBytes,
		size_t *	actualOutLenBytes
	)

Get an attribute 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.

Note: In case of PAL_ERR_BUFFER_TOO_SMALL, the required size is assigned into the actualOutLen parameter.; PAL_X509_CERT_ID_ATTR requires a 33 bytes buffer size.

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

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

Calculate the hash of the part of an X.509 certificate that is to be signed.

This function may be used to validate a certificate signature: Simply retrieve this hash, verify the signature using this hash, the public key and the signature of the X509

Parameters

[in]	x509Cert	Handle to the certificate to hash the TBS (to be signed part).
[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. If 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. Must be at least the size of the digest
[out]	actualOutLenBytes	Size of the digest copied to output. 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_x509CertParse	(	palX509Handle_t	x509Cert,
		const unsigned char *	input,
		size_t	inLen
	)

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

Parameters

[in]	x509Cert	The beginning 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_x509CertVerify	(	palX509Handle_t	x509Cert,
		palX509Handle_t	x509CertChain
	)

Verify one or more DER encoded X.509 certificates.

Parameters

[in]	x509Cert	A handle holding the parsed certificate.
[in]	x509CertChain	Optional. The beginning of the chain to verify the X.509 DER certificate with.

Returns

PAL_SUCCESS on success. In case of failure:

PAL_ERR_X509_BADCERT_EXPIRED
PAL_ERR_X509_BADCERT_FUTURE
PAL_ERR_X509_BADCERT_BAD_MD
PAL_ERR_X509_BADCERT_BAD_PK
PAL_ERR_X509_BADCERT_NOT_TRUSTED
PAL_ERR_X509_BADCERT_BAD_KEY

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

Verify one or more DER-encoded X.509 certificates.

Parameters

[in]	x509Cert	A handle holding the parsed certificate.
[in]	x509CertChain	The beginning of the chain to verify the X509 DER certificate with. Optional.
[out]	verifyResult	A bitmask of the errors that cause the failure. This value is relevant only in case failure.

Returns: PAL_SUCCESS on success. In case of failure returns PAL_ERR_X509_CERT_VERIFY_FAILED.

palStatus_t pal_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_x509CSRFromCertWriteDER	(	palX509Handle_t	x509Cert,
		palx509CSRHandle_t	x509CSR,
		unsigned char *	derBuf,
		size_t	derBufLen,
		size_t *	actualDerBufLen
	)

Writes a CSR from a given X.509 Certificate.

Parameters

[in]	x509Cert	The parsed X.509 certificate on which we generate the CSR from.
[in,out]	x509CSR	The X.509 CSR that has been already initialized with a private key.
[out]	derBuf	A buffer to write to.
[in]	derBufLen	The buffer length.
[out]	actualDerBufLen	The actual length of the written data.

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

palStatus_t pal_x509CSRInit ( palx509CSRHandle_t * x509CSR )

Allocate and initialize 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_x509CSRSetExtendedKeyUsage	(	palx509CSRHandle_t	x509CSR,
		uint32_t	extKeyUsage
	)

Set the extended key usage flags.

Parameters

[in]	x509CSR	The CSR context to configure.
[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_x509CSRSetExtension	(	palx509CSRHandle_t	x509CSR,
		const char *	oid,
		size_t	oidLen,
		const unsigned char *	value,
		size_t	valueLen
	)

Generic function to extend a CSR context.

Parameters

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

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

palStatus_t pal_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 key pair handle, see the note.
[in]	prvKey	The public key to sign with.

Note: To use a key pair, send the desired key pair 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_x509CSRSetKeyUsage	(	palx509CSRHandle_t	x509CSR,
		uint32_t	keyUsage
	)

Set the key usage extension flags for a CSR context.

Parameters

[in]	x509CSR	The CSR context to configure.
[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_x509CSRSetMD	(	palx509CSRHandle_t	x509CSR,
		palMDType_t	mdType
	)

Set the type of 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_x509CSRSetSubject	(	palx509CSRHandle_t	x509CSR,
		const char *	subjectName
	)

Set the subject name for a certificate signing request (CSR). Subject names 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_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]	actualDerLen	The actual length of the written data.

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

palStatus_t pal_x509Free ( palX509Handle_t * x509Cert )

Deallocate all certificate data.

Parameters

[in,out] x509Cert 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_x509Initiate ( palX509Handle_t * x509Cert )

Initialize a certificate chain context.

Parameters

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

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

Documentation

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation