|
| 1 | +/*! |
| 2 | + \ingroup PUF |
| 3 | +
|
| 4 | + For a complete bare-metal example (tested on NUCLEO-H563ZI), see |
| 5 | + https://github.com/wolfSSL/wolfssl-examples/tree/master/puf |
| 6 | +*/ |
| 7 | + |
| 8 | +/*! |
| 9 | + \ingroup PUF |
| 10 | +
|
| 11 | + \brief Initialize a wc_PufCtx structure, zeroing all fields. |
| 12 | + Must be called before any other PUF operations. |
| 13 | +
|
| 14 | + \return 0 on success |
| 15 | + \return BAD_FUNC_ARG if ctx is NULL |
| 16 | +
|
| 17 | + \param ctx pointer to wc_PufCtx structure to initialize |
| 18 | +
|
| 19 | + _Example_ |
| 20 | + \code |
| 21 | + wc_PufCtx ctx; |
| 22 | + ret = wc_PufInit(&ctx); |
| 23 | + \endcode |
| 24 | +
|
| 25 | + \sa wc_PufReadSram |
| 26 | + \sa wc_PufEnroll |
| 27 | + \sa wc_PufZeroize |
| 28 | +*/ |
| 29 | +int wc_PufInit(wc_PufCtx* ctx); |
| 30 | + |
| 31 | +/*! |
| 32 | + \ingroup PUF |
| 33 | +
|
| 34 | + \brief Read raw SRAM data into the PUF context. The sramAddr should |
| 35 | + point to a NOLOAD linker section to preserve the power-on state. |
| 36 | +
|
| 37 | + \return 0 on success |
| 38 | + \return BAD_FUNC_ARG if ctx or sramAddr is NULL |
| 39 | + \return PUF_READ_E if sramSz < WC_PUF_RAW_BYTES |
| 40 | +
|
| 41 | + \param ctx pointer to wc_PufCtx structure |
| 42 | + \param sramAddr pointer to raw SRAM memory region |
| 43 | + \param sramSz size of SRAM buffer (must be >= WC_PUF_RAW_BYTES) |
| 44 | +
|
| 45 | + _Example_ |
| 46 | + \code |
| 47 | + __attribute__((section(".puf_sram"))) |
| 48 | + static volatile uint8_t puf_sram[256]; |
| 49 | + wc_PufReadSram(&ctx, (const byte*)puf_sram, sizeof(puf_sram)); |
| 50 | + \endcode |
| 51 | +
|
| 52 | + \sa wc_PufInit |
| 53 | + \sa wc_PufEnroll |
| 54 | + \sa wc_PufReconstruct |
| 55 | +*/ |
| 56 | +int wc_PufReadSram(wc_PufCtx* ctx, const byte* sramAddr, word32 sramSz); |
| 57 | + |
| 58 | +/*! |
| 59 | + \ingroup PUF |
| 60 | +
|
| 61 | + \brief Perform PUF enrollment. Encodes raw SRAM using BCH(127,64,t=10) |
| 62 | + and generates public helper data. After enrollment the context is ready |
| 63 | + for key derivation and identity retrieval. |
| 64 | +
|
| 65 | + \return 0 on success |
| 66 | + \return BAD_FUNC_ARG if ctx is NULL |
| 67 | + \return PUF_ENROLL_E if enrollment fails |
| 68 | +
|
| 69 | + \param ctx pointer to wc_PufCtx (must have SRAM data loaded) |
| 70 | +
|
| 71 | + _Example_ |
| 72 | + \code |
| 73 | + wc_PufEnroll(&ctx); |
| 74 | + XMEMCPY(helperData, ctx.helperData, WC_PUF_HELPER_BYTES); |
| 75 | + \endcode |
| 76 | +
|
| 77 | + \sa wc_PufReadSram |
| 78 | + \sa wc_PufReconstruct |
| 79 | + \sa wc_PufDeriveKey |
| 80 | +*/ |
| 81 | +int wc_PufEnroll(wc_PufCtx* ctx); |
| 82 | + |
| 83 | +/*! |
| 84 | + \ingroup PUF |
| 85 | +
|
| 86 | + \brief Reconstruct stable PUF bits from noisy SRAM using stored helper |
| 87 | + data. BCH error correction (t=10) corrects up to 10 bit flips per |
| 88 | + 127-bit codeword. |
| 89 | +
|
| 90 | + \return 0 on success |
| 91 | + \return BAD_FUNC_ARG if ctx or helperData is NULL |
| 92 | + \return PUF_RECONSTRUCT_E on failure (too many bit errors or helperSz |
| 93 | + too small) |
| 94 | +
|
| 95 | + \param ctx pointer to wc_PufCtx (must have SRAM data loaded) |
| 96 | + \param helperData pointer to helper data from previous enrollment |
| 97 | + \param helperSz size of helper data (>= WC_PUF_HELPER_BYTES) |
| 98 | +
|
| 99 | + _Example_ |
| 100 | + \code |
| 101 | + wc_PufReconstruct(&ctx, helperData, sizeof(helperData)); |
| 102 | + \endcode |
| 103 | +
|
| 104 | + \sa wc_PufEnroll |
| 105 | + \sa wc_PufDeriveKey |
| 106 | + \sa wc_PufGetIdentity |
| 107 | +*/ |
| 108 | +int wc_PufReconstruct(wc_PufCtx* ctx, const byte* helperData, word32 helperSz); |
| 109 | + |
| 110 | +/*! |
| 111 | + \ingroup PUF |
| 112 | +
|
| 113 | + \brief Derive a cryptographic key from PUF stable bits using HKDF. |
| 114 | + Uses SHA-256 by default, or SHA3-256 when WC_PUF_SHA3 is defined. |
| 115 | + The info parameter provides domain separation for multiple keys. |
| 116 | + Requires HAVE_HKDF. |
| 117 | +
|
| 118 | + \return 0 on success |
| 119 | + \return BAD_FUNC_ARG if ctx or key is NULL, or keySz is 0 |
| 120 | + \return PUF_DERIVE_KEY_E if PUF not ready or HKDF fails |
| 121 | +
|
| 122 | + \param ctx pointer to wc_PufCtx (must be enrolled or reconstructed) |
| 123 | + \param info optional context info for domain separation (may be NULL; |
| 124 | + when NULL, infoSz is treated as 0) |
| 125 | + \param infoSz size of info in bytes |
| 126 | + \param key output buffer for derived key |
| 127 | + \param keySz desired key size in bytes |
| 128 | +
|
| 129 | + _Example_ |
| 130 | + \code |
| 131 | + byte key[32]; |
| 132 | + const byte info[] = "my-app-key"; |
| 133 | + wc_PufDeriveKey(&ctx, info, sizeof(info), key, sizeof(key)); |
| 134 | + \endcode |
| 135 | +
|
| 136 | + \sa wc_PufEnroll |
| 137 | + \sa wc_PufReconstruct |
| 138 | + \sa wc_PufGetIdentity |
| 139 | +*/ |
| 140 | +int wc_PufDeriveKey(wc_PufCtx* ctx, const byte* info, word32 infoSz, |
| 141 | + byte* key, word32 keySz); |
| 142 | + |
| 143 | +/*! |
| 144 | + \ingroup PUF |
| 145 | +
|
| 146 | + \brief Retrieve the device identity hash (SHA-256 or SHA3-256 of stable |
| 147 | + bits). Deterministic for a given device. |
| 148 | +
|
| 149 | + \return 0 on success |
| 150 | + \return BAD_FUNC_ARG if ctx or id is NULL |
| 151 | + \return PUF_IDENTITY_E if PUF not ready or idSz < WC_PUF_ID_SZ |
| 152 | +
|
| 153 | + \param ctx pointer to wc_PufCtx (must be enrolled or reconstructed) |
| 154 | + \param id output buffer for identity hash |
| 155 | + \param idSz size of id buffer (>= WC_PUF_ID_SZ, 32 bytes) |
| 156 | +
|
| 157 | + _Example_ |
| 158 | + \code |
| 159 | + byte identity[WC_PUF_ID_SZ]; |
| 160 | + wc_PufGetIdentity(&ctx, identity, sizeof(identity)); |
| 161 | + \endcode |
| 162 | +
|
| 163 | + \sa wc_PufEnroll |
| 164 | + \sa wc_PufReconstruct |
| 165 | + \sa wc_PufDeriveKey |
| 166 | +*/ |
| 167 | +int wc_PufGetIdentity(wc_PufCtx* ctx, byte* id, word32 idSz); |
| 168 | + |
| 169 | +/*! |
| 170 | + \ingroup PUF |
| 171 | +
|
| 172 | + \brief Securely zeroize all sensitive data in the PUF context using |
| 173 | + ForceZero. Call when PUF is no longer needed. |
| 174 | +
|
| 175 | + \return 0 on success |
| 176 | + \return BAD_FUNC_ARG if ctx is NULL |
| 177 | +
|
| 178 | + \param ctx pointer to wc_PufCtx to zeroize |
| 179 | +
|
| 180 | + _Example_ |
| 181 | + \code |
| 182 | + wc_PufZeroize(&ctx); |
| 183 | + \endcode |
| 184 | +
|
| 185 | + \sa wc_PufInit |
| 186 | +*/ |
| 187 | +int wc_PufZeroize(wc_PufCtx* ctx); |
| 188 | + |
| 189 | +/*! |
| 190 | + \ingroup PUF |
| 191 | +
|
| 192 | + \brief Inject synthetic SRAM test data for testing without hardware. |
| 193 | + Only available when WOLFSSL_PUF_TEST is defined. |
| 194 | +
|
| 195 | + \return 0 on success |
| 196 | + \return BAD_FUNC_ARG if ctx or data is NULL |
| 197 | + \return PUF_READ_E if sz < WC_PUF_RAW_BYTES |
| 198 | +
|
| 199 | + \param ctx pointer to wc_PufCtx |
| 200 | + \param data pointer to synthetic SRAM data |
| 201 | + \param sz size of data (>= WC_PUF_RAW_BYTES, 256 bytes) |
| 202 | +
|
| 203 | + _Example_ |
| 204 | + \code |
| 205 | + byte testSram[WC_PUF_RAW_BYTES]; |
| 206 | + wc_PufSetTestData(&ctx, testSram, sizeof(testSram)); |
| 207 | + \endcode |
| 208 | +
|
| 209 | + \sa wc_PufInit |
| 210 | + \sa wc_PufReadSram |
| 211 | +*/ |
| 212 | +int wc_PufSetTestData(wc_PufCtx* ctx, const byte* data, word32 sz); |
0 commit comments