Mayank Gupta / Mbed OS pelion-example-frdm

Important changes to repositories hosted on mbed.com

Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.

To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.

It is also possible to export all your personal repositories from the account settings page.

Dependencies:   FXAS21002 FXOS8700Q

Embed: (wiki syntax)

« Back to documentation index

pal_Crypto.h File Reference
Typedefs | Enumerations | Functions

pal_Crypto.h File Reference

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

Go to the source code of this file.

Typedefs

typedef enum palAesKeyType palAesKeyType_t
 Key types to be set to the AES engine.
typedef enum palMDType palMDType_t
 Message digest algorithms supported by PAL.
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 enum palGroupIndex palGroupIndex_t
 Supported curves.
typedef enum palKeyUsage palKeyUsage_t
 Key usage options.
typedef enum palExtKeyUsage palExtKeyUsage_t
 Extended key usage options.
typedef enum palKeyToCheck palKeyToCheck_t
 Key check options.
typedef enum palX509Attr palX509Attr_t
 Attributes to be retrieved from the X.509 certificate.

Enumerations

enum  palAesKeyType
 

Key types to be set to the AES engine.

More...
enum  palMDType
 

Message digest algorithms supported by PAL.

More...
enum  palAesMode
 

AES mode for ECB encryption and decryption.

More...
enum  palASNTag
 

The enum tags supported by PAL for ASN.1.

More...
enum  palGroupIndex
 

Supported curves.

More...
enum  palKeyUsage
 

Key usage options.

More...
enum  palExtKeyUsage
 

Extended key usage options.

More...
enum  palKeyToCheck
 

Key check options.

More...
enum  palX509Attr
 

Attributes to be retrieved from the X.509 certificate.

More...

Functions

palStatus_t pal_initAes (palAesHandle_t *aes)
 Initialize an AES context.
palStatus_t pal_freeAes (palAesHandle_t *aes)
 Free an AES context.
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.
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.
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.
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.
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.
palStatus_t pal_x509Initiate (palX509Handle_t *x509Cert)
 Initialize a certificate chain context.
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.
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.
palStatus_t pal_x509CertVerify (palX509Handle_t x509Cert, palX509Handle_t x509CertChain)
 Verify one or more DER encoded X.509 certificates.
palStatus_t pal_x509CertVerifyExtended (palX509Handle_t x509Cert, palX509Handle_t x509CertChain, int32_t *verifyResult)
 Verify one or more DER-encoded X.509 certificates.
palStatus_t pal_x509Free (palX509Handle_t *x509Cert)
 Deallocate all certificate data.
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.
palStatus_t pal_mdUpdate (palMDHandle_t md, const unsigned char *input, size_t inLen)
 Apply an Message Digest (MD) process on a buffer.
palStatus_t pal_mdGetOutputSize (palMDHandle_t md, size_t *bufferSize)
 Get the length of the Message Digest (MD) output.
palStatus_t pal_mdFinal (palMDHandle_t md, unsigned char *output)
 Calculate the final Message Digest (MD).
palStatus_t pal_mdFree (palMDHandle_t *md)
 Free and clear a Message Digest (MD) context.
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.
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.
palStatus_t pal_CCMInit (palCCMHandle_t *ctx)
palStatus_t pal_CCMFree (palCCMHandle_t *ctx)
 Destroy a CCM context.
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.
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 .
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.
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.
palStatus_t pal_CtrDRBGIsSeeded (palCtrDrbgCtxHandle_t ctx)
 Check whether a Counter mode Deterministic Random Byte Generator (CTR-DRBG) context is seeded.
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).
palStatus_t pal_CtrDRBGFree (palCtrDrbgCtxHandle_t *ctx)
 Destroy a Counter mode Deterministic Random Byte Generator (CTR-DRBG) context.
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.
palStatus_t pal_CMACStart (palCMACHandle_t *ctx, const unsigned char *key, size_t keyLenBits, palCipherID_t cipherID)
 Start an iterative CMAC cipher.
palStatus_t pal_CMACUpdate (palCMACHandle_t ctx, const unsigned char *input, size_t inLen)
 Update an iterative CMAC cipher.
palStatus_t pal_CMACFinish (palCMACHandle_t *ctx, unsigned char *output, size_t *outLen)
 Finish an iterative CMAC cipher.
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.
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.
palStatus_t pal_ECKeyNew (palECKeyHandle_t *key)
 Allocate a key context and initialize a key pair as an invalid pair.
palStatus_t pal_ECKeyFree (palECKeyHandle_t *key)
 Release a private or public key context from memory.
palStatus_t pal_parseECPrivateKeyFromDER (const unsigned char *prvDERKey, size_t keyLen, palECKeyHandle_t key)
 Parse a DER-encoded private key.
palStatus_t pal_parseECPublicKeyFromDER (const unsigned char *pubDERKey, size_t keyLen, palECKeyHandle_t key)
 Parse a DER-encoded public key.
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.
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.
palStatus_t pal_ECKeyGenerateKey (palGroupIndex_t grpID, palECKeyHandle_t key)
 Generate a key pair for a given Elliptic Curve.
palStatus_t pal_ECKeyGetCurve (palECKeyHandle_t key, palGroupIndex_t *grpID)
 Retrieve the curve ID if it exists in the given key.
palStatus_t pal_ECGroupInitAndLoad (palCurveHandle_t *grp, palGroupIndex_t index)
 Initialize and set an ECP group using well-known domain parameters.
palStatus_t pal_ECGroupFree (palCurveHandle_t *grp)
 Free the ECP group context.
palStatus_t pal_x509CSRInit (palx509CSRHandle_t *x509CSR)
 Allocate and initialize X.509 certificate signing request (CSR) context.
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.
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.
palStatus_t pal_x509CSRSetKeyUsage (palx509CSRHandle_t x509CSR, uint32_t keyUsage)
 Set the key usage extension flags for a CSR context.
palStatus_t pal_x509CSRSetExtendedKeyUsage (palx509CSRHandle_t x509CSR, uint32_t extKeyUsage)
 Set the extended key usage flags.
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.
palStatus_t pal_x509CSRWriteDER (palx509CSRHandle_t x509CSR, unsigned char *derBuf, size_t derBufLen, size_t *actualDerLen)
 Write a CSR to a DER structure.
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.
palStatus_t pal_x509CSRFree (palx509CSRHandle_t *x509CSR)
 Free the X.509 CSR context.
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.
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.
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.
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.

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

Definition in file pal_Crypto.h.

Typedef Documentation

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 enum palExtKeyUsage palExtKeyUsage_t

Extended key usage options.

typedef enum palGroupIndex palGroupIndex_t

Supported curves.

typedef enum palKeyToCheck palKeyToCheck_t

Key check options.

typedef enum palKeyUsage palKeyUsage_t

Key usage options.

typedef enum palMDType palMDType_t

Message digest algorithms supported by PAL.

typedef enum palX509Attr palX509Attr_t

Attributes to be retrieved from the X.509 certificate.

Enumeration Type Documentation

enum palAesKeyType

Key types to be set to the AES engine.

Definition at line 50 of file pal_Crypto.h.

enum palAesMode

AES mode for ECB encryption and decryption.

Definition at line 61 of file pal_Crypto.h.

enum palASNTag

The enum tags supported by PAL for ASN.1.

Definition at line 67 of file pal_Crypto.h.

enum palExtKeyUsage

Extended key usage options.

Definition at line 119 of file pal_Crypto.h.

enum palGroupIndex

Supported curves.

Definition at line 105 of file pal_Crypto.h.

enum palKeyToCheck

Key check options.

Definition at line 130 of file pal_Crypto.h.

enum palKeyUsage

Key usage options.

Definition at line 111 of file pal_Crypto.h.

enum palMDType

Message digest algorithms supported by PAL.

Definition at line 56 of file pal_Crypto.h.

enum palX509Attr

Attributes to be retrieved from the X.509 certificate.

Definition at line 137 of file pal_Crypto.h.

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.

Definition at line 48 of file pal_Crypto.c.

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.

Definition at line 57 of file pal_Crypto.c.

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.

Definition at line 66 of file pal_Crypto.c.

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.

Definition at line 225 of file pal_Crypto.c.

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]inputA 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.

Definition at line 261 of file pal_Crypto.c.

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]inputA buffer holding the input data.
[in]inLen,:The length of the input data.
[in]iv,:The initialization vector.
[in]ivLen,:The length of the initalization 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.

Definition at line 273 of file pal_Crypto.c.

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.

Definition at line 243 of file pal_Crypto.c.

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.

Definition at line 234 of file pal_Crypto.c.

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.

Definition at line 252 of file pal_Crypto.c.

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.

Definition at line 338 of file pal_Crypto.c.

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.

Definition at line 378 of file pal_Crypto.c.

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.

Definition at line 351 of file pal_Crypto.c.

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.

Definition at line 364 of file pal_Crypto.c.

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.

Definition at line 329 of file pal_Crypto.c.

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.

Definition at line 319 of file pal_Crypto.c.

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.

Definition at line 285 of file pal_Crypto.c.

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.

Definition at line 309 of file pal_Crypto.c.

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.

Definition at line 401 of file pal_Crypto.c.

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.

Definition at line 629 of file pal_Crypto.c.

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 ofthe 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.

Definition at line 639 of file pal_Crypto.c.

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.

Definition at line 649 of file pal_Crypto.c.

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.

Definition at line 472 of file pal_Crypto.c.

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.

Definition at line 463 of file pal_Crypto.c.

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.

Definition at line 419 of file pal_Crypto.c.

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.

Definition at line 481 of file pal_Crypto.c.

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.

Definition at line 490 of file pal_Crypto.c.

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.

Definition at line 410 of file pal_Crypto.c.

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.

Definition at line 30 of file pal_Crypto.c.

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.

Definition at line 21 of file pal_Crypto.c.

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.

Definition at line 194 of file pal_Crypto.c.

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.

Definition at line 203 of file pal_Crypto.c.

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.

Definition at line 185 of file pal_Crypto.c.

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.

Definition at line 392 of file pal_Crypto.c.

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.

Definition at line 167 of file pal_Crypto.c.

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.

Definition at line 176 of file pal_Crypto.c.

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.

Definition at line 428 of file pal_Crypto.c.

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.

Definition at line 437 of file pal_Crypto.c.

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.

Definition at line 39 of file pal_Crypto.c.

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.

Definition at line 212 of file pal_Crypto.c.

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.

Definition at line 446 of file pal_Crypto.c.

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.

Definition at line 455 of file pal_Crypto.c.

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.

Definition at line 110 of file pal_Crypto.c.

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.

Definition at line 659 of file pal_Crypto.c.

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.

Definition at line 97 of file pal_Crypto.c.

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

Definition at line 139 of file pal_Crypto.c.

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`.

in order to turn off the MSB bit.

Definition at line 123 of file pal_Crypto.c.

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.

Definition at line 616 of file pal_Crypto.c.

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.

Definition at line 603 of file pal_Crypto.c.

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.

Definition at line 499 of file pal_Crypto.c.

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.

Definition at line 564 of file pal_Crypto.c.

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.

Definition at line 577 of file pal_Crypto.c.

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.

Definition at line 525 of file pal_Crypto.c.

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.

Definition at line 551 of file pal_Crypto.c.

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.

Definition at line 538 of file pal_Crypto.c.

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.

Definition at line 512 of file pal_Crypto.c.

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.

Definition at line 590 of file pal_Crypto.c.

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.

Definition at line 154 of file pal_Crypto.c.

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.

Definition at line 84 of file pal_Crypto.c.

Generated on Tue Jul 12 2022 20:21:04 by  doxygen 1.7.2