Naming patterns for multi-part & interruptible Crypto APIs

[athoelke]

Context

MBed TLS has implemented an experimental (Beta) API for incremental/interruptible hash signature algorithms. See Mbed-TLS/mbedtls#7095. Before committing this interface into the Crypto API specification, there is a need to look ahead and ensure that the API design is capable of handling future needs for other multi-part and interruptible interfaces for signature algorithms.

For the Crypto API, we expect to [eventually] have the following APIs:

• interruptible sign & verify hash (this is the subject of the Mbed TLS PR)
• multi-part sign & verify message
• interruptible, multi-part sign & verify message

Observations

Unlike the multi-part symmetric operations, these operations could benefit from having distinct operation structures:

• Asymmetric signature operations have very different data requirements for the sign and verify algorithms
• Multi-part sign/verify message needs to maintain internal hash state while processing the message, sign/verify hash does not
• Interruptible operations must maintain significant state in the operation context during the step-wise computation, that is not needed for non-interruptible operations.

So we might want each of the six operations to have distinct operation structure names, and thus also distinct API names for the full flow of each operation.

If we use the symmetric multi-part operations as a pattern, then the multi-part sign & verify message would like end up as follows (which makes a lot of sense):

psa_sign_message_operation_t
psa_sign_message_setup(op, key, alg)
psa_sign_message_update(op, [inbuf] msg)
psa_sign_message_finish(op, [outbuf] sig)
psa_sign_message_abort(op)

psa_verify_message_operation_t
psa_verify_message_setup(op, key, alg, [inbuf] sig)
psa_verify_message_update(op, [inbuf] msg)
psa_verify_message_finish(op)
psa_verify_message_abort(op)

Note that the signature is input to the verification operation at setup. This is required as some asymmetric signature verification algorithms need the signature prior to processing the message.

The Mbed TLS beta interface for interruptible sign/verify hash is as follows:

psa_sign_hash_interruptible_operation_t
psa_sign_hash_start(op, key, alg, [inbuf] hash)
psa_sign_hash_complete(op, [outbuf] sig)
psa_sign_hash_abort(op)

psa_verify_hash_interruptible_operation_t
psa_verify_hash_start(op, key, alg, [inbuf] hash, [inbuf] sig)
psa_verify_hash_complete(op)
psa_verify_hash_abort(op)

Note that 'interruptible' only appears in the operation structure name (and its initializers), but not in the primary operation functions.

However, there is no way to consistently combine these two patterns for a multi-part interruptible sign/verify interface.

The data structure naming is OK:

psa_sign_message_interruptible_operation_t

The pattern of using 'complete' for 'try and finish an interruptible operation' suggests we have:

psa_sign_message_complete(op, [outbuf] sig)

But then, we have trouble with choosing a suitable verb for some of the processing functions:

• Do we 'setup' or 'start' an interruptible multi-part operation?

And we have name-collision problems with the others:

• psa_sign_message_update() and psa_sign_message_abort() are already taken and work with the psa_sign_message_operation_t type.

Analysis

There are a number of non-functional concerns for designing these APIs:

1. Consistency of the API for different types of interruptible operations
2. Consistency of the API between interruptible and non-interruptible forms of the same operation
3. Where is the best place to add the qualifier 'interruptible' to the identifiers?
4. There is a risk of creating some very long identifiers, which hinders code readability
5. Long identifier names must still be distinguishable in their first 31 characters; C99 does not require an implementation to support more than 31 character external identifiers (although many do)

All of the straight-forward approaches to extending the Mbed TLS beta API for the other use cases fails, sometimes badly, on more than one of these issues. We probably need to define something slightly different to the beta interface.

Revisiting the earlier assumption

Do we really need six different operation structures?

We could unify interruptible sign/verify-message operations with interruptible sign/verify-hash operations. During a message-signing operation, while processing the message, the operation structure needs to contain a hash context but no interrupted-asymmetric-operation state, and in practice the hash context is smaller (e.g. 208 bytes for SHA-512).

So interruptible sign could follow the following pattern:

• Setup from key, algorithm.
• Complete setup in a loop until not INCOMPLETE.
• Either:
  • input hash; or
  • update in a loop over the input message.
• Complete signature in a loop until not INCOMPLETE.
• Permit abort at any time.

Interruptible verify is similar, but before complete you need an additional input which is the signature to verify. This needs to be supplied before the message, as some verification algorithms require elements of the signature prior to processing the message.

Proposal

Define a new set of interfaces for all three uses cases, with the interfaces for interruptible signature operations superceding the experimental API in Mbed TLS.

Multi-part message signatures

For multi-part message signature, the suggested API would be as follows:

psa_sign_message_operation_t
PSA_SIGN_MESSAGE_OPERATION_INIT
psa_sign_message_operation_init()
psa_sign_message_setup(op, key, alg)
psa_sign_message_update(op, [inbuf] msg)
psa_sign_message_finish(op, [outbuf] sig)
psa_sign_message_abort(op)

psa_verify_message_operation_t
PSA_VERIFY_MESSAGE_OPERATION_INIT
psa_verify_message_operation_init()
psa_verify_message_setup(op, key, alg, [inbuf] sig)
psa_verify_message_update(op, [inbuf] msg)
psa_verify_message_finish(op)
psa_verify_message_abort(op)

Interruptible hash & message signatures

For the interruptible API, we rework the experimental sign-hash interruptible operation to include multi-part sign-message (and similarly for verify)

psa_sign_interruptible_operation_t
PSA_SIGN_INTERRUPTIBLE_OPERATION_INIT
psa_sign_interruptible_operation_init()
psa_sign_interruptible_setup(op, key, alg)
psa_sign_interruptible_setup_complete(op)
psa_sign_interruptible_hash(op, [inbuf] hash)
psa_sign_interruptible_update(op, [inbuf] msg)
psa_sign_interruptible_complete(op, [outbuf] sig)
psa_sign_interruptible_abort(op)

psa_verify_interruptible_operation_t
PSA_VERIFY_INTERRUPTIBLE_OPERATION_INIT
psa_verify_interruptible_operation_init()
psa_verify_interruptible_setup(op, key, alg, [inbuf] sig)
psa_verify_interruptible_setup_complete(op)
psa_verify_interruptible_hash(op, [inbuf] hash)
psa_verify_interruptible_update(op, [inbuf] msg)
psa_verify_interruptible_complete(op)
psa_verify_interruptible_abort(op)

Note: the structure and naming of this API would permit Mbed TLS to continue to provide the beta interruptible sign-hash API, implemented as a thin wrapper over this proposed API.

Example usage of the interruptible sign operation

This is simplified code, to demonstrate the API flow.

1. Initialize the operation:

   psa_sign_interruptible_operation_top = {0};
   

2. Setup the signing algorithm and key:

   psa_sign_interruptible_setup(&op, key, alg);
   while (psa_sign_interruptible_setup_complete(&op) == PSA_OPERATION_INCOMPLETE)
       ;
   

3. Then either:

   1. Provide the hash:

      psa_interruptible_sign_hash(&op, &hash, hash_len)
      

   2. Or supply a message in one or more calls:

      psa_interruptible_sign_update(&op, &msg_buf, buf_len)
      

   3. Need to decide if we permit neither to be called, and we sign the empty message? - or if that is treated as a programming error (bad-state). In the latter case the empty message can be signed by calling psa_interruptible_sign_update() with a zero-length buffer.

4. To finish:

   uint8_t sig[];
   size_t sig_len;
   while (psa_interruptible_sign_complete(&op, &sig, sizeof(sig), &sig_len) == PSA_OPERATION_INCOMPLETE)
       ;
   

Any of these can return an error, in which case psa_interruptible_sign_abort(&op) must be called, as per existing multi-part operation rules.