PSA unified driver prototype

Makefile

@@ -14,7 +14,7 @@ programs: lib
 	$(MAKE) -C programs
 
 lib:
-	$(MAKE) -C library
+	$(MAKE) -C library "PSA_DRIVERS=$(abspath $(PSA_DRIVERS))"
 
 tests: lib
 	$(MAKE) -C tests

docs/architecture/Makefile

@@ -4,6 +4,7 @@ default: all
 
 all_markdown = \
 	       mbed-crypto-storage-specification.md \
+	       psa-driver-interface.md \
 	       testing/driver-interface-test-strategy.md \
 	       testing/test-framework.md \
 	       # This line is intentionally left blank

include/mbedtls/check_config.h

@@ -559,6 +559,10 @@
 #error "MBEDTLS_PSA_CRYPTO_SE_C defined, but not all prerequisites"
 #endif
 
+#if defined(MBEDTLS_PSA_CRYPTO_DRIVERS) && ! defined(MBEDTLS_PSA_CRYPTO_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/config.h

@@ -1307,6 +1307,17 @@
  */
 #define MBEDTLS_PKCS1_V21
 
+/** \def MBEDTLS_PSA_CRYPTO_DRIVERS
+ *
+ * Enable support for the experimental PSA crypto driver interface.
+ *
+ * Requires: MBEDTLS_PSA_CRYPTO_C.
+ *
+ * \warning This interface is experimental and may change or be removed
+ * without notice.
+ */
+//#define MBEDTLS_PSA_CRYPTO_DRIVERS
+
 /**
  * \def MBEDTLS_PSA_CRYPTO_SPM
  *

include/psa/crypto_driver.h

@@ -0,0 +1,52 @@
+/**
+ * \file psa/crypto_driver.h
+ * \brief PSA cryptoprocessor driver interface
+ *
+ * This header declares types and function signatures for cryptoprocessor
+ * drivers.
+ *
+ * This file is part of the PSA Crypto Driver Model, containing functions for
+ * driver developers to implement to enable hardware to be called in a
+ * standardized way by a PSA Cryptographic API implementation. The functions
+ * comprising the driver model, which driver authors implement, are not
+ * intended to be called by application developers.
+ */
+
+/*
+ *  Copyright (C) 2020, 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.
+ */
+#ifndef PSA_CRYPTO_DRIVER_H
+#define PSA_CRYPTO_DRIVER_H
+
+#include <stddef.h>
+#include <stdint.h>
+
+/* Include type definitions (psa_status_t, psa_algorithm_t,
+ * psa_key_type_t, etc.) and macros to build and analyze values
+ * of these types. */
+#include "crypto_types.h"
+#include "crypto_values.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* PSA_CRYPTO_DRIVER_H */

include/psa/crypto_sizes.h

@@ -659,4 +659,41 @@
      PSA_KEY_TYPE_IS_ECC_PUBLIC_KEY(key_type) ? PSA_KEY_EXPORT_ECC_PUBLIC_KEY_MAX_SIZE(key_bits) : \
      0)
 
+#define PSA_VENDOR_RSA_MAX_PUBLIC_KEY_SIZE \
+    PSA_KEY_EXPORT_RSA_PUBLIC_KEY_MAX_SIZE(PSA_VENDOR_RSA_MAX_KEY_BITS)
+#define PSA_VENDOR_RSA_MAX_KEY_PAIR_SIZE \
+    PSA_KEY_EXPORT_RSA_KEY_PAIR_MAX_SIZE(PSA_VENDOR_RSA_MAX_KEY_BITS)
+#define PSA_VENDOR_ECC_MAX_PUBLIC_KEY_SIZE \
+    PSA_KEY_EXPORT_ECC_PUBLIC_KEY_MAX_SIZE(PSA_VENDOR_ECC_MAX_CURVE_BITS)
+#define PSA_VENDOR_ECC_MAX_KEY_PAIR_SIZE \
+    PSA_BITS_TO_BYTES(PSA_VENDOR_ECC_MAX_CURVE_BITS)
+
+/** Sufficient output buffer size for psa_export_key() on a public key or psa_export_public_key().
+ */
+#define PSA_EXPORT_PUBLIC_KEY_MAX_SIZE 0
+#if (defined(MBEDTLS_RSA_C) || defined(MBEDTLS_PK_RSA_ALT_SUPPORT)) && \
+    PSA_VENDOR_RSA_MAX_PUBLIC_KEY_SIZE > PSA_EXPORT_PUBLIC_KEY_MAX_SIZE
+#undef PSA_EXPORT_PUBLIC_KEY_MAX_SIZE
+#define PSA_EXPORT_PUBLIC_KEY_MAX_SIZE PSA_VENDOR_RSA_MAX_PUBLIC_KEY_SIZE
+#endif
+#if defined(MBEDTLS_ECP_C) && \
+    PSA_VENDOR_ECC_MAX_PUBLIC_KEY_SIZE > PSA_EXPORT_PUBLIC_KEY_MAX_SIZE
+#undef PSA_EXPORT_PUBLIC_KEY_MAX_SIZE
+#define PSA_EXPORT_PUBLIC_KEY_MAX_SIZE PSA_VENDOR_ECC_MAX_PUBLIC_KEY_SIZE
+#endif
+
+/** Sufficient output buffer size for psa_export_key() on a key pair.
+ */
+#define PSA_EXPORT_KEY_PAIR_MAX_SIZE 0
+#if (defined(MBEDTLS_RSA_C) || defined(MBEDTLS_PK_RSA_ALT_SUPPORT)) && \
+    PSA_VENDOR_RSA_MAX_KEY_PAIR_SIZE > PSA_EXPORT_KEY_PAIR_MAX_SIZE
+#undef PSA_EXPORT_KEY_PAIR_MAX_SIZE
+#define PSA_EXPORT_KEY_PAIR_MAX_SIZE PSA_VENDOR_RSA_MAX_KEY_PAIR_SIZE
+#endif
+#if defined(MBEDTLS_ECP_C) && \
+    PSA_VENDOR_ECC_MAX_KEY_PAIR_SIZE > PSA_EXPORT_KEY_PAIR_MAX_SIZE
+#undef PSA_EXPORT_KEY_PAIR_MAX_SIZE
+#define PSA_EXPORT_KEY_PAIR_MAX_SIZE PSA_VENDOR_ECC_MAX_KEY_PAIR_SIZE
+#endif
+
 #endif /* PSA_CRYPTO_SIZES_H */

include/psa/crypto_types.h

@@ -108,18 +108,117 @@ typedef uint32_t psa_algorithm_t;
  * The lifetime of a key indicates where it is stored and what system actions
  * may create and destroy it.
  *
- * Keys with the lifetime #PSA_KEY_LIFETIME_VOLATILE are automatically
- * destroyed when the application terminates or on a power reset.
+ * Lifetime values have the following structure:
+ * - Bits 0-7 (#PSA_KEY_LIFETIME_GET_PERSISTENCE(\c lifetime)):
+ *   persistence level. This value indicates what device management
+ *   actions can cause it to be destroyed. In particular, it indicates
+ *   whether the key is _volatile_ or _persistent_.
+ *   See ::psa_key_persistence_t for more information.
+ * - Bits 8-31 (#PSA_KEY_LIFETIME_GET_LOCATION(\c lifetime)):
+ *   location indicator. This value indicates where the key is stored
+ *   and where operations on the key are performed.
+ *   See ::psa_key_location_t for more information.
+ *
+ * Volatile keys are automatically destroyed when the application instance
+ * terminates or on a power reset of the device. Persistent keys are
+ * preserved until the application explicitly destroys them or until an
+ * implementation-specific device management event occurs (for example,
+ * a factory reset).
  *
- * Keys with a lifetime other than #PSA_KEY_LIFETIME_VOLATILE are said
- * to be _persistent_.
- * Persistent keys are preserved if the application or the system restarts.
  * Persistent keys have a key identifier of type #psa_key_id_t.
+ * This identifier remains valid throughout the lifetime of the key,
+ * even if the application instance that created the key terminates.
  * The application can call psa_open_key() to open a persistent key that
  * it created previously.
+ *
+ * This specification defines two basic lifetime values:
+ * - Keys with the lifetime #PSA_KEY_LIFETIME_VOLATILE are volatile.
+ *   All implementations should support this lifetime.
+ * - Keys with the lifetime #PSA_KEY_LIFETIME_PERSISTENT are persistent.
+ *   All implementations that have access to persistent storage with
+ *   appropriate security guarantees should support this lifetime.
  */
 typedef uint32_t psa_key_lifetime_t;
 
+/** Encoding of key persistence levels.
+ *
+ * What distinguishes different persistence levels is what device management
+ * events may cause keys to be destroyed. _Volatile_ keys are destroyed
+ * by a power reset. Persistent keys may be destroyed by events such as
+ * a transfer of ownership or a factory reset. What management events
+ * actually affect persistent keys at different levels is outside the
+ * scope of the PSA Cryptography specification.
+ *
+ * This specification defines the following values of persistence levels:
+ * - \c 0 = #PSA_KEY_PERSISTENCE_VOLATILE: volatile key.
+ *   A volatile key is automatically destroyed by the implementation when
+ *   the application instance terminates. In particular, a volatile key
+ *   is automatically destroyed on a power reset of the device.
+ * - \c 1 = #PSA_KEY_PERSISTENCE_DEFAULT:
+ *   persistent key with a default lifetime.
+ *   Implementations should support this value if they support persistent
+ *   keys at all.
+ *   Applications should use this value if they have no specific needs that
+ *   are only met by implementation-specific features.
+ * - \c 2-127: persistent key with a PSA-specified lifetime.
+ *   The PSA Cryptography specification does not define the meaning of these
+ *   values, but other PSA specifications may do so.
+ * - \c 128-254: persistent key with a vendor-specified lifetime.
+ *   No PSA specification will define the meaning of these values, so
+ *   implementations may choose the meaning freely.
+ *   As a guideline, higher persistence levels should cause a key to survive
+ *   more management events than lower levels.
+ * - \c 255 = #PSA_KEY_PERSISTENCE_READ_ONLY:
+ *   read-only or write-once key.
+ *   A key with this persistence level cannot be destroyed.
+ *   Implementations that support such keys may either allow their creation
+ *   through the PSA Cryptography API, preferably only to applications with
+ *   the appropriate privilege, or only expose keys created through
+ *   implementation-specific means such as a factory ROM engraving process.
+ *   Note that keys that are read-only due to policy restrictions
+ *   rather than due to physical limitations should not have this
+ *   persistence levels.
+ *
+ * \note Key persistence levels are 8-bit values. Key management
+ *       interfaces operate on lifetimes (type ::psa_key_lifetime_t) which
+ *       encode the persistence as the lower 8 bits of a 32-bit value.
+ */
+typedef uint8_t psa_key_persistence_t;
+
+/** Encoding of key location indicators.
+ *
+ * If an implementation of this API can make calls to external
+ * cryptoprocessors such as secure elements, the location of a key
+ * indicates which secure element performs the operations on the key.
+ * If an implementation offers multiple physical locations for persistent
+ * storage, the location indicator reflects at which physical location
+ * the key is stored.
+ *
+ * This specification defines the following values of location indicators:
+ * - \c 0: primary local storage.
+ *   All implementations should support this value.
+ *   The primary local storage is typically the same storage area that
+ *   contains the key metadata.
+ * - \c 1: primary secure element.
+ *   Implementations should support this value if there is a secure element
+ *   attached to the operating environment.
+ *   As a guideline, secure elements may provide higher resistance against
+ *   side channel and physical attacks than the primary local storage, but may
+ *   have restrictions on supported key types, sizes, policies and operations
+ *   and may have different performance characteristics.
+ * - \c 2-0x7fffff: other locations defined by a PSA specification.
+ *   The PSA Cryptography does not currently assign any meaning to these
+ *   locations, but future versions of this specification or other PSA
+ *   specifications may do so.
+ * - \c 0x800000-0xffffff: vendor-defined locations.
+ *   No PSA specification will assign a meaning to locations in this range.
+ *
+ * \note Key location indicators are 24-bit values. Key management
+ *       interfaces operate on lifetimes (type ::psa_key_lifetime_t) which
+ *       encode the location as the upper 24 bits of a 32-bit value.
+ */
+typedef uint32_t psa_key_location_t;
+
 /** Encoding of identifiers of persistent keys.
  *
  * - Applications may freely choose key identifiers in the range

include/psa/crypto_values.h

@@ -1539,12 +1539,20 @@
  * @{
  */
 
-/** A volatile key only exists as long as the handle to it is not closed.
+/** The default lifetime for volatile keys.
+ *
+ * A volatile key only exists as long as the handle to it is not closed.
  * The key material is guaranteed to be erased on a power reset.
+ *
+ * A key with this lifetime is typically stored in the RAM area of the
+ * PSA Crypto subsystem. However this is an implementation choice.
+ * If an implementation stores data about the key in a non-volatile memory,
+ * it must release all the resources associated with the key and erase the
+ * key material if the calling application terminates.
  */
 #define PSA_KEY_LIFETIME_VOLATILE               ((psa_key_lifetime_t)0x00000000)
 
-/** The default storage area for persistent keys.
+/** The default lifetime for persistent keys.
  *
  * A persistent key remains in storage until it is explicitly destroyed or
  * until the corresponding storage area is wiped. This specification does
@@ -1555,9 +1563,77 @@
  * This lifetime value is the default storage area for the calling
  * application. Implementations may offer other storage areas designated
  * by other lifetime values as implementation-specific extensions.
+ * See ::psa_key_lifetime_t for more information.
  */
 #define PSA_KEY_LIFETIME_PERSISTENT             ((psa_key_lifetime_t)0x00000001)
 
+/** The persistence level of volatile keys.
+ *
+ * See ::psa_key_persistence_t for more information.
+ */
+#define PSA_KEY_PERSISTENCE_VOLATILE            ((psa_key_persistence_t)0x00)
+
+/** The default persistence level for persistent keys.
+ *
+ * See ::psa_key_persistence_t for more information.
+ */
+#define PSA_KEY_PERSISTENCE_DEFAULT             ((psa_key_persistence_t)0x01)
+
+/** A persistence level indicating that a key is never destroyed.
+ *
+ * See ::psa_key_persistence_t for more information.
+ */
+#define PSA_KEY_PERSISTENCE_READ_ONLY           ((psa_key_persistence_t)0xff)
+
+#define PSA_KEY_LIFETIME_GET_PERSISTENCE(lifetime)      \
+    ((psa_key_persistence_t)((lifetime) & 0x000000ff))
+
+#define PSA_KEY_LIFETIME_GET_LOCATION(lifetime)      \
+    ((psa_key_location_t)((lifetime) >> 8))
+
+/** Whether a key lifetime indicates that the key is volatile.
+ *
+ * A volatile key is automatically destroyed by the implementation when
+ * the application instance terminates. In particular, a volatile key
+ * is automatically destroyed on a power reset of the device.
+ *
+ * A key that is not volatile is persistent. Persistent keys are
+ * preserved until the application explicitly destroys them or until an
+ * implementation-specific device management event occurs (for example,
+ * a factory reset).
+ *
+ * \param lifetime      The lifetime value to query (value of type
+ *                      ::psa_key_lifetime_t).
+ *
+ * \return \c 1 if the key is volatile, otherwise \c 0.
+ */
+#define PSA_KEY_LIFETIME_IS_VOLATILE(lifetime)  \
+    (PSA_KEY_LIFETIME_GET_PERSISTENCE(lifetime) == \
+     PSA_KEY_LIFETIME_PERSISTENCE_VOLATILE)
+
+/** Construct a lifetime from a persistence level and a location.
+ *
+ * \param persistence   The persistence level
+ *                      (value of type ::psa_key_persistence_t).
+ * \param location      The location indicator
+ *                      (value of type ::psa_key_location_t).
+ *
+ * \return The constructed lifetime value.
+ */
+#define PSA_KEY_LIFETIME_FROM_PERSISTENCE_AND_LOCATION(persistence, location) \
+    ((location) << 8 | (persistence))
+
+/** The local storage area for persistent keys.
+ *
+ * This storage area is available on all systems that can store persistent
+ * keys without delegating the storage to a third-party cryptoprocessor.
+ *
+ * See ::psa_key_location_t for more information.
+ */
+#define PSA_KEY_LOCATION_LOCAL_STORAGE          ((psa_key_location_t)0x000000)
+
+#define PSA_KEY_LOCATION_VENDOR_FLAG            ((psa_key_location_t)0x800000)
+
 /** The minimum value for a key identifier chosen by the application.
  */
 #define PSA_KEY_ID_USER_MIN                     ((psa_app_key_id_t)0x00000001)

library/.gitignore

@@ -2,3 +2,4 @@
 libmbed*
 *.sln
 *.vcxproj
+/psa_crypto_driver_wrappers.c