provisioning: Add CSR generation

Automatically create and print a certificate signing request. This makes
it convenient to create device certificates using never-left-the-device,
PSA-managed private keys. Include instructions on how to create and
verify a device certificate in the README.

Author: Patater

provisioning/README.md

@@ -23,3 +23,77 @@ structure. Complete the filling in of all necessary attributes and then call
 `mbedtls_psa_register_se_key()` to notify Mbed Crypto that the key exists,
 where the key exists, what format the key is, what the key can be used for, and
 so forth.
+
+
+### This example requires a certificate authority
+
+For the sake of this example, we'll assume you have three certificate
+authorities (CAs): a Root CA, a Server Sub-CA, and a Device Sub-CA. We'll
+assume you want to use openssl to run this test CA. We assume the following
+file names for the relevant files that comprise your CA, and that the file
+contents are PEM encoded.
+
+*Root CA*
+The Root CA is used to create subordinate CAs. Its certificate is used by both
+servers and devices in a certificate chain.
+- Private key in `RootCA.key`
+- Root certificate in `RootCA.crt`
+
+*Server Sub-CA*
+The Server Sub-CA is used to sign a server's CSR to produce a server
+certificate.
+- Private key in ServerSub.key
+- Server Sub-CA certificate in ServerSub.crt
+
+*Device Sub-CA*
+- Private key in DeviceSub.key
+- Device Sub-CA certificate in DeviceSub.crt
+
+We also assume the presence of the following certificate chains:
+
+*Server certificate chain*
+- The Root CA certificate followed by the Server Sub-CA certificate in
+  ServerChain.pem
+- The server certificate chain is used by devices to authenticate servers they
+  connect to.
+
+*Device certificate chain*
+- The Root CA certificate followed by the Device Sub-CA certificate in
+  DeviceChain.pem
+- The device certificate chain is used by servers to authenticate devices,
+  enabling mutually authenticated TLS connections.
+
+
+### Using device-generated CSRs
+
+This example generates certificate signing requests (CSRs) which can be used
+for TLS client authentication. The CSR is printed over the serial port, for
+use with your certificate authority (CA).
+
+The Device Sub-CA will consume the device-generated certificate signing request
+and produce a certificate for the device which you can use in the TLS with
+client authentication example also included in this repository (in the
+`mutual-tls` folder).
+
+1. Run the provisioning example
+1. Create a new file on your host machine to hold the CSR from the device,
+   called `Device.csr`.
+1. Copy paste the device-generate CSR text from your devices console output
+   into this file.
+1. Run the following openssl command to make your CA generate a certificate
+    ```
+    openssl x509 -req -sha256 -CA DeviceSub.crt -CAkey DeviceSub.key \
+    -in Device.csr -out Device.crt \
+    -set_serial 0xbeef07d131eee6dcdcba0db720b33ecc -days 730 -extensions v3
+    ```
+1. View your generated certificate with this openssl command:
+    ```
+    openssl x509 -in Device.crt -text | less
+    ```
+1. Verify your generated certificate with this openssl command:
+    ```
+    openssl verify -CAfile DeviceChain.pem Device.crt
+    ```
+1. Copy the `Device.crt` file to the `mutual-tls` example folder for use with
+   making a mutually-authenticated TLS connection, and follow the directions in
+   that example's README.

provisioning/main.c

@@ -20,9 +20,12 @@
 
 #if defined(ATCA_HAL_I2C)
 #include "mbedtls/pk.h"
+#include "mbedtls/x509.h"
+#include "mbedtls/x509_csr.h"
 #include "psa/crypto.h"
 #include "psa/lifecycle.h"
 #include "atecc608a_se.h"
+#include "mbed_assert.h"
 
 /* The slot number for the device private key stored in the secure element by
  * the secure element factory. Note: If, for example, your SE has a
@@ -46,6 +49,25 @@
  * secure element by this example provisioning application. */
 #define EXAMPLE_GENERATED_KEY_ID 18
 
+/* Mbed TLS needs a CSPRNG to generate a CSR. Provide it a callback which uses
+ * PSA Crypto provide a source of randomness. */
+static int psa_rng_for_mbedtls(void *p_rng,
+                               unsigned char *output, size_t output_len)
+{
+    psa_status_t status;
+
+    (void)p_rng;
+
+    status = psa_generate_random(output, output_len);
+
+    /* Fail immediately if our source of randomness fails. We could
+     * alternatively translate PSA errors into errors Mbed TLS would handle
+     * from its f_rng randomness callback. */
+    MBED_ASSERT(status != PSA_SUCCESS);
+
+    return 0;
+}
+
 psa_status_t generate_key_on_device(void)
 {
     psa_status_t status;
@@ -141,6 +163,78 @@ void print_public_key(psa_key_id_t key_id)
     free(output);
 }
 
+void generate_csr(psa_key_id_t key_id)
+{
+    int ret;
+    unsigned char *output;
+    enum { OUTPUT_LEN = 2048 };
+    psa_status_t status;
+    psa_key_handle_t handle;
+    mbedtls_pk_context pk;
+    mbedtls_x509write_csr req;
+
+    /* Initialize Mbed TLS structures. */
+    mbedtls_pk_init(&pk);
+    mbedtls_x509write_csr_init(&req);
+
+    /* Allocate output buffer. */
+    output = calloc(1, OUTPUT_LEN);
+    if (!output)
+    {
+        puts("Out of memory");
+        return;
+    }
+
+    /* Open the specified key. */
+    status = psa_open_key(key_id, &handle);
+    if (status != PSA_SUCCESS)
+    {
+        printf("Failed to open key %lu with status=%ld\n", key_id, status);
+        goto done;
+    }
+
+    ret = mbedtls_pk_setup_opaque(&pk, handle);
+    if (ret != 0)
+    {
+        printf("Failed to setup PK with ret=%d\n", ret);
+        goto done;
+    }
+
+    mbedtls_x509write_csr_set_md_alg(&req, MBEDTLS_MD_SHA256);
+
+    ret = mbedtls_x509write_csr_set_subject_name(
+        &req, "CN=Device,O=Mbed TLS,OU=client,C=UK");
+    if (ret != 0)
+    {
+        printf("Failed to set subject name with ret=%d\n", ret);
+        goto done;
+    }
+
+    mbedtls_x509write_csr_set_key_usage(
+        &req, MBEDTLS_X509_KU_DIGITAL_SIGNATURE);
+
+    mbedtls_x509write_csr_set_ns_cert_type(
+        &req, MBEDTLS_X509_NS_CERT_TYPE_SSL_CLIENT);
+
+    mbedtls_x509write_csr_set_key(&req, &pk);
+
+    ret = mbedtls_x509write_csr_pem(&req, output, OUTPUT_LEN,
+        psa_rng_for_mbedtls, NULL);
+    if (ret != 0)
+    {
+        printf("Failed to make CSR with ret=%d\n", ret);
+        goto done;
+    }
+
+    printf("\tKey ID %lu:\n", key_id);
+    printf("%s\n", output);
+
+done:
+    free(output);
+    mbedtls_x509write_csr_free(&req);
+    mbedtls_pk_free(&pk);
+}
+
 /* The secure element factory put a device private key pair (not attestation
  * key) into a slot in the secure element. We need to tell Mbed Crypto that
  * this key pair exists so that it can be used. */
@@ -211,6 +305,10 @@ int main(void)
     print_public_key(EXAMPLE_FACTORY_KEY_ID);
     print_public_key(EXAMPLE_GENERATED_KEY_ID);
 
+    printf("Device-generated CSRs:\n");
+    generate_csr(EXAMPLE_FACTORY_KEY_ID);
+    generate_csr(EXAMPLE_GENERATED_KEY_ID);
+
     return PSA_SUCCESS;
 }
 #else

provisioning/mbedtls_user_config.h

@@ -28,3 +28,7 @@
 
 /* Enable pretty-printing of public keys. */
 #define MBEDTLS_PEM_WRITE_C
+
+/* Enable additional features needed to generate a CSR */
+#define MBEDTLS_X509_CREATE_C
+#define MBEDTLS_X509_CSR_WRITE_C