Merge pull request #6 from Patater/factory-entropy-example

Add factory entropy injection to the example

Author: Patater

README.md

@@ -6,6 +6,33 @@ List of examples contained within this repository:
 * Cipher encrypt/decrypt using an AES key in cipher block chain (CBC) mode with PKCS7 padding using multiple blocks.
 * Cipher encrypt/decrypt using an AES key in counter (CTR) mode using multiple blocks.
 
+## Factory injection of entropy
+
+This example also contains a fake entropy injection example. Use of this
+function (`mbedtls_psa_inject_entropy()`) is demonstrated in this example, but
+it is not a function users would ever need to call as part of their
+applications. The function is useful for factory tool developers only.
+
+In a production system, and in the absence of other sources of entropy, a
+factory tool can inject entropy into the device. After the factory tool
+completes manufacturing of a device, that device must contain enough entropy
+for the lifetime of the device or be able to produce it with an on-board TRNG.
+
+A factory application wishing to inject entropy should configure Mbed Crypto
+using the Mbed TLS configuration system (for the PSA Secure Processing Element,
+SPE), such as in the factory application's SPE binary's `mbed_app.json` as
+follows:
+
+```javascript
+{
+    "macros": [
+        "MBEDTLS_ENTROPY_NV_SEED=1",
+        "MBEDTLS_PLATFORM_NV_SEED_READ_MACRO=mbed_default_seed_read",
+        "MBEDTLS_PLATFORM_NV_SEED_WRITE_MACRO=mbed_default_seed_write"
+    ]
+}
+```
+
 ## Prerequisites
 * Install <a href='https://github.com/ARMmbed/mbed-cli#installing-mbed-cli'>Mbed CLI</a>
 

main.cpp

@@ -19,6 +19,7 @@
 #endif
 
 #include "psa/crypto.h"
+#include "entropy.h"
 #include <string.h>
 #include <inttypes.h>
 
@@ -331,8 +332,38 @@ static void cipher_examples(void)
     }
 }
 
+static void fake_set_initial_nvseed(void)
+{
+    /* This function, fake_set_initial_nvseed(), is useless on platforms that
+     * have already been manufactured correctly. This function demonstrates
+     * what a factory tool may do in order to manufacture a device that does
+     * not have its own source of entropy. */
+
+    /* mbedtls_psa_inject_entropy() is always present, but calls to it will
+     * always fail unless the PSA Secure Processing Element (SPE) is configured
+     * with both MBEDTLS_ENTROPY_NV_SEED and MBEDTLS_PSA_HAS_ITS_IO by the
+     * SPE's Mbed TLS configuration system. */
+    uint8_t seed[MBEDTLS_ENTROPY_MAX_SEED_SIZE];
+
+    /* Calculate a fake seed for injecting. A real factory application would
+     * inject true entropy for use as the initial NV Seed. */
+    for (size_t i = 0; i < sizeof(seed); ++i) {
+        seed[i] = i;
+    }
+
+    int status = mbedtls_psa_inject_entropy(seed, sizeof(seed));
+    if (status) {
+        /* The device may already have an NV Seed injected, or another error
+         * may have happened during injection. */
+        mbedtls_printf("warning (%d) - this attempt at entropy injection"
+                       " failed\n", status);
+    }
+}
+
 int main(void)
 {
+    fake_set_initial_nvseed();
+
     ASSERT_STATUS(psa_crypto_init(), PSA_SUCCESS);
     cipher_examples();
 exit:

mbed_app.json

@@ -1,8 +1,12 @@
 {
     "target_overrides": {
         "*": {
-             "platform.stdio-convert-newlines": true
+             "platform.stdio-convert-newlines": true,
+             "target.extra_labels_add": ["PSA"]
         }
-    }
+    },
+    "macros": [
+        "MBEDTLS_USER_CONFIG_FILE=\"mbedtls_user_config.h\""
+    ]
 }
 

mbedtls_user_config.h

@@ -0,0 +1,32 @@
+/*
+ *  Copyright (C) 2006-2018, Arm Limited, All Rights Reserved
+ *  SPDX-License-Identifier: Apache-2.0
+ *
+ *  Licensed under the Apache License, Version 2.0 (the "License"); you may
+ *  not use this file except in compliance with the License.
+ *  You may obtain a copy of the License at
+ *
+ *  http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  Unless required by applicable law or agreed to in writing, software
+ *  distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ *  WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  See the License for the specific language governing permissions and
+ *  limitations under the License.
+ *
+ *  This file is part of Mbed TLS (https://tls.mbed.org)
+ */
+
+/* Enable PSA APIs, which this example depends on. */
+#if !defined(MBEDTLS_PSA_CRYPTO_C)
+#   define MBEDTLS_PSA_CRYPTO_C
+#endif
+
+/* Enable the default implementation of the PSA entropy injection API if we are
+ * building for an SPE. */
+#if defined(COMPONENT_PSA_SRV_IMPL) || defined(COMPONENT_PSA_SRV_EMUL)
+#   define MBEDTLS_ENTROPY_NV_SEED
+#   define MBEDTLS_PSA_HAS_ITS_IO
+#   define MBEDTLS_PLATFORM_NV_SEED_READ_MACRO mbed_default_seed_read
+#   define MBEDTLS_PLATFORM_NV_SEED_WRITE_MACRO mbed_default_seed_write
+#endif