puf.h

Functions

	Name
int	wc_PufInit(wc_PufCtx * ctx) Initialize a wc_PufCtx structure, zeroing all fields. Must be called before any other PUF operations.
int	wc_PufReadSram(wc_PufCtx * ctx, const byte * sramAddr, word32 sramSz) Read raw SRAM data into the PUF context. The sramAddr should point to a NOLOAD linker section to preserve the power-on state.
int	wc_PufEnroll(wc_PufCtx * ctx) Perform PUF enrollment. Encodes raw SRAM using BCH(127,64,t=10) and generates public helper data. After enrollment the context is ready for key derivation and identity retrieval.
int	wc_PufReconstruct(wc_PufCtx * ctx, const byte * helperData, word32 helperSz) Reconstruct stable PUF bits from noisy SRAM using stored helper data. BCH error correction (t=10) corrects up to 10 bit flips per 127-bit codeword.
int	wc_PufDeriveKey(wc_PufCtx * ctx, const byte * info, word32 infoSz, byte * key, word32 keySz) Derive a cryptographic key from PUF stable bits using HKDF. Uses SHA-256 by default, or SHA3-256 when WC_PUF_SHA3 is defined. The info parameter provides domain separation for multiple keys. Requires HAVE_HKDF.
int	wc_PufGetIdentity(wc_PufCtx * ctx, byte * id, word32 idSz) Retrieve the device identity hash (SHA_256 or SHA3_256 of stable bits). Deterministic for a given device.
int	wc_PufZeroize(wc_PufCtx * ctx) Securely zeroize all sensitive data in the PUF context using ForceZero. Call when PUF is no longer needed.
int	wc_PufSetTestData(wc_PufCtx * ctx, const byte * data, word32 sz) Inject synthetic SRAM test data for testing without hardware. Only available when WOLFSSL_PUF_TEST is defined.

Functions Documentation

function wc_PufInit

int wc_PufInit(
    wc_PufCtx * ctx
)

Initialize a wc_PufCtx structure, zeroing all fields. Must be called before any other PUF operations.

Parameters:

• ctx pointer to wc_PufCtx structure to initialize

See:

• wc_PufReadSram
• wc_PufEnroll
• wc_PufZeroize

Return:

• 0 on success
• BAD_FUNC_ARG if ctx is NULL

For a complete bare-metal example (tested on NUCLEO-H563ZI), see https://github.com/wolfSSL/wolfssl-examples/tree/master/puf

Example

wc_PufCtx ctx;
ret = wc_PufInit(&ctx);

function wc_PufReadSram

int wc_PufReadSram(
    wc_PufCtx * ctx,
    const byte * sramAddr,
    word32 sramSz
)

Read raw SRAM data into the PUF context. The sramAddr should point to a NOLOAD linker section to preserve the power-on state.

Parameters:

• ctx pointer to wc_PufCtx structure
• sramAddr pointer to raw SRAM memory region
• sramSz size of SRAM buffer (must be >= WC_PUF_RAW_BYTES)

See:

• wc_PufInit
• wc_PufEnroll
• wc_PufReconstruct

Return:

• 0 on success
• BAD_FUNC_ARG if ctx or sramAddr is NULL
• PUF_READ_E if sramSz < WC_PUF_RAW_BYTES

Example

__attribute__((section(".puf_sram")))
static volatile uint8_t puf_sram[256];
wc_PufReadSram(&ctx, (const byte*)puf_sram, sizeof(puf_sram));

function wc_PufEnroll

int wc_PufEnroll(
    wc_PufCtx * ctx
)

Perform PUF enrollment. Encodes raw SRAM using BCH(127,64,t=10) and generates public helper data. After enrollment the context is ready for key derivation and identity retrieval.

Parameters:

• ctx pointer to wc_PufCtx (must have SRAM data loaded)

See:

• wc_PufReadSram
• wc_PufReconstruct
• wc_PufDeriveKey

Return:

• 0 on success
• BAD_FUNC_ARG if ctx is NULL
• PUF_ENROLL_E if enrollment fails

Example

wc_PufEnroll(&ctx);
XMEMCPY(helperData, ctx.helperData, WC_PUF_HELPER_BYTES);

function wc_PufReconstruct

int wc_PufReconstruct(
    wc_PufCtx * ctx,
    const byte * helperData,
    word32 helperSz
)

Reconstruct stable PUF bits from noisy SRAM using stored helper data. BCH error correction (t=10) corrects up to 10 bit flips per 127-bit codeword.

Parameters:

• ctx pointer to wc_PufCtx (must have SRAM data loaded)
• helperData pointer to helper data from previous enrollment
• helperSz size of helper data (>= WC_PUF_HELPER_BYTES)

See:

• wc_PufEnroll
• wc_PufDeriveKey
• wc_PufGetIdentity

Return:

• 0 on success
• BAD_FUNC_ARG if ctx or helperData is NULL
• PUF_RECONSTRUCT_E on failure (too many bit errors or helperSz too small)

Example

wc_PufReconstruct(&ctx, helperData, sizeof(helperData));

function wc_PufDeriveKey

int wc_PufDeriveKey(
    wc_PufCtx * ctx,
    const byte * info,
    word32 infoSz,
    byte * key,
    word32 keySz
)

Derive a cryptographic key from PUF stable bits using HKDF. Uses SHA-256 by default, or SHA3-256 when WC_PUF_SHA3 is defined. The info parameter provides domain separation for multiple keys. Requires HAVE_HKDF.

Parameters:

• ctx pointer to wc_PufCtx (must be enrolled or reconstructed)
• info optional context info for domain separation (may be NULL; when NULL, infoSz is treated as 0)
• infoSz size of info in bytes
• key output buffer for derived key
• keySz desired key size in bytes

See:

• wc_PufEnroll
• wc_PufReconstruct
• wc_PufGetIdentity

Return:

• 0 on success
• BAD_FUNC_ARG if ctx or key is NULL, or keySz is 0
• PUF_DERIVE_KEY_E if PUF not ready or HKDF fails

Example

byte key[32];
const byte info[] = "my-app-key";
wc_PufDeriveKey(&ctx, info, sizeof(info), key, sizeof(key));

function wc_PufGetIdentity

int wc_PufGetIdentity(
    wc_PufCtx * ctx,
    byte * id,
    word32 idSz
)

Retrieve the device identity hash (SHA-256 or SHA3-256 of stable bits). Deterministic for a given device.

Parameters:

• ctx pointer to wc_PufCtx (must be enrolled or reconstructed)
• id output buffer for identity hash
• idSz size of id buffer (>= WC_PUF_ID_SZ, 32 bytes)

See:

• wc_PufEnroll
• wc_PufReconstruct
• wc_PufDeriveKey

Return:

• 0 on success
• BAD_FUNC_ARG if ctx or id is NULL
• PUF_IDENTITY_E if PUF not ready or idSz < WC_PUF_ID_SZ

Example

byte identity[WC_PUF_ID_SZ];
wc_PufGetIdentity(&ctx, identity, sizeof(identity));

function wc_PufZeroize

int wc_PufZeroize(
    wc_PufCtx * ctx
)

Securely zeroize all sensitive data in the PUF context using ForceZero. Call when PUF is no longer needed.

Parameters:

• ctx pointer to wc_PufCtx to zeroize

See: wc_PufInit

Return:

• 0 on success
• BAD_FUNC_ARG if ctx is NULL

Example

wc_PufZeroize(&ctx);

function wc_PufSetTestData

int wc_PufSetTestData(
    wc_PufCtx * ctx,
    const byte * data,
    word32 sz
)

Inject synthetic SRAM test data for testing without hardware. Only available when WOLFSSL_PUF_TEST is defined.

Parameters:

• ctx pointer to wc_PufCtx
• data pointer to synthetic SRAM data
• sz size of data (>= WC_PUF_RAW_BYTES, 256 bytes)

See:

• wc_PufInit
• wc_PufReadSram

Return:

• 0 on success
• BAD_FUNC_ARG if ctx or data is NULL
• PUF_READ_E if sz < WC_PUF_RAW_BYTES

Example

byte testSram[WC_PUF_RAW_BYTES];
wc_PufSetTestData(&ctx, testSram, sizeof(testSram));

Source code

int wc_PufInit(wc_PufCtx* ctx);

int wc_PufReadSram(wc_PufCtx* ctx, const byte* sramAddr, word32 sramSz);

int wc_PufEnroll(wc_PufCtx* ctx);

int wc_PufReconstruct(wc_PufCtx* ctx, const byte* helperData, word32 helperSz);

int wc_PufDeriveKey(wc_PufCtx* ctx, const byte* info, word32 infoSz,
                    byte* key, word32 keySz);

int wc_PufGetIdentity(wc_PufCtx* ctx, byte* id, word32 idSz);

int wc_PufZeroize(wc_PufCtx* ctx);

int wc_PufSetTestData(wc_PufCtx* ctx, const byte* data, word32 sz);

---

Updated on 2026-07-16 at 03:12:19 +0000