cuberite/polarssl
1
0
Fork 0
mirror of https://github.com/cuberite/polarssl.git synced 2025-09-09 15:22:11 -04:00
Code Issues Packages Projects Releases Wiki Activity

Document the need to call psa_crypto_init() with USE_PSA_CRYPTO

Browse Source 
When MBEDTLS_USE_PSA_CRYPTO is enabled, the application must call
psa_crypto_init() before directly or indirectly calling cipher or PK code
that will use PSA under the hood. Document this explicitly for some
functions.

To avoid clutter, this commit only documents the need to call
psa_crypto_init() in common, non-obvious cases: using a PK object that was
not constructed using PSA, X.509 processing, or setting up an SSL context.
Functions that are normally only called after such a function (for example,
using a cipher or PK context constructed from a PSA key), or where the need
for PSA is obvious because they take a key ID as argument, do not need more
explicit documentaion.

Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>
This commit is contained in:
Gilles Peskine 2023-03-07 20:22:51 +01:00
parent 40d79cef35
commit 07ae208f12
5 changed files with 53 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
include/mbedtls/pk.h
View File

@ -402,6 +402,11 @@ int mbedtls_pk_can_do(const mbedtls_pk_context *ctx, mbedtls_pk_type_t type);
* Use \c mbedtls_pk_verify_ext( MBEDTLS_PK_RSASSA_PSS, ... )
* to verify RSASSA_PSS signatures.
*
* \note If #MBEDTLS_USE_PSA_CRYPTO is enabled, the PSA crypto
* subsystem must have been initialized by calling
* psa_crypto_init() before calling this function,
* if the key might be an ECC (ECDSA) key.
*
* \note If hash_len is 0, then the length associated with md_alg
* is used instead, or an error returned if it is invalid.
*

8
include/mbedtls/ssl.h
View File

@ -1544,6 +1544,10 @@ void mbedtls_ssl_init(mbedtls_ssl_context *ssl);
* Calling mbedtls_ssl_setup again is not supported, even
* if no session is active.
*
* \note If #MBEDTLS_USE_PSA_CRYPTO is enabled, the PSA crypto
* subsystem must have been initialized by calling
* psa_crypto_init() before calling this function.
*
* \param ssl SSL context
* \param conf SSL configuration to use
*
@ -3980,6 +3984,10 @@ int mbedtls_ssl_get_session(const mbedtls_ssl_context *ssl, mbedtls_ssl_session
* in which case the datagram of the underlying transport that is
* currently being processed might or might not contain further
* DTLS records.
*
* \note If #MBEDTLS_USE_PSA_CRYPTO is enabled, the PSA crypto
* subsystem must have been initialized by calling
* psa_crypto_init() before calling this function.
*/
int mbedtls_ssl_handshake(mbedtls_ssl_context *ssl);

12
include/mbedtls/x509_crl.h
View File

@ -95,6 +95,10 @@ mbedtls_x509_crl;
/**
* \brief Parse a DER-encoded CRL and append it to the chained list
*
* \note If #MBEDTLS_USE_PSA_CRYPTO is enabled, the PSA crypto
* subsystem must have been initialized by calling
* psa_crypto_init() before calling this function.
*
* \param chain points to the start of the chain
* \param buf buffer holding the CRL data in DER format
* \param buflen size of the buffer
@ -109,6 +113,10 @@ int mbedtls_x509_crl_parse_der(mbedtls_x509_crl *chain,
*
* \note Multiple CRLs are accepted only if using PEM format
*
* \note If #MBEDTLS_USE_PSA_CRYPTO is enabled, the PSA crypto
* subsystem must have been initialized by calling
* psa_crypto_init() before calling this function.
*
* \param chain points to the start of the chain
* \param buf buffer holding the CRL data in PEM or DER format
* \param buflen size of the buffer
@ -124,6 +132,10 @@ int mbedtls_x509_crl_parse(mbedtls_x509_crl *chain, const unsigned char *buf, si
*
* \note Multiple CRLs are accepted only if using PEM format
*
* \note If #MBEDTLS_USE_PSA_CRYPTO is enabled, the PSA crypto
* subsystem must have been initialized by calling
* psa_crypto_init() before calling this function.
*
* \param chain points to the start of the chain
* \param path filename to read the CRLs from (in PEM or DER encoding)
*

20
include/mbedtls/x509_crt.h
View File

@ -283,6 +283,10 @@ extern const mbedtls_x509_crt_profile mbedtls_x509_crt_profile_suiteb;
* \brief Parse a single DER formatted certificate and add it
* to the end of the provided chained list.
*
* \note If #MBEDTLS_USE_PSA_CRYPTO is enabled, the PSA crypto
* subsystem must have been initialized by calling
* psa_crypto_init() before calling this function.
*
* \param chain The pointer to the start of the CRT chain to attach to.
* When parsing the first CRT in a chain, this should point
* to an instance of ::mbedtls_x509_crt initialized through
@ -344,6 +348,10 @@ typedef int (*mbedtls_x509_crt_ext_cb_t)(void *p_ctx,
* \brief Parse a single DER formatted certificate and add it
* to the end of the provided chained list.
*
* \note If #MBEDTLS_USE_PSA_CRYPTO is enabled, the PSA crypto
* subsystem must have been initialized by calling
* psa_crypto_init() before calling this function.
*
* \param chain The pointer to the start of the CRT chain to attach to.
* When parsing the first CRT in a chain, this should point
* to an instance of ::mbedtls_x509_crt initialized through
@ -394,6 +402,10 @@ int mbedtls_x509_crt_parse_der_with_ext_cb(mbedtls_x509_crt *chain,
* temporary ownership of the CRT buffer until the CRT
* is destroyed.
*
* \note If #MBEDTLS_USE_PSA_CRYPTO is enabled, the PSA crypto
* subsystem must have been initialized by calling
* psa_crypto_init() before calling this function.
*
* \param chain The pointer to the start of the CRT chain to attach to.
* When parsing the first CRT in a chain, this should point
* to an instance of ::mbedtls_x509_crt initialized through
@ -434,6 +446,10 @@ int mbedtls_x509_crt_parse_der_nocopy(mbedtls_x509_crt *chain,
* long as the certificates are enclosed in the PEM specific
* '-----{BEGIN/END} CERTIFICATE-----' delimiters.
*
* \note If #MBEDTLS_USE_PSA_CRYPTO is enabled, the PSA crypto
* subsystem must have been initialized by calling
* psa_crypto_init() before calling this function.
*
* \param chain The chain to which to add the parsed certificates.
* \param buf The buffer holding the certificate data in PEM or DER format.
* For certificates in PEM encoding, this may be a concatenation
@ -458,6 +474,10 @@ int mbedtls_x509_crt_parse(mbedtls_x509_crt *chain, const unsigned char *buf, si
* of failed certificates it encountered. If none complete
* correctly, the first error is returned.
*
* \note If #MBEDTLS_USE_PSA_CRYPTO is enabled, the PSA crypto
* subsystem must have been initialized by calling
* psa_crypto_init() before calling this function.
*
* \param chain points to the start of the chain
* \param path filename to read the certificates from
*

8
include/mbedtls/x509_csr.h
View File

@ -82,6 +82,10 @@ mbedtls_x509write_csr;
*
* \note CSR attributes (if any) are currently silently ignored.
*
* \note If #MBEDTLS_USE_PSA_CRYPTO is enabled, the PSA crypto
* subsystem must have been initialized by calling
* psa_crypto_init() before calling this function.
*
* \param csr CSR context to fill
* \param buf buffer holding the CRL data
* \param buflen size of the buffer
@ -96,6 +100,10 @@ int mbedtls_x509_csr_parse_der(mbedtls_x509_csr *csr,
*
* \note See notes for \c mbedtls_x509_csr_parse_der()
*
* \note If #MBEDTLS_USE_PSA_CRYPTO is enabled, the PSA crypto
* subsystem must have been initialized by calling
* psa_crypto_init() before calling this function.
*
* \param csr CSR context to fill
* \param buf buffer holding the CRL data
* \param buflen size of the buffer