Merge psa api branch into development

docs/architecture/mbed-crypto-storage-specification.md

@@ -193,3 +193,92 @@ The layout of a key file is:
 * key material length (4 bytes)
 * key material: output of `psa_export_key`
 * Any trailing data is rejected on load.
+
+Mbed Crypto TBD
+---------------
+
+Tags: TBD
+
+Released in TBD 2019. <br>
+Integrated in Mbed OS TBD.
+
+### Changes introduced in TBD
+
+* The layout of a key file now has a lifetime field before the type field.
+* Key files can store references to keys in a secure element. In such key files, the key material contains the slot number.
+
+### File namespace on a PSA platform on TBD
+
+Assumption: ITS provides a 64-bit file identifier namespace. The Crypto service can use arbitrary file identifiers and no other part of the system accesses the same file identifier namespace.
+
+Assumption: the owner identifier is a nonzero value of type `int32_t`.
+
+* Files 0 through 0xfffeffff: unused.
+* Files 0xffff0000 through 0xffffffff: reserved for internal use of the crypto library or crypto service. See [non-key files](#non-key-files-on-tbd).
+* Files 0x100000000 through 0xffffffffffff: [content](#key-file-format-for-1.0.0) of the [key whose identifier is the file identifier](#key-names-for-1.0.0). The upper 32 bits determine the owner.
+
+### File namespace on ITS as a library on TBD
+
+Assumption: ITS provides a 64-bit file identifier namespace. The entity using the crypto library can use arbitrary file identifiers and no other part of the system accesses the same file identifier namespace.
+
+This is a library integration, so there is no owner. The key file identifier is identical to the key identifier.
+
+* File 0: unused.
+* Files 1 through 0xfffeffff: [content](#key-file-format-for-1.0.0) of the [key whose identifier is the file identifier](#key-names-for-1.0.0).
+* Files 0xffff0000 through 0xffffffff: reserved for internal use of the crypto library or crypto service. See [non-key files](#non-key-files-on-tbd).
+* Files 0x100000000 through 0xffffffffffffffff: unused.
+
+### Non-key files on TBD
+
+File identifiers in the range 0xffff0000 through 0xffffffff are reserved for internal use in Mbed Crypto.
+
+* Files 0xfffffe02 through 0xfffffeff (`PSA_CRYPTO_SE_DRIVER_ITS_UID_BASE + lifetime`): secure element driver storage. The content of the file is the secure element driver's persistent data.
+* File 0xffffff52 (`PSA_CRYPTO_ITS_RANDOM_SEED_UID`): [nonvolatile random seed](#nonvolatile-random-seed-file-format-for-1.0.0).
+* File 0xffffff54 (`PSA_CRYPTO_ITS_TRANSACTION_UID`): [transaction file](#transaction-file-format-for-tbd).
+* Other files are unused and reserved for future use.
+
+### Key file format for TBD
+
+All integers are encoded in little-endian order in 8-bit bytes except where otherwise indicated.
+
+The layout of a key file is:
+
+* magic (8 bytes): `"PSA\0KEY\0"`.
+* version (4 bytes): 0.
+* lifetime (4 bytes): `psa_key_lifetime_t` value.
+* type (4 bytes): `psa_key_type_t` value.
+* policy usage flags (4 bytes): `psa_key_usage_t` value.
+* policy usage algorithm (4 bytes): `psa_algorithm_t` value.
+* policy enrollment algorithm (4 bytes): `psa_algorithm_t` value.
+* key material length (4 bytes).
+* key material:
+    * For a transparent key: output of `psa_export_key`.
+    * For an opaque key (key in a secure element): slot number (8 bytes), in platform endianness.
+* Any trailing data is rejected on load.
+
+### Transaction file format for TBD
+
+The transaction file contains data about an ongoing action that cannot be completed atomically. It exists only if there is an ongoing transaction.
+
+All integers are encoded in platform endianness.
+
+All currently existing transactions concern a key in a secure element.
+
+The layout of a transaction file is:
+
+* type (2 bytes): the [transaction type](#transaction-types-on-tbd).
+* unused (2 bytes)
+* lifetime (4 bytes): `psa_key_lifetime_t` value that corresponds to a key in a secure element.
+* slot number (8 bytes): `psa_key_slot_number_t` value. This is the unique designation of the key for the secure element driver.
+* key identifier (4 bytes in a library integration, 8 bytes on a PSA platform): the internal representation of the key identifier. On a PSA platform, this encodes the key owner in the same way as [in file identifiers for key files](#file-namespace-on-a-psa-platform-on-tbd)).
+
+#### Transaction types on TBD
+
+* 0x0001: key creation. The following locations may or may not contain data about the key that is being created:
+    * The slot in the secure element designated by the slot number.
+    * The file containing the key metadata designated by the key identifier.
+    * The driver persistent data.
+* 0x0002: key destruction. The following locations may or may not still contain data about the key that is being destroyed:
+    * The slot in the secure element designated by the slot number.
+    * The file containing the key metadata designated by the key identifier.
+    * The driver persistent data.

docs/getting_started.md

@@ -73,7 +73,7 @@ Importing a key and checking key information:
 1. Test the information stored in this slot:
 ```C
     int key_slot = 1;
-    uint8_t *data = "KEYPAIR_KEY_DATA";
+    uint8_t *data = "KEY_PAIR_KEY_DATA";
     size_t data_size;
     psa_key_type_t type = PSA_KEY_TYPE_RSA_PUBLIC_KEY;
     size_t got_bits;
@@ -127,7 +127,7 @@ This allows the key in the key slot to be used for RSA signing.
                              PSA_ALG_RSA_PKCS1V15_SIGN_RAW);
     status = psa_set_key_policy(key_slot, &policy);
 
-    status = psa_import_key(key_slot, PSA_KEY_TYPE_RSA_KEYPAIR,
+    status = psa_import_key(key_slot, PSA_KEY_TYPE_RSA_KEY_PAIR,
                             key, sizeof(key));
 
     /* Sing message using the key */
@@ -335,7 +335,7 @@ Deriving a new AES-CTR 128-bit encryption key into a given key slot using HKDF w
 1. Set up the generator using the `psa_key_derivation` function providing a key slot containing a key that can be used for key derivation and a salt and label (Note: salt and label are optional).
 1. Initiate a key policy to for the derived key by calling `psa_key_policy_set_usage()` with `PSA_KEY_USAGE_ENCRYPT` parameter and the algorithm `PSA_ALG_CTR`.
 1. Set the key policy to the derived key slot.
-1. Import a key from generator into the desired key slot using (`psa_generator_import_key`).
+1. Import a key from generator into the desired key slot using (`psa_key_derivation_output_key`).
 1. Clean up generator.
 
 At this point the derived key slot holds a new 128-bit AES-CTR encryption key derived from the key, salt and label provided:
@@ -358,7 +358,7 @@ At this point the derived key slot holds a new 128-bit AES-CTR encryption key de
 
     psa_algorithm_t alg = PSA_ALG_HKDF(PSA_ALG_SHA_256);
     psa_key_policy_t policy = PSA_KEY_POLICY_INIT;
-    psa_crypto_generator_t generator = PSA_CRYPTO_GENERATOR_INIT;
+    psa_key_derivation_operation_t generator = PSA_KEY_DERIVATION_OPERATION_INIT;
     size_t derived_bits = 128;
     size_t capacity = PSA_BITS_TO_BYTES(derived_bits);
 
@@ -378,10 +378,10 @@ At this point the derived key slot holds a new 128-bit AES-CTR encryption key de
 
     psa_set_key_policy(derived_key, &policy);
 
-    psa_generator_import_key(derived_key, PSA_KEY_TYPE_AES, derived_bits, &generator);
+    psa_key_derivation_output_key(derived_key, PSA_KEY_TYPE_AES, derived_bits, &generator);
 
     /* Clean up generator and key */
-    psa_generator_abort(&generator);
+    psa_key_derivation_abort(&generator);
     /* as part of clean up you may want to clean up the keys used by calling:
      * psa_destroy_key( base_key ); or psa_destroy_key( derived_key ); */
     mbedtls_psa_crypto_free();
@@ -510,7 +510,7 @@ Generate a piece of random 128-bit AES data:
     psa_set_key_policy(slot, &policy);
 
     /* Generate a key */
-    psa_generate_key(slot, PSA_KEY_TYPE_AES, bits, NULL, 0);
+    psa_generate_key(slot, PSA_KEY_TYPE_AES, bits);
 
     psa_export_key(slot, exported, exported_size, &exported_length)
 

include/mbedtls/check_config.h

@@ -458,6 +458,12 @@
 #error "MBEDTLS_PSA_CRYPTO_SPM defined, but not all prerequisites"
 #endif
 
+#if defined(MBEDTLS_PSA_CRYPTO_SE_C) &&    \
+    ! ( defined(MBEDTLS_PSA_CRYPTO_C) && \
+        defined(MBEDTLS_PSA_CRYPTO_STORAGE_C) )
+#error "MBEDTLS_PSA_CRYPTO_SE_C defined, but not all prerequisites"
+#endif
+
 #if defined(MBEDTLS_PSA_CRYPTO_STORAGE_C) &&            \
     ! defined(MBEDTLS_PSA_CRYPTO_C)
 #error "MBEDTLS_PSA_CRYPTO_STORAGE_C defined, but not all prerequisites"

include/mbedtls/cipher_internal.h

@@ -124,14 +124,13 @@ typedef enum
     MBEDTLS_CIPHER_PSA_KEY_UNSET = 0,
     MBEDTLS_CIPHER_PSA_KEY_OWNED, /* Used for PSA-based cipher contexts which */
                                   /* use raw key material internally imported */
-                                  /* into a allocated key slot, and which     */
-                                  /* hence need to destroy that key slot      */
-                                  /* when they are no longer needed.          */
+                                  /* as a volatile key, and which hence need  */
+                                  /* to destroy that key when the context is  */
+                                  /* freed.                                   */
     MBEDTLS_CIPHER_PSA_KEY_NOT_OWNED, /* Used for PSA-based cipher contexts   */
-                                      /* which use a key from a key slot      */
-                                      /* provided by the user, and which      */
-                                      /* hence should not be destroyed when   */
-                                      /* the context is no longer needed.     */
+                                      /* which use a key provided by the      */
+                                      /* user, and which hence will not be    */
+                                      /* destroyed when the context is freed. */
 } mbedtls_cipher_psa_key_ownership;
 
 typedef struct

include/mbedtls/config.h

@@ -1746,6 +1746,22 @@
  */
 #define MBEDTLS_PSA_CRYPTO_C
 
+/**
+ * \def MBEDTLS_PSA_CRYPTO_SE_C
+ *
+ * Enable secure element support in the Platform Security Architecture
+ * cryptography API.
+ *
+ * \warning This feature is not yet suitable for production. It is provided
+ *          for API evaluation and testing purposes only.
+ *
+ * Module:  library/psa_crypto_se.c
+ *
+ * Requires: MBEDTLS_PSA_CRYPTO_C, MBEDTLS_PSA_CRYPTO_STORAGE_C
+ *
+ */
+//#define MBEDTLS_PSA_CRYPTO_SE_C
+
 /**
  * \def MBEDTLS_PSA_CRYPTO_STORAGE_C
  *

include/mbedtls/pk.h

@@ -217,7 +217,7 @@ void mbedtls_pk_init( mbedtls_pk_context *ctx );
  *
  * \note            For contexts that have been set up with
  *                  mbedtls_pk_setup_opaque(), this does not free the underlying
- *                  key slot and you still need to call psa_destroy_key()
+ *                  PSA key and you still need to call psa_destroy_key()
  *                  independently if you want to destroy that key.
  */
 void mbedtls_pk_free( mbedtls_pk_context *ctx );
@@ -259,29 +259,29 @@ int mbedtls_pk_setup( mbedtls_pk_context *ctx, const mbedtls_pk_info_t *info );
 
 #if defined(MBEDTLS_USE_PSA_CRYPTO)
 /**
- * \brief           Initialize a PK context to wrap a PSA key slot.
+ * \brief           Initialize a PK context to wrap a PSA key.
  *
  * \note            This function replaces mbedtls_pk_setup() for contexts
- *                  that wrap a (possibly opaque) PSA key slot instead of
+ *                  that wrap a (possibly opaque) PSA key instead of
  *                  storing and manipulating the key material directly.
  *
  * \param ctx       The context to initialize. It must be empty (type NONE).
- * \param key       The PSA key slot to wrap, which must hold an ECC key pair
+ * \param key       The PSA key to wrap, which must hold an ECC key pair
  *                  (see notes below).
  *
- * \note            The wrapped key slot must remain valid as long as the
+ * \note            The wrapped key must remain valid as long as the
  *                  wrapping PK context is in use, that is at least between
  *                  the point this function is called and the point
  *                  mbedtls_pk_free() is called on this context. The wrapped
- *                  key slot might then be independently used or destroyed.
+ *                  key might then be independently used or destroyed.
  *
  * \note            This function is currently only available for ECC key
  *                  pairs (that is, ECC keys containing private key material).
  *                  Support for other key types may be added later.
  *
  * \return          \c 0 on success.
  * \return          #MBEDTLS_ERR_PK_BAD_INPUT_DATA on invalid input
- *                  (context already used, invalid key slot).
+ *                  (context already used, invalid key handle).
  * \return          #MBEDTLS_ERR_PK_FEATURE_UNAVAILABLE if the key is not an
  *                  ECC key pair.
  * \return          #MBEDTLS_ERR_PK_ALLOC_FAILED on allocation failure.
@@ -788,26 +788,27 @@ int mbedtls_pk_load_file( const char *path, unsigned char **buf, size_t *n );
 
 #if defined(MBEDTLS_USE_PSA_CRYPTO)
 /**
- * \brief           Turn an EC key into an Opaque one
+ * \brief           Turn an EC key into an opaque one.
  *
  * \warning         This is a temporary utility function for tests. It might
  *                  change or be removed at any time without notice.
  *
  * \note            Only ECDSA keys are supported so far. Signing with the
  *                  specified hash is the only allowed use of that key.
  *
- * \param pk        Input: the EC key to transfer to a PSA key slot.
- *                  Output: a PK context wrapping that PSA key slot.
- * \param slot      Output: the chosen slot for storing the key.
- *                  It's the caller's responsibility to destroy that slot
- *                  after calling mbedtls_pk_free() on the PK context.
+ * \param pk        Input: the EC key to import to a PSA key.
+ *                  Output: a PK context wrapping that PSA key.
+ * \param handle    Output: a PSA key handle.
+ *                  It's the caller's responsibility to call
+ *                  psa_destroy_key() on that handle after calling
+ *                  mbedtls_pk_free() on the PK context.
  * \param hash_alg  The hash algorithm to allow for use with that key.
  *
  * \return          \c 0 if successful.
  * \return          An Mbed TLS error code otherwise.
  */
 int mbedtls_pk_wrap_as_opaque( mbedtls_pk_context *pk,
-                               psa_key_handle_t *slot,
+                               psa_key_handle_t *handle,
                                psa_algorithm_t hash_alg );
 #endif /* MBEDTLS_USE_PSA_CRYPTO */
 

include/mbedtls/psa_util.h

@@ -413,7 +413,7 @@ static inline int mbedtls_psa_err_translate_pk( psa_status_t status )
         /* All other failures */
         case PSA_ERROR_COMMUNICATION_FAILURE:
         case PSA_ERROR_HARDWARE_FAILURE:
-        case PSA_ERROR_TAMPERING_DETECTED:
+        case PSA_ERROR_CORRUPTION_DETECTED:
             return( MBEDTLS_ERR_PK_HW_ACCEL_FAILED );
         default: /* We return the same as for the 'other failures',
                   * but list them separately nonetheless to indicate