Merge pull request #75 from billphipps/doc_updates

Updates to correct documentation bug and minor API tweaks.

Author: bigbrett

src/wh_client.c

@@ -1188,160 +1188,3 @@ int wh_Client_CounterDestroy(whClientContext* c, whNvmId counterId)
     }
     return ret;
 }
-
-#if 0
-#ifndef WOLFHSM_CFG_NO_CRYPTO
-
-#ifdef HAVE_CURVE25519
-int wh_Client_SetKeyIdCurve25519(curve25519_key* key, whNvmId keyId)
-{
-    if (key == NULL)
-        return WH_ERROR_BADARGS;
-    key->devCtx = (void*)((intptr_t)keyId);
-    key->pubSet = 1;
-    key->privSet = 1;
-    return WH_ERROR_OK;
-}
-
-int wh_Client_GetKeyIdCurve25519(curve25519_key* key, whNvmId* outId)
-{
-    if (key == NULL || outId == NULL)
-        return WH_ERROR_BADARGS;
-    *outId = (intptr_t)key->devCtx;
-    return WH_ERROR_OK;
-}
-#endif /* HAVE_CURVE25519 */
-
-#ifndef NO_RSA
-int wh_Client_SetKeyIdRsa(RsaKey* key, whNvmId keyId)
-{
-    if (key == NULL)
-        return WH_ERROR_BADARGS;
-    key->devCtx = (void*)((intptr_t)keyId);
-    return WH_ERROR_OK;
-}
-
-int wh_Client_GetKeyIdRsa(RsaKey* key, whNvmId* outId)
-{
-    if (key == NULL || outId == NULL)
-        return WH_ERROR_BADARGS;
-    *outId = (intptr_t)key->devCtx;
-    return WH_ERROR_OK;
-}
-#endif
-
-#ifndef NO_AES
-int wh_Client_SetKeyIdAes(Aes* key, whNvmId keyId)
-{
-    if (key == NULL)
-        return WH_ERROR_BADARGS;
-    key->devCtx = (void*)((intptr_t)keyId);
-    return WH_ERROR_OK;
-}
-
-int wh_Client_GetKeyIdAes(Aes* key, whNvmId* outId)
-{
-    if (key == NULL || outId == NULL)
-        return WH_ERROR_BADARGS;
-    *outId = (intptr_t)key->devCtx;
-    return WH_ERROR_OK;
-}
-#endif
-
-#ifdef WOLFSSL_CMAC
-int wh_Client_SetKeyIdCmac(Cmac* key, whNvmId keyId)
-{
-    if (key == NULL)
-        return WH_ERROR_BADARGS;
-    key->devCtx = (void*)((intptr_t)keyId);
-    return WH_ERROR_OK;
-}
-
-int wh_Client_GetKeyIdCmac(Cmac* key, whNvmId* outId)
-{
-    if (key == NULL || outId == NULL)
-        return WH_ERROR_BADARGS;
-    *outId = (intptr_t)key->devCtx;
-    return WH_ERROR_OK;
-}
-
-int wh_Client_AesCmacGenerate(Cmac* cmac, byte* out, word32* outSz,
-    const byte* in, word32 inSz, whNvmId keyId, void* heap)
-{
-    int ret;
-    ret = wc_InitCmac_ex(cmac, NULL, 0, WC_CMAC_AES, NULL, heap,
-        WH_DEV_ID);
-    /* set keyId */
-    if (ret == 0)
-        ret = wh_Client_SetKeyIdCmac(cmac, keyId);
-    if (ret == 0)
-        ret = wc_CmacUpdate(cmac, in, inSz);
-    if (ret == 0)
-        ret = wc_CmacFinal(cmac, out, outSz);
-    return ret;
-}
-
-int wh_Client_AesCmacVerify(Cmac* cmac, const byte* check, word32 checkSz,
-    const byte* in, word32 inSz, whNvmId keyId, void* heap)
-{
-    int ret;
-    word32 outSz = AES_BLOCK_SIZE;
-    byte out[AES_BLOCK_SIZE];
-    ret = wc_InitCmac_ex(cmac, NULL, 0, WC_CMAC_AES, NULL, heap,
-        WH_DEV_ID);
-    /* set keyId */
-    if (ret == 0)
-        ret = wh_Client_SetKeyIdCmac(cmac, keyId);
-    if (ret == 0)
-        ret = wc_CmacUpdate(cmac, in, inSz);
-    if (ret == 0)
-        ret = wc_CmacFinal(cmac, out, &outSz);
-    if (ret == 0)
-        ret = memcmp(out, check, outSz) == 0 ? 0 : 1;
-    return ret;
-}
-
-int wh_Client_CmacCancelableResponse(whClientContext* c, Cmac* cmac,
-    uint8_t* out, uint16_t* outSz)
-{
-    whPacket* packet;
-    uint8_t* packOut;
-    int ret;
-    uint16_t group;
-    uint16_t action;
-    uint16_t dataSz;
-    if (c == NULL || cmac == NULL)
-        return WH_ERROR_BADARGS;
-    packet = (whPacket*)wh_CommClient_GetDataPtr(c->comm);
-    /* out is after the fixed size fields */
-    packOut = (uint8_t*)(&packet->cmacRes + 1);
-    do {
-        ret = wh_Client_RecvResponse(c, &group, &action, &dataSz,
-            (uint8_t*)packet);
-    } while (ret == WH_ERROR_NOTREADY);
-    /* check for out of sequence action */
-    if (ret == 0 && (group != WH_MESSAGE_GROUP_CRYPTO ||
-        action != WC_ALGO_TYPE_CMAC)) {
-        ret = WH_ERROR_ABORTED;
-    }
-    if (ret == 0) {
-        if (packet->rc != 0)
-            ret = packet->rc;
-        /* read keyId and out */
-        else {
-            cmac->devCtx = (void*)((intptr_t)packet->cmacRes.keyId);
-            if (out != NULL) {
-                if (packet->cmacRes.outSz > *outSz)
-                    ret = WH_ERROR_BADARGS;
-                else {
-                    XMEMCPY(out, packOut, packet->cmacRes.outSz);
-                    *outSz = packet->cmacRes.outSz;
-                }
-            }
-        }
-    }
-    return ret;
-}
-#endif /* WOLFSSL_CMAC */
-#endif  /* !WOLFHSM_CFG_NO_CRYPTO */
-#endif /*0*/

src/wh_client_crypto.c

@@ -78,7 +78,7 @@ static int _EccMakeKey(whClientContext* ctx,
 static int _Curve25519MakeKey(whClientContext* ctx,
         uint16_t size,
         whKeyId *inout_key_id, whNvmFlags flags,
-        uint16_t label_len, uint8_t* label,
+        const uint8_t* label, uint16_t label_len,
         curve25519_key* key);
 #endif /* HAVE_CURVE25519 */
 
@@ -1230,7 +1230,7 @@ int wh_Client_Curve25519ExportKey(whClientContext* ctx, whKeyId keyId,
 static int _Curve25519MakeKey(whClientContext* ctx,
         uint16_t size,
         whKeyId *inout_key_id, whNvmFlags flags,
-        uint16_t label_len, uint8_t* label,
+        const uint8_t* label, uint16_t label_len,
         curve25519_key* key)
 {
     int ret = 0;
@@ -1329,7 +1329,7 @@ static int _Curve25519MakeKey(whClientContext* ctx,
 int wh_Client_Curve25519MakeCacheKey(whClientContext* ctx,
         uint16_t size,
         whKeyId *inout_key_id, whNvmFlags flags,
-        uint16_t label_len, uint8_t* label)
+        const uint8_t* label, uint16_t label_len)
 {
     /* Valid keyid ptr is required in this form */
     if (inout_key_id == NULL) {
@@ -1339,7 +1339,7 @@ int wh_Client_Curve25519MakeCacheKey(whClientContext* ctx,
     return _Curve25519MakeKey(ctx,
             size,
             inout_key_id, flags,
-            label_len, label,
+            label, label_len,
             NULL);
 }
 
@@ -1354,7 +1354,7 @@ int wh_Client_Curve25519MakeExportKey(whClientContext* ctx,
     return _Curve25519MakeKey(ctx,
             size,
             NULL, WH_NVM_FLAGS_EPHEMERAL,
-            0, NULL,
+            NULL, 0,
             key);
 }
 

test/wh_test_crypto.c

@@ -503,13 +503,13 @@ static int whTest_CryptoCurve25519(whClientContext* ctx, int devId, WC_RNG* rng)
                 WH_ERROR_PRINT("Failed to wc_curve25519_init_ex %d\n", ret);
             } else {
                 ret = wh_Client_Curve25519MakeCacheKey(ctx, key_size,
-                        &key_id_a, flags, sizeof(label_a), label_a);
+                        &key_id_a, flags, label_a, sizeof(label_a));
                 if (ret != 0) {
                     WH_ERROR_PRINT("Failed to make cached key %d\n", ret);
                 }
                 if (ret == 0) {
                     ret = wh_Client_Curve25519MakeCacheKey(ctx, key_size,
-                            &key_id_b, flags, sizeof(label_b), label_b);
+                            &key_id_b, flags, label_b, sizeof(label_b));
                     if (ret != 0) {
                         WH_ERROR_PRINT("Failed to make cached key %d\n", ret);
                     }

wolfhsm/wh_client.h

@@ -54,7 +54,7 @@
 #ifndef WOLFHSM_CFG_NO_CRYPTO
 
 /* Device Id to be registered and passed to wolfCrypt functions */
-enum {
+enum WH_CLIENT_DEVID_ENUM {
     WH_DEV_ID = 0x5748534D, /* "WHSM" */
 #ifdef WOLFHSM_CFG_DMA
     WH_DEV_ID_DMA = 0x57444D41, /* "WDMA" */
@@ -226,7 +226,7 @@ int wh_Client_CommInfoRequest(whClientContext* c);
  *                                      size of each key in server RAM
  * @param[out] out_cfg_keycache_bigcount Pointer to store the server's number of
  *                                    big keys in the server RAM
- * @param[out] out_cfg_keycache_big bufsize Pointer to store the server's
+ * @param[out] out_cfg_keycache_bigbufsize bufsize Pointer to store the server's
  *                                    maximum size of each big key in server RAM
  * @param[out] out_cfg_customcb_count Pointer to store the server's number of
  *                                    custom callbacks
@@ -274,6 +274,10 @@ int wh_Client_CommInfoResponse(whClientContext* c,
  *                                    keys in the server RAM
  * @param[out] out_cfg_keycache_bufsize Pointer to store the server's maximum
  *                                      size of each key in server RAM
+ * @param[out] out_cfg_keycache_bigcount Pointer to store the server's number of
+ *                                    keys in the server RAM
+ * @param[out] out_cfg_keycache_bigbufsize Pointer to store the server's maximum
+ *                                      size of each key in server RAM
  * @param[out] out_cfg_customcb_count Pointer to store the server's number of
  *                                    custom callbacks
  * @param[out] out_cfg_dmaaddr_count Pointer to store the server's number of
@@ -1699,5 +1703,4 @@ int wh_Client_CustomCbCheckRegisteredResponse(whClientContext* c,
 int wh_Client_CustomCbCheckRegistered(whClientContext* c, uint16_t id,
                                       int* responseError);
 
-
 #endif /* !WOLFHSM_WH_CLIENT_H_ */

wolfhsm/wh_client_crypto.h

@@ -130,18 +130,63 @@ int wh_Client_Curve25519ImportKey(whClientContext* ctx, curve25519_key* key,
 int wh_Client_Curve25519ExportKey(whClientContext* ctx, whKeyId keyId,
         curve25519_key* key, uint16_t label_len, uint8_t* label);
 
-/* TODO: Generate a Curve25519 key on the server and put it in the server keycache */
+/**
+ * @brief Generate a Curve25519 key in the server key cache
+ *
+ * This function requests the server to generate a new Curve25519 key and insert
+ * it into the server's key cache.
+ *
+ * @param[in] ctx Pointer to the client context
+ * @param[in] size Size of the key to generate in bytes, normally set to
+ *                 CURVE25519_KEY_SIZE.
+ * @param[in,out] inout_key_id. Set to WH_KEYID_ERASED to have the server
+ *                select a unique id for this key.
+ * @param[in] flags Optional flags to be associated with the key while in the
+ *                  key cache or after being committed. Set to WH_NVM_FLAGS_NONE
+ *                  if not used.
+ * @param[in] label Optional label to be associated with the key while in the
+ *                  key cache or after being committed. Set to NULL if not used.
+ * @param[in] label_len Size of the label up to WH_NVM_LABEL_SIZE. Set to 0 if
+ *                      not used.
+ * @return int Returns 0 on success or a negative error code on failure.
+ */
 int wh_Client_Curve25519MakeCacheKey(whClientContext* ctx,
         uint16_t size,
-        whKeyId *inout_key_Id, whNvmFlags flags,
-        uint16_t label_len, uint8_t* label);
+        whKeyId *inout_key_id, whNvmFlags flags,
+        const uint8_t* label, uint16_t label_len);
 
-/* TODO: Generate a Curve25519 key on the server and export it inta a local struct */
+/**
+ * @brief Generate a Curve25519 key by the server and export to the client
+ *
+ * This function requests the server to generate a new Curve25519 key pair and
+ * export it to the client, without using any key cache or additional resources
+ *
+ * @param[in] ctx Pointer to the client context
+ * @param[in] size Size of the key to generate in bytes, normally set to
+ *                 CURVE25519_KEY_SIZE.
+ * @param[in] key Pointer to a wolfCrypt key structure, which will be
+ *                initialized to the new key pair when successful
+ * @return int Returns 0 on success or a negative error code on failure.
+ */
 int wh_Client_Curve25519MakeExportKey(whClientContext* ctx,
-        uint16_t size,
-        curve25519_key* key);
+        uint16_t size, curve25519_key* key);
 
-/* TODO: Compute an X25519 shared secret */
+/**
+ * @brief Compute an X25519 shared secret using a public and private key
+ *
+ * This function requests the server compute the shared secret using the
+ * provided wolfCrypt private and public keys.  Note, the client will
+ * temporarily import any missing key material to the server as required.
+ *
+ * @param[in] ctx Pointer to the client context
+ * @param[in] priv_key Pointer to a wolfCrypt key structure that holds the
+ *                     private key
+ * @param[in] pub_key Pointer to a wolfCrypt key structure that holds the
+ *                    public key
+ * @param[in] endian Endianness of the values.  EC25519_BIG_ENDIAN (typical) or
+ *                   EC25519_LITTLE_ENDIAN
+ * @return int Returns 0 on success or a negative error code on failure.
+ */
 int wh_Client_Curve25519SharedSecret(whClientContext* ctx,
         curve25519_key* priv_key, curve25519_key* pub_key,
         int endian, uint8_t* out, uint16_t *out_size);