Merge pull request #325 from gilles-peskine-arm/psa-sign_hash

Rename psa_asymmetric_{sign_verify} to psa_{sign,verify}_hash

Author: gilles-peskine-arm

docs/getting_started.md

@@ -119,8 +119,8 @@ Mbed Crypto supports encrypting, decrypting, signing and verifying messages usin
 **Prerequisites to performing asymmetric signature operations:**
 * Initialize the library with a successful call to `psa_crypto_init()`.
 * Have a valid key with appropriate attributes set:
-    * Usage flag `PSA_KEY_USAGE_SIGN` to allow signing.
-    * Usage flag `PSA_KEY_USAGE_VERIFY` to allow signature verification.
+    * Usage flag `PSA_KEY_USAGE_SIGN_HASH` to allow signing.
+    * Usage flag `PSA_KEY_USAGE_VERIFY_HASH` to allow signature verification.
     * Algorithm set to the desired signature algorithm.
 
 This example shows how to sign a hash that has already been calculated:
@@ -133,7 +133,7 @@ void sign_a_message_using_rsa(const uint8_t *key, size_t key_len)
                         0x60, 0x41, 0x8a, 0xaf, 0x0c, 0xc5, 0xab, 0x58,
                         0x7f, 0x42, 0xc2, 0x57, 0x0a, 0x88, 0x40, 0x95,
                         0xa9, 0xe8, 0xcc, 0xac, 0xd0, 0xf6, 0x54, 0x5c};
-    uint8_t signature[PSA_ASYMMETRIC_SIGNATURE_MAX_SIZE] = {0};
+    uint8_t signature[PSA_SIGNATURE_MAX_SIZE] = {0};
     size_t signature_length;
     psa_key_handle_t handle;
 
@@ -148,7 +148,7 @@ void sign_a_message_using_rsa(const uint8_t *key, size_t key_len)
     }
 
     /* Set key attributes */
-    psa_set_key_usage_flags(&attributes, PSA_KEY_USAGE_SIGN);
+    psa_set_key_usage_flags(&attributes, PSA_KEY_USAGE_SIGN_HASH);
     psa_set_key_algorithm(&attributes, PSA_ALG_RSA_PKCS1V15_SIGN_RAW);
     psa_set_key_type(&attributes, PSA_KEY_TYPE_RSA_KEY_PAIR);
     psa_set_key_bits(&attributes, 1024);
@@ -161,10 +161,10 @@ void sign_a_message_using_rsa(const uint8_t *key, size_t key_len)
     }
 
     /* Sign message using the key */
-    status = psa_asymmetric_sign(handle, PSA_ALG_RSA_PKCS1V15_SIGN_RAW,
-                                 hash, sizeof(hash),
-                                 signature, sizeof(signature),
-                                 &signature_length);
+    status = psa_sign_hash(handle, PSA_ALG_RSA_PKCS1V15_SIGN_RAW,
+                           hash, sizeof(hash),
+                           signature, sizeof(signature),
+                           &signature_length);
     if (status != PSA_SUCCESS) {
         printf("Failed to sign\n");
         return;
@@ -861,7 +861,7 @@ Mbed Crypto provides a simple way to generate a key or key pair.
     }
 
     /* Generate a key */
-    psa_set_key_usage_flags(&attributes, PSA_KEY_USAGE_SIGN);
+    psa_set_key_usage_flags(&attributes, PSA_KEY_USAGE_SIGN_HASH);
     psa_set_key_algorithm(&attributes,
                           PSA_ALG_DETERMINISTIC_ECDSA(PSA_ALG_SHA_256));
     psa_set_key_type(&attributes,

include/mbedtls/pk.h

@@ -134,11 +134,11 @@ typedef struct mbedtls_pk_rsassa_pss_options
 #endif
 
 #if defined(MBEDTLS_USE_PSA_CRYPTO)
-#if PSA_ASYMMETRIC_SIGNATURE_MAX_SIZE > MBEDTLS_PK_SIGNATURE_MAX_SIZE
-/* PSA_ASYMMETRIC_SIGNATURE_MAX_SIZE is the maximum size of a signature made
+#if PSA_SIGNATURE_MAX_SIZE > MBEDTLS_PK_SIGNATURE_MAX_SIZE
+/* PSA_SIGNATURE_MAX_SIZE is the maximum size of a signature made
  * through the PSA API in the PSA representation. */
 #undef MBEDTLS_PK_SIGNATURE_MAX_SIZE
-#define MBEDTLS_PK_SIGNATURE_MAX_SIZE PSA_ASYMMETRIC_SIGNATURE_MAX_SIZE
+#define MBEDTLS_PK_SIGNATURE_MAX_SIZE PSA_SIGNATURE_MAX_SIZE
 #endif
 
 #if PSA_VENDOR_ECDSA_SIGNATURE_MAX_SIZE + 11 > MBEDTLS_PK_SIGNATURE_MAX_SIZE

include/psa/crypto.h

@@ -2879,7 +2879,7 @@ psa_status_t psa_aead_abort(psa_aead_operation_t *operation);
  * \retval #PSA_ERROR_BUFFER_TOO_SMALL
  *         The size of the \p signature buffer is too small. You can
  *         determine a sufficient buffer size by calling
- *         #PSA_ASYMMETRIC_SIGN_OUTPUT_SIZE(\c key_type, \c key_bits, \p alg)
+ *         #PSA_SIGN_OUTPUT_SIZE(\c key_type, \c key_bits, \p alg)
  *         where \c key_type and \c key_bits are the type and bit-size
  *         respectively of \p handle.
  * \retval #PSA_ERROR_NOT_SUPPORTED
@@ -2895,13 +2895,13 @@ psa_status_t psa_aead_abort(psa_aead_operation_t *operation);
  *         It is implementation-dependent whether a failure to initialize
  *         results in this error code.
  */
-psa_status_t psa_asymmetric_sign(psa_key_handle_t handle,
-                                 psa_algorithm_t alg,
-                                 const uint8_t *hash,
-                                 size_t hash_length,
-                                 uint8_t *signature,
-                                 size_t signature_size,
-                                 size_t *signature_length);
+psa_status_t psa_sign_hash(psa_key_handle_t handle,
+                           psa_algorithm_t alg,
+                           const uint8_t *hash,
+                           size_t hash_length,
+                           uint8_t *signature,
+                           size_t signature_size,
+                           size_t *signature_length);
 
 /**
  * \brief Verify the signature a hash or short message using a public key.
@@ -2941,12 +2941,12 @@ psa_status_t psa_asymmetric_sign(psa_key_handle_t handle,
  *         It is implementation-dependent whether a failure to initialize
  *         results in this error code.
  */
-psa_status_t psa_asymmetric_verify(psa_key_handle_t handle,
-                                   psa_algorithm_t alg,
-                                   const uint8_t *hash,
-                                   size_t hash_length,
-                                   const uint8_t *signature,
-                                   size_t signature_length);
+psa_status_t psa_verify_hash(psa_key_handle_t handle,
+                             psa_algorithm_t alg,
+                             const uint8_t *hash,
+                             size_t hash_length,
+                             const uint8_t *signature,
+                             size_t signature_length);
 
 /**
  * \brief Encrypt a short message with a public key.

include/psa/crypto_compat.h

@@ -0,0 +1,109 @@
+/**
+ * \file psa/crypto_compat.h
+ *
+ * \brief PSA cryptography module: Backward compatibility aliases
+ *
+ * This header declares alternative names for macro and functions.
+ * New application code should not use these names.
+ * These names may be removed in a future version of Mbed Crypto.
+ *
+ * \note This file may not be included directly. Applications must
+ * include psa/crypto.h.
+ */
+/*
+ *  Copyright (C) 2019, 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.
+ *
+ *  This file is part of mbed TLS (https://tls.mbed.org)
+ */
+
+#ifndef PSA_CRYPTO_COMPAT_H
+#define PSA_CRYPTO_COMPAT_H
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#if !defined(MBEDTLS_DEPRECATED_REMOVED)
+
+/*
+ * Mechanism for declaring deprecated values
+ */
+#if defined(MBEDTLS_DEPRECATED_WARNING) && !defined(MBEDTLS_PSA_DEPRECATED)
+#define MBEDTLS_PSA_DEPRECATED __attribute__((deprecated))
+#else
+#define MBEDTLS_PSA_DEPRECATED
+#endif
+
+typedef MBEDTLS_PSA_DEPRECATED size_t mbedtls_deprecated_size_t;
+typedef MBEDTLS_PSA_DEPRECATED psa_status_t mbedtls_deprecated_psa_status_t;
+typedef MBEDTLS_PSA_DEPRECATED psa_key_usage_t mbedtls_deprecated_psa_key_usage_t;
+
+#define MBEDTLS_DEPRECATED_CONSTANT( type, value )      \
+    ( (mbedtls_deprecated_##type) ( value ) )
+
+/*
+ * Deprecated PSA Crypto error code definitions (PSA Crypto API  <= 1.0 beta2)
+ */
+#define PSA_ERROR_UNKNOWN_ERROR \
+    MBEDTLS_DEPRECATED_CONSTANT( psa_status_t, PSA_ERROR_GENERIC_ERROR )
+#define PSA_ERROR_OCCUPIED_SLOT \
+    MBEDTLS_DEPRECATED_CONSTANT( psa_status_t, PSA_ERROR_ALREADY_EXISTS )
+#define PSA_ERROR_EMPTY_SLOT \
+    MBEDTLS_DEPRECATED_CONSTANT( psa_status_t, PSA_ERROR_DOES_NOT_EXIST )
+#define PSA_ERROR_INSUFFICIENT_CAPACITY \
+    MBEDTLS_DEPRECATED_CONSTANT( psa_status_t, PSA_ERROR_INSUFFICIENT_DATA )
+#define PSA_ERROR_TAMPERING_DETECTED \
+    MBEDTLS_DEPRECATED_CONSTANT( psa_status_t, PSA_ERROR_CORRUPTION_DETECTED )
+
+/*
+ * Deprecated PSA Crypto numerical encodings (PSA Crypto API  <= 1.0 beta3)
+ */
+#define PSA_KEY_USAGE_SIGN \
+    MBEDTLS_DEPRECATED_CONSTANT( psa_key_usage_t, PSA_KEY_USAGE_SIGN_HASH )
+#define PSA_KEY_USAGE_VERIFY \
+    MBEDTLS_DEPRECATED_CONSTANT( psa_key_usage_t, PSA_KEY_USAGE_VERIFY_HASH )
+
+/*
+ * Deprecated PSA Crypto size calculation macros (PSA Crypto API  <= 1.0 beta3)
+ */
+#define PSA_ASYMMETRIC_SIGNATURE_MAX_SIZE \
+    MBEDTLS_DEPRECATED_CONSTANT( size_t, PSA_SIGNATURE_MAX_SIZE )
+#define PSA_ASYMMETRIC_SIGN_OUTPUT_SIZE( key_type, key_bits, alg ) \
+    MBEDTLS_DEPRECATED_CONSTANT( size_t, PSA_SIGN_OUTPUT_SIZE( key_type, key_bits, alg ) )
+
+/*
+ * Deprecated PSA Crypto function names (PSA Crypto API  <= 1.0 beta3)
+ */
+/* Make these macros and not wrappers so that there is no cost to
+ * applications that don't use the deprecated names.
+ *
+ * Put backslash-newline after "#define" to bypass check-names.sh which
+ * would otherwise complain about lowercase macro names.
+ */
+#define \
+    psa_asymmetric_sign( key, alg, hash, hash_length, signature, signature_size, signature_length ) \
+    ( (mbedtls_deprecated_psa_status_t) psa_sign_hash( key, alg, hash, hash_length, signature, signature_size, signature_length ) )
+#define \
+    psa_asymmetric_verify( key, alg, hash, hash_length, signature, signature_length ) \
+    ( (mbedtls_deprecated_psa_status_t) psa_verify_hash( key, alg, hash, hash_length, signature, signature_length ) )
+
+#endif /* MBEDTLS_DEPRECATED_REMOVED */
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* PSA_CRYPTO_COMPAT_H */

include/psa/crypto_extra.h

@@ -32,28 +32,15 @@
 
 #include "mbedtls/platform_util.h"
 
+#include "crypto_compat.h"
+
 #ifdef __cplusplus
 extern "C" {
 #endif
 
 /* UID for secure storage seed */
 #define PSA_CRYPTO_ITS_RANDOM_SEED_UID 0xFFFFFF52
 
-/*
- * Deprecated PSA Crypto error code definitions
- */
-#if !defined(MBEDTLS_DEPRECATED_REMOVED)
-#define PSA_ERROR_UNKNOWN_ERROR \
-    MBEDTLS_DEPRECATED_NUMERIC_CONSTANT( PSA_ERROR_GENERIC_ERROR )
-#define PSA_ERROR_OCCUPIED_SLOT \
-    MBEDTLS_DEPRECATED_NUMERIC_CONSTANT( PSA_ERROR_ALREADY_EXISTS )
-#define PSA_ERROR_EMPTY_SLOT \
-    MBEDTLS_DEPRECATED_NUMERIC_CONSTANT( PSA_ERROR_DOES_NOT_EXIST )
-#define PSA_ERROR_INSUFFICIENT_CAPACITY \
-    MBEDTLS_DEPRECATED_NUMERIC_CONSTANT( PSA_ERROR_INSUFFICIENT_DATA )
-#define PSA_ERROR_TAMPERING_DETECTED \
-    MBEDTLS_DEPRECATED_NUMERIC_CONSTANT( PSA_ERROR_CORRUPTION_DETECTED )
-#endif
 
 /** \addtogroup attributes
  * @{

include/psa/crypto_sizes.h

@@ -411,7 +411,7 @@
 #define PSA_ECDSA_SIGNATURE_SIZE(curve_bits)    \
     (PSA_BITS_TO_BYTES(curve_bits) * 2)
 
-/** Sufficient signature buffer size for psa_asymmetric_sign().
+/** Sufficient signature buffer size for psa_sign_hash().
  *
  * This macro returns a sufficient buffer size for a signature using a key
  * of the specified type and size, with the specified algorithm.
@@ -429,31 +429,31 @@
  *
  * \return If the parameters are valid and supported, return
  *         a buffer size in bytes that guarantees that
- *         psa_asymmetric_sign() will not fail with
+ *         psa_sign_hash() will not fail with
  *         #PSA_ERROR_BUFFER_TOO_SMALL.
  *         If the parameters are a valid combination that is not supported
  *         by the implementation, this macro shall return either a
  *         sensible size or 0.
  *         If the parameters are not valid, the
  *         return value is unspecified.
  */
-#define PSA_ASYMMETRIC_SIGN_OUTPUT_SIZE(key_type, key_bits, alg)        \
+#define PSA_SIGN_OUTPUT_SIZE(key_type, key_bits, alg)        \
     (PSA_KEY_TYPE_IS_RSA(key_type) ? ((void)alg, PSA_BITS_TO_BYTES(key_bits)) : \
      PSA_KEY_TYPE_IS_ECC(key_type) ? PSA_ECDSA_SIGNATURE_SIZE(key_bits) : \
      ((void)alg, 0))
 
 #define PSA_VENDOR_ECDSA_SIGNATURE_MAX_SIZE     \
     PSA_ECDSA_SIGNATURE_SIZE(PSA_VENDOR_ECC_MAX_CURVE_BITS)
 
-/** \def PSA_ASYMMETRIC_SIGNATURE_MAX_SIZE
+/** \def PSA_SIGNATURE_MAX_SIZE
  *
  * Maximum size of an asymmetric signature.
  *
  * This macro must expand to a compile-time constant integer. This value
  * should be the maximum size of a signature supported by the implementation,
  * in bytes, and must be no smaller than this maximum.
  */
-#define PSA_ASYMMETRIC_SIGNATURE_MAX_SIZE                               \
+#define PSA_SIGNATURE_MAX_SIZE                               \
     (PSA_BITS_TO_BYTES(PSA_VENDOR_RSA_MAX_KEY_BITS) > PSA_VENDOR_ECDSA_SIGNATURE_MAX_SIZE ? \
      PSA_BITS_TO_BYTES(PSA_VENDOR_RSA_MAX_KEY_BITS) :                   \
      PSA_VENDOR_ECDSA_SIGNATURE_MAX_SIZE)
@@ -682,7 +682,7 @@
  *
  * \return If the parameters are valid and supported, return
  *         a buffer size in bytes that guarantees that
- *         psa_asymmetric_sign() will not fail with
+ *         psa_sign_hash() will not fail with
  *         #PSA_ERROR_BUFFER_TOO_SMALL.
  *         If the parameters are a valid combination that is not supported
  *         by the implementation, this macro shall return either a

include/psa/crypto_values.h

@@ -766,17 +766,17 @@
  * Then you may create and use a key as follows:
  * - Set the key usage field using #PSA_ALG_ANY_HASH, for example:
  *   ```
- *   psa_set_key_usage_flags(&attributes, PSA_KEY_USAGE_SIGN); // or VERIFY
+ *   psa_set_key_usage_flags(&attributes, PSA_KEY_USAGE_SIGN_HASH); // or VERIFY
  *   psa_set_key_algorithm(&attributes, PSA_xxx_SIGNATURE(PSA_ALG_ANY_HASH));
  *   ```
  * - Import or generate key material.
- * - Call psa_asymmetric_sign() or psa_asymmetric_verify(), passing
+ * - Call psa_sign_hash() or psa_verify_hash(), passing
  *   an algorithm built from `PSA_xxx_SIGNATURE` and a specific hash. Each
  *   call to sign or verify a message may use a different hash.
  *   ```
- *   psa_asymmetric_sign(handle, PSA_xxx_SIGNATURE(PSA_ALG_SHA_256), ...);
- *   psa_asymmetric_sign(handle, PSA_xxx_SIGNATURE(PSA_ALG_SHA_512), ...);
- *   psa_asymmetric_sign(handle, PSA_xxx_SIGNATURE(PSA_ALG_SHA3_256), ...);
+ *   psa_sign_hash(handle, PSA_xxx_SIGNATURE(PSA_ALG_SHA_256), ...);
+ *   psa_sign_hash(handle, PSA_xxx_SIGNATURE(PSA_ALG_SHA_512), ...);
+ *   psa_sign_hash(handle, PSA_xxx_SIGNATURE(PSA_ALG_SHA3_256), ...);
  *   ```
  *
  * This value may not be used to build other algorithms that are
@@ -1641,7 +1641,7 @@
  *
  * For a key pair, this concerns the private key.
  */
-#define PSA_KEY_USAGE_SIGN                      ((psa_key_usage_t)0x00000400)
+#define PSA_KEY_USAGE_SIGN_HASH                 ((psa_key_usage_t)0x00000400)
 
 /** Whether the key may be used to verify a message signature.
  *
@@ -1651,7 +1651,7 @@
  *
  * For a key pair, this concerns the public key.
  */
-#define PSA_KEY_USAGE_VERIFY                    ((psa_key_usage_t)0x00000800)
+#define PSA_KEY_USAGE_VERIFY_HASH               ((psa_key_usage_t)0x00000800)
 
 /** Whether the key may be used to derive other keys.
  */

library/pk.c

@@ -621,7 +621,7 @@ int mbedtls_pk_wrap_as_opaque( mbedtls_pk_context *pk,
 
     /* prepare the key attributes */
     psa_set_key_type( &attributes, key_type );
-    psa_set_key_usage_flags( &attributes, PSA_KEY_USAGE_SIGN );
+    psa_set_key_usage_flags( &attributes, PSA_KEY_USAGE_SIGN_HASH );
     psa_set_key_algorithm( &attributes, PSA_ALG_ECDSA(hash_alg) );
 
     /* import private key into PSA */

library/pk_wrap.c

@@ -578,7 +578,7 @@ static int ecdsa_verify_wrap( void *ctx, mbedtls_md_type_t md_alg,
     psa_sig_md = PSA_ALG_ECDSA( psa_md );
 
     psa_set_key_type( &attributes, PSA_KEY_TYPE_ECC_PUBLIC_KEY( curve ) );
-    psa_set_key_usage_flags( &attributes, PSA_KEY_USAGE_VERIFY );
+    psa_set_key_usage_flags( &attributes, PSA_KEY_USAGE_VERIFY_HASH );
     psa_set_key_algorithm( &attributes, psa_sig_md );
 
     status = psa_import_key( &attributes,
@@ -605,9 +605,9 @@ static int ecdsa_verify_wrap( void *ctx, mbedtls_md_type_t md_alg,
         goto cleanup;
     }
 
-    if( psa_asymmetric_verify( key_handle, psa_sig_md,
-                               hash, hash_len,
-                               buf, 2 * signature_part_size )
+    if( psa_verify_hash( key_handle, psa_sig_md,
+                         hash, hash_len,
+                         buf, 2 * signature_part_size )
          != PSA_SUCCESS )
     {
          ret = MBEDTLS_ERR_ECP_VERIFY_FAILED;
@@ -1023,8 +1023,8 @@ static int pk_opaque_sign_wrap( void *ctx, mbedtls_md_type_t md_alg,
         return( MBEDTLS_ERR_PK_BAD_INPUT_DATA );
 
     /* make the signature */
-    status = psa_asymmetric_sign( *key, alg, hash, hash_len,
-                                        sig, buf_len, sig_len );
+    status = psa_sign_hash( *key, alg, hash, hash_len,
+                            sig, buf_len, sig_len );
     if( status != PSA_SUCCESS )
         return( mbedtls_psa_err_translate_pk( status ) );