Skip to content

Relax the permitted-algorithm policy for ECDSA #312

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

Merged
athoelke merged 3 commits into from
Oct 20, 2025
Merged

Relax the permitted-algorithm policy for ECDSA #312

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
adcf5bf
Relex the permitted-algorithm policy for ECDSA
athoelke Oct 15, 2025
ca3607c
Fix description of ECDSA signature structure
athoelke Oct 17, 2025
53ca265
Updated the key policy introduction to include the ECDSA algorithm eq…
athoelke Oct 17, 2025
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
18 changes: 12 additions & 6 deletions doc/crypto/api/keys/policy.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
29 changes: 20 additions & 9 deletions doc/crypto/api/ops/signature.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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::

Expand Down Expand Up @@ -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

Expand Down
6 changes: 6 additions & 0 deletions doc/crypto/appendix/history.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Copy link
Copy Markdown
Contributor

@gilles-peskine-arm gilles-peskine-arm Oct 16, 2025

Choose a reason for hiding this comment

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

I think these exceptions should be mentioned in the “Permitted algorithms” section of the chapter on policies. Not necessarily the full list, but at least the general ideas that some algorithms are considered partially equivalent. Maybe just say that it's the case for some signature algorithms, which are only considered equivalent for verification? According to the current text, “A specific algorithm value permits exactly that particular algorithm” (plus NONE and various wildcard cases), which rules out the ML-DSA, SLH-DSA and now ECDSA verification relaxation.

Copy link
Copy Markdown
Contributor Author

@athoelke athoelke Oct 16, 2025 •
edited
Loading

Choose a reason for hiding this comment

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

Good point - the PQC extension didn't actually modify that text, because it is outside the main spec for now.

Copy link
Copy Markdown
Contributor

@gilles-peskine-arm gilles-peskine-arm Oct 16, 2025

Choose a reason for hiding this comment

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

That text should also make it clear that the policy enforcement there depends not only on the key metadata and the requested algorithm for the operation, but also on the nature of the operation.

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.

That doesn't completely rule out the fact that a policy of PSA_ALG_ECDSA(PSA_ALG_SHA_256) allows PSA_ALG_DETERMINISTIC_ECDSA(PSA_ALG_SHA_256) for verification but not for signature, but it strongly hints that only the algorithm matters.

This is reflected architecturally, for example, in Mbed TLS/TF-PSA-Crypto, where the policy check is implemented as a function

static psa_status_t psa_key_policy_permits(const psa_key_policy_t *policy,
                                           psa_key_type_t key_type,
                                           psa_algorithm_t alg)

which will need to take an extra argument that allows distinguishing signature from verification. (The key type is not enough since a key pair can be used to verify a signature.)

Copy link
Copy Markdown
Contributor Author

@athoelke athoelke Oct 17, 2025

Choose a reason for hiding this comment

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

This approaches what we have described for psa_check_key_usage - where the role the key takes in the algorithm matters, not just the algorithm itself.

Copy link
Copy Markdown
Contributor Author

@athoelke athoelke Oct 17, 2025

Choose a reason for hiding this comment

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

I've tried to capture this in a rewording of the permitted algorithm policy introduction.

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
~~~~~~~~~~~~~~~~~~~~~~~~

Expand Down