Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

PSA key identifiers rework #3527

Merged
merged 17 commits into from
Sep 15, 2020
Merged

PSA key identifiers rework #3527

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
17 commits
Select commit Hold shift + click to select a range
80b9510
psa: Move psa_key_file_id_t definition to crypto_types.h
ronald-cron-arm Aug 28, 2020
27238fc
psa: Use psa_key_file_id_t as the key id type
ronald-cron-arm Jul 23, 2020
039a98b
Define always psa_key_id_t as defined in PSA crypto spec
ronald-cron-arm Jul 23, 2020
fa7d7af
psa: Don't reset the key owner id in psa_set_key_lifetime
ronald-cron-arm Jul 24, 2020
72f65fc
psa: Rename pss_key_owner_id_t to mbedtls_key_owner_id_t
ronald-cron-arm Sep 1, 2020
71016a9
psa: Rename psa_key_file_id_t to mbedtls_svc_key_id_t
ronald-cron-arm Aug 28, 2020
2647b68
Set MBEDTLS_PSA_CRYPTO_KEY_ID_ENCODES_OWNER in full configuration
ronald-cron-arm Jul 29, 2020
ecfb237
Fix PSA code and unit tests
ronald-cron-arm Jul 23, 2020
978d57d
tests: psa: Fix storage purge in se_driver_hal tests (1)
ronald-cron-arm Aug 26, 2020
5731f6f
tests: psa: Fix storage purge in se_driver_hal tests (2)
ronald-cron-arm Aug 26, 2020
81e0050
tests: psa: Add owner identifier as test parameter
ronald-cron-arm Jul 28, 2020
f1c9a55
tests: psa: Add checks involving unknown key owner ids
ronald-cron-arm Jul 29, 2020
79ca427
psa: storage: Use key id macros to compute ITS file identifier
ronald-cron-arm Aug 25, 2020
5eba579
Remove unnecessary inline definition
ronald-cron-arm Sep 15, 2020
9a2511e
Fix key owner identifier documentation
ronald-cron-arm Sep 14, 2020
cb54610
Set MBEDTLS_PSA_CRYPTO_KEY_ID_ENCODES_OWNER in baremetal configuration
ronald-cron-arm Sep 14, 2020
7424f0d
psa: Move key identifier related macros and functions
ronald-cron-arm Sep 14, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 6 additions & 6 deletions configs/config-psa-crypto.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1144,20 +1144,20 @@
*/
//#define MBEDTLS_ENTROPY_NV_SEED

/* MBEDTLS_PSA_CRYPTO_KEY_FILE_ID_ENCODES_OWNER
/* MBEDTLS_PSA_CRYPTO_KEY_ID_ENCODES_OWNER
*
* In PSA key storage, encode the owner of the key.
* Enable key identifiers that encode a key owner identifier.
*
* This is only meaningful when building the library as part of a
* multi-client service. When you activate this option, you must provide
* an implementation of the type psa_key_owner_id_t and a translation
* from psa_key_file_id_t to file name in all the storage backends that
* multi-client service. When you activate this option, you must provide an
* implementation of the type mbedtls_key_owner_id_t and a translation from
* mbedtls_svc_key_id_t to file name in all the storage backends that you
* you wish to support.
*
* Note that this option is meant for internal use only and may be removed
* without notice.
*/
//#define MBEDTLS_PSA_CRYPTO_KEY_FILE_ID_ENCODES_OWNER
//#define MBEDTLS_PSA_CRYPTO_KEY_ID_ENCODES_OWNER

/**
* \def MBEDTLS_MEMORY_DEBUG
Expand Down
10 changes: 4 additions & 6 deletions docs/architecture/mbed-crypto-storage-specification.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -107,14 +107,12 @@ Backward compatibility commitments: TBD

### Key names for 1.0.0

Information about each key is stored in a dedicated file designated by a _key file identifier_ (`psa_key_file_id_t`). The key file identifier is constructed from the 32-bit key identifier (`psa_key_id_t`) and, if applicable, an identifier of the owner of the key. In integrations where there is no concept of key owner (in particular, in library integrations), the key file identifier is exactly the key identifier. When the library is integrated into a service, the service determines the semantics of the owner identifier.
Information about each key is stored in a dedicated file designated by the key identifier. In integrations where there is no concept of key owner (in particular, in library integrations), the key identifier is exactly the key identifier as defined in the PSA Cryptography API specification (`psa_key_id_t`). In integrations where there is a concept of key owner (integration into a service for example), the key identifier is made of an owner identifier (its semantics and type are integration specific) and of the key identifier (`psa_key_id_t`) from the key owner point of view.

The way in which the file name is constructed from the key file identifier depends on the storage backend. The content of the file is described [below](#key-file-format-for-1.0.0).
The way in which the file name is constructed from the key identifier depends on the storage backend. The content of the file is described [below](#key-file-format-for-1.0.0).

The valid values for a key identifier are the range from 1 to 0xfffeffff. This limitation on the range is not documented in user-facing documentation: according to the user-facing documentation, arbitrary 32-bit values are valid.

* Library integration: the key file name is just the key identifer. This is a 32-bit value.
* PSA service integration: the key file identifier is `(uint32_t)owner_uid << 32 | key_id` where `key_id` is the key identifier specified by the application and `owner_uid` (of type `int32_t`) is the calling partition identifier provided to the server by the partition manager. This is a 64-bit value.
* Library integration: the key file name is just the key identifier as defined in the PSA crypto specification. This is a 32-bit value.
* PSA service integration: the key file name is `(uint32_t)owner_uid << 32 | key_id` where `key_id` is the key identifier from the owner point of view and `owner_uid` (of type `int32_t`) is the calling partition identifier provided to the server by the partition manager. This is a 64-bit value.

### Key file format for 1.0.0

Expand Down
13 changes: 5 additions & 8 deletions include/mbedtls/config.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1258,20 +1258,17 @@
*/
//#define MBEDTLS_ENTROPY_NV_SEED

/* MBEDTLS_PSA_CRYPTO_KEY_FILE_ID_ENCODES_OWNER
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

TF-M uses MBEDTLS_PSA_CRYPTO_KEY_FILE_ID_ENCODES_OWNER, so if we remove it or change its semantics, we need to provide a transition path or work this out with the TF-M development team. Sure, we did say that this option was meant for internal use only, but this is another TF project, which is close to internal use, and it's the heir of the project that the option was meant for (Mbed OS PSA).

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

When the TF-M team updates to a new version of the present library it is easy for them to change such a define if necessary, changing it shouldn't be a problem for them.

/* MBEDTLS_PSA_CRYPTO_KEY_ID_ENCODES_OWNER
*
* In PSA key storage, encode the owner of the key.
* Enable key identifiers that encode a key owner identifier.
*
* This is only meaningful when building the library as part of a
* multi-client service. When you activate this option, you must provide
* an implementation of the type psa_key_owner_id_t and a translation
* from psa_key_file_id_t to file name in all the storage backends that
* you wish to support.
* The owner of a key is identified by a value of type ::mbedtls_key_owner_id_t
* which is currently hard-coded to be int32_t.
*
* Note that this option is meant for internal use only and may be removed
* without notice.
*/
//#define MBEDTLS_PSA_CRYPTO_KEY_FILE_ID_ENCODES_OWNER
//#define MBEDTLS_PSA_CRYPTO_KEY_ID_ENCODES_OWNER

/**
* \def MBEDTLS_MEMORY_DEBUG
Expand Down
23 changes: 12 additions & 11 deletions include/psa/crypto.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -146,11 +146,11 @@ static psa_key_attributes_t psa_key_attributes_init(void);
* linkage). This function may be provided as a function-like macro,
* but in this case it must evaluate each of its arguments exactly once.
*
* \param[out] attributes The attribute structure to write to.
* \param id The persistent identifier for the key.
* \param[out] attributes The attribute structure to write to.
* \param key The persistent identifier for the key.
*/
static void psa_set_key_id(psa_key_attributes_t *attributes,
psa_key_id_t id);
static void psa_set_key_id( psa_key_attributes_t *attributes,
mbedtls_svc_key_id_t key );

/** Set the location of a persistent key.
*
Expand Down Expand Up @@ -192,7 +192,8 @@ static void psa_set_key_lifetime(psa_key_attributes_t *attributes,
* This value is unspecified if the attribute structure declares
* the key as volatile.
*/
static psa_key_id_t psa_get_key_id(const psa_key_attributes_t *attributes);
static mbedtls_svc_key_id_t psa_get_key_id(
const psa_key_attributes_t *attributes);

/** Retrieve the lifetime from key attributes.
*
Expand Down Expand Up @@ -392,8 +393,9 @@ void psa_reset_key_attributes(psa_key_attributes_t *attributes);
* with a lifetime other than #PSA_KEY_LIFETIME_VOLATILE. A persistent key
* always has a nonzero key identifier, set with psa_set_key_id() when
* creating the key. Implementations may provide additional pre-provisioned
* keys that can be opened with psa_open_key(). Such keys have a key identifier
* in the vendor range, as documented in the description of #psa_key_id_t.
* keys that can be opened with psa_open_key(). Such keys have an application
* key identifier in the vendor range, as documented in the description of
* #psa_key_id_t.
*
* The application must eventually close the handle with psa_close_key() or
* psa_destroy_key() to release associated resources. If the application dies
Expand All @@ -408,7 +410,7 @@ void psa_reset_key_attributes(psa_key_attributes_t *attributes);
* portable to implementations that only permit a single key handle to be
* opened. See also :ref:\`key-handles\`.
*
* \param id The persistent identifier of the key.
* \param key The persistent identifier of the key.
* \param[out] handle On success, a handle to the key.
*
* \retval #PSA_SUCCESS
Expand Down Expand Up @@ -436,9 +438,8 @@ void psa_reset_key_attributes(psa_key_attributes_t *attributes);
* It is implementation-dependent whether a failure to initialize
* results in this error code.
*/
psa_status_t psa_open_key(psa_key_id_t id,
psa_key_handle_t *handle);

psa_status_t psa_open_key( mbedtls_svc_key_id_t key,
psa_key_handle_t *handle );

/** Close a key handle.
*
Expand Down
4 changes: 2 additions & 2 deletions include/psa/crypto_extra.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -232,9 +232,9 @@ typedef struct mbedtls_psa_stats_s
/** Number of slots that are not used for anything. */
size_t empty_slots;
/** Largest key id value among open keys in internal persistent storage. */
psa_app_key_id_t max_open_internal_key_id;
psa_key_id_t max_open_internal_key_id;
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Minor: the commit message “Define always psa_key_id_t as defined in PSA crypto spec” should be “Always define …”. Not worth rebasing for just that. Please don't change it unless you need to rebase for some other reason anyway.

/** Largest key id value among open keys in secure elements. */
psa_app_key_id_t max_open_external_key_id;
psa_key_id_t max_open_external_key_id;
} mbedtls_psa_stats_t;

/** \brief Get statistics about
Expand Down
71 changes: 27 additions & 44 deletions include/psa/crypto_platform.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -44,57 +44,40 @@
/* PSA requires several types which C99 provides in stdint.h. */
#include <stdint.h>

#if ( defined(__ARMCC_VERSION) || defined(_MSC_VER) ) && \
!defined(inline) && !defined(__cplusplus)
#define inline __inline
#endif

gilles-peskine-arm marked this conversation as resolved.
Show resolved Hide resolved
/* Integral type representing a key handle. */
typedef uint16_t psa_key_handle_t;

/* This implementation distinguishes *application key identifiers*, which
* are the key identifiers specified by the application, from
* *key file identifiers*, which are the key identifiers that the library
* sees internally. The two types can be different if there is a remote
* call layer between the application and the library which supports
* multiple client applications that do not have access to each others'
* keys. The point of having different types is that the key file
* identifier may encode not only the key identifier specified by the
* application, but also the the identity of the application.
#if defined(MBEDTLS_PSA_CRYPTO_KEY_ID_ENCODES_OWNER)

/* Building for the PSA Crypto service on a PSA platform, a key owner is a PSA
* partition identifier.
*
* Note that this is an internal concept of the library and the remote
* call layer. The application itself never sees anything other than
* #psa_app_key_id_t with its standard definition.
* The function psa_its_identifier_of_slot() in psa_crypto_storage.c that
* translates a key identifier to a key storage file name assumes that
* mbedtls_key_owner_id_t is an 32 bits integer. This function thus needs
* reworking if mbedtls_key_owner_id_t is not defined as a 32 bits integer
* here anymore.
*/
typedef int32_t mbedtls_key_owner_id_t;

/* The application key identifier is always what the application sees as
* #psa_key_id_t. */
typedef uint32_t psa_app_key_id_t;

#if defined(MBEDTLS_PSA_CRYPTO_KEY_FILE_ID_ENCODES_OWNER)

#if defined(PSA_CRYPTO_SECURE)
/* Building for the PSA Crypto service on a PSA platform. */
/* A key owner is a PSA partition identifier. */
typedef int32_t psa_key_owner_id_t;
#endif

typedef struct
/** Compare two key owner identifiers.
*
* \param id1 First key owner identifier.
* \param id2 Second key owner identifier.
*
* \return Non-zero if the two key owner identifiers are equal, zero otherwise.
*/
static inline int mbedtls_key_owner_id_equal( mbedtls_key_owner_id_t id1,
mbedtls_key_owner_id_t id2 )
{
uint32_t key_id;
psa_key_owner_id_t owner;
} psa_key_file_id_t;
#define PSA_KEY_FILE_GET_KEY_ID( file_id ) ( ( file_id ).key_id )

/* Since crypto.h is used as part of the PSA Cryptography API specification,
* it must use standard types for things like the argument of psa_open_key().
* If it wasn't for that constraint, psa_open_key() would take a
* `psa_key_file_id_t` argument. As a workaround, make `psa_key_id_t` an
* alias for `psa_key_file_id_t` when building for a multi-client service. */
typedef psa_key_file_id_t psa_key_id_t;
#define PSA_KEY_ID_INIT {0, 0}

#else /* !MBEDTLS_PSA_CRYPTO_KEY_FILE_ID_ENCODES_OWNER */

/* By default, a key file identifier is just the application key identifier. */
typedef psa_app_key_id_t psa_key_file_id_t;
#define PSA_KEY_FILE_GET_KEY_ID( id ) ( id )
return( id1 == id2 );
}

#endif /* !MBEDTLS_PSA_CRYPTO_KEY_FILE_ID_ENCODES_OWNER */
#endif /* MBEDTLS_PSA_CRYPTO_KEY_ID_ENCODES_OWNER */

#endif /* PSA_CRYPTO_PLATFORM_H */
15 changes: 7 additions & 8 deletions include/psa/crypto_struct.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -330,12 +330,12 @@ typedef struct
psa_key_type_t type;
psa_key_bits_t bits;
psa_key_lifetime_t lifetime;
psa_key_id_t id;
mbedtls_svc_key_id_t id;
psa_key_policy_t policy;
psa_key_attributes_flag_t flags;
} psa_core_key_attributes_t;

#define PSA_CORE_KEY_ATTRIBUTES_INIT {PSA_KEY_TYPE_NONE, 0, PSA_KEY_LIFETIME_VOLATILE, PSA_KEY_ID_INIT, PSA_KEY_POLICY_INIT, 0}
#define PSA_CORE_KEY_ATTRIBUTES_INIT {PSA_KEY_TYPE_NONE, 0, PSA_KEY_LIFETIME_VOLATILE, MBEDTLS_SVC_KEY_ID_INIT, PSA_KEY_POLICY_INIT, 0}

struct psa_key_attributes_s
{
Expand All @@ -359,15 +359,15 @@ static inline struct psa_key_attributes_s psa_key_attributes_init( void )
return( v );
}

static inline void psa_set_key_id(psa_key_attributes_t *attributes,
psa_key_id_t id)
static inline void psa_set_key_id( psa_key_attributes_t *attributes,
mbedtls_svc_key_id_t key )
{
attributes->core.id = id;
attributes->core.id = key;
if( attributes->core.lifetime == PSA_KEY_LIFETIME_VOLATILE )
attributes->core.lifetime = PSA_KEY_LIFETIME_PERSISTENT;
}

static inline psa_key_id_t psa_get_key_id(
static inline mbedtls_svc_key_id_t psa_get_key_id(
const psa_key_attributes_t *attributes)
{
return( attributes->core.id );
Expand All @@ -379,9 +379,8 @@ static inline void psa_set_key_lifetime(psa_key_attributes_t *attributes,
attributes->core.lifetime = lifetime;
if( lifetime == PSA_KEY_LIFETIME_VOLATILE )
{
#ifdef MBEDTLS_PSA_CRYPTO_KEY_FILE_ID_ENCODES_OWNER
#ifdef MBEDTLS_PSA_CRYPTO_KEY_ID_ENCODES_OWNER
attributes->core.id.key_id = 0;
attributes->core.id.owner = 0;
#else
attributes->core.id = 0;
#endif
Expand Down
29 changes: 20 additions & 9 deletions include/psa/crypto_types.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,8 @@
#ifndef PSA_CRYPTO_TYPES_H
#define PSA_CRYPTO_TYPES_H

#include "crypto_platform.h"

#include <stdint.h>

/** \defgroup error Error codes
Expand Down Expand Up @@ -123,7 +125,7 @@ typedef uint32_t psa_algorithm_t;
* implementation-specific device management event occurs (for example,
* a factory reset).
*
* Persistent keys have a key identifier of type #psa_key_id_t.
* Persistent keys have a key identifier of type #mbedtls_svc_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
Expand Down Expand Up @@ -226,15 +228,24 @@ typedef uint32_t psa_key_location_t;
* - 0 is reserved as an invalid key identifier.
* - Key identifiers outside these ranges are reserved for future use.
*/
/* Implementation-specific quirk: The Mbed Crypto library can be built as
* part of a multi-client service that exposes the PSA Crypto API in each
* client and encodes the client identity in the key id argument of functions
* such as psa_open_key(). In this build configuration, we define
* psa_key_id_t in crypto_platform.h instead of here. */
#if !defined(MBEDTLS_PSA_CRYPTO_KEY_FILE_ID_ENCODES_OWNER)
typedef uint32_t psa_key_id_t;
#define PSA_KEY_ID_INIT 0
#endif

#if !defined(MBEDTLS_PSA_CRYPTO_KEY_ID_ENCODES_OWNER)
typedef psa_key_id_t mbedtls_svc_key_id_t;

#else /* MBEDTLS_PSA_CRYPTO_KEY_ID_ENCODES_OWNER */
/* Implementation-specific: The Mbed Cryptography library can be built as
* part of a multi-client service that exposes the PSA Cryptograpy API in each
* client and encodes the client identity in the key identifier argument of
* functions such as psa_open_key().
*/
typedef struct
{
psa_key_id_t key_id;
mbedtls_key_owner_id_t owner;
} mbedtls_svc_key_id_t;

#endif /* !MBEDTLS_PSA_CRYPTO_KEY_ID_ENCODES_OWNER */

/**@}*/

Expand Down
Loading