SharkSSL C/C++ Reference
TLS, cryptography, certificates, and PSA integration

Detailed Description

AES-GCM.

Data Structures

struct  SharkSslAesGcmCtx
 AesGcmCtx. More...
 

Typedefs

typedef struct SharkSslAesGcmCtx SharkSslAesGcmCtx
 AesGcmCtx. More...
 

Functions

SHARKSSL_API SHARKSSL_AES_API_STATUS SharkSslAesGcmCtx_constructor (SharkSslAesGcmCtx *ctx, const U8 *key, U8 keyLen)
 Initialize. More...
 
SHARKSSL_API int SharkSslAesGcmCtx_encrypt (SharkSslAesGcmCtx *ctx, const U8 vect[12], U8 tagout[16], const U8 *auth, U16 authlen, const U8 *input, U8 *output, U32 len)
 Encrypt and authenticate one complete message. More...
 
SHARKSSL_API int SharkSslAesGcmCtx_decrypt (SharkSslAesGcmCtx *ctx, const U8 vect[12], U8 tagin[16], const U8 *auth, U16 authlen, U8 *input, U8 *output, U32 len)
 Decrypt and authenticate one complete message. More...
 

Typedef Documentation

◆ SharkSslAesGcmCtx

AesGcmCtx.

Function Documentation

◆ SharkSslAesGcmCtx_constructor()

SHARKSSL_AES_API_STATUS SharkSslAesGcmCtx_constructor ( SharkSslAesGcmCtx *  ctx,
const U8 *  key,
U8  keyLen 
)

Initialize.

The caller owns the context.

Parameters
ctxUninitialized data of size sizeof(SharkSslAesGcmCtx).
keythe encryption/decryption key
keyLen'key' length

The key length is in bytes: 16, 24, or 32, subject to the enabled algorithms/backend. Clear the context with its destructor after use.

Returns
Native build: void, with no return value. With SHARKSSL_PSA_CONSUMER_STANDALONE_AES=1: int, 0 on success and -1 on invalid arguments or provider failure.

◆ SharkSslAesGcmCtx_decrypt()

SHARKSSL_API int SharkSslAesGcmCtx_decrypt ( SharkSslAesGcmCtx *  ctx,
const U8  vect[12],
U8  tagin[16],
const U8 *  auth,
U16  authlen,
U8 *  input,
U8 *  output,
U32  len 
)

Decrypt and authenticate one complete message.

Parameters
ctxcontext initialized by SharkSslAesGcmCtx_constructor.
vectthe same IV as used in SharkSslAesGcmCtx_encrypt.
taginrequired 16-byte expected tag from the matching encryption call. The native and PSA implementations read it without modification.
auththe same auth as used in SharkSslAesGcmCtx_encrypt or NULL if not used.
authlenthe length of the 'auth' parameter.
inputthe data to be decrypted.
outputthe decrypted plaintext. This buffer may be the same as input. On authentication failure, its contents are invalid and may be modified. Discard them; in-place decryption may also destroy the ciphertext.
lenciphertext length in bytes. Keep it below 2^29 with the common native implementation, matching the encryption restriction.
Returns
0 when the tag matches, nonzero otherwise. Do not access output until this function returns.

◆ SharkSslAesGcmCtx_encrypt()

int SharkSslAesGcmCtx_encrypt ( SharkSslAesGcmCtx *  ctx,
const U8  vect[12],
U8  tagout[16],
const U8 *  auth,
U16  authlen,
const U8 *  input,
U8 *  output,
U32  len 
)

Encrypt and authenticate one complete message.

Each call authenticates one complete message and writes its tag.

Parameters
ctxinitialized context, retained for reuse with distinct nonces.
vectrequired 12-byte nonce. Never reuse a nonce with the same key.
tagoutrequired 16-byte output tag; overwritten, not accumulated.
authoptional additional authenticated data (AAD). These bytes are authenticated but not encrypted; NULL requires authlen=0.
authlenAAD length in bytes.
inputplaintext bytes, borrowed for this call.
outputwritable ciphertext buffer of at least len bytes. Exact in-place operation is supported.
lenplaintext length in bytes. Keep it below 2^29 when using the common native implementation, whose GCM bit-length field is 32 bits.

Each call starts a separate GCM message. To store a large object in chunks, assign a distinct nonce to every chunk under this key and keep each chunk's nonce, AAD, and tag for decryption. A previous tag is not input to the next call. Authenticate chunk order/identity in the AAD when the application must detect rearrangement or substitution.

It does not continue a previous GCM message or accumulate the previous tag. Use a distinct 12-byte nonce for every encrypted message under a key, including separately stored chunks; do not reuse a nonce across calls.

Returns
int: 0 on success; -1 on an argument/provider failure in the PSA consumer. The native implementation requires valid inputs and returns 0.