Initial implementation

Author: twcook86

doc/dox_comments/header_files/puf.h

@@ -9,7 +9,8 @@
     \ingroup PUF
 
     \brief Initialize a wc_PufCtx structure, zeroing all fields.
-    Must be called before any other PUF operations.
+    Hardware PUF (WOLFSSL_HWPUF) may turn on power/clock and reset the
+    peripheral. Must be called before any other PUF operations.
 
     \return 0 on success
     \return BAD_FUNC_ARG if ctx is NULL
@@ -22,17 +23,45 @@
     ret = wc_PufInit(&ctx);
     \endcode
 
+    \sa wc_PufDeinit
     \sa wc_PufReadSram
     \sa wc_PufEnroll
     \sa wc_PufZeroize
 */
 int wc_PufInit(wc_PufCtx* ctx);
 
+/*!
+    \ingroup PUF
+
+    \brief Deinitialize a wc_PufCtx structure, zeroing all fields.
+    Hardware PUF (WOLFSSL_HWPUF) may turn off power/clock and reset the
+    peripheral.
+
+    \return 0 on success
+    \return BAD_FUNC_ARG if ctx is NULL
+
+    \param ctx pointer to wc_PufCtx structure to initialize
+
+    _Example_
+    \code
+    wc_PufCtx ctx;
+    ret = wc_PufDeinit(&ctx);
+    \endcode
+
+    \sa wc_PufInit
+    \sa wc_PufReadSram
+    \sa wc_PufEnroll
+    \sa wc_PufZeroize
+*/
+int wc_PufDeinit(wc_PufCtx* ctx);
+
 /*!
     \ingroup PUF
 
     \brief Read raw SRAM data into the PUF context. The sramAddr should
     point to a NOLOAD linker section to preserve the power-on state.
+    This function is valid for software PUF (WOLFSSL_PUF), but invalid for
+    hardware PUF (WOLFSSL_HWPUF)
 
     \return 0 on success
     \return BAD_FUNC_ARG if ctx or sramAddr is NULL
@@ -58,9 +87,14 @@ int wc_PufReadSram(wc_PufCtx* ctx, const byte* sramAddr, word32 sramSz);
 /*!
     \ingroup PUF
 
-    \brief Perform PUF enrollment. Encodes raw SRAM using BCH(127,64,t=10)
+    \brief Perform PUF enrollment.
+    For software PUF (WOLFSSL_PUF), 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.
+    For hardware PUF (WOLFSSL_HWPUF), encodes raw SRAM using a proprietary
+    method and generates an Activation Code.  After enrollment, device must
+    go through a deinit/init/reconstruct cycle, before device is ready for
+    key generation/derivation.  There is no helperData for hardware puf.
 
     \return 0 on success
     \return BAD_FUNC_ARG if ctx is NULL
@@ -76,16 +110,21 @@ int wc_PufReadSram(wc_PufCtx* ctx, const byte* sramAddr, word32 sramSz);
 
     \sa wc_PufReadSram
     \sa wc_PufReconstruct
+    \sa wc_PufGenerateKey
     \sa wc_PufDeriveKey
 */
 int wc_PufEnroll(wc_PufCtx* ctx);
 
 /*!
     \ingroup PUF
 
-    \brief 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.
+    \brief Performs reconstruction (starts puf) with data from enrollment.
+    For software PUF (WOLFSSL_PUF), reconstructs 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.
+    For hardware PUF (WOLFSSL_HWPUF), starts PUF peripheral with an activation
+    code, which is stored internally in RAM during a previous enrollment, or
+    is stored in flash in a known location.  helperData is ignored for hw puf.
 
     \return 0 on success
     \return BAD_FUNC_ARG if ctx or helperData is NULL
@@ -110,18 +149,58 @@ int wc_PufReconstruct(wc_PufCtx* ctx, const byte* helperData, word32 helperSz);
 /*!
     \ingroup PUF
 
-    \brief Derive a cryptographic key from PUF stable bits using HKDF.
+    \brief Generates a key and returns a key code (WOLFSSL_HWPUF only).
+    The key code can be later used to derive the key.
+    This function is invalid for software PUF (WOLFSSL_PUF).
+
+    \return 0 on success
+    \return BAD_FUNC_ARG if ctx or kcBuf is NULL, or keyIdx/keySz/kcBufSz is bad
+    \return PUF_GENERATE_KEY_E if PUF not ready or key generation fails
+
+    \param ctx pointer to wc_PufCtx (must be enrolled or reconstructed)
+    \param keyIdx key index 0 to 15.  If 0, when derived, will be sent directly
+    to hardware bus (never exposed in ram)
+    \param keySz size of key in bytes, 16, 24, 32 are valid
+    \param kcBuf key code output buffer
+    \param kcBufSz size of key code output buffer
+
+    _Example_
+    \code
+    byte key[32];
+    const byte info[] = "my-app-key";
+    wc_PufDeriveKey(&ctx, info, sizeof(info), key, sizeof(key));
+    \endcode
+
+    \sa wc_PufEnroll
+    \sa wc_PufReconstruct
+    \sa wc_PufGetIdentity
+    \sa wc_PufDeriveKey
+*/
+int wc_PufGenerateKey(wc_PufCtx* ctx, byte keyIdx, word32 keySz,
+                      byte* kcBuf, word32 kcBufSz);
+
+/*!
+    \ingroup PUF
+
+    \brief Derive a cryptographic key
+    For software PUF (WOLFSSL_PUF), derives key from 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.
+    For hardware PUF (WOLFSSL_HWPUF), derives key from the key code previously
+    generated.  If the key was originally generated with key index 0, then the
+    derived key is sent directly to the hardware bus, and key buffer will be
+    zeroed.
 
     \return 0 on success
     \return BAD_FUNC_ARG if ctx or key is NULL, or keySz is 0
-    \return PUF_DERIVE_KEY_E if PUF not ready or HKDF fails
+    \return PUF_DERIVE_KEY_E if PUF not ready or key derivation fails
 
     \param ctx pointer to wc_PufCtx (must be enrolled or reconstructed)
-    \param info optional context info for domain separation (may be NULL;
-    when NULL, infoSz is treated as 0)
+    \param info For software PUF (WOLFSSL_PUF), this is optional context info
+    for domain separation (may be NULL; when NULL, infoSz is treated as 0).
+    For hardware PUF (WOLFSSL_HWPUF), this is the key code returned when the
+    key was generated.
     \param infoSz size of info in bytes
     \param key output buffer for derived key
     \param keySz desired key size in bytes
@@ -135,6 +214,7 @@ int wc_PufReconstruct(wc_PufCtx* ctx, const byte* helperData, word32 helperSz);
 
     \sa wc_PufEnroll
     \sa wc_PufReconstruct
+    \sa wc_PufGenerateKey
     \sa wc_PufGetIdentity
 */
 int wc_PufDeriveKey(wc_PufCtx* ctx, const byte* info, word32 infoSz,
@@ -145,6 +225,8 @@ int wc_PufDeriveKey(wc_PufCtx* ctx, const byte* info, word32 infoSz,
 
     \brief Retrieve the device identity hash (SHA-256 or SHA3-256 of stable
     bits). Deterministic for a given device.
+    This function is valid for software PUF (WOLFSSL_PUF), but invalid for
+    hardware PUF (WOLFSSL_HWPUF).
 
     \return 0 on success
     \return BAD_FUNC_ARG if ctx or id is NULL
@@ -191,6 +273,8 @@ int wc_PufZeroize(wc_PufCtx* ctx);
 
     \brief Inject synthetic SRAM test data for testing without hardware.
     Only available when WOLFSSL_PUF_TEST is defined.
+    This function is valid for software PUF (WOLFSSL_PUF), but invalid for
+    hardware PUF (WOLFSSL_HWPUF).
 
     \return 0 on success
     \return BAD_FUNC_ARG if ctx or data is NULL