Document mbedtls_pk_setup_opaque and mbedtls_pk_copy_from_psa
Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>
diff --git a/docs/psa-transition.md b/docs/psa-transition.md
index cc81acc..f86845b 100644
--- a/docs/psa-transition.md
+++ b/docs/psa-transition.md
@@ -902,11 +902,32 @@
The export format is the same format used for `psa_import_key`, described in “[Creating keys for asymmetric cryptography](#creating-keys-for-asymmetric-cryptography)” above.
-A future extension of the PSA API will support other export formats. Until those are implemented, see “[Exporting a PK key by wrapping](#exporting-a-pk-key-by-wrapping)” for ways to use the PK module to format a PSA key.
+A future extension of the PSA API will support other export formats. Until those are implemented, see “[Exposing a PSA key via PK](#exposing-a-psa-key-via-pk)” for ways to use the PK module to format a PSA key.
-#### Exporting a PK key by wrapping
+#### Exposing a PSA key via PK
-You can wrap a PSA key object in a PK key context with `mbedtls_pk_setup_opaque`. This allows you to call functions such as `mbedtls_pk_write_key_der`, `mbedtls_pk_write_pubkey_der`, `mbedtls_pk_write_pubkey_pem`, `mbedtls_pk_write_key_pem` or `mbedtls_pk_write_pubkey` to export the key data in various formats.
+This section discusses how to use a PSA key in a context that requires a PK object, such as PK formatting functions (`mbedtls_pk_write_key_der`, `mbedtls_pk_write_pubkey_der`, `mbedtls_pk_write_pubkey_pem`, `mbedtls_pk_write_key_pem` or `mbedtls_pk_write_pubkey`), Mbed TLS X.509 functions, Mbed TLS SSL functions, or another API that involves `mbedtls_pk_context` objects. Two functions from `pk.h` help with that:
+
+* [`mbedtls_pk_copy_from_psa`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/file/pk_8h/#pk_8h_1ab8e88836fd9ee344ffe630c40447bd08) copies a PSA key into a PK object. The PSA key must be exportable. The PK object remains valid even if the PSA key is destroyed.
+* [`mbedtls_pk_setup_opaque`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/file/pk_8h/#pk_8h_1a4c04ac22ab9c1ae09cc29438c308bf05) sets up a PK object that wraps the PSA key. The PK object can only be used as permitted by the PSA key's policy. The PK object contains a reference to the PSA key identifier, therefore PSA key must not be destroyed as long as the PK object remains alive.
+
+Here is some sample code illustrating how to use the PK module to format a PSA public key or the public key of a PSA key pair.
+```
+int write_psa_pubkey(psa_key_id_t key_id,
+ unsigned char *buf, size_t size, size_t *len) {
+ mbedtls_pk_context pk;
+ mbedtls_pk_init(&pk);
+ int ret = mbedtls_pk_setup_opaque(&pk, key_id);
+ if (ret != 0) goto exit;
+ ret = mbedtls_pk_write_pubkey_der(&pk, buf, size);
+ if (ret < 0) goto exit;
+ *len = ret;
+ memmove(buf, buf + size - ret, ret);
+ ret = 0;
+exit:
+ mbedtls_pk_free(&pk);
+}
+```
### Signature operations