SharkSSL C/C++ Reference
TLS, cryptography, certificates, and PSA integration
Crypto context and buffer helpers

Detailed Description

Hash cloning, cleanup, one-shot adapters and representation helpers.

Availability follows the feature macros and selected native or PSA backend.

Functions

SHARKSSL_API int sharkssl_rng (U8 *, U16)
 Fill a buffer using the configured random generator. More...
 
SHARKSSL_API int sharkssl_kmemcmp (const void *a, const void *b, U32 n)
 Compare byte strings without early exit based on differing bytes. More...
 
void sharkssl_clear (void *data, U32 len)
 Overwrite a buffer through the implementation clearing routine. More...
 
U16 sharkssl_getHashLen (U8 hashID)
 Return the digest size for an enabled SharkSSL hash ID. More...
 
int sharkssl_hash (U8 *digest, U8 *data, U32 len, U8 hashID)
 Compute a complete digest using a SharkSSL hash ID. More...
 
SHARKSSL_API int SharkSslSha1Ctx_clone (const SharkSslSha1Ctx *source, SharkSslSha1Ctx *target)
 Clone an active PSA hash context without consuming the source. More...
 
SHARKSSL_API int SharkSslSha1Ctx_abort (SharkSslSha1Ctx *ctx)
 Abort a PSA hash operation and release its resources. More...
 
SHARKSSL_API int SharkSslSha224Ctx_clone (const SharkSslSha224Ctx *source, SharkSslSha224Ctx *target)
 Clone an active PSA hash context without consuming the source. More...
 
SHARKSSL_API int SharkSslSha224Ctx_abort (SharkSslSha224Ctx *ctx)
 Abort a PSA hash operation and release its resources. More...
 
SHARKSSL_API int SharkSslSha256Ctx_clone (const SharkSslSha256Ctx *source, SharkSslSha256Ctx *target)
 Clone an active PSA hash context without consuming the source. More...
 
SHARKSSL_API int SharkSslSha256Ctx_abort (SharkSslSha256Ctx *ctx)
 Abort a PSA hash operation and release its resources. More...
 
SHARKSSL_API int SharkSslSha384Ctx_clone (const SharkSslSha384Ctx *source, SharkSslSha384Ctx *target)
 Clone an active PSA hash context without consuming the source. More...
 
SHARKSSL_API int SharkSslSha384Ctx_abort (SharkSslSha384Ctx *ctx)
 Abort a PSA hash operation and release its resources. More...
 
SHARKSSL_API int SharkSslSha512Ctx_clone (const SharkSslSha512Ctx *source, SharkSslSha512Ctx *target)
 Clone an active PSA hash context without consuming the source. More...
 
SHARKSSL_API int SharkSslSha512Ctx_abort (SharkSslSha512Ctx *ctx)
 Abort a PSA hash operation and release its resources. More...
 
SHARKSSL_API int SharkSslSha224Ctx_constructor (SharkSslSha224Ctx *ctx)
 Initialize a PSA SHA-224 streaming operation. More...
 
SHARKSSL_API int SharkSslSha224Ctx_append (SharkSslSha224Ctx *ctx, const U8 *data, U32 len)
 Append bytes to an active PSA SHA-224 operation. More...
 
SHARKSSL_API int SharkSslSha224Ctx_finish (SharkSslSha224Ctx *ctx, U8 digest[SHARKSSL_SHA224_HASH_LEN])
 Finish PSA SHA-224 and release the operation. More...
 
SHARKSSL_API int sharkssl_sha224 (const U8 *data, U32 len, U8 *digest)
 Compute a one-shot SHA-224 digest through PSA. More...
 
SHARKSSL_API int SharkSslHMACCtx_destructor (SharkSslHMACCtx *ctx)
 Clear an HMAC context and release any owned PSA resources. More...
 
SHARKSSL_API int SharkSslChaChaCtx_destructor (SharkSslChaChaCtx *ctx)
 Abort a standalone PSA ChaCha20 operation and destroy its imported key. More...
 
SHARKSSL_API int sharkssl_chacha20poly1305_encrypt (const U8 key[32], const U8 nonce[12], const U8 *aad, const U8 *input, U8 *output, U8 tag[16], U32 len, U16 aadLen)
 Perform one-shot ChaCha20-Poly1305 encryption and authentication. More...
 
SHARKSSL_API int sharkssl_chacha20poly1305_decrypt (const U8 key[32], const U8 nonce[12], const U8 *aad, const U8 *input, const U8 tag[16], U8 *output, U32 len, U16 aadLen)
 Perform one-shot ChaCha20-Poly1305 authenticated decryption. More...
 
SHARKSSL_API int SharkSslAesCtx_cbc_pkcs7_decrypt (SharkSslAesCtx *ctx, const U8 iv[16], const U8 *input, U8 *output, U32 *outputLen, U32 len, U32 outputCapacity)
 Decrypt PSA AES-CBC and remove PKCS#7 padding. More...
 
SHARKSSL_API SHARKSSL_AES_API_STATUS SharkSslAesCtx_ctr_mode (SharkSslAesCtx *ctx, U8 ctr[16], const U8 *input, U8 *output, U32 len)
 Apply the SharkSSL AES counter-mode convention to complete blocks. More...
 

Function Documentation

◆ sharkssl_chacha20poly1305_decrypt()

int sharkssl_chacha20poly1305_decrypt ( const U8  key[32],
const U8  nonce[12],
const U8 *  aad,
const U8 *  input,
const U8  tag[16],
U8 *  output,
U32  len,
U16  aadLen 
)

Perform one-shot ChaCha20-Poly1305 authenticated decryption.

Requires the standalone PSA ChaCha20 adapter and provider multipart AEAD support. Output is cleared on processing failure after validation; invalid arguments may leave it unchanged.

Parameters
keyconst U8[32]; Required borrowed 32-byte key.
nonceconst U8[12]; Required borrowed 12-byte nonce; encryption must not repeat a nonce with the same key.
aadconst U8 *; Borrowed additional authenticated data, or NULL when aadLen is 0.
inputconst U8 *; Borrowed ciphertext bytes, or NULL when len is 0.
tagconst U8[16]; Required borrowed 16-byte expected tag.
outputU8 *; Required caller-owned output buffer of at least len bytes; use only on success.
lenU32; Payload length in bytes.
aadLenU16; Additional authenticated data length in bytes.
Returns
int: 0 on success; -1 for invalid arguments, authentication failure or provider/cleanup failure.

◆ sharkssl_chacha20poly1305_encrypt()

int sharkssl_chacha20poly1305_encrypt ( const U8  key[32],
const U8  nonce[12],
const U8 *  aad,
const U8 *  input,
U8 *  output,
U8  tag[16],
U32  len,
U16  aadLen 
)

Perform one-shot ChaCha20-Poly1305 encryption and authentication.

Requires the standalone PSA ChaCha20 adapter and provider multipart AEAD support. Output is cleared on processing failure after validation; invalid arguments may leave it unchanged.

Parameters
keyconst U8[32]; Required borrowed 32-byte key.
nonceconst U8[12]; Required borrowed 12-byte nonce; encryption must not repeat a nonce with the same key.
aadconst U8 *; Borrowed additional authenticated data, or NULL when aadLen is 0.
inputconst U8 *; Borrowed plaintext bytes, or NULL when len is 0.
outputU8 *; Required caller-owned output buffer of at least len bytes; use only on success.
tagU8[16]; Required caller-owned 16-byte output tag.
lenU32; Payload length in bytes.
aadLenU16; Additional authenticated data length in bytes.
Returns
int: 0 on success; -1 for invalid arguments, authentication failure or provider/cleanup failure.

◆ sharkssl_clear()

void sharkssl_clear ( void *  data,
U32  len 
)

Overwrite a buffer through the implementation clearing routine.

Parameters
datavoid *; Required writable buffer owned by the caller.
lenU32; Number of bytes to overwrite with zeros.

◆ sharkssl_getHashLen()

U16 sharkssl_getHashLen ( U8  hashID)

Return the digest size for an enabled SharkSSL hash ID.

Parameters
hashIDU8; SHARKSSL_HASHID_* selector supported by the selected backend.
Returns
U16: Digest length in bytes, or 0 for an unsupported or disabled selector.

◆ sharkssl_hash()

int sharkssl_hash ( U8 *  digest,
U8 *  data,
U32  len,
U8  hashID 
)

Compute a complete digest using a SharkSSL hash ID.

Parameters
digestU8 *; Required caller-owned output, at least sharkssl_getHashLen(hashID) bytes.
dataU8 *; Input bytes, borrowed and not modified; may be NULL only when len is 0.
lenU32; Input length in bytes.
hashIDU8; Enabled SHARKSSL_HASHID_* selector supported by the selected backend.
Returns
int: 0 on success; -1 for invalid arguments, unsupported hash or allocation/provider failure. Discard output on failure.

◆ sharkssl_kmemcmp()

int sharkssl_kmemcmp ( const void *  a,
const void *  b,
U32  n 
)

Compare byte strings without early exit based on differing bytes.

Parameters
aconst void *; Required first readable buffer of n bytes.
bconst void *; Required second readable buffer of n bytes.
nU32; Number of bytes to compare.
Returns
int: 0 when equal; nonzero otherwise. This is not a lexicographic ordering result.

◆ sharkssl_rng()

int sharkssl_rng ( U8 *  output,
U16  len 
)

Fill a buffer using the configured random generator.

Initialize and seed the selected RNG with sufficient entropy before cryptographic use. See sharkssl_entropyEx and the configuration guide; a successful call alone does not establish entropy quality.

Parameters
outputU8 *; Required writable caller-owned buffer of len bytes.
lenU16; Requested number of random bytes.
Returns
int: 0 on success; nonzero on allocation or generator/provider failure. Discard the buffer on failure.

◆ sharkssl_sha224()

int sharkssl_sha224 ( const U8 *  data,
U32  len,
U8 *  digest 
)

Compute a one-shot SHA-224 digest through PSA.

Requires SHARKSSL_PSA_CONSUMER, SHARKSSL_USE_SHA_224 and provider SHA-224 support.

Parameters
dataconst U8 *; Borrowed input, or NULL when len is 0.
lenU32; Input length in bytes.
digestU8 *; Required caller-owned 28-byte output.
Returns
int: 0 on success; -1 for invalid arguments or provider failure.

◆ SharkSslAesCtx_cbc_pkcs7_decrypt()

int SharkSslAesCtx_cbc_pkcs7_decrypt ( SharkSslAesCtx *  ctx,
const U8  iv[16],
const U8 *  input,
U8 *  output,
U32 *  outputLen,
U32  len,
U32  outputCapacity 
)

Decrypt PSA AES-CBC and remove PKCS#7 padding.

Requires SHARKSSL_PSA_CONSUMER_STANDALONE_AES and provider CBC-PKCS7 support. CBC padding does not authenticate the ciphertext. Processing failures clear outputCapacity bytes after validation.

Parameters
ctxSharkSslAesCtx *; Required valid AES context initialized with the key.
ivconst U8[16]; Required borrowed 16-byte IV; unchanged.
inputconst U8 *; Required ciphertext buffer, borrowed for the call.
outputU8 *; Required caller-owned plaintext buffer; only outputLen bytes are valid on success.
outputLenU32 *; Required output byte count, initialized to 0.
lenU32; Nonzero ciphertext length in bytes, a multiple of 16.
outputCapacityU32; Output capacity in bytes, at least len.
Returns
int: 0 on success; -1 for invalid arguments, padding failure or provider/cleanup failure.

◆ SharkSslAesCtx_ctr_mode()

SHARKSSL_AES_API_STATUS SharkSslAesCtx_ctr_mode ( SharkSslAesCtx *  ctx,
U8  ctr[16],
const U8 *  input,
U8 *  output,
U32  len 
)

Apply the SharkSSL AES counter-mode convention to complete blocks.

The counter increments from byte 0 with carry before encrypting each block. This little-endian convention differs from the provider PSA_ALG_CTR interface. Do not reuse a counter sequence with the same key.

Parameters
ctxSharkSslAesCtx *; Required initialized AES context using the encryption key schedule.
ctrU8[16]; Required 16-byte mutable counter, retained by the caller between calls.
inputconst U8 *; Readable input of len bytes; required when len is nonzero.
outputU8 *; Writable output of len bytes; required when len is nonzero.
lenU32; Byte count, a multiple of 16.
Returns
SHARKSSL_AES_API_STATUS: Native build: void. PSA standalone AES: 0 on success or -1 on argument/provider failure.

◆ SharkSslChaChaCtx_destructor()

int SharkSslChaChaCtx_destructor ( SharkSslChaChaCtx *  ctx)

Abort a standalone PSA ChaCha20 operation and destroy its imported key.

Requires SHARKSSL_PSA_CONSUMER_STANDALONE_CHACHA20. The context is cleared; reconstruct before reuse. Native builds use the destructor macro instead.

Parameters
ctxSharkSslChaChaCtx *; Required initialized PSA ChaCha20 context; caller retains the storage.
Returns
int: 0 on successful cleanup; -1 for NULL or provider cleanup failure.

◆ SharkSslHMACCtx_destructor()

int SharkSslHMACCtx_destructor ( SharkSslHMACCtx *  ctx)

Clear an HMAC context and release any owned PSA resources.

The native implementation clears the derived pads. The PSA consumer aborts the MAC and destroys its imported key. Do not continue appending after destruction.

Parameters
ctxSharkSslHMACCtx *; Required initialized context; caller retains the storage.
Returns
int: 0 on successful cleanup; -1 for invalid context or PSA cleanup failure.

◆ SharkSslSha1Ctx_abort()

int SharkSslSha1Ctx_abort ( SharkSslSha1Ctx *  ctx)

Abort a PSA hash operation and release its resources.

Requires SHARKSSL_PSA_CONSUMER and the selected hash. Reconstruct before appending again.

Parameters
ctxSharkSslSha1Ctx *; Required context initialized by construction or cloning.
Returns
int: 0 on successful abort; -1 for a NULL context or provider failure.

◆ SharkSslSha1Ctx_clone()

int SharkSslSha1Ctx_clone ( const SharkSslSha1Ctx *  source,
SharkSslSha1Ctx *  target 
)

Clone an active PSA hash context without consuming the source.

Requires SHARKSSL_PSA_CONSUMER and the selected hash. Finish or abort each copy independently; do not overwrite a live target.

Parameters
sourceconst SharkSslSha1Ctx *; Required active context, borrowed and unchanged.
targetSharkSslSha1Ctx *; Required distinct storage with no live PSA operation; receives an independent operation.
Returns
int: 0 on success; -1 for invalid state/arguments or provider failure.

◆ SharkSslSha224Ctx_abort()

int SharkSslSha224Ctx_abort ( SharkSslSha224Ctx *  ctx)

Abort a PSA hash operation and release its resources.

Requires SHARKSSL_PSA_CONSUMER and the selected hash. Reconstruct before appending again.

Parameters
ctxSharkSslSha224Ctx *; Required context initialized by construction or cloning.
Returns
int: 0 on successful abort; -1 for a NULL context or provider failure.

◆ SharkSslSha224Ctx_append()

int SharkSslSha224Ctx_append ( SharkSslSha224Ctx *  ctx,
const U8 *  data,
U32  len 
)

Append bytes to an active PSA SHA-224 operation.

Parameters
ctxSharkSslSha224Ctx *; Required active, unfinished context.
dataconst U8 *; Borrowed input; may be NULL only when len is 0.
lenU32; Input length in bytes.
Returns
int: 0 on success; -1 for invalid state/arguments or provider failure.

◆ SharkSslSha224Ctx_clone()

int SharkSslSha224Ctx_clone ( const SharkSslSha224Ctx *  source,
SharkSslSha224Ctx *  target 
)

Clone an active PSA hash context without consuming the source.

Requires SHARKSSL_PSA_CONSUMER and the selected hash. Finish or abort each copy independently; do not overwrite a live target.

Parameters
sourceconst SharkSslSha224Ctx *; Required active context, borrowed and unchanged.
targetSharkSslSha224Ctx *; Required distinct storage with no live PSA operation; receives an independent operation.
Returns
int: 0 on success; -1 for invalid state/arguments or provider failure.

◆ SharkSslSha224Ctx_constructor()

int SharkSslSha224Ctx_constructor ( SharkSslSha224Ctx *  ctx)

Initialize a PSA SHA-224 streaming operation.

Requires SHARKSSL_PSA_CONSUMER and SHARKSSL_USE_SHA_224. Finish or abort before reusing the storage.

Parameters
ctxSharkSslSha224Ctx *; Required storage with no live operation; caller retains ownership.
Returns
int: 0 on success; -1 on invalid arguments or provider failure.

◆ SharkSslSha224Ctx_finish()

int SharkSslSha224Ctx_finish ( SharkSslSha224Ctx *  ctx,
U8  digest[SHARKSSL_SHA224_HASH_LEN] 
)

Finish PSA SHA-224 and release the operation.

Parameters
ctxSharkSslSha224Ctx *; Required active context; reconstruct before reuse.
digestU8[SHARKSSL_SHA224_HASH_LEN]; Required caller-owned 28-byte output.
Returns
int: 0 on success; -1 on state, provider or cleanup failure. Discard the digest on failure.

◆ SharkSslSha256Ctx_abort()

int SharkSslSha256Ctx_abort ( SharkSslSha256Ctx *  ctx)

Abort a PSA hash operation and release its resources.

Requires SHARKSSL_PSA_CONSUMER and the selected hash. Reconstruct before appending again.

Parameters
ctxSharkSslSha256Ctx *; Required context initialized by construction or cloning.
Returns
int: 0 on successful abort; -1 for a NULL context or provider failure.

◆ SharkSslSha256Ctx_clone()

int SharkSslSha256Ctx_clone ( const SharkSslSha256Ctx *  source,
SharkSslSha256Ctx *  target 
)

Clone an active PSA hash context without consuming the source.

Requires SHARKSSL_PSA_CONSUMER and the selected hash. Finish or abort each copy independently; do not overwrite a live target.

Parameters
sourceconst SharkSslSha256Ctx *; Required active context, borrowed and unchanged.
targetSharkSslSha256Ctx *; Required distinct storage with no live PSA operation; receives an independent operation.
Returns
int: 0 on success; -1 for invalid state/arguments or provider failure.

◆ SharkSslSha384Ctx_abort()

int SharkSslSha384Ctx_abort ( SharkSslSha384Ctx *  ctx)

Abort a PSA hash operation and release its resources.

Requires SHARKSSL_PSA_CONSUMER and the selected hash. Reconstruct before appending again.

Parameters
ctxSharkSslSha384Ctx *; Required context initialized by construction or cloning.
Returns
int: 0 on successful abort; -1 for a NULL context or provider failure.

◆ SharkSslSha384Ctx_clone()

int SharkSslSha384Ctx_clone ( const SharkSslSha384Ctx *  source,
SharkSslSha384Ctx *  target 
)

Clone an active PSA hash context without consuming the source.

Requires SHARKSSL_PSA_CONSUMER and the selected hash. Finish or abort each copy independently; do not overwrite a live target.

Parameters
sourceconst SharkSslSha384Ctx *; Required active context, borrowed and unchanged.
targetSharkSslSha384Ctx *; Required distinct storage with no live PSA operation; receives an independent operation.
Returns
int: 0 on success; -1 for invalid state/arguments or provider failure.

◆ SharkSslSha512Ctx_abort()

int SharkSslSha512Ctx_abort ( SharkSslSha512Ctx *  ctx)

Abort a PSA hash operation and release its resources.

Requires SHARKSSL_PSA_CONSUMER and the selected hash. Reconstruct before appending again.

Parameters
ctxSharkSslSha512Ctx *; Required context initialized by construction or cloning.
Returns
int: 0 on successful abort; -1 for a NULL context or provider failure.

◆ SharkSslSha512Ctx_clone()

int SharkSslSha512Ctx_clone ( const SharkSslSha512Ctx *  source,
SharkSslSha512Ctx *  target 
)

Clone an active PSA hash context without consuming the source.

Requires SHARKSSL_PSA_CONSUMER and the selected hash. Finish or abort each copy independently; do not overwrite a live target.

Parameters
sourceconst SharkSslSha512Ctx *; Required active context, borrowed and unchanged.
targetSharkSslSha512Ctx *; Required distinct storage with no live PSA operation; receives an independent operation.
Returns
int: 0 on success; -1 for invalid state/arguments or provider failure.