mirror/mbedtls
1
0
Fork 0
mirror of https://github.com/Mbed-TLS/mbedtls.git synced 2025-02-06 12:40:02 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Document mbedtls_pk_setup_opaque and mbedtls_pk_copy_from_psa

Browse Source 
Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>
This commit is contained in:
Gilles Peskine 2024-03-04 19:20:15 +01:00
parent 9d04f0872f
commit 0612adc0f7
1 changed files with 24 additions and 3 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

27
docs/psa-transition.md
View File

@ -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