Platform Security Architecture (PSA) API

Functions

	Name
int	wolfSSL_CTX_psa_enable(WOLFSSL_CTX * ctx) This function enables PSA support on the given context.
int	wolfSSL_set_psa_ctx(WOLFSSL * ssl, struct psa_ssl_ctx * ctx) This function setup the PSA context for the given SSL session.
void	wolfSSL_free_psa_ctx(struct psa_ssl_ctx * ctx) This function releases the resources used by a PSA context.
int	wolfSSL_psa_set_private_key_id(struct psa_ssl_ctx * ctx, psa_key_id_t id) This function set the private key used by an SSL session.
int	wc_psa_get_random(unsigned char * out, word32 sz) This function generates random bytes using the PSA crypto API. This is a wrapper around the PSA random number generation functions.
int	wc_psa_aes_encrypt_decrypt(Aes * aes, const uint8_t * input, uint8_t * output, size_t length, psa_algorithm_t alg, int direction) This function performs AES encryption or decryption using the PSA crypto API. It supports various AES modes through the algorithm parameter.

Functions Documentation

function wolfSSL_CTX_psa_enable

int wolfSSL_CTX_psa_enable(
    WOLFSSL_CTX * ctx
)

This function enables PSA support on the given context.

Parameters:

• ctx pointer to the WOLFSSL_CTX object on which the PSA support must be enabled

See: wolfSSL_set_psa_ctx

Return:

• WOLFSSL_SUCCESS on success
• BAD_FUNC_ARG if ctx == NULL

Example

WOLFSSL_CTX *ctx;
ctx = wolfSSL_CTX_new(wolfTLSv1_2_client_method());
if (!ctx)
    return NULL;
ret = wolfSSL_CTX_psa_enable(ctx);
if (ret != WOLFSSL_SUCCESS)
    printf("can't enable PSA on ctx");

function wolfSSL_set_psa_ctx

int wolfSSL_set_psa_ctx(
    WOLFSSL * ssl,
    struct psa_ssl_ctx * ctx
)

This function setup the PSA context for the given SSL session.

Parameters:

• ssl pointer to the WOLFSSL where the ctx will be enabled
• ctx pointer to a struct psa_ssl_ctx (must be unique for a ssl session)

See:

• wolfSSL_psa_set_private_key_id
• wolfSSL_psa_free_psa_ctx

Return:

• WOLFSSL_SUCCESS on success
• BAD_FUNC_ARG if ssl or ctx are NULL

This function setup the PSA context for the TLS callbacks to the given SSL session. At the end of the session, the resources used by the context should be freed using wolfSSL_free_psa_ctx().

Example

// Create new ssl session
WOLFSSL *ssl;
struct psa_ssl_ctx psa_ctx = { 0 };
ssl = wolfSSL_new(ctx);
if (!ssl)
    return NULL;
// setup PSA context
ret = wolfSSL_set_psa_ctx(ssl, ctx);

function wolfSSL_free_psa_ctx

void wolfSSL_free_psa_ctx(
    struct psa_ssl_ctx * ctx
)

This function releases the resources used by a PSA context.

Parameters:

• ctx pointer to a struct psa_ssl_ctx

See: wolfSSL_set_psa_ctx

function wolfSSL_psa_set_private_key_id

int wolfSSL_psa_set_private_key_id(
    struct psa_ssl_ctx * ctx,
    psa_key_id_t id
)

This function set the private key used by an SSL session.

Parameters:

• ctx pointer to a struct psa_ssl_ctx
• id PSA id of the key to be used as private key

See: wolfSSL_set_psa_ctx

Example

// Create new ssl session
WOLFSSL *ssl;
struct psa_ssl_ctx psa_ctx = { 0 };
psa_key_id_t key_id;

// key provisioning already done
get_private_key_id(&key_id);

ssl = wolfSSL_new(ctx);
if (!ssl)
    return NULL;

wolfSSL_psa_set_private_key_id(&psa_ctx, key_id);
wolfSSL_set_psa_ctx(ssl, ctx);

function wc_psa_get_random

int wc_psa_get_random(
    unsigned char * out,
    word32 sz
)

This function generates random bytes using the PSA crypto API. This is a wrapper around the PSA random number generation functions.

Parameters:

• out pointer to buffer to store random bytes
• sz number of random bytes to generate

See: wc_RNG_GenerateBlock

Return:

• 0 On success
• Negative value on error

Example

byte random[32];

int ret = wc_psa_get_random(random, sizeof(random));
if (ret != 0) {
    // error generating random bytes
}

function wc_psa_aes_encrypt_decrypt

int wc_psa_aes_encrypt_decrypt(
    Aes * aes,
    const uint8_t * input,
    uint8_t * output,
    size_t length,
    psa_algorithm_t alg,
    int direction
)

This function performs AES encryption or decryption using the PSA crypto API. It supports various AES modes through the algorithm parameter.

Parameters:

• aes pointer to initialized Aes structure
• input pointer to input data buffer
• output pointer to output data buffer
• length length of data to process
• alg PSA algorithm identifier specifying the AES mode
• direction encryption (1) or decryption (0)

See:

• wc_AesEncrypt
• wc_AesDecrypt

Return:

• 0 On success
• Negative value on error

Example

Aes aes;
byte key[16] = { }; // AES key
byte input[16] = { }; // plaintext
byte output[16];

wc_AesInit(&aes, NULL, INVALID_DEVID);
wc_AesSetKey(&aes, key, sizeof(key), NULL, AES_ENCRYPTION);
int ret = wc_psa_aes_encrypt_decrypt(&aes, input, output,
                                     sizeof(input),
                                     PSA_ALG_ECB_NO_PADDING, 1);

---

Updated on 2025-12-31 at 01:16:02 +0000