Add interruptible Crypto API operations

[athoelke]

This is a rebased version of #107 and #199, targetting version 1.6 of the specification.

Apart from adding the previously drafted APIs, this incorporates other changes to the documentation since the original PRs. The introductory text for interruptible signatures has also been updated to reflect the presence of both multi-part signatures and interruptibel signature APIs.

[gilles-peskine-arm]

I've reviewed the document with the partial implementation in TF-PSA-Crypto in mind. We know that we'll need to update our implementation since it followed a now outdated beta.

Many of my comments apply to multiple operation types. I only noted the first place where I noticed something.

My biggest concern is the verify flow. For verify-message, I don't think providing the signature before the message works out in practice.

[gilles-peskine-arm]

Can you remind me why the signature is passed during setup, rather than after the message?

Streaming protocols often send the message before the signature to verify, so in practice, this is likely to be a burden if the algorithm doesn't follow the sign-the-hash paradigm.

[athoelke]

That limits the algorithm selection: PureEdDSA, SLH-DSA, LMS, and XMSS all require the randomisation element from the signature as part of the hash prefix before the message content.

[athoelke]

Deferred-signature verification support has been added

[gilles-peskine-arm]

This section could use a subsection that discusses op counts:

• xxx_iop_get_num_ops() functions (still meaningful after complete() returns PSA_SUCCESS).
• psa_iop_set_max_ops() and a brief statement that ops do not have a fixed meaning.

[athoelke]

This is currently present in lines 252-256. Is there more that should be said here?

[gilles-peskine-arm]

The section introduces the concepts, but I think it should be a bit more concrete. At the very least, it should mention the get_num_ops naming convention.

[athoelke]

Done

[athoelke]

My biggest concern is the verify flow. For verify-message, I don't think providing the signature before the message works out in practice.

Quick response on this:

1. such an observation also affects the already defined verify-message multi-part operation.
2. Deferring the signature is not possible for PureEdDSA, SLH-DSA, LMS/HSS, or XMSS - although it is for ECDSA, RSA-*, HashEdDSA, HashSLH-DSA and all forms of ML-DSA.

A algorithm-agnostic flow requires the signature before the message parts.

[athoelke]

Following discussion - we need to support use cases where the signature is only provided after the message content (required for some streaming protocols), as well as use cases where the signature is provided before the message (which is required for some algorithms).

For psa_verify_iop_t, the proposal is to enable a 'late signature' flow, that is only available for some algorithms, and a general 'early signature' flow that works for any algorithm.

Using the current psa_verify_iop_setup() function signals the use of the general/early-signature flow, and the rest of the API should be used as currently described.

For the new flow, three additional APIs are provided:

psa_status_t psa_verify_iop_setup_deferred_signature(...);
psa_status_t psa_verify_iop_set_signature(...);
#define PSA_ALG_SIGN_SUPPORTS_DEFERRED_SIGNATURE(alg) ...

• psa_verify_iop_setup_deferred_signature() acts like the current setup function, but without the signature. This indicates that the application will only provide the signature after the message/hash input immediately before completion. If the algorithm or implementation does not support that flow, this is reported as an error response to this function call.
• psa_verify_iop_set_signature() supplies the signature to an interruptible verify operation, after all the message/hash input has been provided, and before any call to psa_verify_iop_complete(). If called when a signature has already been provided, this returns BAD_STATE.
• If no signature has been provided (either in setup or via psa_verify_iop_set_signature()), then psa_verify_iop_complete() returns BAD_STATE.
• PSA_ALG_SIGN_SUPPORTS_DEFERRED_SIGNATURE() reports whether or not a signature algorithm enables a late-signature flow. This is independent of implememtation-specific support for late flows.

This design, providing a distinct setup function, enables the implementation to detect the application intent explicitly and immediately, and respond with an error if not supported. With a more generic, single setup function without a signature; the application intent can only be inferred when psa_verify_iop_setup_complete() is called before providing a signature.

[athoelke]

I think I've managed to address all of the substanive issues raised in the feedback so far. I would appreciate a re-review of the resulting updated PR.

[gilles-peskine-arm]

Thanks for the updates. I only have a couple of minor nits now, except maybe for one point. I want to think further about verification with and without deferred signature.

[gilles-peskine-arm]

psa_generate_key_iop_custom() can also fail with PSA_ERROR_BAD_STATE if psa_generate_key_iop_custom() has already been called.

[athoelke]

I'll review all the sequencing statements affected by adding this function.

[athoelke]

Done

[gilles-peskine-arm]

It's technically true that psa_generate_key_iop_custom() and psa_generate_key_iop_complete() are the next two functions that may be used for a normal flow (non-aborted, eventually succeeding). However, the way I understand this sentence is that one may either call custom() or the complete() loop. It's not clear either here or in the documentation of custom() that custom() should be followed by a complete() loop.

[athoelke]

Done

[gilles-peskine-arm]

There's still an ambiguity here in the second clause, where it's not clear whether the clause describes what caused the error or what must be done to avoid the error. I think it would be simpler to understand if error descriptions always described what causes the error.

Suggested change

	* The operation state is not valid: setup must be complete, and no call to `psa_sign_iop_set_context()`, `psa_sign_iop_hash()`, `psa_sign_iop_update()`, or `psa_sign_iop_complete()` has been made.
	* The operation state is not valid: setup must be complete, and no call to `psa_sign_iop_set_context()`, `psa_sign_iop_hash()`, `psa_sign_iop_update()`, or `psa_sign_iop_complete()` must have been made.

or

Suggested change

	* The operation state is not valid: setup must be complete, and no call to `psa_sign_iop_set_context()`, `psa_sign_iop_hash()`, `psa_sign_iop_update()`, or `psa_sign_iop_complete()` has been made.
	* The operation state is not valid: the operation is inactive, setup is incomplete, or a call to `psa_sign_iop_set_context()`, `psa_sign_iop_hash()`, `psa_sign_iop_update()`, or `psa_sign_iop_complete()` has been made.

(I haven't made a list of where this pattern occurs.)

[athoelke]

This could be widespread - I think in all the MP operations, the 'The operation state is not valid:...' conditions for BAD_STATE go on to define what 'valid' means for the function. The statement here mixes requirement tone - 'setup must be complete' - with present tense state tone - 'no call to ... has been made'.

The second alternative is tempting, with the description actually presents the states that are invalid. I would introduce it as 'The operation state is invalid: ...' - this removes the [existing] ambiguity as to whether the statement that follows is a definition of 'valid states' or of 'not valid states'?

For consistency, this might be a change we should make across all operation functions? - which goes well beyond the remit of this PR. But we could do that for these interruptibles, and follow with a spec-wide edit for the existing multi-parts?

[gilles-peskine-arm]

This still isn't fully accurate: if psa_xxx_iop_start() is called on an already active object, it's a BAD_STATE error, but the object doesn't “remain inactive”.

[athoelke]

Quite right, but 'ouch!':

• This affects all the interruptibles in this PR. The statement is only true if the operation was inactive prior to the call.

• All existing multi-part operations suffer from a differently word defect of the same category. They state:

  If psa_xxx_setup() returns an error, the operation object is unchanged.

  Which is also only true if the operation was inactive to start with.

We changed the wording for the interruptibles, because the ops count can be changed by the call. But we have missed the 'If the operation was not inactive, psa_xxx_setup() returns PSA_ERROR_BAD_STATE, otherwise ...` that should preceed the current statements for all of these APIs.

[athoelke]

Looks like this warrants an issue to address this omission across all multi-part operations.

[gilles-peskine-arm]

I definitely don't want to implement a key id reservation in TF-PSA-Crypto. I wouldn't mind if reservation was forbidden. But there may be lower-level implementations where persistent key slots are tied more directly to physical addresses where reserving makes more sense, so I'm ok with allowing it in the specification.

[gilles-peskine-arm]

The section introduces the concepts, but I think it should be a bit more concrete. At the very least, it should mention the get_num_ops naming convention.

[athoelke]

I had another thought about the verification and deferred signatures.

For both the multi-part and interruptible verification operations, the operation object wil have to copy some or all of the signature data if it is passed during setup. For PQC signatures, this can be a very sizeable buffer and will be challenging for constrained implementations with no dynamic allocation.

However, although it might work (from a memory management point of view) to have the application deal with the signature memory issue, and pass the signature to both the setup and the finishing phases for an algorithm that requires the signature before the message - is there a security/cryptographic risk in having the application pass what is meant to be the same signature data twice to the implementation?