Add temporary list of tasks for G1 and G2

Work in progress, some tasks have very explicit definitions and details
on how to execute, others much less so; some may need splitting.

These documents are temporary anyway, to give a rough idea of the work
remaining to reach those goals (both of which we started, but only for
some use case so far). Ultimately the result will be actionable and
estimated tasks on github.

Signed-off-by: Manuel Pégourié-Gonnard <manuel.pegourie-gonnard@arm.com>

docs/architecture/psa-migration/tasks-g1.md

@@ -0,0 +1,152 @@
+This document is temporary; it lists tasks to achieve G1 as described in
+`strategy.md` while the strategy is being reviewed - once that's done,
+corresponding github issues will be created and this document removed.
+
+For all of the tasks here, no specific testing is expected to be required,
+beyond passing the existing tests in a build with `MBEDTLS_USE_PSA_ENABLED`,
+see `testing.md`.
+
+Symmetric crypto
+================
+
+Hashes
+------
+
+### Use `psa_hash` in all of X.509
+
+Conditionally on `MBEDTLS_USE_PSA_CRYPTO`, replace all remaining calls to
+`mbedtls_md()` or `mbedtls_sha1_ret()` by calls `psa_hash` functions, namely:
+- replace `mbedtls_md()` in `x509_crt_verifycrl()` in `x509_crt.c`
+- replace `mbedtls_md()` in `mbedtls_x509write_crt_der()` in `x509write_crt.c`
+- replace `mbedtls_sha1_ret() in
+  `mbedtls_x509write_crt_set_subject_key_identifier()` in `x509write_crt.c`
+- replace `mbedtls_sha1_ret() in
+  `mbedtls_x509write_crt_set_authority_key_identifier()` in `x509write_crt.c`
+- already done in `x509_crt_check_signature()` in `x509_crt.c`, but might
+  want to replace multi-part with single-part.
+- already done in `mbedtls_x509write_csr_der_internal()` in
+  `x509write_csr.c`, but might want to replace multi-part with single-part.
+
+HMAC
+----
+
+### Variable-time HMAC in TLS record protection
+
+- This is about the calls to `mbedtls_md_hmac_xxx()` in
+`mbedtls_ssl_decrypt_buf()` and `mbedtls_ssl_encrypt_buf()`, but excludes the
+call in `mbedtls_ssl_cf_hmad()` (which it its own task).
+- Might need to change the `transform` structure to hold a PSA context instead
+  of an MD context. Note: might keep the MD context in parallel until the
+constant-time part is done as well.
+
+TODO: study this better so it can be estimated.
+
+### Constant-time HMAC in TLS record protection
+
+This is `mbedtls_ssl_cf_hmac()`. The PSA code might look a bit different as
+we'll probably need to store the HMAC key somewhere and compute the ipad/opad
+explicitly instead of using (the internals of) the MD layers for that.
+
+TODO: study this better so it can be estimated.
+
+Ciphers
+-------
+
+### Use PSA for all cipher operations in TLS
+
+- extend existing `mbedtls_cipher_setup_psa()` and related code to support
+  other ciphers than AES that can be used in TLS: ARIA (depends on #4959),
+Camellia, ChachaPoly.
+- extend unit-testing in `test_suite_cipher` to test those new ciphers as
+  AES-based cipher are already tested
+- remove the fallback mechanism in all places where `cipher_setup_psa()` is
+  called from TLS code
+- expand use of `run_test_psa()` in `ssl-opt.sh`
+
+Asymmetric crypto
+=================
+
+ECDSA
+-----
+
+### Make `mbedtls_pk_sign()` use PSA for ECDSA operations
+
+- This is already done with `PK_OPAQUE` contexts, but this task is about doing
+it for regulard `ECKEY`/`ECDSA` contexts.
+- May share some code (transcoding) with the exist support for `PK_OPAQUE`
+  contexts
+
+RSA signature (and verification)
+--------------------------------
+
+### Make `mbedtls_pk_sign()` use PSA for RSA operations
+
+- with regular `PK_RSA` context
+- only PKCS#1 v1.5 for this task
+- similar to what's done for ECDSA, except no need for transcoding (I think)
+
+### Make `mbedtls_pk_verify()` use PSA for RSA operations
+
+- with regular `PK_RSA` context
+- only PKCS#1 v1.5 for this task
+- similar to what's done for ECDSA, except no need for transcoding (I think)
+
+### Make `mbedtls_pk_verify_ext()` use PSA for RSA operations
+
+- with regular `PK_RSA` context
+- this is for RSA-PSS
+- similar to what's done for ECDSA, except no need for transcoding (I think)
+- acceptable to enforce that all hashes are equal in the parameters (as
+  imposed by the PSA API) and reject the signature otherwise
+- then need to check if all X.509 tests still pass, and if some don't, make
+  them depend on `!MBEDTLS_USE_PSA_CRYPTO`
+
+RISK: see `psa-limitations.md`
+
+RSA en/decryption
+-----------------
+
+### Make `mbedtls_pk_encrypt()` use PSA for RSA operations
+
+- with regular `PK_RSA` context
+
+### Make `mbedtls_pk_decrypt()` use PSA for RSA operations
+
+- with regular `PK_RSA` context
+
+ECDH
+----
+
+### Write remaining utilities for ECDH parsing/writing
+
+- PSA only provides an API for the operation, need to parse and write
+  parameters and public keys to/from grp ID + string of bytes
+- need to complete what was done in 4a.1
+- testing: positive: extract known-good inputs/outputs from actual handshakes?
+- testing: negative: manipulate known-good input to make it invalid
+
+Note: future task in this section depend on this one, but not on each other.
+
+### Use PSA for ECDHE in ECDHE-ECDSA and ECDHE-RSA server-side
+
+- may need to separate branches from other ECDHE-based key exchanges
+- only server-side (client-side is already done, can be used for inspiration)
+
+### Use PSA for ECDH in ECDHE-PSK (all sides and versions)
+
+- only with non-opaque PSK (support for opaque PSK here is part of G2)
+
+### Use PSA for ECDH in static-ECDH key exchanges
+
+- may require additional utility functions to load from cert to PSA
+
+FFDH
+----
+
+This may be hard, see `psa-limitations.md`
+
+EC J-PAKE
+---------
+
+Use PSA for all EC J-PAKE operations in TLS (both sides).
+(TODO: consider how this could be split.)

docs/architecture/psa-migration/tasks-g2.md

@@ -0,0 +1,80 @@
+This document is temporary; it lists tasks to achieve G2 as described in
+`strategy.md` while the strategy is being reviewed - once that's done,
+corresponding github issues will be created and this document removed.
+
+For all of the tasks here, specific testing (integration and unit test depending
+on the task) is required, see `testing.md`.
+
+RSA Signature operations
+========================
+
+In PK
+-----
+
+### Modify existing `PK_OPAQUE` type to allow for RSA keys
+
+- the following must work and be tested: `mbedtls_pk_get_type()`,
+  `mbedtls_pk_get_name()`, `mbedtls_pk_get_bitlen()`, `mbedtls_pk_get_len()`,
+`mbedtls_pk_can_do()`.
+- most likely adapt `pk_psa_genkey()` in `test_suite_pk.function`.
+- all other function (sign, verify, encrypt, decrypt, check pair, debug) will
+  return `MBEDTLS_ERR_PK_TYPE_MISMATCH` and this will be tested too.
+
+### Modify `mbedtls_pk_wrap_as_opaque()` to work with RSA.
+
+- OK to have policy hardcoded on signing with PKCS1v1.5, or allow more if
+  available at this time
+
+### Modify `mbedtls_pk_write_pubkey_der()` to work with RSA-opaque.
+
+- OK to just test that a generated key (with `pk_psa_genkey()`) can be
+  written, without checking for correctness of the result - this will be
+tested as part of another task
+
+### Make `mbedtls_pk_sign()` work with RSA-opaque.
+
+- testing may extend `pk_psa_sign()` in `test_suite_pk_function` by adding
+  selector for ECDSA/RSA.
+
+In X.509
+--------
+
+### Test using RSA-opaque for CSR generation
+
+- similar to what's already done with ECDSA-opaque
+
+### Test using opaque keys for Certificate generation
+
+- similar to what's done with testing CSR generation
+- should test both RSA and ECDSA as ECDSA is not tested yet
+- might require slight code adaptations, even if unlikely
+
+
+In TLS
+------
+
+### Test using RSA-opaque for TLS client auth
+
+- similar to what's already done with ECDSA-opaque
+
+### Test using RSA-opaque for TLS server auth
+
+- similar to what's already done with ECDSA-opaque
+- key exchanges: ECDHE-RSA and DHE-RSA
+
+RSA decrypt
+===========
+
+### Extend `PK_OPAQUE` to allow RSA decryption (PKCS1 v1.5)
+
+### Test using that in TLS for RSA and RSA-PSK key exchange.
+
+Support opaque PSKs for "mixed-PSK" key exchanges
+=================================================
+
+See `PSA-limitations.md`.
+
+Possible split:
+- one task to extend PSA (see `PSA-limitations.md`)
+- then one task per handshake: DHE-PSK, ECDHE-PSK, RSA-PSK (with tests for
+  each)