Merge pull request #221 from athoelke/crypto-signature-introduction

Provide an clear overview of the asymmetric signature API
ARM-software · Nov 4, 2024 · 3b63e4b · 3b63e4b
2 parents b2eab5e + 32ce931
commit 3b63e4b
Show file tree

Hide file tree

Showing 7 changed files with 354 additions and 373 deletions.
diff --git a/doc/crypto/api/keys/policy.rst b/doc/crypto/api/keys/policy.rst
@@ -204,7 +204,9 @@ The usage flags are encoded in a bitmask, which has the type `psa_key_usage_t`.
     .. summary::
         Permission to sign a message hash with the key.
 
-    This flag is required to use the key to sign a message hash in an asymmetric signature operation. The flag must be present on keys used when calling `psa_sign_hash()`.
+    This flag is required to use the key to sign a pre-computed message hash in an asymmetric signature operation. The flag must be present on keys used with the following APIs:
+
+    *   `psa_sign_hash()`
 
     This flag automatically sets `PSA_KEY_USAGE_SIGN_MESSAGE`: if an application sets the flag `PSA_KEY_USAGE_SIGN_HASH` when creating a key, then the key always has the permissions conveyed by `PSA_KEY_USAGE_SIGN_MESSAGE`, and the flag `PSA_KEY_USAGE_SIGN_MESSAGE` will also be present when the application queries the usage flags of the key.
 
@@ -216,7 +218,9 @@ The usage flags are encoded in a bitmask, which has the type `psa_key_usage_t`.
     .. summary::
         Permission to verify a message hash with the key.
 
-    This flag is required to use the key to verify a message hash in an asymmetric signature verification operation. The flag must be present on keys used when calling `psa_verify_hash()`.
+    This flag is required to use the key to verify a pre-computed message hash in an asymmetric signature verification operation. The flag must be present on keys used with the following APIs:
+
+    *   `psa_verify_hash()`
 
     This flag automatically sets `PSA_KEY_USAGE_VERIFY_MESSAGE`: if an application sets the flag `PSA_KEY_USAGE_VERIFY_HASH` when creating a key, then the key always has the permissions conveyed by `PSA_KEY_USAGE_VERIFY_MESSAGE`, and the flag `PSA_KEY_USAGE_VERIFY_MESSAGE` will also be present when the application queries the usage flags of the key.
 

diff --git a/doc/crypto/api/library/status.rst b/doc/crypto/api/library/status.rst
@@ -12,29 +12,29 @@ The following elements are defined in :file:`psa/error.h` from :cite-title:`PSA-
 
 .. code-block:: xref
 
-   typedef int32_t psa_status_t;
-
-   #define PSA_SUCCESS ((psa_status_t)0)
-
-   #define PSA_ERROR_GENERIC_ERROR         ((psa_status_t)-132)
-   #define PSA_ERROR_NOT_PERMITTED         ((psa_status_t)-133)
-   #define PSA_ERROR_NOT_SUPPORTED         ((psa_status_t)-134)
-   #define PSA_ERROR_INVALID_ARGUMENT      ((psa_status_t)-135)
-   #define PSA_ERROR_INVALID_HANDLE        ((psa_status_t)-136)
-   #define PSA_ERROR_BAD_STATE             ((psa_status_t)-137)
-   #define PSA_ERROR_BUFFER_TOO_SMALL      ((psa_status_t)-138)
-   #define PSA_ERROR_ALREADY_EXISTS        ((psa_status_t)-139)
-   #define PSA_ERROR_DOES_NOT_EXIST        ((psa_status_t)-140)
-   #define PSA_ERROR_INSUFFICIENT_MEMORY   ((psa_status_t)-141)
-   #define PSA_ERROR_INSUFFICIENT_STORAGE  ((psa_status_t)-142)
-   #define PSA_ERROR_INSUFFICIENT_DATA     ((psa_status_t)-143)
-   #define PSA_ERROR_COMMUNICATION_FAILURE ((psa_status_t)-145)
-   #define PSA_ERROR_STORAGE_FAILURE       ((psa_status_t)-146)
-   #define PSA_ERROR_HARDWARE_FAILURE      ((psa_status_t)-147)
-   #define PSA_ERROR_INVALID_SIGNATURE     ((psa_status_t)-149)
-   #define PSA_ERROR_CORRUPTION_DETECTED   ((psa_status_t)-151)
-   #define PSA_ERROR_DATA_CORRUPT          ((psa_status_t)-152)
-   #define PSA_ERROR_DATA_INVALID          ((psa_status_t)-153)
+    typedef int32_t psa_status_t;
+
+    #define PSA_SUCCESS ((psa_status_t)0)
+
+    #define PSA_ERROR_GENERIC_ERROR         ((psa_status_t)-132)
+    #define PSA_ERROR_NOT_PERMITTED         ((psa_status_t)-133)
+    #define PSA_ERROR_NOT_SUPPORTED         ((psa_status_t)-134)
+    #define PSA_ERROR_INVALID_ARGUMENT      ((psa_status_t)-135)
+    #define PSA_ERROR_INVALID_HANDLE        ((psa_status_t)-136)
+    #define PSA_ERROR_BAD_STATE             ((psa_status_t)-137)
+    #define PSA_ERROR_BUFFER_TOO_SMALL      ((psa_status_t)-138)
+    #define PSA_ERROR_ALREADY_EXISTS        ((psa_status_t)-139)
+    #define PSA_ERROR_DOES_NOT_EXIST        ((psa_status_t)-140)
+    #define PSA_ERROR_INSUFFICIENT_MEMORY   ((psa_status_t)-141)
+    #define PSA_ERROR_INSUFFICIENT_STORAGE  ((psa_status_t)-142)
+    #define PSA_ERROR_INSUFFICIENT_DATA     ((psa_status_t)-143)
+    #define PSA_ERROR_COMMUNICATION_FAILURE ((psa_status_t)-145)
+    #define PSA_ERROR_STORAGE_FAILURE       ((psa_status_t)-146)
+    #define PSA_ERROR_HARDWARE_FAILURE      ((psa_status_t)-147)
+    #define PSA_ERROR_INVALID_SIGNATURE     ((psa_status_t)-149)
+    #define PSA_ERROR_CORRUPTION_DETECTED   ((psa_status_t)-151)
+    #define PSA_ERROR_DATA_CORRUPT          ((psa_status_t)-152)
+    #define PSA_ERROR_DATA_INVALID          ((psa_status_t)-153)
 
 These definitions must be available to an application that includes the :file:`psa/crypto.h` header file.
 
@@ -89,7 +89,7 @@ Some of the common status codes have a more precise meaning when returned by a f
 .. _specific-errors:
 
 Error codes specific to the |API|
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 .. header:: psa/crypto
     :seq: 2

diff --git a/doc/crypto/api/ops/algorithms.rst b/doc/crypto/api/ops/algorithms.rst
@@ -20,7 +20,7 @@ The specific algorithm identifiers are described alongside the cryptographic ope
 *   :secref:`cipher-algorithms`
 *   :secref:`aead-algorithms`
 *   :secref:`key-derivation-algorithms`
-*   :secref:`sign-algorithms`
+*   :secref:`sign`
 *   :secref:`asymmetric-encryption-algorithms`
 *   :secref:`key-agreement-algorithms`
 *   :secref:`pake`
@@ -150,7 +150,7 @@ Algorithm categories
     .. return::
         ``1`` if ``alg`` is an asymmetric signature algorithm, ``0`` otherwise. This macro can return either ``0`` or ``1`` if ``alg`` is not a supported algorithm identifier.
 
-    See :secref:`sign-algorithms` for a list of defined signature algorithms.
+    See :secref:`sign` for a list of defined signature algorithms.
 
 .. macro:: PSA_ALG_IS_ASYMMETRIC_ENCRYPTION
     :definition: /* specification-defined value */

diff --git a/doc/crypto/api/ops/hash.rst b/doc/crypto/api/ops/hash.rst
@@ -184,7 +184,7 @@ Hash algorithms
     .. summary::
         The first 512 bits (64 bytes) of the SHAKE256 output.
 
-    This is the prehashing for Ed448ph (see `PSA_ALG_ED448PH`).
+    This is the pre-hashing for Ed448ph (see `PSA_ALG_ED448PH`).
 
     SHAKE256 is defined in :cite:`FIPS202`.