lib/mbedtls
1
0
Fork 0
mirror of https://github.com/Mbed-TLS/mbedtls.git synced 2025-08-07 06:42:56 +03:00
Code Activity

Merge pull request #8937 from valeriosetti/issue8712

Browse Source 
Clarify the documentation of mbedtls_pk_setup_opaque
This commit is contained in:
Bence Szépkúti
2024-04-04 13:40:57 +00:00
committed by GitHub
parent 387aafff5b 1c7f5dea8b
commit a376f84eb1
4 changed files with 53 additions and 61 deletions
Download Patch File Download Diff File Expand all files Collapse all files

50
include/mbedtls/pk.h
View File

@@ -359,32 +359,40 @@ int mbedtls_pk_setup(mbedtls_pk_context *ctx, const mbedtls_pk_info_t *info);
#if defined(MBEDTLS_USE_PSA_CRYPTO)
/**
* \brief Initialize a PK context to wrap a PSA key.
* \brief Initialize a PK context to wrap a PSA key.
*
* \note This function replaces mbedtls_pk_setup() for contexts
* that wrap a (possibly opaque) PSA key instead of
* storing and manipulating the key material directly.
* This function creates a PK context which wraps a PSA key. The PSA wrapped
* key must be an EC or RSA key pair (DH is not suported in the PK module).
*
* \param ctx The context to initialize. It must be empty (type NONE).
* \param key The PSA key to wrap, which must hold an ECC or RSA key
* pair (see notes below).
* Under the hood PSA functions will be used to perform the required
* operations and, based on the key type, used algorithms will be:
* * EC:
* * verify, verify_ext, sign, sign_ext: ECDSA.
* * RSA:
* * sign, decrypt: use the primary algorithm in the wrapped PSA key;
* * sign_ext: RSA PSS if the pk_type is #MBEDTLS_PK_RSASSA_PSS, otherwise
* it falls back to the sign() case;
* * verify, verify_ext, encrypt: not supported.
*
* \note The wrapped key must remain valid as long as the
* wrapping PK context is in use, that is at least between
* the point this function is called and the point
* mbedtls_pk_free() is called on this context. The wrapped
* key might then be independently used or destroyed.
* In order for the above operations to succeed, the policy of the wrapped PSA
* key must allow the specified algorithm.
*
* \note This function is currently only available for ECC or RSA
* key pairs (that is, keys containing private key material).
* Support for other key types may be added later.
* Opaque PK contexts wrapping an EC keys also support \c mbedtls_pk_check_pair(),
* whereas RSA ones do not.
*
* \return \c 0 on success.
* \return #MBEDTLS_ERR_PK_BAD_INPUT_DATA on invalid input
* (context already used, invalid key identifier).
* \return #MBEDTLS_ERR_PK_FEATURE_UNAVAILABLE if the key is not an
* ECC key pair.
* \return #MBEDTLS_ERR_PK_ALLOC_FAILED on allocation failure.
* \warning The PSA wrapped key must remain valid as long as the wrapping PK
* context is in use, that is at least between the point this function
* is called and the point mbedtls_pk_free() is called on this context.
*
* \param ctx The context to initialize. It must be empty (type NONE).
* \param key The PSA key to wrap, which must hold an ECC or RSA key pair.
*
* \return \c 0 on success.
* \return #MBEDTLS_ERR_PK_BAD_INPUT_DATA on invalid input (context already
* used, invalid key identifier).
* \return #MBEDTLS_ERR_PK_FEATURE_UNAVAILABLE if the key is not an ECC or
* RSA key pair.
* \return #MBEDTLS_ERR_PK_ALLOC_FAILED on allocation failure.
*/
int mbedtls_pk_setup_opaque(mbedtls_pk_context *ctx,
const mbedtls_svc_key_id_t key);