Skip to content

Commit 953c21c

Browse files
night1ridernight1rider
committed
Add more in depth comments in header file for she.h
1 parent 97f43a1 commit 953c21c

1 file changed

Lines changed: 143 additions & 22 deletions

File tree

‎wolfssl/wolfcrypt/she.h‎

Lines changed: 143 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -34,14 +34,14 @@
3434
extern "C" {
3535
#endif
3636

37-
#define WC_SHE_KEY_SZ 16
38-
#define WC_SHE_UID_SZ 15
37+
#define WC_SHE_KEY_SZ 16 /* AES-128 key size (128 bits) */
38+
#define WC_SHE_UID_SZ 15 /* SHE UID size (120 bits) */
3939

40-
#define WC_SHE_M1_SZ 16
41-
#define WC_SHE_M2_SZ 32
42-
#define WC_SHE_M3_SZ 16
43-
#define WC_SHE_M4_SZ 32
44-
#define WC_SHE_M5_SZ 16
40+
#define WC_SHE_M1_SZ 16 /* UID(15B) | KeyID(4b) | AuthID(4b) */
41+
#define WC_SHE_M2_SZ 32 /* AES-CBC(K1, counter|flags|pad|newkey) */
42+
#define WC_SHE_M3_SZ 16 /* AES-CMAC(K2, M1|M2) */
43+
#define WC_SHE_M4_SZ 32 /* UID|IDs + AES-ECB(K3, counter|pad) */
44+
#define WC_SHE_M5_SZ 16 /* AES-CMAC(K4, M4) */
4545

4646
/* crypto callback sub-types for WC_ALGO_TYPE_SHE */
4747
enum wc_SheType {
@@ -129,28 +129,55 @@ typedef struct wc_SHE {
129129
} wc_SHE;
130130

131131

132-
/* Initialize SHE context, store heap hint and device ID */
132+
/* Initialize SHE context, store heap hint and device ID.
133+
* she - pointer to wc_SHE structure to initialize
134+
* heap - heap hint for internal allocations, or NULL
135+
* devId - crypto callback device ID, or INVALID_DEVID for software */
133136
WOLFSSL_API int wc_SHE_Init(wc_SHE* she, void* heap, int devId);
134137

135138
#ifdef WOLF_PRIVATE_KEY_ID
136-
/* Initialize with opaque hardware key identifier */
139+
/* Initialize with opaque hardware key identifier.
140+
* Useful when using callbacks and additional info needs to be attached
141+
* to the SHE context to determine slot or key group information.
142+
* she - pointer to wc_SHE structure to initialize
143+
* id - opaque key identifier bytes
144+
* len - length of id in bytes (0 to WC_SHE_MAX_ID_LEN)
145+
* heap - heap hint for internal allocations, or NULL
146+
* devId - crypto callback device ID */
137147
WOLFSSL_API int wc_SHE_Init_Id(wc_SHE* she, unsigned char* id, int len,
138148
void* heap, int devId);
139-
/* Initialize with human-readable key label */
149+
150+
/* Initialize with human-readable key label.
151+
* Useful when using callbacks and additional info needs to be attached
152+
* to the SHE context to determine slot or key group information.
153+
* she - pointer to wc_SHE structure to initialize
154+
* label - NUL-terminated key label string
155+
* heap - heap hint for internal allocations, or NULL
156+
* devId - crypto callback device ID */
140157
WOLFSSL_API int wc_SHE_Init_Label(wc_SHE* she, const char* label,
141158
void* heap, int devId);
142159
#endif
143160

144-
/* Scrub and zero the context */
161+
/* Scrub all data and zero the context. Safe to call on NULL. */
145162
WOLFSSL_API void wc_SHE_Free(wc_SHE* she);
146163

147-
/* Get UID from hardware; callback required (WC_SHE_SET_UID) */
164+
/* Get UID from hardware via callback (WC_SHE_SET_UID).
165+
* she - initialized SHE context with a registered callback
166+
* uid - buffer to receive the 120-bit (15-byte) SHE UID
167+
* uidSz - size of uid buffer in bytes
168+
* ctx - read-only caller context passed to the callback
169+
* (e.g. challenge buffer, HSM handle) */
148170
#if defined(WOLF_CRYPTO_CB) && !defined(NO_WC_SHE_GETUID)
149171
WOLFSSL_API int wc_SHE_GetUID(wc_SHE* she, byte* uid, word32 uidSz,
150172
const void* ctx);
151173
#endif
152174

153-
/* Get counter from hardware; callback required */
175+
/* Get monotonic counter from hardware via callback (WC_SHE_GET_COUNTER).
176+
* she - initialized SHE context with a registered callback
177+
* counter - pointer to receive the current counter value.
178+
* The SHE spec uses a 28-bit counter. The caller should
179+
* increment this value before passing to GenerateM1M2M3/M4M5.
180+
* ctx - read-only caller context passed to the callback */
154181
#if defined(WOLF_CRYPTO_CB) && !defined(NO_WC_SHE_GETCOUNTER)
155182
WOLFSSL_API int wc_SHE_GetCounter(wc_SHE* she, word32* counter,
156183
const void* ctx);
@@ -160,29 +187,84 @@ WOLFSSL_API int wc_SHE_GetCounter(wc_SHE* she, word32* counter,
160187
* Useful for some HSMs that support multiple key groups with
161188
* different derivation constants. */
162189
#ifdef WOLFSSL_SHE_EXTENDED
163-
/* Set KDF constants (CENC/CMAC). Defaults set by Init. NULL to skip. */
190+
/* Set KDF constants used in Miyaguchi-Preneel key derivation.
191+
* Defaults are KEY_UPDATE_ENC_C and KEY_UPDATE_MAC_C from the SHE spec.
192+
* Either pointer may be NULL to leave that constant unchanged.
193+
* she - initialized SHE context
194+
* encC - 16-byte encryption derivation constant (CENC), or NULL
195+
* encCSz - must be WC_SHE_KEY_SZ (16) when encC is non-NULL
196+
* macC - 16-byte MAC derivation constant (CMAC), or NULL
197+
* macCSz - must be WC_SHE_KEY_SZ (16) when macC is non-NULL */
164198
WOLFSSL_API int wc_SHE_SetKdfConstants(wc_SHE* she,
165199
const byte* encC, word32 encCSz,
166200
const byte* macC, word32 macCSz);
167201

168-
/* Override M2P cleartext header. Skips auto-build from counter/flags. */
202+
/* Override M2 cleartext header (first 16 bytes of M2 before encryption).
203+
* When set, GenerateM1M2M3 uses this instead of auto-building from
204+
* counter and flags. The header is: counter(28b)|flags(4b)|zeros(96b).
205+
* she - initialized SHE context
206+
* header - 16-byte cleartext header block
207+
* headerSz - must be WC_SHE_KEY_SZ (16) */
169208
WOLFSSL_API int wc_SHE_SetM2Header(wc_SHE* she,
170209
const byte* header, word32 headerSz);
171210

172-
/* Override M4P cleartext header. Skips auto-build from counter. */
211+
/* Override M4 cleartext counter block (16-byte block encrypted with K3).
212+
* When set, GenerateM4M5 uses this instead of auto-building from counter.
213+
* The block is: counter(28b)|1(1b)|zeros(99b).
214+
* she - initialized SHE context
215+
* header - 16-byte cleartext counter block
216+
* headerSz - must be WC_SHE_KEY_SZ (16) */
173217
WOLFSSL_API int wc_SHE_SetM4Header(wc_SHE* she,
174218
const byte* header, word32 headerSz);
175219
#endif /* WOLFSSL_SHE_EXTENDED */
176220

177-
/* Import externally-provided M1/M2/M3 into context; sets generated flag */
221+
/* Import externally-provided M1/M2/M3 into context.
222+
* Sets the generated flag so the callback for GenerateM4M5 can
223+
* read M1/M2/M3 from the context to send to hardware.
224+
* she - initialized SHE context
225+
* m1 - 16-byte M1 message (UID | KeyID | AuthID)
226+
* m1Sz - must be WC_SHE_M1_SZ (16)
227+
* m2 - 32-byte M2 message (encrypted counter|flags|pad|newkey)
228+
* m2Sz - must be WC_SHE_M2_SZ (32)
229+
* m3 - 16-byte M3 message (CMAC over M1|M2)
230+
* m3Sz - must be WC_SHE_M3_SZ (16) */
178231
#if defined(WOLF_CRYPTO_CB) || !defined(NO_WC_SHE_IMPORT_M123)
179232
WOLFSSL_API int wc_SHE_ImportM1M2M3(wc_SHE* she,
180233
const byte* m1, word32 m1Sz,
181234
const byte* m2, word32 m2Sz,
182235
const byte* m3, word32 m3Sz);
183236
#endif
184237

185-
/* Generate M1/M2/M3 and write to caller buffers */
238+
/* Generate M1/M2/M3 for the SHE key update protocol and write to
239+
* caller-provided buffers. Callback optional — if a callback is
240+
* registered it is tried first; if it returns CRYPTOCB_UNAVAILABLE
241+
* the software path runs. This allows a secure element to generate
242+
* M1/M2/M3 when it holds the auth key internally.
243+
*
244+
* she - initialized SHE context
245+
* uid - 15-byte SHE UID (120-bit ECU/module identifier)
246+
* uidSz - must be WC_SHE_UID_SZ (15)
247+
* authKeyId - slot ID of the authorizing key (0-14, e.g.
248+
* MASTER_ECU_KEY=1, KEY_1..KEY_10=4..13)
249+
* authKey - 16-byte value of the authorizing key. Used to derive
250+
* K1 (encryption) and K2 (MAC). May be NULL when the
251+
* callback handles key access.
252+
* authKeySz - must be WC_SHE_KEY_SZ (16) when authKey is non-NULL
253+
* targetKeyId - slot ID of the key being loaded (1-14)
254+
* newKey - 16-byte value of the new key to load. Placed in M2
255+
* cleartext and used to derive K3/K4 for M4/M5.
256+
* May be NULL when the callback handles key access.
257+
* newKeySz - must be WC_SHE_KEY_SZ (16) when newKey is non-NULL
258+
* counter - 28-bit monotonic counter value. Must be strictly greater
259+
* than the counter stored in the target slot on the SHE.
260+
* flags - key protection flags (lower 4 bits of the counter|flags
261+
* word in M2).
262+
* m1 - output buffer for M1 (16 bytes)
263+
* m1Sz - size of m1 buffer, must be >= WC_SHE_M1_SZ
264+
* m2 - output buffer for M2 (32 bytes)
265+
* m2Sz - size of m2 buffer, must be >= WC_SHE_M2_SZ
266+
* m3 - output buffer for M3 (16 bytes)
267+
* m3Sz - size of m3 buffer, must be >= WC_SHE_M3_SZ */
186268
WOLFSSL_API int wc_SHE_GenerateM1M2M3(wc_SHE* she,
187269
const byte* uid, word32 uidSz,
188270
byte authKeyId, const byte* authKey, word32 authKeySz,
@@ -192,7 +274,25 @@ WOLFSSL_API int wc_SHE_GenerateM1M2M3(wc_SHE* she,
192274
byte* m2, word32 m2Sz,
193275
byte* m3, word32 m3Sz);
194276

195-
/* Generate M4/M5 and write to caller buffers */
277+
/* Generate M4/M5 verification messages and write to caller-provided
278+
* buffers. Independent of M1/M2/M3 — can be called on a separate
279+
* context. Callback optional — useful for uploading M1/M2/M3 to an
280+
* HSM which loads the key and returns M4/M5 as proof.
281+
*
282+
* she - initialized SHE context
283+
* uid - 15-byte SHE UID (same UID used for M1)
284+
* uidSz - must be WC_SHE_UID_SZ (15)
285+
* authKeyId - slot ID of the authorizing key (same as in M1)
286+
* targetKeyId - slot ID of the key being loaded (same as in M1)
287+
* newKey - 16-byte value of the new key. Used to derive K3
288+
* (encryption for M4 counter block) and K4 (MAC for M5).
289+
* May be NULL when the callback handles key access.
290+
* newKeySz - must be WC_SHE_KEY_SZ (16) when newKey is non-NULL
291+
* counter - 28-bit monotonic counter (same value as in M2)
292+
* m4 - output buffer for M4 (32 bytes)
293+
* m4Sz - size of m4 buffer, must be >= WC_SHE_M4_SZ
294+
* m5 - output buffer for M5 (16 bytes)
295+
* m5Sz - size of m5 buffer, must be >= WC_SHE_M5_SZ */
196296
WOLFSSL_API int wc_SHE_GenerateM4M5(wc_SHE* she,
197297
const byte* uid, word32 uidSz,
198298
byte authKeyId, byte targetKeyId,
@@ -201,8 +301,22 @@ WOLFSSL_API int wc_SHE_GenerateM4M5(wc_SHE* she,
201301
byte* m4, word32 m4Sz,
202302
byte* m5, word32 m5Sz);
203303

204-
/* Export key from hardware as M1-M5; callback required.
205-
* Some HSMs allow exporting certain key slots (e.g. RAM key) in SHE format. */
304+
/* Export a key from hardware in SHE loadable format (M1-M5).
305+
* Callback required — dispatches to WC_SHE_EXPORT_KEY.
306+
* Some HSMs allow exporting certain key slots (e.g. RAM key) so they
307+
* can be re-loaded later via the SHE key update protocol.
308+
* she - initialized SHE context with a registered callback
309+
* m1 - output buffer for M1 (16 bytes), or NULL to skip
310+
* m1Sz - size of m1 buffer
311+
* m2 - output buffer for M2 (32 bytes), or NULL to skip
312+
* m2Sz - size of m2 buffer
313+
* m3 - output buffer for M3 (16 bytes), or NULL to skip
314+
* m3Sz - size of m3 buffer
315+
* m4 - output buffer for M4 (32 bytes), or NULL to skip
316+
* m4Sz - size of m4 buffer
317+
* m5 - output buffer for M5 (16 bytes), or NULL to skip
318+
* m5Sz - size of m5 buffer
319+
* ctx - read-only caller context passed to the callback */
206320
#if defined(WOLF_CRYPTO_CB) && !defined(NO_WC_SHE_EXPORTKEY)
207321
WOLFSSL_API int wc_SHE_ExportKey(wc_SHE* she,
208322
byte* m1, word32 m1Sz,
@@ -213,7 +327,14 @@ WOLFSSL_API int wc_SHE_ExportKey(wc_SHE* she,
213327
const void* ctx);
214328
#endif
215329

216-
/* Internal: Miyaguchi-Preneel AES-128 compression, exposed for testing */
330+
/* Internal: Miyaguchi-Preneel AES-128 one-way compression.
331+
* H_0 = 0, H_i = E_{H_{i-1}}(M_i) XOR M_i XOR H_{i-1}.
332+
* Only valid for AES-128 where key size equals block size.
333+
* Exposed via WOLFSSL_TEST_VIS for testing.
334+
* aes - caller-owned, already-initialized Aes structure
335+
* in - input data (e.g. BaseKey || KDF_Constant, 32 bytes)
336+
* inSz - length of input in bytes (zero-padded to block boundary)
337+
* out - output buffer for 16-byte compressed result */
217338
WOLFSSL_TEST_VIS int wc_She_AesMp16(Aes* aes, const byte* in, word32 inSz,
218339
byte* out);
219340

0 commit comments

Comments
 (0)