PSA mode lets the Barracuda App Server (BAS) use your platform's key store through the same Lua Trusted Platform Module (TPM) API, ba.tpm. You can sign data, manage certificates, and encrypt saved data without handling private signing keys in Lua. Hardware protection depends on the provider and key storage you select.

Trying it on Windows? Follow the Windows quick start. The supplied Mako project creates its development key store automatically.

Integrating a target? Follow the four steps below. A PSA Crypto provider is the library and drivers that implement Arm's Platform Security Architecture (PSA) cryptographic API on your platform. You supply the provider; BAS supplies the integration. Lua application developers can go directly to the working example.

1. Choose device-specific or shared data

A root secret is a random 32-byte value kept in the provider's persistent key store. BAS uses it to derive encryption keys. Provisioning means installing that secret before the first normal startup.

Your requirement	What to do
Data stays on its own device	Set the C compiler definition `BA_PSA_GLOBALKEY_USE_DEVICE_ROOT=1`. BAS creates the device root automatically. You do not need to provision a root.
Several devices must read the same encrypted data	Leave `BA_PSA_GLOBALKEY_USE_DEVICE_ROOT` at its default `0` and provision the same global root on those devices. Follow the shared-root steps. BAS still creates each device's own root automatically.

Choose the first option unless you need sharing. With it, ba.tpm.globalkey() and ba.tpm.uniquekey() both use the device root, and standalone Xedge's xcfg.bin stays device-specific. Changing this choice later changes the encryption keys.

2. Build with a compatible provider

Use the normal build for your target and set these integer C compiler definitions in both the host and BAS:

/* Minimal setup for data that stays on its own device. */
#define BA_ENABLE_TPM 1
#define SHARKSSL_PSA_CONSUMER 1
#define BA_PSA_GLOBALKEY_USE_DEVICE_ROOT 1

The supplied Mako and Xedge build files already set BA_ENABLE_TPM=1. Use inc as the public include directory: <psa/crypto.h> and <psa-consumer/SharkSslPSAConsumerECDSA.h> keep their subdirectory names. For another provider, put its matching header directory before BAS inc, and add its libraries and platform drivers. amalgamation/BAS.c already includes the PSA integration; do not compile lpsa.c or the consumer adapters again.

Check the provider before building: it must support persistent P-256/P-384 signing keys, HKDF-SHA-512 derivation from stored roots (HKDF-SHA-256 when SHARKSSL_USE_SHA_512=0), and AES-256-GCM, plus the algorithms required by your Transport Layer Security (TLS) connections. A signing-only driver is insufficient. Select appropriate protected locations for roots, signing keys, and temporary encryption keys; see provider requirements and settings.

Use the instructions for your host:

3. Initialize the provider and load matching resources

Initialize the provider's entropy, hardware connection, and persistent storage. Require psa_crypto_init() to succeed before cryptographic use. Install the global root first if you selected shared data in step 1.

Host	Where to initialize	Resources to rebuild
Mako	Implement `int makoInitPsa(void)`; Mako calls it after service/daemon setup and before cryptographic use	A current `mako.zip`; its builder includes PSA support automatically.
Standalone Xedge	Implement `int xedgeInitPsa(void)`; `barracuda()` calls it before cryptographic use	Build Xedge resources with environment variable `SHARKSSL_PSA_CONSUMER=1`, as well as enabling the C definition.

Both hosts already register the native binding and initialize ba.tpm before applications run. Do not add Lua initialization to your application. Return 0 from your host's provider hook on success, or a nonzero error to stop startup. The hook is required whenever SHARKSSL_PSA_CONSUMER=1; see the Mako hook contract or Xedge hook contract. Both hooks run before resource verification and Lua creation. Debugger restarts recreate Lua while retaining the provider and keys. Xedge's xedgeInitDiskIo() and xedgeOpenAUX() run too late for provider initialization. Mako's makoOpenAUX() is a softTPM hook and is not called in PSA builds. Initialization errors stop startup; there is no automatic fallback to softTPM.

For a different BAS host, follow the custom-host startup sequence.

4. Check the result and keep the keys

Run the Lua signing example in your application. In a PSA build, ba.psa is true and identifies the backend. The example must also complete successfully; the flag alone does not test keys or prove hardware protection.

Restart the server. Confirm that the example reuses the key and prints the same public-key fingerprint. Before using encrypted data in production, also save and reload it after a restart. If devices share data, verify that a second provisioned device can read it.

Keep the provider's persistent key store, certificates, and certificate-management state across updates. Losing a root can make encrypted data unreadable; losing a signing key requires a new identity. Before switching an existing softTPM installation to PSA, recover the data you need or plan a reset. Changing from an earlier PSA KDF or changing the selected HKDF hash also requires migration: existing root policies are rejected, not replaced. There is no automatic data migration.

Only for shared data: install a global root

Generate one random 32-byte secret for the group of devices that will share data. Use your provider's secure provisioning process, not a password or a constant in application source.
Install that same secret on each device as persistent key ID 1, using the attributes below. Keep ID 2 available for the automatic device root.
Retain this key store across restarts and firmware updates. Use the same HKDF hash, derivation name and returned key length on every device that shares data.

Global-root attribute	Required value
Type and size	`PSA_KEY_TYPE_DERIVE`, 256 bits
Algorithm	`PSA_ALG_HKDF(PSA_ALG_SHA_512)`, or `PSA_ALG_HKDF(PSA_ALG_SHA_256)` when `SHARKSSL_USE_SHA_512=0`
Usage	Exactly `PSA_KEY_USAGE_DERIVE`; no EXPORT or COPY permission
Lifetime and location	Persistent, at the location selected by `BA_PSA_ROOT_LOCATION`

Your provider's provisioning tool or trusted psa_import_key() flow performs the installation. The ID identifies the stored secret; using ID 1 on two devices does not make their secrets equal. For custom IDs and locations, see the root settings.

If setup fails

For numeric errors from the supplied Windows simulator, see the startup error numbers and recovery steps. They distinguish build/provider failures from incompatible or damaged storage.

Symptom	First check
Startup reports a PSA TPM/root error	Was the provider's storage initialized? Either enable the device-root option or install the required global root with the attributes above.
An operation is unsupported or not permitted	Check the provider's algorithms, key attributes, and selected locations against the requirements.
Standalone Xedge fails while loading its configuration	Rebuild both the C code and resources for PSA. Existing softTPM-encrypted configuration requires migration or reset.
A new build cannot read previously saved data	Check that it uses the original key store and root settings. Do not erase the store to fix a startup error.

Further detail

Read PSA Crypto: How It Works for storage policies, derivation, recovery, and provider internals.