Document test strategy for USE_PSA_CRYPTO
Note: removed `mbedtls_x509write_crt_set_subject_key()` from the list of
things that should be tested, as it's taking public key rather than a
keypair.
Signed-off-by: Manuel Pégourié-Gonnard <manuel.pegourie-gonnard@arm.com>
diff --git a/docs/architecture/psa-migration/testing.md b/docs/architecture/psa-migration/testing.md
new file mode 100644
index 0000000..754686b
--- /dev/null
+++ b/docs/architecture/psa-migration/testing.md
@@ -0,0 +1,95 @@
+Testing strategy for `MBEDTLS_USE_PSA_CRYPTO`
+=============================================
+
+This document records the testing strategy used so far in implementing
+`MBEDTLS_USE_PSA_CRYPTO`.
+
+
+General considerations
+----------------------
+
+There needs to be at least one build in `all.sh` that enables
+`MBEDTLS_USE_PSA_CRYPTO` and runs the full battery of tests. Currently that's
+ensured by the fact that `scripts/config.py full` enables
+`MBEDTLS_USE_PSA_CRYPTO`.
+
+Generally, code review is enough to ensure that PSA APIs are indeed used where
+they should be when `MBEDTLS_USE_PSA_CRYPTO` is enabled.
+
+However, when it comes to TLS, we also have the option of using debug messages
+to confirm which code path is taken. This is generaly un-necessary, except when
+a decision is made at run-time about whether to use the PSA or legacy code
+path. For example, for record protection, currently some ciphers are supported
+via PSA while some others aren't, with a run-time fallback. In this case, it's
+good to have a debug message checked by the test case to confirm that the
+right decision was made at run-time, i. e. that we didn't use the fallback for
+ciphers that are supposed to be supported.
+
+
+New APIs meant for application use
+----------------------------------
+
+For example, `mbedtls_pk_setup_opaque()` is meant to be used by applications
+in order to create PK contexts that can then be passed to existing TLS and
+X.509 APIs (which remain unchanged).
+
+In that case, we want:
+
+- unit testing of the new API and directly-related APIs - for example:
+ - in `test_suite_pk` we have a new test function `pk_psa_utils` that exercises
+ `mbedtls_pk_setup_opaque()` and checks that various utility functions
+ (`mbedtls_pk_get_type()` etc.) work and the functions that are expected to
+ fail (`mbedtls_pk_verify()` etc) return the expected error.
+ - in `test_suite_pk` we modified the existing `pk_psa_sign` test function to
+ check that signature generation works as expected
+ - in `test_suite_pkwrite` we should have a new test function checking that
+ exporting (writing out) the public part of the key works as expected and
+ that exporting the private key fails as expected.
+- integration testing of the new API with each existing API which should
+ accepts a context created this way - for example:
+ - in `programs/ssl/ssl_client2` a new option `key_opaque` that causes the
+ new API to be used, and one or more tests in `ssl-opt.sh` using that.
+ (We should have the same server-side.)
+ - in `test_suite_x509write` we have a new test function
+ `x509_csr_check_opaque()` checking integration of the new API with the
+ existing `mbedtls_x509write_csr_set_key()`.
+ (We should have something similar for
+ `mbedtls_x509write_crt_set_issuer_key()`.)
+
+For some APIs, for example with `mbedtls_ssl_conf_psk_opaque()`, unit testing
+does not make sense, so we only have integration testing.
+
+New APIs meant for internal use
+-------------------------------
+
+For example, `mbedtls_cipher_setup_psa()` is meant to be used by the TLS
+layer, but probably not directly by applications.
+
+In that case, we want:
+
+- unit testing of the new API and directly-related APIs - for example:
+ - in `test_suite_cipher`, the existing test functions `auth_crypt_tv` and
+ `test_vec_crypt` gained a new parameter `use_psa` and corresponding test
+ cases
+- integration testing:
+ - usually already covered by existing tests for higher-level modules:
+ - for example simple use of `mbedtls_cipher_setup_psa()` in TLS is already
+ covered by running the existing TLS tests in a build with
+ `MBEDTLS_USA_PSA_CRYPTO` enabled
+ - however if use of the new API in higher layers involves more logic that
+ use of the old API, specific integrations test may be required
+ - for example, the logic to fall back from `mbedtls_cipher_setup_psa()` to
+ `mbedtls_cipher_setup()` in TLS is tested by `run_test_psa` in
+ `ssl-opt.sh`.
+
+Internal changes
+----------------
+
+For example, use of PSA to compute the TLS 1.2 PRF.
+
+Changes in this category rarely require specific testing, as everything should
+be already be covered by running the existing tests in a build with
+`MBEDTLS_USE_PSA_CRYPTO` enabled.
+
+However, if additional logic is involved, or there are run-time decisions about
+whether to use the PSA or legacy code paths, specific tests might be in order.
diff --git a/docs/use-psa-crypto.md b/docs/use-psa-crypto.md
index 6ec2dca..1f554e5 100644
--- a/docs/use-psa-crypto.md
+++ b/docs/use-psa-crypto.md
@@ -60,10 +60,9 @@
- `mbedtls_x509write_csr_set_key()` to generate a CSR (certificate signature
request).
-In the TLS and X.509 API, there are two other functions which accept a key or
-keypair as a PK context: `mbedtls_x509write_crt_set_subject_key()` and
-`mbedtls_x509write_crt_set_issuer_key()`. Use of opaque contexts here probably
-works but is so far untested.
+In the TLS and X.509 API, there's one other function which accepts a keypair
+as a PK context: `mbedtls_x509write_crt_set_issuer_key()`. Use of opaque
+contexts here probably works but is so far untested.
### PSA-held (opaque) keys for TLS pre-shared keys (PSK)