Skip to content

Commit 6b83732

Browse files
twcook86twcook86
committed
Initial implementation
1 parent 4b8fd23 commit 6b83732

16 files changed

Lines changed: 1461 additions & 5 deletions

File tree

‎.wolfssl_known_macro_extras‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -777,6 +777,7 @@ WOLFSSL_HARDEN_TLS_ALLOW_TRUNCATED_HMAC
777777
WOLFSSL_HARDEN_TLS_NO_PKEY_CHECK
778778
WOLFSSL_HARDEN_TLS_NO_SCR_CHECK
779779
WOLFSSL_HOSTNAME_VERIFY_ALT_NAME_ONLY
780+
WOLFSSL_HWPUF
780781
WOLFSSL_I2D_ECDSA_SIG_ALLOC
781782
WOLFSSL_IAR_ARM_TIME
782783
WOLFSSL_IGNORE_BAD_CERT_PATH
@@ -860,6 +861,7 @@ WOLFSSL_NO_XOR_OPS
860861
WOLFSSL_NRF51_AES
861862
WOLFSSL_NXP_CASPER_ECC_MUL2ADD
862863
WOLFSSL_NXP_CASPER_ECC_MULMOD
864+
WOLFSSL_NXP_HWPUF
863865
WOLFSSL_NXP_LPC55S6X
864866
WOLFSSL_OLDTLS_AEAD_CIPHERSUITES
865867
WOLFSSL_OLD_SET_CURVES_LIST

‎doc/dox_comments/header_files/hwpuf.h‎

Lines changed: 264 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,264 @@
1+
/*!
2+
\ingroup HWPUF
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 HWPUF
10+
11+
\brief Initialize a wc_HWPUF structure, zeroing all fields.
12+
Must be called before any other HWPUF operations.
13+
14+
\return 0 on success
15+
\return BAD_FUNC_ARG if hwpuf is NULL
16+
17+
\param hwpuf pointer to wc_HWPUF structure to initialize
18+
19+
_Example_
20+
\code
21+
wc_HWPUF s_hwpuf;
22+
ret = wc_HWPUF_Init(&s_hwpuf);
23+
\endcode
24+
25+
\sa wc_HWPUF_Init
26+
\sa wc_HWPUF_Deinit
27+
\sa wc_HWPUF_Unregister
28+
*/
29+
int wc_HWPUF_Register(wc_HWPUF* hwpuf, void* heap, int devId);
30+
31+
/*!
32+
\ingroup HWPUF
33+
34+
\brief Initialize a wc_HWPUF structure, zeroing all fields.
35+
Must be called before any other HWPUF operations.
36+
37+
\return 0 on success
38+
\return BAD_FUNC_ARG if hwpuf is NULL
39+
40+
\param hwpuf pointer to wc_HWPUF structure to initialize
41+
42+
_Example_
43+
\code
44+
wc_HWPUF s_hwpuf;
45+
ret = wc_HWPUF_Init(&s_hwpuf);
46+
\endcode
47+
48+
\sa wc_HWPUF_Register
49+
\sa wc_HWPUF_Init
50+
\sa wc_HWPUF_Deinit
51+
\sa wc_HWPUF_Zeroize
52+
*/
53+
int wc_HWPUF_Unregister(wc_HWPUF* hwpuf);
54+
55+
/*!
56+
\ingroup HWPUF
57+
58+
\brief Initialize a wc_HWPUF structure, zeroing all fields.
59+
Must be called before any other HWPUF operations.
60+
61+
\return 0 on success
62+
\return BAD_FUNC_ARG if hwpuf is NULL
63+
64+
\param hwpuf pointer to wc_HWPUF structure to initialize
65+
66+
_Example_
67+
\code
68+
wc_HWPUF s_hwpuf;
69+
ret = wc_HWPUF_Init(&s_hwpuf);
70+
\endcode
71+
72+
\sa wc_HWPUF_Deinit
73+
\sa wc_HWPUF_Enroll
74+
\sa wc_HWPUF_Start
75+
\sa wc_HWPUF_Zeroize
76+
*/
77+
int wc_HWPUF_Init(wc_HWPUF* hwpuf);
78+
79+
/*!
80+
\ingroup HWPUF
81+
82+
\brief Initialize a wc_HWPUF structure, zeroing all fields.
83+
Must be called before any other HWPUF operations.
84+
85+
\return 0 on success
86+
\return BAD_FUNC_ARG if hwpuf is NULL
87+
88+
\param hwpuf pointer to wc_HWPUF structure to initialize
89+
90+
_Example_
91+
\code
92+
wc_HWPUF s_hwpuf;
93+
ret = wc_HWPUF_Deinit(&s_hwpuf);
94+
\endcode
95+
96+
\sa wc_HWPUF_Init
97+
\sa wc_HWPUF_Zeroize
98+
*/
99+
int wc_HWPUF_Deinit(wc_HWPUF* hwpuf);
100+
101+
/*!
102+
\ingroup HWPUF
103+
104+
\brief Perform HWPUF enrollment. Encodes raw SRAM using BCH(127,64,t=10)
105+
and generates public helper data. After enrollment the context is ready
106+
for key derivation and identity retrieval.
107+
108+
\return 0 on success
109+
\return BAD_FUNC_ARG if hwpuf is NULL
110+
\return HWPUF_ENROLL_E if enrollment fails
111+
112+
\param hwpuf pointer to wc_HWPUF (must have SRAM data loaded)
113+
114+
_Example_
115+
\code
116+
wc_HWPUF_Enroll(&s_hwpuf);
117+
XMEMCPY(helperData, hwpuf.helperData, WC_HWPUF_HELPER_BYTES);
118+
\endcode
119+
120+
\sa wc_HWPUF_Start
121+
\sa wc_HWPUF_GetKey
122+
*/
123+
int wc_HWPUF_Enroll(wc_HWPUF* hwpuf);
124+
125+
/*!
126+
\ingroup HWPUF
127+
128+
\brief Reconstruct stable HWPUF bits from noisy SRAM using stored helper
129+
data. BCH error correction (t=10) corrects up to 10 bit flips per
130+
127-bit codeword.
131+
132+
\return 0 on success
133+
\return BAD_FUNC_ARG if hwpuf or helperData is NULL
134+
\return HWPUF_RECONSTRUCT_E on failure (too many bit errors or helperSz
135+
too small)
136+
137+
\param hwpuf pointer to wc_HWPUF
138+
139+
_Example_
140+
\code
141+
wc_HWPUF_Start(&s_hwpuf);
142+
\endcode
143+
144+
\sa wc_HWPUF_Enroll
145+
\sa wc_HWPUF_GetKey
146+
*/
147+
int wc_HWPUF_Start(wc_HWPUF* hwpuf);
148+
149+
/*!
150+
\ingroup HWPUF
151+
152+
\brief Derive a cryptographic key from HWPUF stable bits using HKDF.
153+
Uses SHA-256 by default, or SHA3-256 when WC_HWPUF_SHA3 is defined.
154+
The info parameter provides domain separation for multiple keys.
155+
Requires HAVE_HKDF.
156+
157+
\return 0 on success
158+
\return BAD_FUNC_ARG if hwpuf or key is NULL, or keySz is 0
159+
\return HWPUF_DERIVE_KEY_E if HWPUF not ready or HKDF fails
160+
161+
\param hwpuf pointer to wc_HWPUF (must be enrolled or reconstructed)
162+
\param info optional context info for domain separation (may be NULL;
163+
when NULL, infoSz is treated as 0)
164+
\param infoSz size of info in bytes
165+
\param key output buffer for derived key
166+
\param keySz desired key size in bytes
167+
168+
_Example_
169+
\code
170+
byte key[32];
171+
const byte info[] = "my-app-key";
172+
wc_HWPUF_GetKey(&s_hwpuf, info, sizeof(info), key, sizeof(key));
173+
\endcode
174+
175+
\sa wc_HWPUF_Start
176+
*/
177+
int wc_HWPUF_GenerateKey(wc_HWPUF* hwpuf, byte keyIdx, word32 keySz,
178+
byte* keycode, word32 keycodeSz);
179+
180+
/*!
181+
\ingroup HWPUF
182+
183+
\brief Derive a cryptographic key from HWPUF stable bits using HKDF.
184+
Uses SHA-256 by default, or SHA3-256 when WC_HWPUF_SHA3 is defined.
185+
The info parameter provides domain separation for multiple keys.
186+
Requires HAVE_HKDF.
187+
188+
\return 0 on success
189+
\return BAD_FUNC_ARG if hwpuf or key is NULL, or keySz is 0
190+
\return HWPUF_DERIVE_KEY_E if HWPUF not ready or HKDF fails
191+
192+
\param hwpuf pointer to wc_HWPUF (must be enrolled or reconstructed)
193+
\param info optional context info for domain separation (may be NULL;
194+
when NULL, infoSz is treated as 0)
195+
\param infoSz size of info in bytes
196+
\param key output buffer for derived key
197+
\param keySz desired key size in bytes
198+
199+
_Example_
200+
\code
201+
byte key[32];
202+
const byte info[] = "my-app-key";
203+
wc_HWPUF_GetKey(&s_hwpuf, info, sizeof(info), key, sizeof(key));
204+
\endcode
205+
206+
\sa wc_HWPUF_Enroll
207+
\sa wc_HWPUF_Start
208+
*/
209+
int wc_HWPUF_SetKey(wc_HWPUF* hwpuf, byte keyIdx,
210+
byte* key, word32 keySz,
211+
byte* keycode, word32 keycodeSz);
212+
213+
/*!
214+
\ingroup HWPUF
215+
216+
\brief Derive a cryptographic key from HWPUF stable bits using HKDF.
217+
Uses SHA-256 by default, or SHA3-256 when WC_HWPUF_SHA3 is defined.
218+
The info parameter provides domain separation for multiple keys.
219+
Requires HAVE_HKDF.
220+
221+
\return 0 on success
222+
\return BAD_FUNC_ARG if hwpuf or key is NULL, or keySz is 0
223+
\return HWPUF_DERIVE_KEY_E if HWPUF not ready or HKDF fails
224+
225+
\param hwpuf pointer to wc_HWPUF (must be enrolled or reconstructed)
226+
\param info optional context info for domain separation (may be NULL;
227+
when NULL, infoSz is treated as 0)
228+
\param infoSz size of info in bytes
229+
\param key output buffer for derived key
230+
\param keySz desired key size in bytes
231+
232+
_Example_
233+
\code
234+
byte key[32];
235+
const byte info[] = "my-app-key";
236+
wc_HWPUF_GetKey(&s_hwpuf, info, sizeof(info), key, sizeof(key));
237+
\endcode
238+
239+
\sa wc_HWPUF_Enroll
240+
\sa wc_HWPUF_Start
241+
*/
242+
int wc_HWPUF_GetKey(wc_HWPUF* hwpuf, byte* keycode, word32 keycodeSz,
243+
byte* key, word32 keySz);
244+
245+
/*!
246+
\ingroup HWPUF
247+
248+
\brief Securely zeroize all sensitive data in the HWPUF context using
249+
ForceZero. Call when HWPUF is no longer needed.
250+
251+
\return 0 on success
252+
\return BAD_FUNC_ARG if hwpuf is NULL
253+
254+
\param hwpuf pointer to wc_HWPUF to zeroize
255+
256+
_Example_
257+
\code
258+
wc_HWPUF_Zeroize(&s_hwpuf);
259+
\endcode
260+
261+
\sa wc_HWPUF_Init
262+
\sa wc_HWPUF_Deinit
263+
*/
264+
int wc_HWPUF_Zeroize(wc_HWPUF* hwpuf);

0 commit comments

Comments
 (0)