From 0612adc0f7dec712563a8cc1b048d67131084006 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Mon, 4 Mar 2024 19:20:15 +0100 Subject: [PATCH] Document mbedtls_pk_setup_opaque and mbedtls_pk_copy_from_psa Signed-off-by: Gilles Peskine --- docs/psa-transition.md | 27 ++++++++++++++++++++++++--- 1 file changed, 24 insertions(+), 3 deletions(-) diff --git a/docs/psa-transition.md b/docs/psa-transition.md index cc81acc587..f86845bbc2 100644 --- a/docs/psa-transition.md +++ b/docs/psa-transition.md @@ -902,11 +902,32 @@ To export a PSA public key or to export the public key of a PSA key pair object, 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