diff --git a/doc/crypto/api/keys/policy.rst b/doc/crypto/api/keys/policy.rst index 40dc7704..a7ba84e6 100644 --- a/doc/crypto/api/keys/policy.rst +++ b/doc/crypto/api/keys/policy.rst @@ -26,20 +26,26 @@ Permitted algorithms The permitted algorithm is encoded using a algorithm identifier, as described in :secref:`algorithms`. -This specification only defines policies that restrict keys to a single algorithm, which is consistent with both common practice and security good practice. +For most algorithms, this specification only defines policies that restrict keys to a single algorithm, which is consistent with both common practice and security good practice. -The following algorithm policies are supported: +If the permitted algorithm is `PSA_ALG_NONE`, no cryptographic operation is permitted with the key. +The key can still be used for non-cryptographic actions such as exporting, if permitted by the usage flags. -* `PSA_ALG_NONE` does not permit any cryptographic operation with the key. The key can still be used for non-cryptographic actions such as exporting, if permitted by the usage flags. -* A specific algorithm value permits exactly that particular algorithm. -* A signature algorithm constructed with `PSA_ALG_ANY_HASH` permits the specified signature scheme with any hash algorithm. In addition, :code:`PSA_ALG_RSA_PKCS1V15_SIGN(PSA_ALG_ANY_HASH)` also permits the `PSA_ALG_RSA_PKCS1V15_SIGN_RAW` signature algorithm. +For a cryptographic operation, the permitted algorithm value must exactly match the requested algorithm, except in the following cases: + +* The following pairs of signature algorithms are considered equivalent for verification, but not for computing the signature: + + - `PSA_ALG_ECDSA` and `PSA_ALG_DETERMINISTIC_ECDSA`. +* A signature algorithm constructed with `PSA_ALG_ANY_HASH` permits the specified signature scheme with any hash algorithm. + In addition, :code:`PSA_ALG_RSA_PKCS1V15_SIGN(PSA_ALG_ANY_HASH)` also permits the `PSA_ALG_RSA_PKCS1V15_SIGN_RAW` signature algorithm. * A standalone key-agreement algorithm also permits the specified key-agreement scheme to be combined with any key-derivation algorithm. * An algorithm built from `PSA_ALG_AT_LEAST_THIS_LENGTH_MAC()` permits any MAC algorithm from the same base class (for example, CMAC) which computes or verifies a MAC length greater than or equal to the length encoded in the wildcard algorithm. * An algorithm built from `PSA_ALG_AEAD_WITH_AT_LEAST_THIS_LENGTH_TAG()` permits any AEAD algorithm from the same base class (for example, CCM) which computes or verifies a tag length greater than or equal to the length encoded in the wildcard algorithm. * The `PSA_ALG_CCM_STAR_ANY_TAG` wildcard algorithm permits the `PSA_ALG_CCM_STAR_NO_TAG` cipher algorithm, the `PSA_ALG_CCM` AEAD algorithm, and the :code:`PSA_ALG_AEAD_WITH_SHORTENED_TAG(PSA_ALG_CCM, tag_length)` truncated-tag AEAD algorithm for ``tag_length`` equal to 4, 8 or 16. * The wildcard key policy `PSA_ALG_WPA3_SAE_ANY` permits a password key or WPA3-SAE password token key to be used with any WPA3-SAE cipher suite. -When a key is used in a cryptographic operation, the application must supply the algorithm to use for the operation. This algorithm is checked against the key's permitted-algorithm policy. +When a key is used in a cryptographic operation, the application supplies the algorithm to use for the operation. +The algorithm and operation are checked against the key's permitted-algorithm policy. .. function:: psa_set_key_algorithm diff --git a/doc/crypto/api/ops/signature.rst b/doc/crypto/api/ops/signature.rst index d963b546..7c62c510 100644 --- a/doc/crypto/api/ops/signature.rst +++ b/doc/crypto/api/ops/signature.rst @@ -334,15 +334,21 @@ ECDSA signature algorithms This algorithm is randomized: each invocation returns a different, equally valid signature. - .. note:: + The ECDSA signature scheme is defined by :cite-title:`SEC1`, and also by :cite-title:`X9-62`, with a random per-message secret number :math:`k`. + + The representation of the signature as a byte string consists of the concatenation of the signature values :math:`r` and :math:`s`. + Each of :math:`r` and :math:`s` is encoded as a big-endian :math:`m`-octet string, where :math:`m` is the integer for which :math:`2^{8(m-1)} \leq q < 2^{8m}`, and :math:`q` is the order of the elliptic curve. + + When based on the same hash algorithm, the verification operations for `PSA_ALG_ECDSA` and `PSA_ALG_DETERMINISTIC_ECDSA` are identical. A signature created using `PSA_ALG_ECDSA` can be verified with the same key using either `PSA_ALG_ECDSA` or `PSA_ALG_DETERMINISTIC_ECDSA`. Similarly, a signature created using `PSA_ALG_DETERMINISTIC_ECDSA` can be verified with the same key using either `PSA_ALG_ECDSA` or `PSA_ALG_DETERMINISTIC_ECDSA`. - When based on the same hash algorithm, the verification operations for `PSA_ALG_ECDSA` and `PSA_ALG_DETERMINISTIC_ECDSA` are identical. A signature created using `PSA_ALG_ECDSA` can be verified with the same key using either `PSA_ALG_ECDSA` or `PSA_ALG_DETERMINISTIC_ECDSA`. Similarly, a signature created using `PSA_ALG_DETERMINISTIC_ECDSA` can be verified with the same key using either `PSA_ALG_ECDSA` or `PSA_ALG_DETERMINISTIC_ECDSA`. + .. note:: - In particular, it is impossible to determine whether a signature was produced with deterministic ECDSA or with randomized ECDSA: it is only possible to verify that a signature was made with ECDSA with the private key corresponding to the public key used for the verification. + A verifier cannot determine whether a signature was produced with deterministic ECDSA or with randomized ECDSA: it is only possible to verify that a signature was made with ECDSA with the private key corresponding to the public key used for the verification. - This signature scheme is defined by :cite-title:`SEC1`, and also by :cite-title:`X9-62`, with a random per-message secret number :math:`k`. + When :code:`PSA_ALG_ECDSA(hash_alg)` is used as a permitted algorithm in a key policy, this permits: - The representation of the signature as a byte string consists of the concatenation of the signature values :math:`r` and :math:`s`. Each of :math:`r` and :math:`s` is encoded as an :math:`N`-octet string, where :math:`N` is the length of the base point of the curve in octets. Each value is represented in big-endian order, with the most significant octet first. + * :code:`PSA_ALG_ECDSA(hash_alg)` as the algorithm in a call to any signing function. + * :code:`PSA_ALG_ECDSA(hash_alg)` or :code:`PSA_ALG_DETERMINISTIC_ECDSA(hash_alg)` as the algorithm in a call to any signature verification function. .. subsection:: Compatible key types @@ -368,7 +374,7 @@ ECDSA signature algorithms This algorithm is randomized: each invocation returns a different, equally valid signature. - This is the same signature scheme as `PSA_ALG_ECDSA()`, but without specifying a hash algorithm, and skipping the message hashing operation. + This is the same signature scheme as `PSA_ALG_ECDSA`, but without specifying a hash algorithm, and skipping the message hashing operation. .. warning:: @@ -410,13 +416,18 @@ ECDSA signature algorithms This is the deterministic ECDSA signature scheme defined by :RFC-title:`6979`. - The representation of a signature is the same as with `PSA_ALG_ECDSA()`. + The representation of a signature is the same as with `PSA_ALG_ECDSA`. + + When based on the same hash algorithm, the verification operations for `PSA_ALG_ECDSA` and `PSA_ALG_DETERMINISTIC_ECDSA` are identical. A signature created using `PSA_ALG_ECDSA` can be verified with the same key using either `PSA_ALG_ECDSA` or `PSA_ALG_DETERMINISTIC_ECDSA`. Similarly, a signature created using `PSA_ALG_DETERMINISTIC_ECDSA` can be verified with the same key using either `PSA_ALG_ECDSA` or `PSA_ALG_DETERMINISTIC_ECDSA`. .. note:: - When based on the same hash algorithm, the verification operations for `PSA_ALG_ECDSA` and `PSA_ALG_DETERMINISTIC_ECDSA` are identical. A signature created using `PSA_ALG_ECDSA` can be verified with the same key using either `PSA_ALG_ECDSA` or `PSA_ALG_DETERMINISTIC_ECDSA`. Similarly, a signature created using `PSA_ALG_DETERMINISTIC_ECDSA` can be verified with the same key using either `PSA_ALG_ECDSA` or `PSA_ALG_DETERMINISTIC_ECDSA`. + A verifier cannot determine whether a signature was produced with deterministic ECDSA or with randomized ECDSA: it is only possible to verify that a signature was made with ECDSA with the private key corresponding to the public key used for the verification. + + When :code:`PSA_ALG_DETERMINISTIC_ECDSA(hash_alg)` is used as a permitted algorithm in a key policy, this permits: - In particular, it is impossible to determine whether a signature was produced with deterministic ECDSA or with randomized ECDSA: it is only possible to verify that a signature was made with ECDSA with the private key corresponding to the public key used for the verification. + * :code:`PSA_ALG_DETERMINISTIC_ECDSA(hash_alg)` as the algorithm in a call to any signing function. + * :code:`PSA_ALG_DETERMINISTIC_ECDSA(hash_alg)` or :code:`PSA_ALG_ECDSA(hash_alg)` as the algorithm in a call to any signature verification function. .. subsection:: Compatible key types diff --git a/doc/crypto/appendix/history.rst b/doc/crypto/appendix/history.rst index e4b89510..fa516c22 100644 --- a/doc/crypto/appendix/history.rst +++ b/doc/crypto/appendix/history.rst @@ -39,6 +39,12 @@ Changes to the API See :secref:`pake-wpa3-sae`. +Relaxations +~~~~~~~~~~~ + +* Relaxed the permitted-key policy requirements for ECDSA verification, to be consistent with those for ML-DSA and SLH-DSA. + When verifying a signature, the `PSA_ALG_ECDSA` and `PSA_ALG_DETERMINISTIC_ECDSA` are considered equivalent when checking the key's permitted-algorithm policy. + Clarifications and fixes ~~~~~~~~~~~~~~~~~~~~~~~~