From 1139249bfaa82636bb1cbeab23a5abb1dffc11da Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Mon, 27 May 2019 14:53:19 +0200 Subject: [PATCH] Don't refer to PSA keys as slots anymore The PSA documentation no longer uses the word "slot", so using it in the Mbed Crypto documentation would be misleading. --- include/mbedtls/cipher_internal.h | 13 ++++++------- include/mbedtls/pk.h | 29 +++++++++++++++-------------- 2 files changed, 21 insertions(+), 21 deletions(-) diff --git a/include/mbedtls/cipher_internal.h b/include/mbedtls/cipher_internal.h index d711339004..8ea2a98829 100644 --- a/include/mbedtls/cipher_internal.h +++ b/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 diff --git a/include/mbedtls/pk.h b/include/mbedtls/pk.h index 24951a6e1f..0e24b1a5e3 100644 --- a/include/mbedtls/pk.h +++ b/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,21 +259,21 @@ 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). @@ -281,7 +281,7 @@ int mbedtls_pk_setup( mbedtls_pk_context *ctx, const mbedtls_pk_info_t *info ); * * \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,7 +788,7 @@ 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. @@ -796,18 +796,19 @@ int mbedtls_pk_load_file( const char *path, unsigned char **buf, size_t *n ); * \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 */