Build and run Mako with the supplied software PSA Crypto provider. The project creates its development key store and root secrets automatically, so you can try the ba.tpm Lua API without manually provisioning keys. This demonstrates PSA integration on Windows; hardware protection requires a target provider.

Using standalone Xedge? Follow the Xedge Windows quick start.

Before you start

You need the Windows BAS SDK and Visual Studio with the C++ desktop tools and Windows SDK. Use an ordinary Windows Command Prompt (CMD) and start in the BAS root. The SDK includes the provider and matching mako.zip.

1. Select the project

Open examples/MakoServer/VcMake/mako-psa.vcxproj in Visual Studio and select Debug x64. Build Mako and its PSA provider dependency together. Normal Visual Studio builds preserve the simulator's persistent state.

Using an SVN development checkout? Follow the development resource and version steps when building unstamped sources. The released SDK already includes a matching mako.zip and stamped headers.

2. Create fresh simulator state

BuildPsa.cmd is a state setup command, despite its historical name. It does not compile code, locate Visual Studio, or rebuild resources. It uses the existing Debug x64 executable and mako.zip in the project's normal Visual Studio output directory.

This command deletes the old simulator roots and signing keys. Data encrypted with the old roots cannot be recovered with the new ones. Run it only when you want a fresh development state. Stop Mako first.

rem Prepare fresh state for the public SDK's existing Debug x64 executable.

examples\MakoServer\BuildPsa.cmd

Read the warning and type RESET to continue, or press Enter to cancel. The command deletes both psa-simulator/ and psa-simulator.key, then runs Mako once to recreate the state. Its check exercises normal .openports initialization, the default TLS identity and key derivation with server ports disabled. It prints READY only after the executable exits successfully and the check passes. You can then run the same project from Visual Studio.

The initializer is src/PsaSimInit.c, which implements makoInitPsa(). Mako calls it before cryptographic use. The application itself creates the state; the CMD script does not generate or import secret key material.

Keep PsaTestSimulator=true for the public development project. The normal mako.sln builds softTPM instead.

Script output directory

The command takes no arguments and always uses the released VcMake project. Its executable and simulator state directory is examples/MakoServer/obj/VcMake/psa/x64/Debug/.

The script requires mako-psa.exe and mako.zip in that directory. If either is missing, it stops and asks you to build the project first. It always uses that ZIP, ignoring an inherited MAKO_ZIP override. A locked store or a linked output/store path stops setup before deletion.

Exit code 0 means fresh state was created and verified. Exit code 1 means cancellation, reset failure or startup failure; 2 means invalid arguments or missing inputs. Startup failure leaves its temporary log path in the output. Correct the reported cause before retrying. Do not use this command for routine rebuilds or restarts, since each confirmed run replaces the keys. Other project configurations remain available in Visual Studio; this setup command targets Debug x64 only.

3. Run the Lua check

Create a directory named psa-check beside mako-psa.exe. Save the Lua signing example as a file named .preload inside it, not .preload.txt. Then run:

rem Run from the output directory so psa-check is found here.
cd examples\MakoServer\obj\VcMake\psa\x64\Debug
mako-psa.exe -l::psa-check

On first run, expect PSA test simulator storage: ..., Created signing key, and PSA signing check passed. Record the 64-character Public-key SHA-256 value. Stop with Ctrl+C and wait for Mako to exit and the prompt to return. Then run mako-psa.exe -l::psa-check again from the same directory.

Confirm all three results: Reusing signing key, the identical public-key fingerprint, and PSA signing check passed. If the demonstration key already exists from an earlier run, both launches report that it is reused. You do not need to delete the store to repeat this check.

Keep these files together

The first run creates two paths beside the executable:

Path	Keep it because
`psa-simulator/`	It contains the persistent roots and signing keys.
`psa-simulator.key`	It protects the stored key records.

Retain both across normal Visual Studio builds and restarts. Run the reset command only when you deliberately want fresh test keys. If storage is locked, stop the other process using that directory. If a file is missing or corrupt, restore the original store and matching wrapping-secret file when available. A lost key cannot be recovered from its name.

Each new installation creates its own roots. Even ba.tpm.globalkey() values are local to this installation; the simulator does not provision a shared fleet secret.

Startup error numbers

The supplied simulator reports PSA status numbers in messages such as PSA provider initialization failed (-146) or .openports:4: PSA TPM: PSA error -133. The symbolic definitions are in inc/psa/crypto.h. A number identifies an error category; the surrounding message and stored key attributes determine the cause.

Code	PSA name	What to check in this Windows setup
`-133`	`PSA_ERROR_NOT_PERMITTED`	The TPM rejects an incompatible root policy. Current roots must be persistent 256-bit `PSA_KEY_TYPE_DERIVE` keys with HKDF-SHA-512 (HKDF-SHA-256 when `SharkSslUseSha512=0`) and exactly `PSA_KEY_USAGE_DERIVE`. Earlier PBKDF2/SP 800-108 stores, or stores created with the other HKDF hash, have incompatible roots. Preserve them for data recovery; no automatic migration is provided.
`-134`	`PSA_ERROR_NOT_SUPPORTED`	The provider does not support the requested operation or policy. Rebuild Mako and its provider in Visual Studio with matching current headers. The state setup script does not compile code. Replacing only `mako.zip` is insufficient.
`-136`	`PSA_ERROR_INVALID_HANDLE`	A required key is absent, for example global root ID `1`. Restore the matching store. The device root has a separate automatic-creation policy.
`-146`	`PSA_ERROR_STORAGE_FAILURE`	Check the store/key pair, file permissions, wrapping-secret length and whether another process owns the store lock. Keeping the directory but losing its `.key` file fails. Deleting only the directory while retaining `.key` also fails because first-use setup will not overwrite the existing secret.
`-152`	`PSA_ERROR_DATA_CORRUPT`	A stored record is damaged or cannot be authenticated with the supplied wrapping secret. Restore the original matching pair; do not edit record headers or substitute another installation's `.key`.

Deliberately start with fresh test keys

Use this only for a disposable development store. Fresh roots change derived encryption keys, and fresh signing keys change identities. They cannot recover data encrypted using the old roots. If you need that data, restore the original store and matching wrapping secret instead.

Stop Mako and wait for the process to exit.
If you need a backup, copy the complete directory and its matching .key file together before proceeding. Preserve their permissions.
Run BuildPsa.cmd for the VcMake project's existing Debug x64 output. Read the deletion warning and type RESET.
Require the READY message. Then open the same project in Visual Studio, select Debug x64, and run. Normal subsequent starts reuse the new keys.

The command handles a missing directory or a missing .key by removing whichever remains before initializing. Do not manually create an empty psa-simulator directory. If startup fails after deletion, correct the cause and rerun setup; an interrupted attempt may leave partial state.

For another provider, follow the Mako target build steps. For storage, startup, and error behavior, read How It Works.