Symbols ![]()
loading...
Files ![]()
loading...
mbedTLS library
mbedTLS is a library defining the following symbols:Most used functions
Name
Location
Summary
Combines a high-level and low-level error code together. This function can be called directly however it is usually called via the #MBEDTLS_ERROR_ADD macro. While a value of zero is not a negative error code, it is still an error code (that denotes success) and can be combined with both a negative error code or another value of zero.
Initialize an MPI context. This makes the MPI ready to be set or freed, but does not define a value for the MPI.
Securely zeroize a buffer The function is meant to wipe the data contained in a buffer so that it can no longer be recovered even if the program memory is later compromised. Call this function on sensitive data stored on the stack before returning from a function, and on sensitive data stored on the heap before freeing the heap object. It is extremely difficult to guarantee that calls to mbedtls_platform_zeroize() are not removed by aggressive compiler optimizations in a portable way. For this reason, Mbed TLS provides the configuration option MBEDTLS_PLATFORM_ZEROIZE_ALT, which allows users to configure mbedtls_platform_zeroize() to use a suitable implementation for their platform and needs
Get the tag and length of the element. Check for the requested tag. Updates the pointer to immediately behind the tag and length.
Securely zeroize a buffer then free it. Similar to making consecutive calls to \c mbedtls_platform_zeroize() and \c mbedtls_free(), but has code size savings, and potential for optimisation in the future. Guaranteed to be a no-op if \p buf is \c NULL and \p len is 0.
Allocate a local copy of an input buffer and copy the contents into it.
Export X into unsigned binary data, big endian. Always fills the whole buffer, which will start with zeros if the number is smaller.
This function checks if the remaining size in a buffer is greater or equal than a needed space.
This function returns the message-digest information associated with the given digest type.
Return the number of bits up to and including the most significant bit of value \c 1. * \note This is same as the one-based index of the most significant bit of value \c 1.
This function feeds an input buffer into an ongoing SHA-512 checksum calculation.
Retrieve the lifetime from key attributes. This function may be declared as `static` (i.e. without external linkage). This function may be provided as a function-like macro, but in this case it must evaluate its argument exactly once.
This function clears the internal structure of \p ctx and frees any embedded internal structure, but does not free \p ctx itself. If you have called mbedtls_md_setup() on \p ctx, you must call mbedtls_md_free() when you are no longer using the context. Calling this function if you have previously called mbedtls_md_init() and nothing else is optional. You must not call this function if you have not called mbedtls_md_init().
Copy from a local copy of an output buffer back to the original, then free the local copy.
This function initializes a message-digest context without binding it to a particular message-digest algorithm. This function should always be called first. It prepares the context for mbedtls_md_setup() for binding it to a message-digest algorithm.
Add a message fragment to a multipart hash operation. The application must call psa_hash_setup() before calling this function. If this function returns an error status, the operation enters an error state and must be aborted by calling psa_hash_abort().
Quick access to an RSA context inside a PK context. \warning This function can only be used when the type of the context, as returned by mbedtls_pk_get_type(), is #MBEDTLS_PK_RSA. Ensuring that is the caller's responsibility. Alternatively, you can check whether this function returns NULL.
Wrap a call to psa_unregister_read in the global key slot mutex. If threading is disabled, this simply calls psa_unregister_read.
Ensure that a value cannot be known at compile time.
This function frees and clears the cipher-specific context of \p ctx. Freeing \p ctx itself remains the responsibility of the caller.
Boolean "or" operation. Functionally equivalent to: \p x || \p y
Constant-time buffer comparison without branches. This is equivalent to the standard memcmp function, but is likely to be compiled to code using bitwise operations rather than a branch, such that the time taken is constant w.r.t. the data pointed to by \p a and \p b, and w.r.t. whether \p a and \p b are equal or not. It is not constant-time w.r.t. \p n . This function can be used to write constant-time code by replacing branches with bit operations using masks.
This function sets up an ECP group context from a standardized set of domain parameters.
This function initializes the specified AES context. It must be the first API called before using the context.
Retrieve entropy from the accumulator (Maximum length: MBEDTLS_ENTROPY_BLOCK_SIZE) (Thread-safe if MBEDTLS_THREADING_C is enabled)
This function initializes the CTR_DRBG context, and prepares it for mbedtls_ctr_drbg_seed() or mbedtls_ctr_drbg_free().
- The \p custom string. In addition, if you do not pass a nonce in \p custom, the sum of the entropy length and the entropy nonce length must be: - at least 24 bytes for a 128-bit strength (maximum achievable strength when using AES-128); - at least 48 bytes for a 256-bit strength (maximum achievable strength when using AES-256).
This function resets CTR_DRBG context to the state immediately after initial call of mbedtls_ctr_drbg_init().
This function extracts the message-digest size from the message-digest information structure.
Get the description of a key given its identifier and policy constraints and lock it. The key must have allow all the usage flags set in \p usage. If \p alg is nonzero, the key must allow operations with this algorithm. If \p alg is zero, the algorithm is not checked. In case of a persistent key, the function loads the description of the key into a key slot if not already done. On success, the returned key slot has been registered for reading. It is the responsibility of the caller to then unregister once they have finished reading the contents of the slot. The caller unregisters by calling psa_unregister_read() or psa_unregister_read_under_mutex(). psa_unregister_read() must be called if and only if the caller already holds the global key slot mutex (when mutexes are enabled). psa_unregister_read_under_mutex() encapsulates the unregister with mutex lock and unlock operations.
The generic cipher update function. It encrypts or decrypts using the given cipher context. Writes as many block-sized blocks of data as possible to output. Any data that cannot be written immediately is either added to the next block, or flushed when mbedtls_cipher_finish() is called. Exception: For MBEDTLS_MODE_ECB, expects a single block in size. For example, 16 Bytes for AES.
The random generator function for the PSA subsystem. This function is suitable as the `f_rng` random generator function parameter of many `mbedtls_xxx` functions. The implementation of this function depends on the configuration of the library.
Quick access to an EC context inside a PK context. \warning This function can only be used when the type of the context, as returned by mbedtls_pk_get_type(), is #MBEDTLS_PK_ECKEY, #MBEDTLS_PK_ECKEY_DH, or #MBEDTLS_PK_ECDSA. Ensuring that is the caller's responsibility. Alternatively, you can check whether this function returns NULL.
This function prepares a cipher context for use with the given cipher primitive.
Initialize a PK context with the information given and allocates the type-specific PK subcontext.
Retrieve an integer ASN.1 tag and its value. Updates the pointer to immediately behind the full tag.
After calling mbedtls_ssl_handshake() to start the SSL handshake you can call this function to check whether the handshake is over for a given SSL context. This function should be also used to determine when to stop calling mbedtls_handshake_step() for that context.
This function starts a SHA-384 or SHA-512 checksum calculation.
This function finishes the SHA-512 operation, and writes the result to the output buffer.
This function performs a scalar multiplication of a point by an integer: \p R = \p m * \p P. It is not thread-safe to use same group in multiple threads.
This function feeds an input buffer into an ongoing SHA-256 checksum calculation.
Retrieve the key type from key attributes. This function may be declared as `static` (i.e. without external linkage). This function may be provided as a function-like macro, but in this case it must evaluate its argument exactly once.
Abort a hash operation. Aborting an operation frees all associated resources except for the \p operation structure itself. Once aborted, the operation object can be reused for another operation by calling psa_hash_setup() again. You may call this function any time after the operation object has been initialized by one of the methods described in #psa_hash_operation_t. In particular, calling psa_hash_abort() after the operation has been terminated by a call to psa_hash_abort(), psa_hash_finish() or psa_hash_verify() is safe and has no effect.
This function retrieves the cipher-information structure associated with the given cipher type.
This function initializes the specified AES context. It must be the first API called before using the context.
This function gives the message-digest size associated to message-digest type.
Write an arbitrary-precision number (#MBEDTLS_ASN1_INTEGER) in ASN.1 format.
Update record layer This function roughly separates the implementation of the logic of (D)TLS from the implementation of the secure transport. The record layer takes as input an untrusted underlying transport (stream or datagram) and transforms it into a serially multiplexed, secure transport, which conceptually provides the following: (1) Three datagram based, content-agnostic transports for handshake, alert and CCS messages. (2) One stream- or datagram-based transport for application data. (3) Functionality for changing the underlying transform securing the contents. The interface to this functionality is given as follows: a Updating [Currently implemented by mbedtls_ssl_read_record] Check if and on which of the four 'ports' data is pending: Nothing, a controlling datagram of type (1), or application data (2). In any case data is present, internal buffers provide access to the data for the user to process it. Consumption of type (1) datagrams is done automatically on the next update, invalidating that the internal buffers for previous datagrams, while consumption of application data (2) is user-controlled. b Reading of application data [Currently manual adaption of ssl->in_offt pointer] As mentioned in the last paragraph, consumption of data is different from the automatic consumption of control datagrams (1) because application data is treated as a stream. c Tracking availability of application data [Currently manually through decreasing ssl->in_msglen] For efficiency and to retain datagram semantics for application data in case of DTLS, the record layer provides functionality for checking how much application data is still available in the internal buffer. d Changing the transformation securing the communication. Given an opaque implementation of the record layer in the above sense, it should be possible to implement the logic of (D)TLS on top of it without the need to know anything about the record layer's internals. This is done e.g. in all the handshake handling functions, and in the application data reading function mbedtls_ssl_read.
Read out the current state of the SHA digest loaded in the engine. If the SHA suffix padding block has been executed already, the value that is read is the SHA digest (in big endian format). Otherwise, the value that is read is an interim SHA state.
This function initializes an ECP group context without loading any domain parameters.
This function feeds an input buffer into an ongoing SHA-1 checksum calculation. \warning SHA-1 is considered a weak message digest and its use constitutes a security risk. We recommend considering stronger message digests instead.
Free referenced items in an SSL session including the peer certificate and clear memory
Boolean "and" operation. Functionally equivalent to: \p x && \p y
Read a buffer for PEM information and store the resulting data into the specified context buffers.
This function starts a SHA-224 or SHA-256 checksum calculation.
This function finishes the SHA-256 operation, and writes the result to the output buffer.
Attach and enable use of a bundle for certificate verification Attach and enable use of a bundle for certificate verification through a verification callback. If no specific bundle has been set through esp_crt_bundle_set() it will default to the bundle defined in menuconfig and embedded in the binary.
This function imports a set of core parameters into an RSA context. Any sequence of calls to this function should be followed by a call to mbedtls_rsa_complete(), which checks and completes the provided information to a ready-for-use public or private RSA key.
This function clears a GCM context and the underlying cipher sub-context.
Parse one DER-encoded or one or more concatenated PEM-encoded certificates and add them to the chained list. For CRTs in PEM encoding, the function parses permissively: if at least one certificate can be parsed, the function returns the number of certificates for which parsing failed (hence \c 0 if all certificates were parsed successfully). If no certificate could be parsed, the function returns the first (negative) error encountered during parsing. PEM encoded certificates may be interleaved by other data such as human readable descriptions of their content, as long as the certificates are enclosed in the PEM specific '-----{BEGIN/END} CERTIFICATE-----' delimiters.
Boolean "not equal" operation. Functionally equivalent to: \p x != \p y
Boolean "equals" operation. Functionally equivalent to: \p x == \p y
Unlock an engine previously locked with esp_sha_lock_engine() or esp_sha_try_lock_engine()
This function feeds an input buffer into an ongoing GCM encryption or decryption operation. You may call this function zero, one or more times to pass successive parts of the input: the plaintext to encrypt, or the ciphertext (not including the tag) to decrypt. After the last part of the input, call mbedtls_gcm_finish(). This function may produce output in one of the following ways: - Immediate output: the output length is always equal to the input length. - Buffered output: the output consists of a whole number of 16-byte blocks. If the total input length so far (not including associated data) is 16 \* *B* + *A* with *A* < 16 then the total output length is 16 \* *B*. In particular: - It is always correct to call this function with \p output_size >= \p input_length + 15. - If \p input_length is a multiple of 16 for all the calls to this function during an operation, then it is correct to use \p output_size = \p input_length.
AES-CTR buffer encryption/decryption Warning: You have to keep the maximum use of your counter in mind! Note: Due to the nature of CTR you should use the same key schedule for both encryption and decryption. So a context initialized with esp_aes_setkey_enc() for both AES_ENCRYPT and AES_DECRYPT.
Perform the SSL handshake \warning If this function returns something other than \c 0, #MBEDTLS_ERR_SSL_WANT_READ, #MBEDTLS_ERR_SSL_WANT_WRITE, #MBEDTLS_ERR_SSL_ASYNC_IN_PROGRESS or #MBEDTLS_ERR_SSL_CRYPTO_IN_PROGRESS or #MBEDTLS_ERR_SSL_RECEIVED_NEW_SESSION_TICKET or #MBEDTLS_ERR_SSL_RECEIVED_EARLY_DATA, you must stop using the SSL context for reading or writing, and either free it or call \c mbedtls_ssl_session_reset() on it before re-using it for a new connection; the current connection must be closed.
Set the certificate verification mode Default: NONE on server, REQUIRED on client MBEDTLS_SSL_VERIFY_NONE: peer certificate is not checked (default on server) (insecure on client) MBEDTLS_SSL_VERIFY_OPTIONAL: peer certificate is checked, however the handshake continues even if verification failed; mbedtls_ssl_get_verify_result() can be called after the handshake is complete. MBEDTLS_SSL_VERIFY_REQUIRED: peer *must* present a valid certificate, handshake is aborted if verification failed. (default on client)
Retrieve the key size from key attributes. This function may be declared as `static` (i.e. without external linkage). This function may be provided as a function-like macro, but in this case it must evaluate its argument exactly once.
Abort an AEAD operation. Aborting an operation frees all associated resources except for the \p operation structure itself. Once aborted, the operation object can be reused for another operation by calling psa_aead_encrypt_setup() or psa_aead_decrypt_setup() again. You may call this function any time after the operation object has been initialized as described in #psa_aead_operation_t. In particular, calling psa_aead_abort() after the operation has been terminated by a call to psa_aead_abort(), psa_aead_finish() or psa_aead_verify() is safe and has no effect.
Lock access to AES hardware unit AES hardware unit can only be used by one consumer at a time. esp_aes_xxx API calls automatically manage locking & unlocking of hardware, this function is only needed if you want to call ets_aes_xxx functions directly.
Unlock access to AES hardware unit esp_aes_xxx API calls automatically manage locking & unlocking of hardware, this function is only needed if you want to call ets_aes_xxx functions directly.
Set up a multipart hash operation. The sequence of operations to calculate a hash (message digest) is as follows: -# Allocate an operation object which will be passed to all the functions listed here. -# Initialize the operation object with one of the methods described in the documentation for #psa_hash_operation_t, e.g. #PSA_HASH_OPERATION_INIT. -# Call psa_hash_setup() to specify the algorithm. -# Call psa_hash_update() zero, one or more times, passing a fragment of the message each time. The hash that is calculated is the hash of the concatenation of these messages in order. -# To calculate the hash, call psa_hash_finish(). To compare the hash with an expected value, call psa_hash_verify(). If an error occurs at any step after a call to psa_hash_setup(), the operation will need to be reset by a call to psa_hash_abort(). The application may call psa_hash_abort() at any time after the operation has been initialized. After a successful call to psa_hash_setup(), the application must eventually terminate the operation. The following events terminate an operation: - A successful call to psa_hash_finish() or psa_hash_verify(). - A call to psa_hash_abort().
This function exports the core parameters of an RSA key. If this function runs successfully, the non-NULL buffers pointed to by \p N, \p P, \p Q, \p D, and \p E are fully written, with additional unused space filled leading by zero Bytes. Possible reasons for returning #MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED: An alternative RSA implementation is in use, which stores the key externally, and either cannot or should not export it into RAM. A SW or HW implementation might not support a certain deduction. For example, \p P, \p Q from \p N, \p D, and \p E if the former are not part of the implementation. If the function fails due to an unsupported operation, the RSA context stays intact and remains usable.
Abort a PAKE operation. Aborting an operation frees all associated resources except for the \c operation structure itself. Once aborted, the operation object can be reused for another operation by calling psa_pake_setup() again. This function may be called at any time after the operation object has been initialized as described in #psa_pake_operation_t. In particular, calling psa_pake_abort() after the operation has been terminated by a call to psa_pake_abort() or psa_pake_get_implicit_key() is safe and has no effect.
Retrieve an integer ASN.1 tag and its value. Updates the pointer to immediately behind the full tag.
Get the length of an ASN.1 element. Updates the pointer to immediately behind the length.
This function performs an ARIA single-block encryption or decryption operation. It performs encryption or decryption (depending on whether the key was set for encryption on decryption) on the input data buffer defined in the \p input parameter. mbedtls_aria_init(), and either mbedtls_aria_setkey_enc() or mbedtls_aria_setkey_dec() must be called before the first call to this API with the same context.
The length of the given slice in the key slot table.
This function associates a GCM context with a cipher algorithm and a key.
This function checks that a point is a valid public key on this curve. It only checks that the point is non-zero, has valid coordinates and lies on the curve. It does not verify that it is indeed a multiple of \c G. This additional check is computationally more expensive, is not required by standards, and should not be necessary if the group used has a small cofactor. In particular, it is useless for the NIST groups which all have a cofactor of 1.
This function finishes the SHA-1 operation, and writes the result to the output buffer. \warning SHA-1 is considered a weak message digest and its use constitutes a security risk. We recommend considering stronger message digests instead.
This function sets the padding mode, for cipher modes that use padding.
SHA-1 process data block (internal use only). \warning SHA-1 is considered a weak message digest and its use constitutes a security risk. We recommend considering stronger message digests instead.
This function feeds an input buffer into an ongoing GCM encryption or decryption operation. You may call this function zero, one or more times to pass successive parts of the input: the plaintext to encrypt, or the ciphertext (not including the tag) to decrypt. After the last part of the input, call mbedtls_gcm_finish(). This function may produce output in one of the following ways: - Immediate output: the output length is always equal to the input length. - Buffered output: the output consists of a whole number of 16-byte blocks. If the total input length so far (not including associated data) is 16 \* *B* + *A* with *A* < 16 then the total output length is 16 \* *B*. In particular: - It is always correct to call this function with \p output_size >= \p input_length + 15. - If \p input_length is a multiple of 16 for all the calls to this function during an operation, then it is correct to use \p output_size = \p input_length.
This function returns the block size of the given cipher info structure in bytes.
Finish the calculation of the hash of a message. The application must call psa_hash_setup() before calling this function. This function calculates the hash of the message formed by concatenating the inputs passed to preceding calls to psa_hash_update(). When this function returns successfully, the operation becomes inactive. If this function returns an error status, the operation enters an error state and must be aborted by calling psa_hash_abort(). \warning Applications should not call this function if they expect a specific value for the hash. Call psa_hash_verify() instead. Beware that comparing integrity or authenticity data such as hash values with a function such as \c memcmp is risky because the time taken by the comparison may leak information about the hashed data which could allow an attacker to guess a valid hash and thereby bypass security controls.
This function clears a SHA-1 context. \warning SHA-1 is considered a weak message digest and its use constitutes a security risk. We recommend considering stronger message digests instead.
This function sets padding for an already initialized RSA context.
Read and process the first round message (TLS: contents of the Client/ServerHello extension, excluding extension type and length bytes).
Read and process the second round message (TLS: contents of the Client/ServerKeyExchange).
Public function mbedtls_pk_ec() can be used to get direct access to the wrapped ecp_keypair structure pointed to the pk_ctx. However this is not ideal because it bypasses the PK module on the control of its internal structure (pk_context) fields. For backward compatibility we keep mbedtls_pk_ec() when ECP_C is defined, but we provide 2 very similar functions when only ECP_LIGHT is enabled and not ECP_C. These variants embed the "ro" or "rw" keywords in their name to make the usage of the returned pointer explicit. Of course the returned value is const or non-const accordingly.
Montgomery multiplication: X = A * B * R^-1 mod N (HAC 14.36) \p A and \p B must be in canonical form. That is, < \p N. \p X may be aliased to \p A or \p N, or even \p B (if \p AN_limbs == \p B_limbs) but may not overlap any parameters otherwise. \p A and \p B may alias each other, if \p AN_limbs == \p B_limbs. They may not alias \p N (since they must be in canonical form, they cannot == \p N).
Completely wipe a slot in memory, including its policy. Persistent storage is not affected. Sets the slot's state to PSA_SLOT_EMPTY. If multi-threading is enabled, the caller must hold the global key slot mutex.
This function initializes a SHA-1 context. \warning SHA-1 is considered a weak message digest and its use constitutes a security risk. We recommend considering stronger message digests instead.
This function starts a SHA-1 checksum calculation. \warning SHA-1 is considered a weak message digest and its use constitutes a security risk. We recommend considering stronger message digests instead.
This function initializes the specified GCM context, to make references valid, and prepares the context for mbedtls_gcm_setkey() or mbedtls_gcm_free(). The function does not bind the GCM context to a particular cipher, nor set the key. For this purpose, use mbedtls_gcm_setkey().
Add a message fragment to a multipart MAC operation. The application must call psa_mac_sign_setup() or psa_mac_verify_setup() before calling this function. If this function returns an error status, the operation enters an error state and must be aborted by calling psa_mac_abort().
Abort a cipher operation. Aborting an operation frees all associated resources except for the \p operation structure itself. Once aborted, the operation object can be reused for another operation by calling psa_cipher_encrypt_setup() or psa_cipher_decrypt_setup() again. You may call this function any time after the operation object has been initialized as described in #psa_cipher_operation_t. In particular, calling psa_cipher_abort() after the operation has been terminated by a call to psa_cipher_abort() or psa_cipher_finish() is safe and has no effect.
Return the number of bits of value \c 0 before the least significant bit of value \c 1.
Free a heap-allocated linked list presentation of an ASN.1 sequence, including the first element. There are two common ways to manage the memory used for the representation of a parsed ASN.1 sequence: - Allocate a head node `mbedtls_asn1_sequence *head` with mbedtls_calloc(). Pass this node as the `cur` argument to mbedtls_asn1_get_sequence_of(). When you have finished processing the sequence, call mbedtls_asn1_sequence_free() on `head`. - Allocate a head node `mbedtls_asn1_sequence *head` in any manner, for example on the stack. Make sure that `head->next == NULL`. Pass `head` as the `cur` argument to mbedtls_asn1_get_sequence_of(). When you have finished processing the sequence, call mbedtls_asn1_sequence_free() on `head->cur`, then free `head` itself in the appropriate manner.
Retrieve an AlgorithmIdentifier ASN.1 sequence. Updates the pointer to immediately behind the full AlgorithmIdentifier.
Free all entries in a mbedtls_asn1_named_data list.
Free all shallow entries in a mbedtls_asn1_named_data list, but do not free internal pointer targets.
Parse a single DER formatted certificate and add it to the end of the provided chained list.
Generic function to add to or replace an extension in the CRT
Write an int tag (#MBEDTLS_ASN1_INTEGER) and value in ASN.1 format.
Boolean "not" operation. Functionally equivalent to: ! \p x
Choose between a size_t value and 0. Functionally equivalent to: condition ? if1 : 0. Functionally equivalent to mbedtls_ct_size_if(condition, if1, 0) but results in smaller code size.
Boolean "greater than" operation. Functionally equivalent to: \p x > \p y
Boolean "greater or equal" operation. Functionally equivalent to: \p x >= \p y
Load the contents of a key buffer into an internal RSA representation
Load the contents of a key buffer into an internal ECP representation
This function finishes the GCM operation and generates the authentication tag. It wraps up the GCM stream, and generates the tag. The tag can have a maximum length of 16 Bytes.
Generate a random number uniformly in a range. This function generates a random number between \p min inclusive and \p N exclusive. The procedure complies with RFC 6979 §3.3 (deterministic ECDSA) when the RNG is a suitably parametrized instance of HMAC_DRBG and \p min is \c 1.
This function performs GCM encryption or decryption of a buffer. \warning When this function performs a decryption, it outputs the authentication tag and does not verify that the data is authentic. You should use this function to perform encryption only. For decryption, use mbedtls_gcm_auth_decrypt() instead.
This function finishes the GCM operation and generates the authentication tag. It wraps up the GCM stream, and generates the tag. The tag can have a maximum length of 16 Bytes.
Initialize MD5 context \warning MD5 is considered a weak message digest and its use constitutes a security risk. We recommend considering stronger message digests instead.
MD5 process buffer \warning MD5 is considered a weak message digest and its use constitutes a security risk. We recommend considering stronger message digests instead.
AES-CBC buffer encryption/decryption Length should be a multiple of the block size (16 bytes)
This function sets up an ECDH context from an EC key. It is used by clients and servers in place of the ServerKeyExchange for static ECDH, and imports ECDH parameters from the EC key information of a certificate. \see ecp.h
This function derives and exports the shared secret. This is the last function used by both TLS client and servers. \see ecp.h
Read at most 'len' application data bytes \warning If this function returns something other than a positive value, #MBEDTLS_ERR_SSL_WANT_READ, #MBEDTLS_ERR_SSL_WANT_WRITE, #MBEDTLS_ERR_SSL_ASYNC_IN_PROGRESS, #MBEDTLS_ERR_SSL_CRYPTO_IN_PROGRESS, #MBEDTLS_ERR_SSL_CLIENT_RECONNECT or #MBEDTLS_ERR_SSL_RECEIVED_NEW_SESSION_TICKET or #MBEDTLS_ERR_SSL_RECEIVED_EARLY_DATA, you must stop using the SSL context for reading or writing, and either free it or call \c mbedtls_ssl_session_reset() on it before re-using it for a new connection; the current connection must be closed.
Try to write exactly 'len' application data bytes \warning This function will do partial writes in some cases. If the return value is non-negative but less than length, the function must be called again with updated arguments: buf + ret, len - ret (if ret is the return value) until it returns a value equal to the last 'len' argument. \warning If this function returns something other than a non-negative value, #MBEDTLS_ERR_SSL_WANT_READ, #MBEDTLS_ERR_SSL_WANT_WRITE, #MBEDTLS_ERR_SSL_ASYNC_IN_PROGRESS, #MBEDTLS_ERR_SSL_CRYPTO_IN_PROGRESS or #MBEDTLS_ERR_SSL_RECEIVED_NEW_SESSION_TICKET or #MBEDTLS_ERR_SSL_RECEIVED_EARLY_DATA, you must stop using the SSL context for reading or writing, and either free it or call \c mbedtls_ssl_session_reset() on it before re-using it for a new connection; the current connection must be closed.
Load reasonable default SSL configuration values. (You need to call mbedtls_ssl_config_init() first.)
This function processes a single data block within the ongoing SHA-256 computation. This function is for internal use only.
This function returns the block size of the given cipher in bytes.
This function processes a single data block within the ongoing SHA-512 computation. This function is for internal use only.
Abort a MAC operation. Aborting an operation frees all associated resources except for the \p operation structure itself. Once aborted, the operation object can be reused for another operation by calling psa_mac_sign_setup() or psa_mac_verify_setup() again. You may call this function any time after the operation object has been initialized by one of the methods described in #psa_mac_operation_t. In particular, calling psa_mac_abort() after the operation has been terminated by a call to psa_mac_abort(), psa_mac_sign_finish() or psa_mac_verify_finish() is safe and has no effect.
Abort a key derivation operation. Aborting an operation frees all associated resources except for the \c operation structure itself. Once aborted, the operation object can be reused for another operation by calling psa_key_derivation_setup() again. This function may be called at any time after the operation object has been initialized as described in #psa_key_derivation_operation_t. In particular, it is valid to call psa_key_derivation_abort() twice, or to call psa_key_derivation_abort() on an operation that has not been set up.
When the MBEDTLS_GCM_NON_AES_CIPHER_SOFT_FALLBACK is defined, for non-AES GCM operations we need to fallback to the software function definitions of the mbedtls GCM layer. Thus in this case we need declarations for the software funtions. Please refer mbedtls/include/mbedtls/gcm.h for function documentations
Perform a multiplication of an MPI with an unsigned integer: X = A * b
Perform a safe conditional copy of MPI which doesn't reveal whether the condition was true or not. \warning If \p assign is neither 0 nor 1, the result of this function is indeterminate, and the resulting value in \p X might be neither its original value nor the value in \p Y.
This function exports a point as a TLS ECPoint record defined in RFC 4492, Section 5.4.
This function checks if a context contains at least an RSA public key. If the function runs successfully, it is guaranteed that enough information is present to perform an RSA public key operation using mbedtls_rsa_public().
Generate and write the first round message (TLS: contents of the Client/ServerHello extension, excluding extension type and length bytes).
Generate and write the second round message (TLS: contents of the Client/ServerKeyExchange).
This clears an ECJPAKE context and frees any embedded data structure.
Store the certificate DN in printable form into buf; no more than size characters will be written.
Write an AlgorithmIdentifier sequence in ASN.1 format.
Free referenced items in an SSL transform context and clear memory
Return \c mbedtls_ecp_group_id for the specified TLS ID.
Choose between an unsigned value and 0. Functionally equivalent to: condition ? if1 : 0. Functionally equivalent to mbedtls_ct_uint_if(condition, if1, 0) but results in smaller code size.
Perform a fixed-size multiply accumulate operation: X += b * A \p X may be aliased to \p A (when \p X_limbs == \p A_limbs), but may not otherwise overlap. This function operates modulo `2^(biL*X_limbs)`.
This function resets HMAC_DRBG context to the state immediately after initial call of mbedtls_hmac_drbg_init().
Abort a cipher operation. Aborting an operation frees all associated resources except for the \p operation structure itself. Once aborted, the operation object can be reused for another operation.
This function feeds an input buffer as associated data (authenticated but not encrypted data) in a GCM encryption or decryption operation. Call this function after mbedtls_gcm_starts() to pass the associated data. If the associated data is empty, you do not need to call this function. You may not call this function after calling mbedtls_cipher_update().
This function performs GCM encryption or decryption of a buffer.
This function performs multiplication and addition of two points by integers: \p R = \p m * \p P + \p n * \p Q It is not thread-safe to use same group in multiple threads.
Write an OID tag (#MBEDTLS_ASN1_OID) and data in ASN.1 format.
This function starts a GCM encryption or decryption operation.
MD5 final digest \warning MD5 is considered a weak message digest and its use constitutes a security risk. We recommend considering stronger message digests instead.
This function initializes the specified AES XTS context. It must be the first API called before using the context.
AES-CFB128 buffer encryption/decryption. Note: Due to the nature of CFB you should use the same key schedule for both encryption and decryption. So a context initialized with esp_aes_setkey_enc() for both AES_ENCRYPT and AES_DECRYPT.
This function calculates the SHA-512 or SHA-384 checksum of a buffer. The function allocates the context, performs the calculation, and frees the context. The SHA-512 result is calculated as output = SHA-512(input buffer).
This function starts a new CMAC computation by setting the CMAC key, and preparing to authenticate the input data. It must be called with an initialized cipher context. Once this function has completed, data can be supplied to the CMAC computation by calling mbedtls_cipher_cmac_update(). To start a CMAC computation using the same key as a previous CMAC computation, use mbedtls_cipher_cmac_finish().
This function feeds an input buffer into an ongoing CMAC computation. The CMAC computation must have previously been started by calling mbedtls_cipher_cmac_starts() or mbedtls_cipher_cmac_reset(). Call this function as many times as needed to input the data to be authenticated. Once all of the required data has been input, call mbedtls_cipher_cmac_finish() to obtain the result of the CMAC operation.
This function finishes an ongoing CMAC operation, and writes the result to the output buffer. It should be followed either by mbedtls_cipher_cmac_reset(), which starts another CMAC operation with the same key, or mbedtls_cipher_free(), which clears the cipher context.
Read at most 'len' characters. If no error occurs, the actual amount read is returned.
This function implements the AES-CMAC-PRF-128 pseudorandom function, as defined in RFC-4615: The Advanced Encryption Standard-Cipher-based Message Authentication Code-Pseudo-Random Function-128 (AES-CMAC-PRF-128) Algorithm for the Internet Key Exchange Protocol (IKE).
Initialize an SSL context Just makes the context ready for mbedtls_ssl_setup() or mbedtls_ssl_free()
Set up an SSL context for use \warning The conf structure will be accessed during the session. It must not be modified or freed as long as the session is active. \warning This function must be called exactly once per context. Calling mbedtls_ssl_setup again is not supported, even if no session is active.
Set the underlying BIO callbacks for write, read and read-with-timeout.
Initialize an SSL configuration context Just makes the context ready for mbedtls_ssl_config_defaults() or mbedtls_ssl_config_free().
This function initializes the CCM context set in the \p ctx parameter and sets the encryption key.
This function feeds an input buffer as associated data (authenticated but not encrypted data) in a GCM encryption or decryption operation. Call this function after mbedtls_gcm_starts() to pass the associated data. If the associated data is empty, you do not need to call this function. You may not call this function after calling mbedtls_cipher_update().
mbedtls_gcm_context::buf contains the partial state of the computation of the authentication tag. mbedtls_gcm_context::add_len and mbedtls_gcm_context::len indicate different stages of the computation: * len == 0 && add_len == 0: initial state * len == 0 && add_len % 16 != 0: the first `add_len % 16` bytes have a partial block of AD that has been xored in but not yet multiplied in. * len == 0 && add_len % 16 == 0: the authentication tag is correct if the data ends now. * len % 16 != 0: the first `len % 16` bytes have a partial block of ciphertext that has been xored in but not yet multiplied in. * len > 0 && len % 16 == 0: the authentication tag is correct if the data ends now.
The generic all-in-one encryption/decryption function, for all ciphers except AEAD constructs.
Perform a safe conditional swap which doesn't reveal whether the condition was true or not. \warning If \p swap is neither 0 nor 1, the result of this function is indeterminate, and both \p X and \p Y might end up with values different to either of the original ones.
This function retrieves the information defined in mbedtls_ecp_curve_info() for all supported curves.
This function performs multiplication of a point by an integer: \p R = \p m * \p P in a restartable way. \see mbedtls_ecp_mul()
This function checks if a context contains an RSA private key and perform basic consistency checks. \warning This function should catch accidental misconfigurations like swapping of parameters, but it cannot establish full trust in neither the quality nor the consistency of the key material that was used to setup the given RSA context: Consistency: Imported parameters that are irrelevant for the implementation might be silently dropped. If dropped, the current function does not have access to them, and therefore cannot check them. See mbedtls_rsa_complete(). If you want to check the consistency of the entire content of a PKCS1-encoded RSA private key, for example, you should use mbedtls_rsa_validate_params() before setting up the RSA context. Additionally, if the implementation performs empirical checks, these checks substantiate but do not guarantee consistency. Quality: This function is not expected to perform extended quality assessments like checking that the prime factors are safe. Additionally, it is the responsibility of the user to ensure the trustworthiness of the source of his RSA parameters, which goes beyond what is effectively checkable by the library.
This function performs an RSA private key operation. \warning It is deprecated and a security risk to not provide a PRNG here and thereby prevent the use of blinding. Future versions of the library may enforce the presence of a PRNG.
This function retrieves the cipher-information structure associated with the given cipher ID, key size and mode.
Retrieve an AlgorithmIdentifier ASN.1 sequence with NULL or no params. Updates the pointer to immediately behind the full AlgorithmIdentifier.
Verify signature, with options. (Includes verification of the padding depending on type.)
Retrieve a boolean ASN.1 tag and its value. Updates the pointer to immediately behind the full tag.
Unallocate all data related to subject alternative name
Clear MD5 context \warning MD5 is considered a weak message digest and its use constitutes a security risk. We recommend considering stronger message digests instead.
Write a string in ASN.1 format using a specific string encoding tag.
This function writes a named bitstring tag (#MBEDTLS_ASN1_BIT_STRING) and value in ASN.1 format. As stated in RFC 5280 Appendix B, trailing zeroes are omitted when encoding named bitstrings in DER.
Convert an ECC curve identifier from the Mbed TLS encoding to PSA.
Convert an ECC curve identifier from the PSA encoding to Mbed TLS.
Boolean "less than" operation. Functionally equivalent to: \p x < \p y
Choose between two unsigned values. Functionally equivalent to: condition ? if1 : if0.
Choose between an error value and 0. The error value must be in the range [-32767..0]. Functionally equivalent to: condition ? if1 : 0. Functionally equivalent to mbedtls_ct_error_if(condition, if1, 0) but results in smaller code size.
Conditional memcpy. Functionally equivalent to: if (condition) { memcpy(dest, src1, len); } else { if (src2 != NULL) memcpy(dest, src2, len); } It will always read len bytes from src1. If src2 != NULL, it will always read len bytes from src2. If src2 == NULL, it will instead read len bytes from dest (as if src2 == dest).
Change the state of a key slot. This function changes the state of the key slot from expected_state to new state. If the state of the slot was not expected_state, the state is unchanged. If multi-threading is enabled, the caller must hold the global key slot mutex.
Test whether a lifetime designates a key in an external cryptoprocessor.
For output buffers which contain "tags" (outputs that may be checked for validity like hashes, MACs and signatures), fill the unused part of the output buffer (the whole buffer on error, the trailing part on success) with something that isn't a valid tag (barring an attack on the tag and deliberately-crafted input), in case the caller doesn't check the return status properly.
Unregister from reading a key slot. This function decrements the key slot registered reader counter by one. If the state of the slot is PSA_SLOT_PENDING_DELETION, and there is only one registered reader (the caller), this function will call psa_wipe_key_slot(). If multi-threading is enabled, the caller must hold the global key slot mutex.
This function prepares an XTS context for encryption and sets the encryption key.
This function prepares an XTS context for decryption and sets the decryption key.
This function performs a GCM authenticated decryption of a buffer.
This function copies the contents of group \p src into group \p dst.
This function returns the message-digest information from the given context.
This function performs a private RSA operation to sign a message digest using PKCS#1. It is the generic wrapper for performing a PKCS#1 signature.
This function adds the message padding, then performs an RSA operation. It is the generic wrapper for performing a PKCS#1 encryption operation.
Write a public key to a SubjectPublicKeyInfo DER structure Note: data is written at the end of the buffer! Use the return value to determine where you should start using the buffer
This function sets up the ECDH context with the information given. This function should be called after mbedtls_ecdh_init() but before mbedtls_ecdh_make_params(). There is no need to call this function before mbedtls_ecdh_read_params(). This is the first function used by a TLS server for ECDHE ciphersuites.
MD5 context setup \warning MD5 is considered a weak message digest and its use constitutes a security risk. We recommend considering stronger message digests instead.
This function calculates the SHA-224 or SHA-256 checksum of a buffer. The function allocates the context, performs the calculation, and frees the context. The SHA-256 result is calculated as output = SHA-256(input buffer).
This function generates an ECDH keypair on an elliptic curve. This function performs the first of two core computations implemented during the ECDH key exchange. The second core computation is performed by mbedtls_ecdh_compute_shared(). \see ecp.h
The generic cipher finalization function. If data still needs to be flushed from an incomplete block, the data contained in it is padded to the size of the last block, and written to the \p output buffer.
This function initializes the specified AES XTS context. It must be the first API called before using the context.
Write at most 'len' characters. If no error occurs, the actual amount read is returned.
This function returns the size of the IV or nonce for the cipher info structure, in bytes.
Declare the type of a key. This function overwrites any key type previously set in \p attributes. This function may be declared as `static` (i.e. without external linkage). This function may be provided as a function-like macro, but in this case it must evaluate each of its arguments exactly once.
Declare the size of a key. This function overwrites any key size previously set in \p attributes. This function may be declared as `static` (i.e. without external linkage). This function may be provided as a function-like macro, but in this case it must evaluate each of its arguments exactly once.
Read some data from a key derivation operation. This function calculates output bytes from a key derivation algorithm and return those bytes. If you view the key derivation's output as a stream of bytes, this function destructively reads the requested number of bytes from the stream. The operation's capacity decreases by the number of bytes read. If this function returns an error status other than #PSA_ERROR_INSUFFICIENT_DATA, the operation enters an error state and must be aborted by calling psa_key_derivation_abort().
This function performs an AES-OFB (Output Feedback Mode) encryption or decryption operation.
This function initializes the specified CCM context, to make references valid, and prepare the context for mbedtls_ccm_setkey() or mbedtls_ccm_free().
This function releases and clears the specified CCM context and underlying cipher sub-context.
This function performs a CCM authenticated decryption of a buffer.
This function starts a CCM encryption or decryption operation. This function and mbedtls_ccm_set_lengths() must be called before calling mbedtls_ccm_update_ad() or mbedtls_ccm_update(). This function can be called before or after mbedtls_ccm_set_lengths().
This function calculates the full generic CMAC on the input buffer with the provided key. The function allocates the context, performs the calculation, and frees the context. The CMAC result is calculated as output = generic CMAC(cmac key, input buffer).
Reset a key attribute structure to a freshly initialized state. You must initialize the attribute structure as described in the documentation of the type #psa_key_attributes_t before calling this function. Once the structure has been initialized, you may call this function at any time. This function frees any auxiliary resources that the structure may contain.
Import a key in binary format. This function supports any output from psa_export_key(). Refer to the documentation of psa_export_public_key() for the format of public keys and to the documentation of psa_export_key() for the format for other key types. The key data determines the key size. The attributes may optionally specify a key size; in this case it must match the size determined from the key data. A key size of 0 in \p attributes indicates that the key size is solely determined by the key data. Implementations must reject an attempt to import a key of size 0. This specification supports a single format for each key type. Implementations may support other formats as long as the standard format is supported. Implementations that support other formats should ensure that the formats are clearly unambiguous so as to minimize the risk that an invalid input is accidentally interpreted according to a different format.
Miller-Rabin primality test. \warning If \p X is potentially generated by an adversary, for example when validating cryptographic parameters that you didn't generate yourself and that are supposed to be prime, then \p rounds should be at least the half of the security strength of the cryptographic algorithm. On the other hand, if \p X is chosen uniformly or non-adversarially (as is the case when mbedtls_mpi_gen_prime calls this function), then \p rounds can be much lower.
This function resizes an MPI downwards, keeping at least the specified number of limbs. If \c X is smaller than \c nblimbs, it is resized up instead.
Export X into unsigned binary data, little endian. Always fills the whole buffer, which will end with zeros if the number is smaller.
Perform a modular reduction with respect to an integer. r = A mod b
This function generates a keypair with a configurable base point.
This function completes an RSA context from a set of imported core parameters. To setup an RSA public key, precisely \c N and \c E must have been imported. To setup an RSA private key, sufficient information must be present for the other parameters to be derivable. The default implementation supports the following: Derive \c P, \c Q from \c N, \c D, \c E. Derive \c N, \c D from \c P, \c Q, \c E. Alternative implementations need not support these. If this function runs successfully, it guarantees that the RSA context can be used for RSA operations without the risk of failure or crash. \warning This function need not perform consistency checks for the imported parameters. In particular, parameters that are not needed by the implementation might be silently discarded and left unchecked. To check the consistency of the key material, see mbedtls_rsa_check_privkey().
This function performs an RSA operation, then removes the message padding. It is the generic wrapper for performing a PKCS#1 decryption operation. \warning When \p ctx->padding is set to #MBEDTLS_RSA_PKCS_V15, mbedtls_rsa_rsaes_pkcs1_v15_decrypt() is called, which is an inherently dangerous function (CWE-242).
This function performs a PKCS#1 v2.1 PSS verification operation (RSASSA-PSS-VERIFY).
This function performs a public RSA operation and checks the message digest. This is the generic wrapper for performing a PKCS#1 verification.
This function declares the lengths of the message and additional data for a CCM encryption or decryption operation. This function and mbedtls_ccm_starts() must be called before calling mbedtls_ccm_update_ad() or mbedtls_ccm_update(). This function can be called before or after mbedtls_ccm_starts().
This function feeds an input buffer into an ongoing CCM encryption or decryption operation. You may call this function zero, one or more times to pass successive parts of the input: the plaintext to encrypt, or the ciphertext (not including the tag) to decrypt. After the last part of the input, call mbedtls_ccm_finish(). The lengths \p input_len of the data parts should eventually add up exactly to the plaintext length \c plaintext_len passed to mbedtls_ccm_set_lengths(). This function may produce output in one of the following ways: - Immediate output: the output length is always equal to the input length. - Buffered output: except for the last part of input data, the output consists of a whole number of 16-byte blocks. If the total input length so far (not including associated data) is 16 \* *B* + *A* with *A* < 16 then the total output length is 16 \* *B*. For the last part of input data, the output length is equal to the input length plus the number of bytes (*A*) buffered in the previous call to the function (if any). The function uses the plaintext length \c plaintext_len passed to mbedtls_ccm_set_lengths() to detect the last part of input data. In particular: - It is always correct to call this function with \p output_size >= \p input_len + 15. - If \p input_len is a multiple of 16 for all the calls to this function during an operation (not necessary for the last one) then it is correct to use \p output_size =\p input_len.
Write the shared key material to be passed to a Key Derivation Function as described in RFC8236.
Retrieve a bitstring ASN.1 tag without unused bits and its value. Updates the pointer to the beginning of the bit/octet string.
Save session structure as serialized data in a buffer. On client, this can be used for saving session data, potentially in non-volatile storage, for resuming later. On server, this can be used for alternative implementations of session cache or session tickets. \see mbedtls_ssl_session_load()
Check usage of certificate against keyUsage extension.
Convert the certificate DN string \p name into a linked list of mbedtls_x509_name (equivalent to mbedtls_asn1_named_data).
This function clones the state of a SHA-1 context. \warning SHA-1 is considered a weak message digest and its use constitutes a security risk. We recommend considering stronger message digests instead.
Clone (the state of) an MD5 context \warning MD5 is considered a weak message digest and its use constitutes a security risk. We recommend considering stronger message digests instead.
This function returns the given digest type associated with the PSA algorithm identifier. \warning This function does not check if the algorithm is supported, it always returns the corresponding identifier.
Free referenced items in an SSL handshake context and clear memory
This function performs an ARIA-CBC encryption or decryption operation on full blocks. It performs the operation defined in the \p mode parameter (encrypt/decrypt), on the input data buffer defined in the \p input parameter. It can be called as many times as needed, until all the input data is processed. mbedtls_aria_init(), and either mbedtls_aria_setkey_enc() or mbedtls_aria_setkey_dec() must be called before the first call to this API with the same context.
This function performs an ARIA-CFB128 encryption or decryption operation. It performs the operation defined in the \p mode parameter (encrypt or decrypt), on the input data buffer defined in the \p input parameter. For CFB, you must set up the context with mbedtls_aria_setkey_enc(), regardless of whether you are performing an encryption or decryption operation, that is, regardless of the \p mode parameter. This is because CFB mode uses the same key schedule for encryption and decryption.
This function performs an ARIA-CTR encryption or decryption operation. Due to the nature of CTR, you must use the same key schedule for both encryption and decryption operations. Therefore, you must use the context initialized with mbedtls_aria_setkey_enc() for both #MBEDTLS_ARIA_ENCRYPT and #MBEDTLS_ARIA_DECRYPT. \warning You must never reuse a nonce value with the same key. Doing so would void the encryption for the two messages encrypted with the same nonce and key. There are two common strategies for managing nonces with CTR: 1. You can handle everything as a single message processed over successive calls to this function. In that case, you want to set \p nonce_counter and \p nc_off to 0 for the first call, and then preserve the values of \p nonce_counter, \p nc_off and \p stream_block across calls to this function as they will be updated by this function. With this strategy, you must not encrypt more than 2**128 blocks of data with the same key. 2. You can encrypt separate messages by dividing the \p nonce_counter buffer in two areas: the first one used for a per-message nonce, handled by yourself, and the second one updated by this function internally. For example, you might reserve the first 12 bytes for the per-message nonce, and the last 4 bytes for internal use. In that case, before calling this function on a new message you need to set the first 12 bytes of \p nonce_counter to your chosen nonce value, the last 4 to 0, and \p nc_off to 0 (which will cause \p stream_block to be ignored). That way, you can encrypt at most 2**96 messages of up to 2**32 blocks each with the same key. The per-message nonce (or information sufficient to reconstruct it) needs to be communicated with the ciphertext and must be unique. The recommended way to ensure uniqueness is to use a message counter. An alternative is to generate random nonces, but this limits the number of messages that can be securely encrypted: for example, with 96-bit random nonces, you should not encrypt more than 2**32 messages with the same key. Note that for both strategies, sizes are measured in blocks and that an ARIA block is 16 bytes. \warning Upon return, \p stream_block contains sensitive data. Its content must not be written to insecure storage and should be securely discarded as soon as it's no longer needed.
Choose between two mbedtls_mpi_uint values. Functionally equivalent to: condition ? if1 : if0.
Calculate initialisation value for fast Montgomery modular multiplication
Return the minimum number of bits required to represent the value held in the MPI.
HMAC_DRBG context initialization. This function makes the context ready for mbedtls_hmac_drbg_seed(), mbedtls_hmac_drbg_seed_buf() or mbedtls_hmac_drbg_free().
Whether a key custom production parameters structure is the default. Calls to a key generation driver with non-default custom production parameters require a driver supporting custom production parameters.
Prepare a key slot to receive key material. This function allocates a key slot and sets its metadata. If this function fails, call psa_fail_key_creation(). This function is intended to be used as follows: -# Call psa_start_key_creation() to allocate a key slot, prepare it with the specified attributes, and in case of a volatile key assign it a volatile key identifier. -# Populate the slot with the key material. -# Call psa_finish_key_creation() to finalize the creation of the slot. In case of failure at any step, stop the sequence and call psa_fail_key_creation(). On success, the key slot's state is PSA_SLOT_FILLING. It is the responsibility of the caller to change the slot's state to PSA_SLOT_EMPTY/FULL once key creation has finished.
Finalize the creation of a key once its key material has been set. This entails writing the key to persistent storage. If this function fails, call psa_fail_key_creation(). See the documentation of psa_start_key_creation() for the intended use of this function. If the finalization succeeds, the function sets the key slot's state to PSA_SLOT_FULL, and the key slot can no longer be accessed as part of the key creation process.
Abort the creation of a key. You may call this function after calling psa_start_key_creation(), or after psa_finish_key_creation() fails. In other circumstances, this function may not clean up persistent storage. See the documentation of psa_start_key_creation() for the intended use of this function. Sets the slot's state to PSA_SLOT_EMPTY.
Abort a MAC operation using Mbed TLS. Aborting an operation frees all associated resources except for the \p operation structure itself. Once aborted, the operation object can be reused for another operation by calling mbedtls_psa_mac_sign_setup() or mbedtls_psa_mac_verify_setup() again. The PSA core may call this function any time after the operation object has been initialized by one of the methods described in #mbedtls_psa_mac_operation_t. In particular, calling mbedtls_psa_mac_abort() after the operation has been terminated by a call to mbedtls_psa_mac_abort(), mbedtls_psa_mac_sign_finish() or mbedtls_psa_mac_verify_finish() is safe and has no effect.
Abort an AEAD operation. Aborting an operation frees all associated resources except for the \p operation structure itself. Once aborted, the operation object can be reused for another operation by the PSA core by it calling mbedtls_psa_aead_encrypt_setup() or mbedtls_psa_aead_decrypt_setup() again. The PSA core may call this function any time after the operation object has been initialized as described in #mbedtls_psa_aead_operation_t. In particular, calling mbedtls_psa_aead_abort() after the operation has been terminated by a call to mbedtls_psa_aead_abort() or mbedtls_psa_aead_finish() is safe and has no effect.
Get the key buffer size required to store the key material of a key associated with an opaque driver.
Abort an Mbed TLS hash operation. Aborting an operation frees all associated resources except for the \p operation structure itself. Once aborted, the operation object can be reused for another operation by calling mbedtls_psa_hash_setup() again. You may call this function any time after the operation object has been initialized by one of the methods described in #psa_hash_operation_t. In particular, calling mbedtls_psa_hash_abort() after the operation has been terminated by a call to mbedtls_psa_hash_abort(), mbedtls_psa_hash_finish() or mbedtls_psa_hash_verify() is safe and has no effect.
Get the description of a key given its identifier and lock it. The descriptions of volatile keys and loaded persistent keys are stored in key slots. This function returns a pointer to the key slot containing the description of a key given its identifier. In case of a persistent key, the function loads the description of the key into a key slot if not already done. On success, the returned key slot has been registered for reading. It is the responsibility of the caller to call psa_unregister_read(slot) when they have finished reading the contents of the slot. On failure, `*p_slot` is set to NULL. This ensures that it is always valid to call psa_unregister_read on the returned slot.
Set the IV for a symmetric encryption or decryption operation. This function sets the IV (initialization vector), nonce or initial counter value for the encryption or decryption operation.
Encrypt or decrypt a message fragment in an active cipher operation.
Finish encrypting or decrypting a message in a cipher operation.
Write a subjectPublicKey to ASN.1 data Note: function works backwards in data buffer
This function performs a GCM authenticated decryption of a buffer.
Output = MD5( input buffer ) \warning MD5 is considered a weak message digest and its use constitutes a security risk. We recommend considering stronger message digests instead.
This function derives and exports the shared secret \c (G^Y)^X mod \c P.
This function verifies the ECDSA signature of a previously-hashed message. \see ecp.h
Write a private key to a PKCS#1 or SEC1 DER structure Note: data is written at the end of the buffer! Use the return value to determine where you should start using the buffer
This function computes the shared secret. This function performs the second of two core computations implemented during the ECDH key exchange. The first core computation is performed by mbedtls_ecdh_gen_public(). \see ecp.h
This function calculates the SHA-1 checksum of a buffer. The function allocates the context, performs the calculation, and frees the context. The SHA-1 result is calculated as output = SHA-1(input buffer). \warning SHA-1 is considered a weak message digest and its use constitutes a security risk. We recommend considering stronger message digests instead.
Reset an already initialized SSL context for re-use while retaining application-set variables, function pointers and data.
Set the list of allowed ciphersuites and the preference order. First in the list has the highest preference. For TLS 1.2, the notion of ciphersuite determines both the key exchange mechanism and the suite of symmetric algorithms to be used during and after the handshake. For TLS 1.3 (in development), the notion of ciphersuite only determines the suite of symmetric algorithms to be used during and after the handshake, while key exchange mechanisms are configured separately. In Mbed TLS, ciphersuites for both TLS 1.2 and TLS 1.3 are configured via this function. For users of TLS 1.3, there will be separate API for the configuration of key exchange mechanisms. The list of ciphersuites passed to this function may contain a mixture of TLS 1.2 and TLS 1.3 ciphersuite identifiers. This is useful if negotiation of TLS 1.3 should be attempted, but a fallback to TLS 1.2 would be tolerated. \warning The ciphersuites array \p ciphersuites is not copied. It must remain valid for the lifetime of the SSL configuration \p conf.
Set or reset the hostname to check against the received server certificate. It sets the ServerName TLS extension, too, if that extension is enabled. (client-side only) Hostname set to the one provided on success (cleared when NULL). On allocation failure hostname is cleared. On too long input failure, old hostname is unchanged.
Initialize a context Just makes the context ready to be used or freed safely.
Returns an informational string about the verification status of a certificate.
Translate an Mbed TLS error code into a string representation. The result is truncated if necessary and always includes a terminating null byte.
\def PSA_HASH_OPERATION_INIT This macro returns a suitable initializer for a hash operation object of type #psa_hash_operation_t. Return an initial value for a hash operation object.
Retrieve the key identifier from key attributes. This function may be declared as `static` (i.e. without external linkage). This function may be provided as a function-like macro, but in this case it must evaluate its argument exactly once.
Declare usage flags for a key. Usage flags are part of a key's usage policy. They encode what kind of operations are permitted on the key. For more details, refer to the documentation of the type #psa_key_usage_t. This function overwrites any usage flags previously set in \p attributes. This function may be declared as `static` (i.e. without external linkage). This function may be provided as a function-like macro, but in this case it must evaluate each of its arguments exactly once.
Declare the permitted algorithm policy for a key. The permitted algorithm policy of a key encodes which algorithm or algorithms are permitted to be used with this key. The following algorithm policies are supported: - 0 does not allow any cryptographic operation with the key. The key may be used for non-cryptographic actions such as exporting (if permitted by the usage flags). - An algorithm value permits this particular algorithm. - An algorithm wildcard built from #PSA_ALG_ANY_HASH allows the specified signature scheme with any hash algorithm. - An algorithm built from #PSA_ALG_AT_LEAST_THIS_LENGTH_MAC allows any MAC algorithm from the same base class (e.g. CMAC) which generates/verifies a MAC length greater than or equal to the length encoded in the wildcard algorithm. - An algorithm built from #PSA_ALG_AEAD_WITH_AT_LEAST_THIS_LENGTH_TAG allows any AEAD algorithm from the same base class (e.g. CCM) which generates/verifies a tag length greater than or equal to the length encoded in the wildcard algorithm. This function overwrites any algorithm policy previously set in \p attributes. This function may be declared as `static` (i.e. without external linkage). This function may be provided as a function-like macro, but in this case it must evaluate each of its arguments exactly once.
Finish the calculation of the MAC of a message. The application must call psa_mac_sign_setup() before calling this function. This function calculates the MAC of the message formed by concatenating the inputs passed to preceding calls to psa_mac_update(). When this function returns successfully, the operation becomes inactive. If this function returns an error status, the operation enters an error state and must be aborted by calling psa_mac_abort(). \warning Applications should not call this function if they expect a specific value for the MAC. Call psa_mac_verify_finish() instead. Beware that comparing integrity or authenticity data such as MAC values with a function such as \c memcmp is risky because the time taken by the comparison may leak information about the MAC value which could allow an attacker to guess a valid MAC and thereby bypass security controls.
Internal AES block encryption function (Only exposed to allow overriding it, see AES_ENCRYPT_ALT)
Internal AES block decryption function (Only exposed to allow overriding it, see AES_DECRYPT_ALT)
Derive a key from an ongoing key derivation operation with custom production parameters. See the description of psa_key_derivation_out_key() for the operation of this function with the default production parameters. Mbed TLS currently does not currently support any non-default production parameters.
Generate a key or key pair using custom production parameters. See the description of psa_generate_key() for the operation of this function with the default production parameters. In addition, this function supports the following production customizations, described in more detail in the documentation of ::psa_custom_key_parameters_t: - RSA keys: generation with a custom public exponent.
The authenticated encryption (AEAD/NIST_KW) function.
The authenticated encryption (AEAD/NIST_KW) function.
This function retrieves curve information from an internal group identifier.
This function extracts an elliptic curve group ID from a TLS ECParameters record as defined in RFC 4492, Section 5.4.
This function exports an elliptic curve as a TLS ECParameters record as defined in RFC 4492, Section 5.4.
This function performs multiplication and addition of two points by integers: \p R = \p m * \p P + \p n * \p Q in a restartable way. \see \c mbedtls_ecp_muladd()
This function checks that an \c mbedtls_mpi is a valid private key for this curve.
This function imports core RSA parameters, in raw big-endian binary format, into an RSA context. Any sequence of calls to this function should be followed by a call to mbedtls_rsa_complete(), which checks and completes the provided information to a ready-for-use public or private RSA key.
This function performs a PKCS#1 v2.1 OAEP decryption operation (RSAES-OAEP-DECRYPT).
This function performs a PKCS#1 v2.1 OAEP encryption operation (RSAES-OAEP-ENCRYPT).
This function performs a PKCS#1 v2.1 PSS signature operation (RSASSA-PSS-SIGN).
This function computes the ECDSA signature of a previously-hashed message, in a restartable way. \see ecp.h
This function computes the ECDSA signature of a previously-hashed message, in a restartable way. \see ecp.h
This function verifies the ECDSA signature of a previously-hashed message, in a restartable manner \see ecp.h
This function feeds an input buffer as associated data (authenticated but not encrypted data) in a CCM encryption or decryption operation. You may call this function zero, one or more times to pass successive parts of the additional data. The lengths \p ad_len of the data parts should eventually add up exactly to the total length of additional data \c total_ad_len passed to mbedtls_ccm_set_lengths(). You may not call this function after calling mbedtls_ccm_update().
This function finishes the CCM operation and generates the authentication tag. It wraps up the CCM stream, and generates the tag. The tag can have a maximum length of 16 Bytes.
Retrieve a bitstring ASN.1 tag and its value. Updates the pointer to immediately behind the full tag.
Set the verification callback (Optional). If set, the provided verify callback is called for each certificate in the peer's CRT chain, including the trusted root. For more information, please see the documentation of \c mbedtls_x509_crt_verify().
Load serialized session data into a session structure. On client, this can be used for loading saved sessions before resuming them with mbedtls_ssl_set_session(). On server, this can be used for alternative implementations of session cache or session tickets. \warning If a peer certificate chain is associated with the session, the serialized state will only contain the peer's end-entity certificate and the result of the chain verification (unless verification was disabled), but not the rest of the chain. \see mbedtls_ssl_session_save() \see mbedtls_ssl_set_session()
Return the (maximum) number of bytes added by the record layer: header + encryption/MAC overhead (inc. padding)
Parse a DER-encoded CRL and append it to the chained list
This function generates a public key and exports it as a TLS ClientKeyExchange payload. This is the second function used by a TLS client for ECDH(E) ciphersuites. \see ecp.h
This function parses and processes the ECDHE payload of a TLS ClientKeyExchange message. This is the third function used by a TLS server for ECDH(E) ciphersuites. (It is called after mbedtls_ecdh_setup() and mbedtls_ecdh_make_params().) \see ecp.h
Get time in milliseconds. \warning This function returns a monotonically-increasing time value from a start time that will differ from platform to platform, and possibly from run to run of the process.
Store the certificate serial in printable form into buf; no more than size characters will be written.
Check a given mbedtls_x509_time against the system time and tell if it's in the past.
Check a given mbedtls_x509_time against the system time and tell if it's in the future.
This function parses an item in the SubjectAlternativeNames extension. Please note that this function might allocate additional memory for a subject alternative name, thus mbedtls_x509_free_subject_alt_name has to be called to dispose of this additional memory afterwards. \warning The target structure contains pointers to the raw data of the parsed certificate, and its lifetime is restricted by the lifetime of the certificate.
Adds an entropy source to poll (Thread-safe if MBEDTLS_THREADING_C is enabled)
Add data to the accumulator manually (Thread-safe if MBEDTLS_THREADING_C is enabled)
This function sets the amount of entropy grabbed on each seed or reseed. The default value is #MBEDTLS_CTR_DRBG_ENTROPY_LEN.
This function sets the amount of entropy grabbed as a nonce for the initial seeding. Call this function before calling mbedtls_ctr_drbg_seed() to read a nonce from the entropy source during the initial seeding.
This function reseeds the CTR_DRBG context, that is extracts data from the entropy source.
Translate an ASN.1 OID into its numeric representation (e.g. "\x2A\x86\x48\x86\xF7\x0D" into "1.2.840.113549")
Translate EC group identifier into AlgorithmIdentifier OID, for curves that are directly encoded at this level
Return the maximum fragment length (payload, in bytes) for the output buffer. For the client, this is the configured value. For the server, it is the minimum of two - the configured value and the negotiated one. \sa mbedtls_ssl_conf_max_frag_len() \sa mbedtls_ssl_get_max_out_record_payload()
Write a boolean tag (#MBEDTLS_ASN1_BOOLEAN) and value in ASN.1 format.
Create or find a specific named_data entry for writing in a sequence or list based on the OID. If not already in there, a new entry is added to the head of the list. Warning: Destructive behaviour for the val data!
Find the preferred hash for a given signature algorithm.
Return TLS ID for the specified \c mbedtls_ecp_group_id.
Validate cipher suite against config in SSL context.
Increment a big-endian 16-byte value. This is quite performance-sensitive for AES-CTR and CTR-DRBG.
This function initializes the specified ARIA context. It must be the first API called before using the context.
Choose between two size_t values. Functionally equivalent to: condition ? if1 : if0.
Boolean not-equals operation. Functionally equivalent to: \p x != \p y
Choose between an mbedtls_mpi_uint value and 0. Functionally equivalent to: condition ? if1 : 0. Functionally equivalent to mbedtls_ct_mpi_uint_if(condition, if1, 0) but results in smaller code size.
Convert a big-endian byte array aligned to the size of mbedtls_mpi_uint into the storage form used by mbedtls_mpi.
Check if one unsigned MPI is less than another in constant time.
Perform a safe conditional copy of an MPI which doesn't reveal whether assignment was done or not.
Shift an MPI in-place right by a number of bits. Shifting by more bits than there are bit positions in \p X is valid and results in setting \p X to 0. This function's execution time depends on the value of \p count (and of course \p limbs).
Subtract two fixed-size large unsigned integers, returning the borrow. Calculate `A - B` where \p A and \p B have the same size. This function operates modulo `2^(biL*limbs)` and returns the carry (1 if there was a wraparound, i.e. if `A < B`, and 0 otherwise). \p X may be aliased to \p A or \p B, or even both, but may not overlap either otherwise.
Calculate the square of the Montgomery constant. (Needed for conversion and operations in Montgomery form.)
Convert an MPI into Montgomery form. \p X may be aliased to \p A, but may not otherwise overlap it. \p X may not alias \p N (it is in canonical form, so must be strictly less than \p N). Nor may it alias or overlap \p rr (this is unlikely to be required in practice.) This function is a thin wrapper around `mbedtls_mpi_core_montmul()` that is an alternative to calling `mbedtls_mpi_mod_raw_to_mont_rep()` when we don't want to allocate memory.
This function reseeds the HMAC_DRBG context, that is extracts data from the entropy source.
The PKCS#12 derivation function uses a password and a salt to produce pseudo-random bits for a particular "purpose". Depending on the given id, this function can produce an encryption/decryption key, an initialization vector or an integrity key.
This function creates a candidate public key from an LMOTS signature. This can then be compared to the real public key to determine the validity of the signature.
Register as a reader of a key slot. This function increments the key slot registered reader counter by one. If multi-threading is enabled, the caller must hold the global key slot mutex.
Test whether a key slot has any registered readers. If multi-threading is enabled, the caller must hold the global key slot mutex.
Get a key slot containing a transparent key and lock it. A transparent key is a key for which the key material is directly available, as opposed to a key in a secure element and/or to be used by a secure element. This is a temporary function that may be used instead of psa_get_and_lock_key_slot_with_policy() when there is no opaque key support for a cryptographic operation. On success, the returned key slot has been registered for reading. It is the responsibility of the caller to then unregister once they have finished reading the contents of the slot. The caller unregisters by calling psa_unregister_read() or psa_unregister_read_under_mutex(). psa_unregister_read() must be called if and only if the caller already holds the global key slot mutex (when mutexes are enabled). psa_unregister_read_under_mutex() encapsulates psa_unregister_read() with mutex lock and unlock operations.
Wipe key data from a slot. Preserves metadata such as the policy.
Validate the key bit size for unstructured keys.
Check whether a given key type is valid for use with a given MAC algorithm Upon successful return of this function, the behavior of #PSA_MAC_LENGTH when called with the validated \p algorithm and \p key_type is well-defined.
Copy key data (in export format) into an empty key slot. This function assumes that the slot does not contain any key material yet. On failure, the slot content is unchanged.
Add a message fragment to a multipart MAC operation using Mbed TLS. The PSA core calls mbedtls_psa_mac_sign_setup() or mbedtls_psa_mac_verify_setup() before calling this function. If this function returns an error status, the PSA core aborts the operation by calling mbedtls_psa_mac_abort().
Finish encrypting a message in an AEAD operation. The operation must have been set up by the PSA core with mbedtls_psa_aead_encrypt_setup(). This function finishes the authentication of the additional data formed by concatenating the inputs passed to preceding calls to mbedtls_psa_aead_update_ad() with the plaintext formed by concatenating the inputs passed to preceding calls to mbedtls_psa_aead_update(). This function has two output buffers: - \p ciphertext contains trailing ciphertext that was buffered from preceding calls to mbedtls_psa_aead_update(). - \p tag contains the authentication tag. Whether or not this function returns successfully, the PSA core subsequently calls mbedtls_psa_aead_abort() to deactivate the operation.
Set up a multipart hash operation using Mbed TLS routines. If an error occurs at any step after a call to mbedtls_psa_hash_setup(), the operation will need to be reset by a call to mbedtls_psa_hash_abort(). The core may call mbedtls_psa_hash_abort() at any time after the operation has been initialized. After a successful call to mbedtls_psa_hash_setup(), the core must eventually terminate the operation. The following events terminate an operation: - A successful call to mbedtls_psa_hash_finish() or mbedtls_psa_hash_verify(). - A call to mbedtls_psa_hash_abort().
Add a message fragment to a multipart Mbed TLS hash operation. The application must call mbedtls_psa_hash_setup() before calling this function. If this function returns an error status, the operation enters an error state and must be aborted by calling mbedtls_psa_hash_abort().
Finish the calculation of the Mbed TLS-calculated hash of a message. The application must call mbedtls_psa_hash_setup() before calling this function. This function calculates the hash of the message formed by concatenating the inputs passed to preceding calls to mbedtls_psa_hash_update(). When this function returns successfully, the operation becomes inactive. If this function returns an error status, the operation enters an error state and must be aborted by calling mbedtls_psa_hash_abort().
Find a free key slot and reserve it to be filled with a key. This function finds a key slot that is free, sets its state to PSA_SLOT_FILLING and then returns the slot. On success, the key slot's state is PSA_SLOT_FILLING. It is the responsibility of the caller to change the slot's state to PSA_SLOT_EMPTY/FULL once key creation has finished. If multi-threading is enabled, the caller must hold the global key slot mutex.
Get Mbed TLS cipher information given the cipher algorithm PSA identifier as well as the PSA type and size of the key to be used with the cipher algorithm.
Get Mbed TLS cipher information given the cipher algorithm PSA identifier as well as the PSA type and size of the key to be used with the cipher algorithm.
Set the key for a multipart symmetric encryption operation.
Set the key for a multipart symmetric decryption operation.
Get the description in memory of a key given its identifier and lock it. The descriptions of volatile keys and loaded persistent keys are stored in key slots. This function returns a pointer to the key slot containing the description of a key given its identifier. The function searches the key slots containing the description of the key with \p key identifier. The function does only read accesses to the key slots. The function does not load any persistent key thus does not access any storage. For volatile key identifiers, only one key slot is queried as a volatile key with identifier key_id can only be stored in slot of index ( key_id - #PSA_KEY_ID_VOLATILE_MIN ). On success, the function locks the key slot. It is the responsibility of the caller to unlock the key slot when it does not access it anymore. If multi-threading is enabled, the caller must hold the global key slot mutex.
Acquire exclusive access to the SHA shared memory block at SHA_TEXT_BASE This memory block is shared across all the SHA algorithm types. Caller should have already locked a SHA engine before calling this function. Note that it is possible to obtain exclusive access to the memory block even while it is in use by the SHA engine. Caller should use esp_sha_wait_idle() to ensure the SHA engine is not reading from the memory block in hardware. Call esp_sha_unlock_memory_block() when done.
Release exclusive access to the SHA register memory block at SHA_TEXT_BASE Caller should have already locked a SHA engine before calling this function. This function releases the critical section entered by esp_sha_lock_memory_block(). Call following esp_sha_lock_memory_block().
Generic function to add to or replace an extension in the CSR
This function reads and verifies an ECDSA signature. \see ecp.h
Perform a division with remainder of an MPI by an integer: A = Q * b + R
This function extracts the message-digest type from the message-digest information structure.
This function performs a PKCS#1 v1.5 decryption operation (RSAES-PKCS1-v1_5-DECRYPT). \warning This is an inherently dangerous function (CWE-242). Unless it is used in a side channel free and safe way (eg. implementing the TLS protocol as per 7.4.7.1 of RFC 5246), the calling code is vulnerable.
This function computes the ECDSA signature of a previously-hashed message. \see ecp.h
Perform a single step of the SSL handshake \warning Whilst in the past you may have used direct access to the context state (ssl->state) in order to ascertain when to stop calling this function and although you can still do so with something like ssl->MBEDTLS_PRIVATE(state) or by defining MBEDTLS_ALLOW_PRIVATE_ACCESS, this is now considered deprecated and could be broken in any future release. If you still find you have good reason for such direct access, then please do contact the team to explain this (raise an issue or post to the mailing list), so that we can add a solution to your problem that will be guaranteed to work in the future. \warning If this function returns something other than \c 0, #MBEDTLS_ERR_SSL_WANT_READ, #MBEDTLS_ERR_SSL_WANT_WRITE, #MBEDTLS_ERR_SSL_ASYNC_IN_PROGRESS, #MBEDTLS_ERR_SSL_CRYPTO_IN_PROGRESS or #MBEDTLS_ERR_SSL_RECEIVED_NEW_SESSION_TICKET or #MBEDTLS_ERR_SSL_RECEIVED_EARLY_DATA, you must stop using the SSL context for reading or writing, and either free it or call \c mbedtls_ssl_session_reset() on it before re-using it for a new connection; the current connection must be closed.
This function computes the ECDSA signature of a previously-hashed message, deterministic version. For more information, see RFC-6979: Deterministic Usage of the Digital Signature Algorithm (DSA) and Elliptic Curve Digital Signature Algorithm (ECDSA). \see ecp.h
This function parses the DHM parameters in a TLS ServerKeyExchange handshake message (DHM modulus, generator, and public key).
This function creates a DHM key pair and exports the raw public key in big-endian format.
This function sets up an ECDSA context from an EC key pair. \see ecp.h
Configure a key export callback. (Default: none.) This API can be used for two purposes: - Debugging: Use this API to e.g. generate an NSSKeylog file and use it to inspect encrypted traffic in tools such as Wireshark. - Application-specific export: Use this API to implement key exporters, e.g. for EAP-TLS or DTLS-SRTP.
Set the EC J-PAKE password for current handshake.
This function checks if domain parameter A of the curve is \c -3.
This function returns the mode of operation for the cipher. For example, MBEDTLS_MODE_CBC.
Retrieve the algorithm policy from key attributes. This function may be declared as `static` (i.e. without external linkage). This function may be provided as a function-like macro, but in this case it must evaluate its argument exactly once.
Return an initial value for a PAKE cipher suite object.
This function computes the ECDSA signature and writes it to a buffer, serialized as defined in RFC-4492: Elliptic Curve Cryptography (ECC) Cipher Suites for Transport Layer Security (TLS). \warning It is not thread-safe to use the same context in multiple threads. \see ecp.h
This function computes the ECDSA signature and writes it to a buffer, in a restartable way. \see \c mbedtls_ecdsa_write_signature()
This function reads and verifies an ECDSA signature, in a restartable way. \see \c mbedtls_ecdsa_read_signature()
Provide an input for key derivation or key agreement. Which inputs are required and in what order depends on the algorithm. Refer to the documentation of each key derivation or key agreement algorithm for information. This function passes direct inputs, which is usually correct for non-secret inputs. To pass a secret input, which should be in a key object, call psa_key_derivation_input_key() instead of this function. Refer to the documentation of individual step types (`PSA_KEY_DERIVATION_INPUT_xxx` values of type ::psa_key_derivation_step_t) for more information. If this function returns an error status, the operation enters an error state and must be aborted by calling psa_key_derivation_abort().
AES-CFB8 buffer encryption/decryption. Note: Due to the nature of CFB you should use the same key schedule for both encryption and decryption. So a context initialized with esp_aes_setkey_enc() for both AES_ENCRYPT and AES_DECRYPT.
Generate random bytes. \warning This function **can** fail! Callers MUST check the return status and MUST NOT use the content of the output buffer if the return status is not #PSA_SUCCESS.
Retrieve all the publicly-accessible attributes of a key.
Export a key in binary format. The output of this function can be passed to psa_import_key() to create an equivalent object. If the implementation of psa_import_key() supports other formats beyond the format specified here, the output from psa_export_key() must use the representation specified here, not the original representation. For standard key types, the output format is as follows: - For symmetric keys (including MAC keys), the format is the raw bytes of the key. - For DES, the key data consists of 8 bytes. The parity bits must be correct. - For Triple-DES, the format is the concatenation of the two or three DES keys. - For RSA key pairs (#PSA_KEY_TYPE_RSA_KEY_PAIR), the format is the non-encrypted DER encoding of the representation defined by PKCS\#1 (RFC 8017) as `RSAPrivateKey`, version 0. ``` RSAPrivateKey ::= SEQUENCE { version INTEGER, -- must be 0 modulus INTEGER, -- n publicExponent INTEGER, -- e privateExponent INTEGER, -- d prime1 INTEGER, -- p prime2 INTEGER, -- q exponent1 INTEGER, -- d mod (p-1) exponent2 INTEGER, -- d mod (q-1) coefficient INTEGER, -- (inverse of q) mod p } ``` - For elliptic curve key pairs (key types for which #PSA_KEY_TYPE_IS_ECC_KEY_PAIR is true), the format is a representation of the private value as a `ceiling(m/8)`-byte string where `m` is the bit size associated with the curve, i.e. the bit size of the order of the curve's coordinate field. This byte string is in little-endian order for Montgomery curves (curve types `PSA_ECC_FAMILY_CURVEXXX`), and in big-endian order for Weierstrass curves (curve types `PSA_ECC_FAMILY_SECTXXX`, `PSA_ECC_FAMILY_SECPXXX` and `PSA_ECC_FAMILY_BRAINPOOL_PXXX`). For Weierstrass curves, this is the content of the `privateKey` field of the `ECPrivateKey` format defined by RFC 5915. For Montgomery curves, the format is defined by RFC 7748, and output is masked according to §5. For twisted Edwards curves, the private key is as defined by RFC 8032 (a 32-byte string for Edwards25519, a 57-byte string for Edwards448). - For Diffie-Hellman key exchange key pairs (key types for which #PSA_KEY_TYPE_IS_DH_KEY_PAIR is true), the format is the representation of the private key `x` as a big-endian byte string. The length of the byte string is the private key size in bytes (leading zeroes are not stripped). - For public keys (key types for which #PSA_KEY_TYPE_IS_PUBLIC_KEY is true), the format is the same as for psa_export_public_key(). The policy on the key must have the usage flag #PSA_KEY_USAGE_EXPORT set.
Export a public key or the public part of a key pair in binary format. The output of this function can be passed to psa_import_key() to create an object that is equivalent to the public key. This specification supports a single format for each key type. Implementations may support other formats as long as the standard format is supported. Implementations that support other formats should ensure that the formats are clearly unambiguous so as to minimize the risk that an invalid input is accidentally interpreted according to a different format. For standard key types, the output format is as follows: - For RSA public keys (#PSA_KEY_TYPE_RSA_PUBLIC_KEY), the DER encoding of the representation defined by RFC 3279 §2.3.1 as `RSAPublicKey`. ``` RSAPublicKey ::= SEQUENCE { modulus INTEGER, -- n publicExponent INTEGER } -- e ``` - For elliptic curve keys on a twisted Edwards curve (key types for which #PSA_KEY_TYPE_IS_ECC_PUBLIC_KEY is true and #PSA_KEY_TYPE_ECC_GET_FAMILY returns #PSA_ECC_FAMILY_TWISTED_EDWARDS), the public key is as defined by RFC 8032 (a 32-byte string for Edwards25519, a 57-byte string for Edwards448). - For other elliptic curve public keys (key types for which #PSA_KEY_TYPE_IS_ECC_PUBLIC_KEY is true), the format is the uncompressed representation defined by SEC1 §2.3.3 as the content of an ECPoint. Let `m` be the bit size associated with the curve, i.e. the bit size of `q` for a curve over `F_q`. The representation consists of: - The byte 0x04; - `x_P` as a `ceiling(m/8)`-byte string, big-endian; - `y_P` as a `ceiling(m/8)`-byte string, big-endian. - For Diffie-Hellman key exchange public keys (key types for which #PSA_KEY_TYPE_IS_DH_PUBLIC_KEY is true), the format is the representation of the public key `y = g^x mod p` as a big-endian byte string. The length of the byte string is the length of the base prime `p` in bytes. Exporting a public key object or the public part of a key pair is always permitted, regardless of the key's usage flags.
Translate the high-level part of an Mbed TLS error code into a string representation. This function returns a const pointer to an un-modifiable string. The caller must not try to modify the string. It is intended to be used mostly for logging purposes.
Translate the low-level part of an Mbed TLS error code into a string representation. This function returns a const pointer to an un-modifiable string. The caller must not try to modify the string. It is intended to be used mostly for logging purposes.
This function retrieves the list of internal group identifiers of all supported curves in the order of preference.
This function retrieves curve information from a TLS NamedCurve value.
This function sets up an ECP group context from a TLS ECParameters record as defined in RFC 4492, Section 5.4.
This function checks that the keypair objects \p pub and \p prv have the same group and the same public point, and that the private key in \p prv is consistent with the public key.
This function retrieves padding mode of initialized RSA context.
This function retrieves hash identifier of mbedtls_md_type_t type.
This function checks a public-private RSA key pair. It checks each of the contexts, and makes sure they match.
This function performs a PKCS#1 v1.5 encryption operation (RSAES-PKCS1-v1_5-ENCRYPT).
This function performs a PKCS#1 v1.5 signature operation (RSASSA-PKCS1-v1_5-SIGN).
This function performs a PKCS#1 v1.5 verification operation (RSASSA-PKCS1-v1_5-VERIFY).
This function performs a PKCS#1 v2.1 PSS verification operation (RSASSA-PSS-VERIFY).
Library deinitialization. This function clears all data associated with the PSA layer, including the whole key store. This function is not thread safe, it wipes every key slot regardless of state and reader count. It should only be called when no slot is in use. This is an Mbed TLS extension.
Parses and splits an ASN.1 "SEQUENCE OF ". Updates the pointer to immediately behind the full sequence tag. This function allocates memory for the sequence elements. You can free the allocated memory with mbedtls_asn1_sequence_free().
Traverse an ASN.1 SEQUENCE container and call a callback for each entry. This function checks that the input is a SEQUENCE of elements that each have a "must" tag, and calls a callback function on the elements that have a "may" tag. For example, to validate that the input is a SEQUENCE of `tag1` and call `cb` on each element, use ``` mbedtls_asn1_traverse_sequence_of(&p, end, 0xff, tag1, 0, 0, cb, ctx); ``` To validate that the input is a SEQUENCE of ANY and call `cb` on each element, use ``` mbedtls_asn1_traverse_sequence_of(&p, end, 0, 0, 0, 0, cb, ctx); ``` To validate that the input is a SEQUENCE of CHOICE {NULL, OCTET STRING} and call `cb` on each element that is an OCTET STRING, use ``` mbedtls_asn1_traverse_sequence_of(&p, end, 0xfe, 0x04, 0xff, 0x04, cb, ctx); ``` The callback is called on the elements with a "may" tag from left to right. If the input is not a valid SEQUENCE of elements with a "must" tag, the callback is called on the elements up to the leftmost point where the input is invalid. \warning This function is still experimental and may change at any time.
Find a specific named_data entry in a sequence or list based on the OID.
Return the name of the ciphersuite associated with the given ID
Enable / Disable TLS 1.2 session tickets (client only, TLS 1.2 only). Enabled by default.
Return the current maximum outgoing record payload in bytes. \sa mbedtls_ssl_get_max_out_record_payload() \sa mbedtls_ssl_get_record_expansion()
Initiate an SSL renegotiation on the running connection. Client: perform the renegotiation right now. Server: request renegotiation, which will be performed during the next call to mbedtls_ssl_read() if honored by client. \warning If this function returns something other than \c 0, #MBEDTLS_ERR_SSL_WANT_READ, #MBEDTLS_ERR_SSL_WANT_WRITE, #MBEDTLS_ERR_SSL_ASYNC_IN_PROGRESS or #MBEDTLS_ERR_SSL_CRYPTO_IN_PROGRESS, you must stop using the SSL context for reading or writing, and either free it or call \c mbedtls_ssl_session_reset() on it before re-using it for a new connection; the current connection must be closed.
Get the length of the password in bytes from given inputs.
Get the length of the user id in bytes from given inputs.
Get the length of the peer id in bytes from given inputs.
Load one or more certificates and add them to the chained list. Parses permissively. If some certificates can be parsed, the result is the number of failed certificates it encountered. If none complete correctly, the first error is returned.
Restartable version of \c mbedtls_crt_verify_with_profile()
Check usage of certificate against extendedKeyUsage.
Write a built up certificate to a X509 DER structure Note: data is written at the end of the buffer! Use the return value to determine where you should start using the buffer
This function generates an EC key pair and exports its in the format used in a TLS ServerKeyExchange handshake message. This is the second function used by a TLS server for ECDHE ciphersuites. (It is called after mbedtls_ecdh_setup().) \see ecp.h
This function parses the ECDHE parameters in a TLS ServerKeyExchange handshake message. \see ecp.h
This function parses a CN string as an IP address.
Trigger an extra gather poll for the accumulator (Thread-safe if MBEDTLS_THREADING_C is enabled)
Checkup routine Verifies the integrity of the hardware entropy source provided by the function 'mbedtls_hardware_poll()'. Note this is the only hardware entropy source that is known at link time, and other entropy sources configured dynamically at runtime by the function mbedtls_entropy_add_source() will not be tested.
This function turns prediction resistance on or off. The default value is off.
This function updates a CTR_DRBG instance with additional data and uses it to generate random data. This function automatically reseeds if the reseed counter is exceeded or prediction resistance is enabled.
MD5 process data block (internal use only) \warning MD5 is considered a weak message digest and its use constitutes a security risk. We recommend considering stronger message digests instead.
Translate a string containing a dotted-decimal representation of an ASN.1 OID into its encoded form (e.g. "1.2.840.113549" into "\x2A\x86\x48\x86\xF7\x0D"). On success, this function allocates oid->buf from the heap. It must be freed by the caller using mbedtls_free().
Translate an X.509 attribute type OID into the short name (e.g. the OID for an X520 Common Name into "CN")
Translate AlgorithmIdentifier OID into an EC group identifier, for curves that are directly encoded at this level
Translate PKCS#12 PBE algorithm OID into md_type and cipher_type
Return an offset into a buffer. This is just the addition of an offset to a pointer, except that this function also accepts an offset of 0 into a buffer whose pointer is null. (`p + n` has undefined behavior when `p` is null, even when `n == 0`. A null pointer is a valid buffer pointer when the size is 0, for example as the result of `malloc(0)` on some platforms.)
Return the maximum fragment length (payload, in bytes) for the input buffer. This is the negotiated maximum fragment length, or, if there is none, MBEDTLS_SSL_IN_CONTENT_LEN. If it is not defined either, the value is 2^14. This function works as its predecessor, \c mbedtls_ssl_get_max_frag_len(). \sa mbedtls_ssl_conf_max_frag_len() \sa mbedtls_ssl_get_max_in_record_payload()
Write a NULL tag (#MBEDTLS_ASN1_NULL) with zero data in ASN.1 format.
Write a bitstring tag (#MBEDTLS_ASN1_BIT_STRING) and value in ASN.1 format.
Write an octet string tag (#MBEDTLS_ASN1_OCTET_STRING) and value in ASN.1 format.
Given an SSL context and its associated configuration, write the TLS 1.2 specific extensions of the ClientHello message.
PKCS#5 PBES2 function \warning When decrypting: - This function validates the CBC padding and returns #MBEDTLS_ERR_PKCS5_PASSWORD_MISMATCH if the padding is invalid. Note that this can help active adversaries attempting to brute-forcing the password. Note also that there is no guarantee that an invalid password will be detected (the chances of a valid padding with a random password are about 1/255).
Choose between an mbedtls_ct_condition_t and 0. Functionally equivalent to: condition ? if1 : 0. Functionally equivalent to mbedtls_ct_bool_if(condition, if1, 0) but results in smaller code size.
Choose between two mbedtls_ct_condition_t values. Functionally equivalent to: condition ? if1 : if0.
Choose between two error values. The values must be in the range [-32767..0]. Functionally equivalent to: condition ? if1 : if0.
Conditionally set a block of memory to zero. Regardless of the condition, every byte will be read once and written to once. \warning Unlike mbedtls_platform_zeroize, this does not have the same guarantees about not being optimised away if the memory is never read again.
Shift some data towards the left inside a buffer. Functionally equivalent to: memmove(start, start + offset, total - offset); memset(start + (total - offset), 0, offset); Timing independence comes at the expense of performance.
Copy data from a secret position. Functionally equivalent to: memcpy(dst, src + offset, len) This function copies \p len bytes from \p src + \p offset to \p dst, with a code flow and memory access pattern that does not depend on \p offset, but only on \p offset_min, \p offset_max and \p len.
Perform a modular exponentiation: X = A^E mod N \warning This function is not constant time with respect to \p E (the exponent).
Compare a machine integer with an MPI. This function operates in constant time with respect to the values of \p min and \p A.
Perform a safe conditional swap of two MPIs which doesn't reveal whether the swap was done or not.
Import X from unsigned binary data, little-endian. The MPI needs to have enough limbs to store the full value (including any most significant zero bytes in the input).
Import X from unsigned binary data, big-endian. The MPI needs to have enough limbs to store the full value (including any most significant zero bytes in the input).
Shift an MPI in-place left by a number of bits. Shifting by more bits than there are bit positions in \p X will produce an unspecified result. This function's execution time depends on the value of \p count (and of course \p limbs).
Add two fixed-size large unsigned integers, returning the carry. Calculates `A + B` where `A` and `B` have the same size. This function operates modulo `2^(biL*limbs)` and returns the carry (1 if there was a wraparound, and 0 otherwise). \p X may be aliased to \p A or \p B.
Perform a known-size multiplication \p X may not be aliased to any of the inputs for this function. \p A may be aliased to \p B.
Generate a random number uniformly in a range. This function generates a random number between \p min inclusive and \p N exclusive. The procedure complies with RFC 6979 §3.3 (deterministic ECDSA) when the RNG is a suitably parametrized instance of HMAC_DRBG and \p min is \c 1.
Returns the number of limbs of working memory required for a call to `mbedtls_mpi_core_exp_mod()`.
Perform a modular exponentiation with public or secret exponent: X = A^E mod N, where \p A is already in Montgomery form. \warning This function is not constant time with respect to \p E (the exponent). \p X may be aliased to \p A, but not to \p RR or \p E, even if \p E_limbs == \p AN_limbs.
Perform a modular exponentiation with secret exponent: X = A^E mod N, where \p A is already in Montgomery form. \p X may be aliased to \p A, but not to \p RR or \p E, even if \p E_limbs == \p AN_limbs.
Subtract unsigned integer from known-size large unsigned integers. Return the borrow.
Determine if a given MPI has the value \c 0 in constant time with respect to the value (but not with respect to the number of limbs).
Convert an MPI from Montgomery form. \p X may be aliased to \p A, but may not otherwise overlap it. \p X may not alias \p N (it is in canonical form, so must be strictly less than \p N). This function is a thin wrapper around `mbedtls_mpi_core_montmul()` that is an alternative to calling `mbedtls_mpi_mod_raw_from_mont_rep()` when we don't want to allocate memory.
Count leading zero bits in a given integer. \warning The result is undefined if \p a == 0
This function turns prediction resistance on or off. The default value is off.
This function updates an HMAC_DRBG instance with additional data and uses it to generate random data. This function automatically reseeds if the reseed counter is exceeded or prediction resistance is enabled.
PKCS12 Password Based function (encryption / decryption) for cipher-based and mbedtls_md-based PBE's \warning When decrypting: - This function validates the CBC padding and returns #MBEDTLS_ERR_PKCS12_PASSWORD_MISMATCH if the padding is invalid. Note that this can help active adversaries attempting to brute-forcing the password. Note also that there is no guarantee that an invalid password will be detected (the chances of a valid padding with a random password are about 1/255).
Unallocate all PKCS #7 data and zeroize the memory. It doesn't free \p pkcs7 itself. This should be done by the caller.
This function is analogue to \c mbedtls_rsa_rsassa_pss_sign(). The only difference between them is that this function is more flexible on the parameters of \p ctx that are set with \c mbedtls_rsa_set_padding().
Calculate the intersection of two algorithm usage policies. Return 0 (which allows no operation) on incompatibility.
Export a public key or the public part of a key pair in binary format.
Validate optional attributes during key creation. Some key attributes are optional during key creation. If they are specified in the attributes structure, check that they are consistent with the data in the slot. This function should be called near the end of key creation, after the slot in memory is fully populated but before saving persistent data.
Sign a message with a private key. For hash-and-sign algorithms, this includes the hashing step.
Verify the signature of a message with a public key, using a hash-and-sign verification algorithm.
Verify the signature a hash or short message using a public key.
Get the number of ops that a hash signing operation has taken for the previous call. If no call or work has taken place, this will return zero.
Get the number of ops that a hash verification operation has taken for the previous call. If no call or work has taken place, this will return zero.
Start signing a hash or short message with a private key, in an interruptible manner.
Continue and eventually complete the action of signing a hash or short message with a private key, in an interruptible manner.
Start reading and verifying a hash or short message, in an interruptible manner.
Continue and eventually complete the action of signing a hash or short message with a private key, in an interruptible manner.
Perform a key agreement and return the raw shared secret, using built-in raw key agreement functions.
Internal function for raw key agreement Calls the driver wrapper which will hand off key agreement task to the driver's implementation if a driver is present. Fallback specified in the driver wrapper is built-in raw key agreement (psa_key_agreement_raw_builtin).
Get implicitly confirmed shared secret from a PAKE.
Set up a multipart MAC calculation operation using Mbed TLS.
Set up a multipart MAC verification operation using Mbed TLS.
Finish the calculation of the MAC of a message using Mbed TLS. The PSA core calls mbedtls_psa_mac_sign_setup() before calling this function. This function calculates the MAC of the message formed by concatenating the inputs passed to preceding calls to mbedtls_psa_mac_update(). Whether this function returns successfully or not, the PSA core subsequently aborts the operation by calling mbedtls_psa_mac_abort().
Finish the calculation of the MAC of a message and compare it with an expected value using Mbed TLS. The PSA core calls mbedtls_psa_mac_verify_setup() before calling this function. This function calculates the MAC of the message formed by concatenating the inputs passed to preceding calls to mbedtls_psa_mac_update(). It then compares the calculated MAC with the expected MAC passed as a parameter to this function. Whether this function returns successfully or not, the PSA core subsequently aborts the operation by calling mbedtls_psa_mac_abort().
Set the session information for a password-authenticated key exchange.
Get output for a step of a password-authenticated key exchange.
Provide input for a step of a password-authenticated key exchange.
Set the key for a multipart authenticated encryption operation. If an error occurs at any step after a call to mbedtls_psa_aead_encrypt_setup(), the operation is reset by the PSA core by a call to mbedtls_psa_aead_abort(). The PSA core may call mbedtls_psa_aead_abort() at any time after the operation has been initialized, and is required to when the operation is no longer needed.
Set the key for a multipart authenticated decryption operation. If an error occurs at any step after a call to mbedtls_psa_aead_decrypt_setup(), the PSA core resets the operation by a call to mbedtls_psa_aead_abort(). The PSA core may call mbedtls_psa_aead_abort() at any time after the operation has been initialized, and is required to when the operation is no longer needed.
Set the nonce for an authenticated encryption or decryption operation. This function sets the nonce for the authenticated encryption or decryption operation. The PSA core calls mbedtls_psa_aead_encrypt_setup() or mbedtls_psa_aead_decrypt_setup() before calling this function. If this function returns an error status, the PSA core will call mbedtls_psa_aead_abort().
Declare the lengths of the message and additional data for AEAD. The PSA core calls this function before calling mbedtls_psa_aead_update_ad() or mbedtls_psa_aead_update() if the algorithm for the operation requires it. If the algorithm does not require it, calling this function is optional, but if this function is called then the implementation must enforce the lengths. The PSA core may call this function before or after setting the nonce with mbedtls_psa_aead_set_nonce(). - For #PSA_ALG_CCM, calling this function is required. - For the other AEAD algorithms defined in this specification, calling this function is not required. If this function returns an error status, the PSA core calls mbedtls_psa_aead_abort().
Pass additional data to an active AEAD operation. Additional data is authenticated, but not encrypted. The PSA core can call this function multiple times to pass successive fragments of the additional data. It will not call this function after passing data to encrypt or decrypt with mbedtls_psa_aead_update(). Before calling this function, the PSA core will: 1. Call either mbedtls_psa_aead_encrypt_setup() or mbedtls_psa_aead_decrypt_setup(). 2. Set the nonce with mbedtls_psa_aead_set_nonce(). If this function returns an error status, the PSA core will call mbedtls_psa_aead_abort().
Encrypt or decrypt a message fragment in an active AEAD operation. Before calling this function, the PSA core will: 1. Call either mbedtls_psa_aead_encrypt_setup() or mbedtls_psa_aead_decrypt_setup(). The choice of setup function determines whether this function encrypts or decrypts its input. 2. Set the nonce with mbedtls_psa_aead_set_nonce(). 3. Call mbedtls_psa_aead_update_ad() to pass all the additional data. If this function returns an error status, the PSA core will call mbedtls_psa_aead_abort(). This function does not require the input to be aligned to any particular block boundary. If the implementation can only process a whole block at a time, it must consume all the input provided, but it may delay the end of the corresponding output until a subsequent call to mbedtls_psa_aead_update(), mbedtls_psa_aead_finish() provides sufficient input. The amount of data that can be delayed in this way is bounded by #PSA_AEAD_UPDATE_OUTPUT_SIZE.
Calculate the hash (digest) of a message using Mbed TLS routines.
Clone an Mbed TLS hash operation. This function copies the state of an ongoing hash operation to a new operation object. In other words, this function is equivalent to calling mbedtls_psa_hash_setup() on \p target_operation with the same algorithm that \p source_operation was set up for, then mbedtls_psa_hash_update() on \p target_operation with the same input that that was passed to \p source_operation. After this function returns, the two objects are independent, i.e. subsequent calls involving one of the objects do not affect the other object.
Calculate the MAC (message authentication code) of a message using Mbed TLS.
Decrypt a short message with a private key. - For #PSA_ALG_RSA_PKCS1V15_CRYPT, no salt is supported.
Export a public RSA key or the public part of an RSA key pair in binary format.
Sign an already-calculated hash with an RSA private key.
Verify the signature a hash or short message using a public RSA key.
Encrypt a short message with a public key. - For #PSA_ALG_RSA_PKCS1V15_CRYPT, no salt is supported.
Load the public part of an internal ECP, if required.
Export an ECP public key or the public part of an ECP key pair in binary format.
Verify an ECDSA hash or short message signature.
Perform a key agreement and return the raw ECDH shared secret.
Perform a key agreement and return the FFDH shared secret.
Export a public key or the public part of a DH key pair in binary format.
Checks if persistent data is stored for the given key slot number This function checks if any key data or metadata exists for the key slot in the persistent storage.
Format key data and metadata and save to a location for given key slot. This function formats the key data and metadata and saves it to a persistent storage backend. The storage location corresponding to the key slot must be empty, otherwise this function will fail. This function should be called after loading the key into an internal slot to ensure the persistent key is not saved into a storage location corresponding to an already occupied non-persistent key, as well as ensuring the key data is validated. Note: This function will only succeed for key buffers which are not empty. If passed a NULL pointer or zero-length, the function will fail with #PSA_ERROR_INVALID_ARGUMENT.
Parses key data and metadata and load persistent key for given key slot number. This function reads from a storage backend, parses the key data and metadata and writes them to the appropriate output parameters. Note: This function allocates a buffer and returns a pointer to it through the data parameter. On successful return, the pointer is guaranteed to be valid and the buffer contains at least one byte of data. psa_free_persistent_key_data() must be called on the data buffer afterwards to zeroize and free this buffer.
Remove persistent data for the given key slot number.
Free the temporary buffer allocated by psa_load_persistent_key(). This function must be called at some point after psa_load_persistent_key() to zeroize and free the memory allocated to the buffer in that function.
Formats key data and metadata for persistent storage
Parses persistent storage data into key data and metadata
Delete all data from key slots in memory. This function is not thread safe, it wipes every key slot regardless of state and reader count. It should only be called when no slot is in use. This does not affect persistent storage.
Return a key slot to the free list. Call this function when a slot obtained from psa_reserve_free_key_slot() is no longer in use. If multi-threading is enabled, the caller must hold the global key slot mutex.
Validate a key's location. This function checks whether the key's attributes point to a location that is known to the PSA Core, and returns the driver function table if the key is to be found in an external location.
This function generates a DHM key pair and exports its public part together with the DHM parameters in the format used in a TLS ServerKeyExchange handshake message.
Get a pointer to the slot where the given volatile key is located.
Get a pointer to an entry in the persistent key cache.
Convert a single raw coordinate to DER ASN.1 format. The output der buffer is filled backward (i.e. starting from its end). \warning Raw and der buffer must not be overlapping.
Convert a single integer from ASN.1 DER format to raw. \warning Der and raw buffers must not be overlapping.
Compute RSA prime moduli P, Q from public modulus N=PQ and a pair of private and public key.
Compute RSA private exponent from prime moduli and public key.
There is a need for the value of integer N' such that B^-1(B-1)-N^-1N'=1, where B^-1(B-1) mod N=1. Actually, only the least significant part of N' is needed, hence the definition N0'=N' mod b. We reproduce below the simple algorithm from an article by Dusse and Kaliski to efficiently find N0' from N0 and b
Starts a (X * Y) Mod M calculation in hardware. Rinv and M_prime needs to be precalculated in software.
Special-case of (X * Y), where we use hardware montgomery mod multiplication to calculate result where either A or B are >2048 bits so can't use the standard multiplication method.
DigestAlgorithmIdentifier ::= AlgorithmIdentifier This is from x509.h
SignerInfo ::= SEQUENCE { version Version; issuerAndSerialNumber IssuerAndSerialNumber, digestAlgorithm DigestAlgorithmIdentifier, authenticatedAttributes [0] IMPLICIT Attributes OPTIONAL, digestEncryptionAlgorithm DigestEncryptionAlgorithmIdentifier, encryptedDigest EncryptedDigest, unauthenticatedAttributes [1] IMPLICIT Attributes OPTIONAL, Returns 0 if the signerInfo is valid. Return negative error code for failure. Structure must not contain vales for authenticatedAttributes and unauthenticatedAttributes.
Write a CSR (Certificate Signing Request) to a DER structure Note: data is written at the end of the buffer! Use the return value to determine where you should start using the buffer
Set the Diffie-Hellman public P and G values from big-endian binary presentations. (Default values: MBEDTLS_DHM_RFC3526_MODP_2048_[PG]_BIN)
Platform-specific implementation of gmtime_r() The function is a thread-safe abstraction that behaves similarly to the gmtime_r() function from Unix/POSIX. Mbed TLS will try to identify the underlying platform and make use of an appropriate underlying implementation (e.g. gmtime_r() for POSIX and gmtime_s() for Windows). If this is not possible, then gmtime() will be used. In this case, calls from the library to gmtime() will be guarded by the mutex mbedtls_threading_gmtime_mutex if MBEDTLS_THREADING_C is enabled. It is recommended that calls from outside the library are also guarded by this mutex. If MBEDTLS_PLATFORM_GMTIME_R_ALT is defined, then Mbed TLS will unconditionally use the alternative implementation for mbedtls_platform_gmtime_r() supplied by the user at compile time.
This function retrieves curve information from a human-readable name.
Enable / Disable renegotiation support for connection when initiated by peer (Default: MBEDTLS_SSL_RENEGOTIATION_DISABLED) \warning It is recommended to always disable renegotiation unless you know you need it and you know what you're doing. In the past, there have been several issues associated with renegotiation or a poor understanding of its properties.
Return the number of application data bytes remaining to be read from the current record.
Verify a chain of certificates. The verify callback is a user-supplied callback that can clear / modify / add flags for a certificate. If set, the verification callback is called for each certificate in the chain (from the trust-ca down to the presented crt). The parameters for the callback are: (void *parameter, mbedtls_x509_crt *crt, int certificate_depth, int *flags). With the flags representing current flags for that specific certificate and the certificate depth from the bottom (Peer cert depth = 0). All flags left after returning from the callback are also returned to the application. The function should return 0 for anything (including invalid certificates) other than fatal error, as a non-zero return code immediately aborts the verification process. For fatal errors, a specific error code should be used (different from MBEDTLS_ERR_X509_CERT_VERIFY_FAILED which should not be returned at this point), or MBEDTLS_ERR_X509_FATAL_ERROR can be used if no better code is available.
Write an AlgorithmIdentifier sequence in ASN.1 format.
Set the debug callback The callback has the following argument: void * opaque context for the callback int debug level const char * file name int line number const char * message
Register callbacks for DTLS cookies (Server only. DTLS only.) Default: dummy callbacks that fail, in order to force you to register working callbacks (and initialize their context). To disable HelloVerifyRequest, register NULL callbacks. \warning Disabling hello verification allows your server to be used for amplification in DoS attacks against other hosts. Only disable if you known this can't happen in your particular environment.
Set client's transport-level identification info. (Server only. DTLS only.) This is usually the IP address (and port), but could be anything identify the client depending on the underlying network stack. Used for HelloVerifyRequest with DTLS. This is *not* used to route the actual packets.
Set retransmit timeout values for the DTLS handshake. (DTLS only, no effect on TLS.)
Set the allowed groups in order of preference. On server: This only affects the choice of key agreement mechanism On client: this affects the list of groups offered for any use. The server can override our preference order. Both sides: limits the set of groups accepted for use in key sharing.
Configure pre-shared keys (PSKs) and their identities to be used in PSK-based ciphersuites. Only one PSK can be registered, through either mbedtls_ssl_conf_psk() or mbedtls_ssl_conf_psk_opaque(). If you attempt to register more than one PSK, this function fails, though this may change in future versions, which may add support for multiple PSKs.
Set the maximum supported version sent from the client side and/or accepted at the server side.
Set the minimum supported version sent from the client side and/or accepted at the server side.
\def PSA_MAC_OPERATION_INIT This macro returns a suitable initializer for a MAC operation object of type #psa_mac_operation_t. Return an initial value for a MAC operation object.
\def PSA_AEAD_OPERATION_INIT This macro returns a suitable initializer for an AEAD operation object of type #psa_aead_operation_t. Return an initial value for an AEAD operation object.
\def PSA_CIPHER_OPERATION_INIT This macro returns a suitable initializer for a cipher operation object of type #psa_cipher_operation_t. Return an initial value for a cipher operation object.
\def PSA_KEY_DERIVATION_OPERATION_INIT This macro returns a suitable initializer for a key derivation operation object of type #psa_key_derivation_operation_t. Return an initial value for a key derivation operation object.
\def PSA_KEY_ATTRIBUTES_INIT This macro returns a suitable initializer for a key attribute structure of type #psa_key_attributes_t. Return an initial value for a key attributes structure.
Declare a key as persistent and set its key identifier. If the attribute structure currently declares the key as volatile (which is the default content of an attribute structure), this function sets the lifetime attribute to #PSA_KEY_LIFETIME_PERSISTENT. This function does not access storage, it merely stores the given value in the structure. The persistent key will be written to storage when the attribute structure is passed to a key creation function such as psa_import_key(), psa_generate_key(), psa_generate_key_custom(), psa_key_derivation_output_key(), psa_key_derivation_output_key_custom() or psa_copy_key(). This function may be declared as `static` (i.e. without external linkage). This function may be provided as a function-like macro, but in this case it must evaluate each of its arguments exactly once.
Set the location of a persistent key. To make a key persistent, you must give it a persistent key identifier with psa_set_key_id(). By default, a key that has a persistent identifier is stored in the default storage area identifier by #PSA_KEY_LIFETIME_PERSISTENT. Call this function to choose a storage area, or to explicitly declare the key as volatile. This function does not access storage, it merely stores the given value in the structure. The persistent key will be written to storage when the attribute structure is passed to a key creation function such as psa_import_key(), psa_generate_key(), psa_generate_key_custom(), psa_key_derivation_output_key(), psa_key_derivation_output_key_custom() or psa_copy_key(). This function may be declared as `static` (i.e. without external linkage). This function may be provided as a function-like macro, but in this case it must evaluate each of its arguments exactly once.
Retrieve the usage flags from key attributes. This function may be declared as `static` (i.e. without external linkage). This function may be provided as a function-like macro, but in this case it must evaluate its argument exactly once.
This function returns the size of the IV or nonce of the cipher, in Bytes.
Retrieve the PAKE algorithm from a PAKE cipher suite.
Declare the PAKE algorithm for the cipher suite. This function overwrites any PAKE algorithm previously set in \p cipher_suite.
Declare the primitive for a PAKE cipher suite. This function overwrites any primitive previously set in \p cipher_suite.
Retrieve the PAKE primitive bit-size from a PAKE cipher suite.
Declare the hash algorithm for a PAKE cipher suite. This function overwrites any hash algorithm previously set in \p cipher_suite. Refer to the documentation of individual PAKE algorithm types (`PSA_ALG_XXX` values of type ::psa_algorithm_t such that #PSA_ALG_IS_PAKE(\c alg) is true) for more information.
Declare the enrollment algorithm for a key. An operation on a key may indifferently use the algorithm set with psa_set_key_algorithm() or with this function. \warning Setting an enrollment algorithm is not recommended, because using the same key with different algorithms can allow some attacks based on arithmetic relations between different computations made with the same key, or can escalate harmless side channels into exploitable ones. Use this function only if it is necessary to support a protocol for which it has been verified that the usage of the key with multiple algorithms is safe.
This function generates an ECDSA keypair on the given curve. \see ecp.h
Verify the signature of a message with a public key, using a hash-and-sign verification algorithm.
Sign a hash or short message with a private key. Note that to perform a hash-and-sign signature algorithm, you must first calculate the hash by calling psa_hash_setup(), psa_hash_update() and psa_hash_finish(), or alternatively by calling psa_hash_compute(). Then pass the resulting hash as the \p hash parameter to this function. You can use #PSA_ALG_SIGN_GET_HASH(\p alg) to determine the hash algorithm to use.
Verify the signature of a hash or short message using a public key. Note that to perform a hash-and-sign signature algorithm, you must first calculate the hash by calling psa_hash_setup(), psa_hash_update() and psa_hash_finish(), or alternatively by calling psa_hash_compute(). Then pass the resulting hash as the \p hash parameter to this function. You can use #PSA_ALG_SIGN_GET_HASH(\p alg) to determine the hash algorithm to use.
Encrypt a short message with a public key. - For #PSA_ALG_RSA_PKCS1V15_CRYPT, no salt is supported.
Decrypt a short message with a private key. - For #PSA_ALG_RSA_PKCS1V15_CRYPT, no salt is supported.
Set up a key derivation operation. A key derivation algorithm takes some inputs and uses them to generate a byte stream in a deterministic way. This byte stream can be used to produce keys and other cryptographic material. To derive a key: -# Start with an initialized object of type #psa_key_derivation_operation_t. -# Call psa_key_derivation_setup() to select the algorithm. -# Provide the inputs for the key derivation by calling psa_key_derivation_input_bytes() or psa_key_derivation_input_key() as appropriate. Which inputs are needed, in what order, and whether they may be keys and if so of what type depends on the algorithm. -# Optionally set the operation's maximum capacity with psa_key_derivation_set_capacity(). You may do this before, in the middle of or after providing inputs. For some algorithms, this step is mandatory because the output depends on the maximum capacity. -# To derive a key, call psa_key_derivation_output_key() or psa_key_derivation_output_key_custom(). To derive a byte string for a different purpose, call psa_key_derivation_output_bytes(). Successive calls to these functions use successive output bytes calculated by the key derivation algorithm. -# Clean up the key derivation operation object with psa_key_derivation_abort(). If this function returns an error, the key derivation operation object is not changed. If an error occurs at any step after a call to psa_key_derivation_setup(), the operation will need to be reset by a call to psa_key_derivation_abort(). Implementations must reject an attempt to derive a key of size 0.
Retrieve the current capacity of a key derivation operation. The capacity of a key derivation is the maximum number of bytes that it can return. When you get *N* bytes of output from a key derivation operation, this reduces its capacity by *N*.
Set the maximum capacity of a key derivation operation. The capacity of a key derivation operation is the maximum number of bytes that the key derivation operation can return from this point onwards.
Provide a numeric input for key derivation or key agreement. Which inputs are required and in what order depends on the algorithm. However, when an algorithm requires a particular order, numeric inputs usually come first as they tend to be configuration parameters. Refer to the documentation of each key derivation or key agreement algorithm for information. This function is used for inputs which are fixed-size non-negative integers. If this function returns an error status, the operation enters an error state and must be aborted by calling psa_key_derivation_abort().
Provide an input for key derivation in the form of a key. Which inputs are required and in what order depends on the algorithm. Refer to the documentation of each key derivation or key agreement algorithm for information. This function obtains input from a key object, which is usually correct for secret inputs or for non-secret personalization strings kept in the key store. To pass a non-secret parameter which is not in the key store, call psa_key_derivation_input_bytes() instead of this function. Refer to the documentation of individual step types (`PSA_KEY_DERIVATION_INPUT_xxx` values of type ::psa_key_derivation_step_t) for more information. If this function returns an error status, the operation enters an error state and must be aborted by calling psa_key_derivation_abort().
Perform a key agreement and use the shared secret as input to a key derivation. A key agreement algorithm takes two inputs: a private key \p private_key a public key \p peer_key. The result of this function is passed as input to a key derivation. The output of this key derivation can be extracted by reading from the resulting operation to produce keys and other cryptographic material. If this function returns an error status, the operation enters an error state and must be aborted by calling psa_key_derivation_abort().
Derive a key from an ongoing key derivation operation. This function calculates output bytes from a key derivation algorithm and uses those bytes to generate a key deterministically. The key's location, usage policy, type and size are taken from \p attributes. If you view the key derivation's output as a stream of bytes, this function destructively reads as many bytes as required from the stream. The operation's capacity decreases by the number of bytes read. If this function returns an error status other than #PSA_ERROR_INSUFFICIENT_DATA, the operation enters an error state and must be aborted by calling psa_key_derivation_abort(). How much output is produced and consumed from the operation, and how the key is derived, depends on the key type and on the key size (denoted \c bits below): - For key types for which the key is an arbitrary sequence of bytes of a given size, this function is functionally equivalent to calling #psa_key_derivation_output_bytes and passing the resulting output to #psa_import_key. However, this function has a security benefit: if the implementation provides an isolation boundary then the key material is not exposed outside the isolation boundary. As a consequence, for these key types, this function always consumes exactly (\c bits / 8) bytes from the operation. The following key types defined in this specification follow this scheme: - #PSA_KEY_TYPE_AES; - #PSA_KEY_TYPE_ARIA; - #PSA_KEY_TYPE_CAMELLIA; - #PSA_KEY_TYPE_DERIVE; - #PSA_KEY_TYPE_HMAC; - #PSA_KEY_TYPE_PASSWORD_HASH. - For ECC keys on a Montgomery elliptic curve (#PSA_KEY_TYPE_ECC_KEY_PAIR(\c curve) where \c curve designates a Montgomery curve), this function always draws a byte string whose length is determined by the curve, and sets the mandatory bits accordingly. That is: - Curve25519 (#PSA_ECC_FAMILY_MONTGOMERY, 255 bits): draw a 32-byte string and process it as specified in RFC 7748 §5. - Curve448 (#PSA_ECC_FAMILY_MONTGOMERY, 448 bits): draw a 56-byte string and process it as specified in RFC 7748 §5. - For key types for which the key is represented by a single sequence of \c bits bits with constraints as to which bit sequences are acceptable, this function draws a byte string of length (\c bits / 8) bytes rounded up to the nearest whole number of bytes. If the resulting byte string is acceptable, it becomes the key, otherwise the drawn bytes are discarded. This process is repeated until an acceptable byte string is drawn. The byte string drawn from the operation is interpreted as specified for the output produced by psa_export_key(). The following key types defined in this specification follow this scheme: - #PSA_KEY_TYPE_DES. Force-set the parity bits, but discard forbidden weak keys. For 2-key and 3-key triple-DES, the three keys are generated successively (for example, for 3-key triple-DES, if the first 8 bytes specify a weak key and the next 8 bytes do not, discard the first 8 bytes, use the next 8 bytes as the first key, and continue reading output from the operation to derive the other two keys). - Finite-field Diffie-Hellman keys (#PSA_KEY_TYPE_DH_KEY_PAIR(\c group) where \c group designates any Diffie-Hellman group) and ECC keys on a Weierstrass elliptic curve (#PSA_KEY_TYPE_ECC_KEY_PAIR(\c curve) where \c curve designates a Weierstrass curve). For these key types, interpret the byte string as integer in big-endian order. Discard it if it is not in the range [0, *N* - 2] where *N* is the boundary of the private key domain (the prime *p* for Diffie-Hellman, the subprime *q* for DSA, or the order of the curve's base point for ECC). Add 1 to the resulting integer and use this as the private key *x*. This method allows compliance to NIST standards, specifically the methods titled "key-pair generation by testing candidates" in NIST SP 800-56A §5.6.1.1.4 for Diffie-Hellman, in FIPS 186-4 §B.1.2 for DSA, and in NIST SP 800-56A §5.6.1.2.2 or FIPS 186-4 §B.4.2 for elliptic curve keys. - For other key types, including #PSA_KEY_TYPE_RSA_KEY_PAIR, the way in which the operation output is consumed is implementation-defined. In all cases, the data that is read is discarded from the operation. The operation's capacity is decreased by the number of bytes read. For algorithms that take an input step #PSA_KEY_DERIVATION_INPUT_SECRET, the input to that step must be provided with psa_key_derivation_input_key(). Future versions of this specification may include additional restrictions on the derived key based on the attributes and strength of the secret key.
Calculate the MAC of a message and compare it with a reference value.
Set up a multipart MAC calculation operation. This function sets up the calculation of the MAC (message authentication code) of a byte string. To verify the MAC of a message against an expected value, use psa_mac_verify_setup() instead. The sequence of operations to calculate a MAC is as follows: -# Allocate an operation object which will be passed to all the functions listed here. -# Initialize the operation object with one of the methods described in the documentation for #psa_mac_operation_t, e.g. #PSA_MAC_OPERATION_INIT. -# Call psa_mac_sign_setup() to specify the algorithm and key. -# Call psa_mac_update() zero, one or more times, passing a fragment of the message each time. The MAC that is calculated is the MAC of the concatenation of these messages in order. -# At the end of the message, call psa_mac_sign_finish() to finish calculating the MAC value and retrieve it. If an error occurs at any step after a call to psa_mac_sign_setup(), the operation will need to be reset by a call to psa_mac_abort(). The application may call psa_mac_abort() at any time after the operation has been initialized. After a successful call to psa_mac_sign_setup(), the application must eventually terminate the operation through one of the following methods: - A successful call to psa_mac_sign_finish(). - A call to psa_mac_abort().
Set up a multipart MAC verification operation. This function sets up the verification of the MAC (message authentication code) of a byte string against an expected value. The sequence of operations to verify a MAC is as follows: -# Allocate an operation object which will be passed to all the functions listed here. -# Initialize the operation object with one of the methods described in the documentation for #psa_mac_operation_t, e.g. #PSA_MAC_OPERATION_INIT. -# Call psa_mac_verify_setup() to specify the algorithm and key. -# Call psa_mac_update() zero, one or more times, passing a fragment of the message each time. The MAC that is calculated is the MAC of the concatenation of these messages in order. -# At the end of the message, call psa_mac_verify_finish() to finish calculating the actual MAC of the message and verify it against the expected value. If an error occurs at any step after a call to psa_mac_verify_setup(), the operation will need to be reset by a call to psa_mac_abort(). The application may call psa_mac_abort() at any time after the operation has been initialized. After a successful call to psa_mac_verify_setup(), the application must eventually terminate the operation through one of the following methods: - A successful call to psa_mac_verify_finish(). - A call to psa_mac_abort().
Finish the calculation of the MAC of a message and compare it with an expected value. The application must call psa_mac_verify_setup() before calling this function. This function calculates the MAC of the message formed by concatenating the inputs passed to preceding calls to psa_mac_update(). It then compares the calculated MAC with the expected MAC passed as a parameter to this function. When this function returns successfully, the operation becomes inactive. If this function returns an error status, the operation enters an error state and must be aborted by calling psa_mac_abort().
Encrypt a message using a symmetric cipher. This function encrypts a message with a random IV (initialization vector). Use the multipart operation interface with a #psa_cipher_operation_t object to provide other forms of IV.
Decrypt a message using a symmetric cipher. This function decrypts a message encrypted with a symmetric cipher.
Set the key for a multipart symmetric encryption operation. The sequence of operations to encrypt a message with a symmetric cipher is as follows: -# Allocate an operation object which will be passed to all the functions listed here. -# Initialize the operation object with one of the methods described in the documentation for #psa_cipher_operation_t, e.g. #PSA_CIPHER_OPERATION_INIT. -# Call psa_cipher_encrypt_setup() to specify the algorithm and key. -# Call either psa_cipher_generate_iv() or psa_cipher_set_iv() to generate or set the IV (initialization vector). You should use psa_cipher_generate_iv() unless the protocol you are implementing requires a specific IV value. -# Call psa_cipher_update() zero, one or more times, passing a fragment of the message each time. -# Call psa_cipher_finish(). If an error occurs at any step after a call to psa_cipher_encrypt_setup(), the operation will need to be reset by a call to psa_cipher_abort(). The application may call psa_cipher_abort() at any time after the operation has been initialized. After a successful call to psa_cipher_encrypt_setup(), the application must eventually terminate the operation. The following events terminate an operation: - A successful call to psa_cipher_finish(). - A call to psa_cipher_abort().
Set the key for a multipart symmetric decryption operation. The sequence of operations to decrypt a message with a symmetric cipher is as follows: -# Allocate an operation object which will be passed to all the functions listed here. -# Initialize the operation object with one of the methods described in the documentation for #psa_cipher_operation_t, e.g. #PSA_CIPHER_OPERATION_INIT. -# Call psa_cipher_decrypt_setup() to specify the algorithm and key. -# Call psa_cipher_set_iv() with the IV (initialization vector) for the decryption. If the IV is prepended to the ciphertext, you can call psa_cipher_update() on a buffer containing the IV followed by the beginning of the message. -# Call psa_cipher_update() zero, one or more times, passing a fragment of the message each time. -# Call psa_cipher_finish(). If an error occurs at any step after a call to psa_cipher_decrypt_setup(), the operation will need to be reset by a call to psa_cipher_abort(). The application may call psa_cipher_abort() at any time after the operation has been initialized. After a successful call to psa_cipher_decrypt_setup(), the application must eventually terminate the operation. The following events terminate an operation: - A successful call to psa_cipher_finish(). - A call to psa_cipher_abort().
Generate an IV for a symmetric encryption operation. This function generates a random IV (initialization vector), nonce or initial counter value for the encryption operation as appropriate for the chosen algorithm, key type and key size. The application must call psa_cipher_encrypt_setup() before calling this function. If this function returns an error status, the operation enters an error state and must be aborted by calling psa_cipher_abort().
Set the IV for a symmetric encryption or decryption operation. This function sets the IV (initialization vector), nonce or initial counter value for the encryption or decryption operation. The application must call psa_cipher_encrypt_setup() before calling this function. If this function returns an error status, the operation enters an error state and must be aborted by calling psa_cipher_abort().
Encrypt or decrypt a message fragment in an active cipher operation. Before calling this function, you must: 1. Call either psa_cipher_encrypt_setup() or psa_cipher_decrypt_setup(). The choice of setup function determines whether this function encrypts or decrypts its input. 2. If the algorithm requires an IV, call psa_cipher_generate_iv() (recommended when encrypting) or psa_cipher_set_iv(). If this function returns an error status, the operation enters an error state and must be aborted by calling psa_cipher_abort().
Finish encrypting or decrypting a message in a cipher operation. The application must call psa_cipher_encrypt_setup() or psa_cipher_decrypt_setup() before calling this function. The choice of setup function determines whether this function encrypts or decrypts its input. This function finishes the encryption or decryption of the message formed by concatenating the inputs passed to preceding calls to psa_cipher_update(). When this function returns successfully, the operation becomes inactive. If this function returns an error status, the operation enters an error state and must be aborted by calling psa_cipher_abort().
Library initialization. Applications must call this function before calling any other function in this module. Applications may call this function more than once. Once a call succeeds, subsequent calls are guaranteed to succeed. If the application calls other functions before calling psa_crypto_init(), the behavior is undefined. Implementations are encouraged to either perform the operation as if the library had been initialized or to return #PSA_ERROR_BAD_STATE or some other applicable error. In particular, implementations should not return a success status if the lack of initialization may have security implications, for example due to improper seeding of the random number generator.
Set the key for a multipart authenticated encryption operation. The sequence of operations to encrypt a message with authentication is as follows: -# Allocate an operation object which will be passed to all the functions listed here. -# Initialize the operation object with one of the methods described in the documentation for #psa_aead_operation_t, e.g. #PSA_AEAD_OPERATION_INIT. -# Call psa_aead_encrypt_setup() to specify the algorithm and key. -# If needed, call psa_aead_set_lengths() to specify the length of the inputs to the subsequent calls to psa_aead_update_ad() and psa_aead_update(). See the documentation of psa_aead_set_lengths() for details. -# Call either psa_aead_generate_nonce() or psa_aead_set_nonce() to generate or set the nonce. You should use psa_aead_generate_nonce() unless the protocol you are implementing requires a specific nonce value. -# Call psa_aead_update_ad() zero, one or more times, passing a fragment of the non-encrypted additional authenticated data each time. -# Call psa_aead_update() zero, one or more times, passing a fragment of the message to encrypt each time. -# Call psa_aead_finish(). If an error occurs at any step after a call to psa_aead_encrypt_setup(), the operation will need to be reset by a call to psa_aead_abort(). The application may call psa_aead_abort() at any time after the operation has been initialized. After a successful call to psa_aead_encrypt_setup(), the application must eventually terminate the operation. The following events terminate an operation: - A successful call to psa_aead_finish(). - A call to psa_aead_abort().
Set the key for a multipart authenticated decryption operation. The sequence of operations to decrypt a message with authentication is as follows: -# Allocate an operation object which will be passed to all the functions listed here. -# Initialize the operation object with one of the methods described in the documentation for #psa_aead_operation_t, e.g. #PSA_AEAD_OPERATION_INIT. -# Call psa_aead_decrypt_setup() to specify the algorithm and key. -# If needed, call psa_aead_set_lengths() to specify the length of the inputs to the subsequent calls to psa_aead_update_ad() and psa_aead_update(). See the documentation of psa_aead_set_lengths() for details. -# Call psa_aead_set_nonce() with the nonce for the decryption. -# Call psa_aead_update_ad() zero, one or more times, passing a fragment of the non-encrypted additional authenticated data each time. -# Call psa_aead_update() zero, one or more times, passing a fragment of the ciphertext to decrypt each time. -# Call psa_aead_verify(). If an error occurs at any step after a call to psa_aead_decrypt_setup(), the operation will need to be reset by a call to psa_aead_abort(). The application may call psa_aead_abort() at any time after the operation has been initialized. After a successful call to psa_aead_decrypt_setup(), the application must eventually terminate the operation. The following events terminate an operation: - A successful call to psa_aead_verify(). - A call to psa_aead_abort().
Generate a random nonce for an authenticated encryption operation. This function generates a random nonce for the authenticated encryption operation with an appropriate size for the chosen algorithm, key type and key size. The application must call psa_aead_encrypt_setup() before calling this function. If this function returns an error status, the operation enters an error state and must be aborted by calling psa_aead_abort().
Set the nonce for an authenticated encryption or decryption operation. This function sets the nonce for the authenticated encryption or decryption operation. The application must call psa_aead_encrypt_setup() or psa_aead_decrypt_setup() before calling this function. If this function returns an error status, the operation enters an error state and must be aborted by calling psa_aead_abort().
Declare the lengths of the message and additional data for AEAD. The application must call this function before calling psa_aead_update_ad() or psa_aead_update() if the algorithm for the operation requires it. If the algorithm does not require it, calling this function is optional, but if this function is called then the implementation must enforce the lengths. You may call this function before or after setting the nonce with psa_aead_set_nonce() or psa_aead_generate_nonce(). - For #PSA_ALG_CCM, calling this function is required. - For the other AEAD algorithms defined in this specification, calling this function is not required. - For vendor-defined algorithm, refer to the vendor documentation. If this function returns an error status, the operation enters an error state and must be aborted by calling psa_aead_abort().
Pass additional data to an active AEAD operation. Additional data is authenticated, but not encrypted. You may call this function multiple times to pass successive fragments of the additional data. You may not call this function after passing data to encrypt or decrypt with psa_aead_update(). Before calling this function, you must: 1. Call either psa_aead_encrypt_setup() or psa_aead_decrypt_setup(). 2. Set the nonce with psa_aead_generate_nonce() or psa_aead_set_nonce(). If this function returns an error status, the operation enters an error state and must be aborted by calling psa_aead_abort(). \warning When decrypting, until psa_aead_verify() has returned #PSA_SUCCESS, there is no guarantee that the input is valid. Therefore, until you have called psa_aead_verify() and it has returned #PSA_SUCCESS, treat the input as untrusted and prepare to undo any action that depends on the input if psa_aead_verify() returns an error status.
Encrypt or decrypt a message fragment in an active AEAD operation. Before calling this function, you must: 1. Call either psa_aead_encrypt_setup() or psa_aead_decrypt_setup(). The choice of setup function determines whether this function encrypts or decrypts its input. 2. Set the nonce with psa_aead_generate_nonce() or psa_aead_set_nonce(). 3. Call psa_aead_update_ad() to pass all the additional data. If this function returns an error status, the operation enters an error state and must be aborted by calling psa_aead_abort(). \warning When decrypting, until psa_aead_verify() has returned #PSA_SUCCESS, there is no guarantee that the input is valid. Therefore, until you have called psa_aead_verify() and it has returned #PSA_SUCCESS: - Do not use the output in any way other than storing it in a confidential location. If you take any action that depends on the tentative decrypted data, this action will need to be undone if the input turns out not to be valid. Furthermore, if an adversary can observe that this action took place (for example through timing), they may be able to use this fact as an oracle to decrypt any message encrypted with the same key. - In particular, do not copy the output anywhere but to a memory or storage space that you have exclusive access to. This function does not require the input to be aligned to any particular block boundary. If the implementation can only process a whole block at a time, it must consume all the input provided, but it may delay the end of the corresponding output until a subsequent call to psa_aead_update(), psa_aead_finish() or psa_aead_verify() provides sufficient input. The amount of data that can be delayed in this way is bounded by #PSA_AEAD_UPDATE_OUTPUT_SIZE.
Finish encrypting a message in an AEAD operation. The operation must have been set up with psa_aead_encrypt_setup(). This function finishes the authentication of the additional data formed by concatenating the inputs passed to preceding calls to psa_aead_update_ad() with the plaintext formed by concatenating the inputs passed to preceding calls to psa_aead_update(). This function has two output buffers: - \p ciphertext contains trailing ciphertext that was buffered from preceding calls to psa_aead_update(). - \p tag contains the authentication tag. When this function returns successfully, the operation becomes inactive. If this function returns an error status, the operation enters an error state and must be aborted by calling psa_aead_abort().
Finish authenticating and decrypting a message in an AEAD operation. The operation must have been set up with psa_aead_decrypt_setup(). This function finishes the authenticated decryption of the message components: - The additional data consisting of the concatenation of the inputs passed to preceding calls to psa_aead_update_ad(). - The ciphertext consisting of the concatenation of the inputs passed to preceding calls to psa_aead_update(). - The tag passed to this function call. If the authentication tag is correct, this function outputs any remaining plaintext and reports success. If the authentication tag is not correct, this function returns #PSA_ERROR_INVALID_SIGNATURE. When this function returns successfully, the operation becomes inactive. If this function returns an error status, the operation enters an error state and must be aborted by calling psa_aead_abort().
Sign a message with a private key. For hash-and-sign algorithms, this includes the hashing step.
This function encrypts a buffer using CCM*. \warning Passing \c 0 as \p tag_len means that the message is no longer authenticated.
This function performs a CCM* authenticated decryption of a buffer. \warning Passing \c 0 as \p tag_len means that the message is nos longer authenticated.
This function starts a new CMAC operation with the same key as the previous one. It should be called after finishing the previous CMAC operation with mbedtls_cipher_cmac_finish(). After calling this function, call mbedtls_cipher_cmac_update() to supply the new CMAC operation with data.
Derive a key from an ongoing key derivation operation with custom production parameters.
Perform a key agreement and return the raw shared secret. \warning The raw result of a key agreement algorithm such as finite-field Diffie-Hellman or elliptic curve Diffie-Hellman has biases and should not be used directly as key material. It should instead be passed as input to a key derivation algorithm. To chain a key agreement with a key derivation, use psa_key_derivation_key_agreement() and other functions from the key derivation interface.
Generate a key or key pair. The key is generated randomly. Its location, usage policy, type and size are taken from \p attributes. Implementations must reject an attempt to generate a key of size 0. The following type-specific considerations apply: - For RSA keys (#PSA_KEY_TYPE_RSA_KEY_PAIR), the public exponent is 65537. The modulus is a product of two probabilistic primes between 2^{n-1} and 2^n where n is the bit size specified in the attributes.
Generate a key or key pair using custom production parameters.
Set the maximum number of ops allowed to be executed by an interruptible function in a single call. \warning This is a beta API, and thus subject to change at any point. It is not bound by the usual interface stability promises. \warning With implementations that interpret this number as a hard limit, setting this number too small may result in an infinite loop, whereby each call results in immediate return with no ops done (as there is not enough time to execute any), and thus no result will ever be achieved.
Get the maximum number of ops allowed to be executed by an interruptible function in a single call. This will return the last value set by \c psa_interruptible_set_max_ops() or #PSA_INTERRUPTIBLE_MAX_OPS_UNLIMITED if that function has never been called. \warning This is a beta API, and thus subject to change at any point. It is not bound by the usual interface stability promises.
Get the number of ops that a hash signing operation has taken so far. If the operation has completed, then this will represent the number of ops required for the entire operation. After initialization or calling \c psa_sign_hash_interruptible_abort() on the operation, a value of 0 will be returned. \warning This is a beta API, and thus subject to change at any point. It is not bound by the usual interface stability promises. This is a helper provided to help you tune the value passed to \c psa_interruptible_set_max_ops().
Get the number of ops that a hash verification operation has taken so far. If the operation has completed, then this will represent the number of ops required for the entire operation. After initialization or calling \c psa_verify_hash_interruptible_abort() on the operation, a value of 0 will be returned. \warning This is a beta API, and thus subject to change at any point. It is not bound by the usual interface stability promises. This is a helper provided to help you tune the value passed to \c psa_interruptible_set_max_ops().
Start signing a hash or short message with a private key, in an interruptible manner. \see \c psa_sign_hash_complete() \warning This is a beta API, and thus subject to change at any point. It is not bound by the usual interface stability promises.
Continue and eventually complete the action of signing a hash or short message with a private key, in an interruptible manner. \see \c psa_sign_hash_start() \warning This is a beta API, and thus subject to change at any point. It is not bound by the usual interface stability promises.
Abort a sign hash operation. \warning This is a beta API, and thus subject to change at any point. It is not bound by the usual interface stability promises.
Start reading and verifying a hash or short message, in an interruptible manner. \see \c psa_verify_hash_complete() \warning This is a beta API, and thus subject to change at any point. It is not bound by the usual interface stability promises.
Continue and eventually complete the action of reading and verifying a hash or short message signed with a private key, in an interruptible manner. \see \c psa_verify_hash_start() \warning This is a beta API, and thus subject to change at any point. It is not bound by the usual interface stability promises.
Abort a verify hash operation. \warning This is a beta API, and thus subject to change at any point. It is not bound by the usual interface stability promises.
Remove non-essential copies of key material from memory. If the key identifier designates a volatile key, this functions does not do anything and returns successfully. If the key identifier designates a persistent key, then this function will free all resources associated with the key in volatile memory. The key data in persistent storage is not affected and the key can still be used.
Make a copy of a key. Copy key material from one location to another. This function is primarily useful to copy a key from one location to another, since it populates a key using the material from another key which may have a different lifetime. This function may be used to share a key with a different party, subject to implementation-defined restrictions on key sharing. The policy on the source key must have the usage flag #PSA_KEY_USAGE_COPY set. This flag is sufficient to permit the copy if the key has the lifetime #PSA_KEY_LIFETIME_VOLATILE or #PSA_KEY_LIFETIME_PERSISTENT. Some secure elements do not provide a way to copy a key without making it extractable from the secure element. If a key is located in such a secure element, then the key must have both usage flags #PSA_KEY_USAGE_COPY and #PSA_KEY_USAGE_EXPORT in order to make a copy of the key outside the secure element. The resulting key may only be used in a way that conforms to both the policy of the original key and the policy specified in the \p attributes parameter: - The usage flags on the resulting key are the bitwise-and of the usage flags on the source policy and the usage flags in \p attributes. - If both allow the same algorithm or wildcard-based algorithm policy, the resulting key has the same algorithm policy. - If either of the policies allows an algorithm and the other policy allows a wildcard-based algorithm policy that includes this algorithm, the resulting key allows the same algorithm. - If the policies do not allow any algorithm in common, this function fails with the status #PSA_ERROR_INVALID_ARGUMENT. The effect of this function on implementation-defined attributes is implementation-defined.
Destroy a key. This function destroys a key from both volatile memory and, if applicable, non-volatile storage. Implementations shall make a best effort to ensure that the key material cannot be recovered. This function also erases any metadata such as policies and frees resources associated with the key. If a key is currently in use in a multipart operation, then destroying the key will cause the multipart operation to fail. \warning We can only guarantee that the the key material will eventually be wiped from memory. With threading enabled and during concurrent execution, copies of the key material may still exist until all threads have finished using the key.
Calculate the hash (digest) of a message and compare it with a reference value.
Finish the calculation of the hash of a message and compare it with an expected value. The application must call psa_hash_setup() before calling this function. This function calculates the hash of the message formed by concatenating the inputs passed to preceding calls to psa_hash_update(). It then compares the calculated hash with the expected hash passed as a parameter to this function. When this function returns successfully, the operation becomes inactive. If this function returns an error status, the operation enters an error state and must be aborted by calling psa_hash_abort().
Clone a hash operation. This function copies the state of an ongoing hash operation to a new operation object. In other words, this function is equivalent to calling psa_hash_setup() on \p target_operation with the same algorithm that \p source_operation was set up for, then psa_hash_update() on \p target_operation with the same input that that was passed to \p source_operation. After this function returns, the two objects are independent, i.e. subsequent calls involving one of the objects do not affect the other object.
This function adds additional data for AEAD ciphers. Currently supported with GCM and ChaCha20+Poly1305.
This function writes a tag for AEAD ciphers. Currently supported with GCM and ChaCha20+Poly1305. This must be called after mbedtls_cipher_finish().
This function checks the tag for AEAD ciphers. Currently supported with GCM and ChaCha20+Poly1305. This must be called after mbedtls_cipher_finish().
Read an MPI from a line in an opened file. The function returns \c 0 on an empty line. Leading whitespaces are ignored, as is a '0x' prefix for radix \c 16.
This function imports a non-zero point from two ASCII strings.
Calculate the public key from a private key in a key pair.
This function exports generic key-pair parameters. Each of the output parameters can be a null pointer if you do not need that parameter.
This function returns the list of digests supported by the generic digest module.
This function returns the message-digest information associated with the given digest name.
This function returns the name of the message digest for the message-digest information structure given.
This function exports core parameters of an RSA key in raw big-endian binary format. If this function runs successfully, the non-NULL buffers pointed to by \p N, \p P, \p Q, \p D, and \p E are fully written, with additional unused space filled leading by zero Bytes. Possible reasons for returning #MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED: An alternative RSA implementation is in use, which stores the key externally, and either cannot or should not export it into RAM. A SW or HW implementation might not support a certain deduction. For example, \p P, \p Q from \p N, \p D, and \p E if the former are not part of the implementation. If the function fails due to an unsupported operation, the RSA context stays intact and remains usable.
This function performs a PKCS#1 v2.1 PSS signature operation (RSASSA-PSS-SIGN).
This function retrieves the list of ciphers supported by the generic cipher module. For any cipher identifier in the returned list, you can obtain the corresponding generic cipher information structure via mbedtls_cipher_info_from_type(), which can then be used to prepare a cipher context via mbedtls_cipher_setup().
This function retrieves the cipher-information structure associated with the given cipher name.
Set the password for a password-authenticated key exchange from key ID. Call this function when the password, or a value derived from the password, is already present in the key store.
Set the user ID for a password-authenticated key exchange. Call this function to set the user ID. For PAKE algorithms that associate a user identifier with each side of the session you need to call psa_pake_set_peer() as well. For PAKE algorithms that associate a single user identifier with the session, call psa_pake_set_user() only. Refer to the documentation of individual PAKE algorithm types (`PSA_ALG_XXX` values of type ::psa_algorithm_t such that #PSA_ALG_IS_PAKE(\c alg) is true) for more information.
Set the peer ID for a password-authenticated key exchange. Call this function in addition to psa_pake_set_user() for PAKE algorithms that associate a user identifier with each side of the session. For PAKE algorithms that associate a single user identifier with the session, call psa_pake_set_user() only. Refer to the documentation of individual PAKE algorithm types (`PSA_ALG_XXX` values of type ::psa_algorithm_t such that #PSA_ALG_IS_PAKE(\c alg) is true) for more information.
Set the application role for a password-authenticated key exchange. Not all PAKE algorithms need to differentiate the communicating entities. It is optional to call this function for PAKEs that don't require a role to be specified. For such PAKEs the application role parameter is ignored, or #PSA_PAKE_ROLE_NONE can be passed as \c role. Refer to the documentation of individual PAKE algorithm types (`PSA_ALG_XXX` values of type ::psa_algorithm_t such that #PSA_ALG_IS_PAKE(\c alg) is true) for more information.
Get output for a step of a password-authenticated key exchange. Depending on the algorithm being executed, you might need to call this function several times or you might not need to call this at all. The exact sequence of calls to perform a password-authenticated key exchange depends on the algorithm in use. Refer to the documentation of individual PAKE algorithm types (`PSA_ALG_XXX` values of type ::psa_algorithm_t such that #PSA_ALG_IS_PAKE(\c alg) is true) for more information. If this function returns an error status, the operation enters an error state and must be aborted by calling psa_pake_abort().
Provide input for a step of a password-authenticated key exchange. Depending on the algorithm being executed, you might need to call this function several times or you might not need to call this at all. The exact sequence of calls to perform a password-authenticated key exchange depends on the algorithm in use. Refer to the documentation of individual PAKE algorithm types (`PSA_ALG_XXX` values of type ::psa_algorithm_t such that #PSA_ALG_IS_PAKE(\c alg) is true) for more information. If this function returns an error status, the operation enters an error state and must be aborted by calling psa_pake_abort().
Get implicitly confirmed shared secret from a PAKE. At this point there is a cryptographic guarantee that only the authenticated party who used the same password is able to compute the key. But there is no guarantee that the peer is the party it claims to be and was able to do so. That is, the authentication is only implicit. Since the peer is not authenticated yet, no action should be taken yet that assumes that the peer is who it claims to be. For example, do not access restricted files on the peer's behalf until an explicit authentication has succeeded. This function can be called after the key exchange phase of the operation has completed. It imports the shared secret output of the PAKE into the provided derivation operation. The input step #PSA_KEY_DERIVATION_INPUT_SECRET is used when placing the shared key material in the key derivation operation. The exact sequence of calls to perform a password-authenticated key exchange depends on the algorithm in use. Refer to the documentation of individual PAKE algorithm types (`PSA_ALG_XXX` values of type ::psa_algorithm_t such that #PSA_ALG_IS_PAKE(\c alg) is true) for more information. When this function returns successfully, \p operation becomes inactive. If this function returns an error status, both \p operation and \c key_derivation operations enter an error state and must be aborted by calling psa_pake_abort() and psa_key_derivation_abort() respectively.
Open a handle to an existing persistent key. Open a handle to a persistent key. A key is persistent if it was created with a lifetime other than #PSA_KEY_LIFETIME_VOLATILE. A persistent key always has a nonzero key identifier, set with psa_set_key_id() when creating the key. Implementations may provide additional pre-provisioned keys that can be opened with psa_open_key(). Such keys have an application key identifier in the vendor range, as documented in the description of #psa_key_id_t. The application must eventually close the handle with psa_close_key() or psa_destroy_key() to release associated resources. If the application dies without calling one of these functions, the implementation should perform the equivalent of a call to psa_close_key(). Some implementations permit an application to open the same key multiple times. If this is successful, each call to psa_open_key() will return a different key handle.
Close a key handle. If the handle designates a volatile key, this will destroy the key material and free all associated resources, just like psa_destroy_key(). If this is the last open handle to a persistent key, then closing the handle will free all resources associated with the key in volatile memory. The key data in persistent storage is not affected and can be opened again later with a call to psa_open_key(). Closing the key handle makes the handle invalid, and the key handle must not be used again by the application.
Get statistics about resource consumption related to the PSA keystore.
Return the ID of the ciphersuite associated with the given name
Set a connection-specific verification callback (optional). If set, the provided verify callback is called for each certificate in the peer's CRT chain, including the trusted root. For more information, please see the documentation of \c mbedtls_x509_crt_verify().
Set the timeout period for mbedtls_ssl_read() (Default: no timeout.)
Check whether a buffer contains a valid and authentic record that has not been seen before. (DTLS only). This function does not change the user-visible state of the SSL context. Its sole purpose is to provide an indication of the legitimacy of an incoming record. This can be useful e.g. in distributed server environments using the DTLS Connection ID feature, in which connections might need to be passed between service instances on a change of peer address, but where such disruptive operations should only happen after the validity of incoming records has been confirmed.
Configure SSL session ticket callbacks (server only). (Default: none.)
Set a limit on the number of records with a bad MAC before terminating the connection. (DTLS only, no effect on TLS.) Default: 0 (disabled).
Set the session cache callbacks (server-side only) If not set, no session resuming is done (except if session tickets are enabled too). The session cache has the responsibility to check for stale entries based on timeout. See RFC 5246 for recommendations. Warning: session.peer_cert is cleared by the SSL/TLS layer on connection shutdown, so do not cache the pointer! Either set it to NULL or make a full copy of the certificate. The get callback is called once during the initial handshake to enable session resuming. The get function has the following parameters: (void *parameter, mbedtls_ssl_session *session) If a valid entry is found, it should fill the master of the session object with the cached values and return 0, return 1 otherwise. Optionally peer_cert can be set as well if it is properly present in cache entry. The set callback is called once during the initial handshake to enable session resuming after the entire handshake has been finished. The set function has the following parameters: (void *parameter, const mbedtls_ssl_session *session). The function should create a cache entry for future retrieval based on the data in the session structure and should keep in mind that the mbedtls_ssl_session object presented (and all its referenced data) is cleared by the SSL/TLS layer when the connection is terminated. It is recommended to add metadata to determine if an entry is still valid in the future. Return 0 if successfully cached, return 1 otherwise.
Load a session for session resumption. Sessions loaded through this call will be considered for session resumption in the next handshake. \sa mbedtls_ssl_get_session() \sa mbedtls_ssl_session_load()
Retrieve SNI extension value for the current handshake. Available in \c f_cert_cb of \c mbedtls_ssl_conf_cert_cb(), this is the same value passed to \c f_sni callback of \c mbedtls_ssl_conf_sni() and may be used instead of \c mbedtls_ssl_conf_sni().
Set the data required to verify peer certificate for the current handshake
Set DN hints sent to client in CertificateRequest message
Set server side ServerName TLS extension callback (optional, server-side only). If set, the ServerName callback is called whenever the server receives a ServerName TLS extension from the client during a handshake. The ServerName callback has the following parameters: (void *parameter, mbedtls_ssl_context *ssl, const unsigned char *hostname, size_t len). If a suitable certificate is found, the callback must set the certificate(s) and key(s) to use with \c mbedtls_ssl_set_hs_own_cert() (can be called repeatedly), and may optionally adjust the CA and associated CRL with \c mbedtls_ssl_set_hs_ca_chain() as well as the client authentication mode with \c mbedtls_ssl_set_hs_authmode(), then must return 0. If no matching name is found, the callback may return non-zero to abort the handshake.
Get the name of the negotiated Application Layer Protocol. This function should be called after the handshake is completed.
Enable or disable Encrypt-then-MAC (Default: MBEDTLS_SSL_ETM_ENABLED)
Enable or disable Extended Master Secret negotiation. (Default: MBEDTLS_SSL_EXTENDED_MS_ENABLED)
Whether to send a list of acceptable CAs in CertificateRequest messages. (Default: do send)
Set the maximum fragment length to emit and/or negotiate. (Typical: the smaller of #MBEDTLS_SSL_IN_CONTENT_LEN and #MBEDTLS_SSL_OUT_CONTENT_LEN, usually `2^14` bytes) (Server: set maximum fragment length to emit, usually negotiated by the client during handshake) (Client: set maximum fragment length to emit *and* negotiate with the server during handshake) (Default: #MBEDTLS_SSL_MAX_FRAG_LEN_NONE)
Pick the ciphersuites order according to the second parameter in the SSL Server module (MBEDTLS_SSL_SRV_C). (Default, if never called: MBEDTLS_SSL_SRV_CIPHERSUITE_ORDER_SERVER)
Prevent or allow legacy renegotiation. (Default: MBEDTLS_SSL_LEGACY_NO_RENEGOTIATION) MBEDTLS_SSL_LEGACY_NO_RENEGOTIATION allows connections to be established even if the peer does not support secure renegotiation, but does not allow renegotiation to take place if not secure. (Interoperable and secure option) MBEDTLS_SSL_LEGACY_ALLOW_RENEGOTIATION allows renegotiations with non-upgraded peers. Allowing legacy renegotiation makes the connection vulnerable to specific man in the middle attacks. (See RFC 5746) (Most interoperable and least secure option) MBEDTLS_SSL_LEGACY_BREAK_HANDSHAKE breaks off connections if peer does not support secure renegotiation. Results in interoperability issues with non-upgraded peers that do not support renegotiation altogether. (Most secure option, interoperability issues)
Enforce renegotiation requests. (Default: enforced, max_records = 16) When we request a renegotiation, the peer can comply or ignore the request. This function allows us to decide whether to enforce our renegotiation requests by closing the connection if the peer doesn't comply. However, records could already be in transit from the peer when the request is emitted. In order to increase reliability, we can accept a number of records before the expected handshake records. The optimal value is highly dependent on the specific usage scenario. \warning On client, the grace period can only happen during mbedtls_ssl_read(), as opposed to mbedtls_ssl_write() and mbedtls_ssl_renegotiate() which always behave as if max_record was 0. The reason is, if we receive application data from the server, we need a place to write it, which only happens during mbedtls_ssl_read().
Set record counter threshold for periodic renegotiation. (Default: 2^48 - 1) Renegotiation is automatically triggered when a record counter (outgoing or incoming) crosses the defined threshold. The default value is meant to prevent the connection from being closed when the counter is about to reached its maximal value (it is not allowed to wrap). Lower values can be used to enforce policies such as "keys must be refreshed every N packets with cipher X". The renegotiation period can be disabled by setting conf->disable_renegotiation to MBEDTLS_SSL_RENEGOTIATION_DISABLED.
Check if there is data already read from the underlying transport but not yet processed.
Return the current maximum incoming record payload in bytes. \sa mbedtls_ssl_set_mtu() \sa mbedtls_ssl_get_max_in_record_payload() \sa mbedtls_ssl_get_record_expansion()
Return the peer certificate from the current connection. \warning You must not use the pointer returned by this function after any further call to the SSL API, including mbedtls_ssl_read() and mbedtls_ssl_write(); this is because the pointer might change during renegotiation, which happens transparently to the user. If you want to use the certificate across API calls, you must make a copy.
Export a session in order to resume it later. \sa mbedtls_ssl_set_session() \sa mbedtls_ssl_session_save()
This function dynamically sets the memory-management functions used by the library, during runtime.
This function performs any platform-specific initialization operations. Its implementation is platform-specific, and unless platform-specific code is provided, it does nothing.
This function performs any platform teardown operations. Its implementation is platform-specific, and unless platform-specific code is provided, it does nothing.
Set the session information for a password-authenticated key exchange. The sequence of operations to set up a password-authenticated key exchange is as follows: -# Allocate an operation object which will be passed to all the functions listed here. -# Initialize the operation object with one of the methods described in the documentation for #psa_pake_operation_t, e.g. #PSA_PAKE_OPERATION_INIT. -# Call psa_pake_setup() to specify the cipher suite. -# Call \c psa_pake_set_xxx() functions on the operation to complete the setup. The exact sequence of \c psa_pake_set_xxx() functions that needs to be called depends on the algorithm in use. Refer to the documentation of individual PAKE algorithm types (`PSA_ALG_XXX` values of type ::psa_algorithm_t such that #PSA_ALG_IS_PAKE(\c alg) is true) for more information. A typical sequence of calls to perform a password-authenticated key exchange: -# Call psa_pake_output(operation, #PSA_PAKE_STEP_KEY_SHARE, ...) to get the key share that needs to be sent to the peer. -# Call psa_pake_input(operation, #PSA_PAKE_STEP_KEY_SHARE, ...) to provide the key share that was received from the peer. -# Depending on the algorithm additional calls to psa_pake_output() and psa_pake_input() might be necessary. -# Call psa_pake_get_implicit_key() for accessing the shared secret. Refer to the documentation of individual PAKE algorithm types (`PSA_ALG_XXX` values of type ::psa_algorithm_t such that #PSA_ALG_IS_PAKE(\c alg) is true) for more information. If an error occurs at any step after a call to psa_pake_setup(), the operation will need to be reset by a call to psa_pake_abort(). The application may call psa_pake_abort() at any time after the operation has been initialized. After a successful call to psa_pake_setup(), the application must eventually terminate the operation. The following events terminate an operation: - A call to psa_pake_abort(). - A successful call to psa_pake_get_implicit_key().
Load one or more CRLs and append them to the chained list
Set Subject Alternative Name
Retrieve an enumerated ASN.1 tag and its value. Updates the pointer to immediately behind the full tag.
Determine valid PSA attributes that can be used to import a key into PSA. The attributes determined by this function are suitable for calling mbedtls_pk_import_into_psa() to create a PSA key with the same key material. The typical flow of operations involving this function is ``` psa_key_attributes_t attributes = PSA_KEY_ATTRIBUTES_INIT; int ret = mbedtls_pk_get_psa_attributes(pk, &attributes); if (ret != 0) ...; // error handling omitted // Tweak attributes if desired psa_key_id_t key_id = 0; ret = mbedtls_pk_import_into_psa(pk, &attributes, &key_id); if (ret != 0) ...; // error handling omitted ```
Import a key into the PSA key store. This function is equivalent to calling psa_import_key() with the key material from \p pk. The typical way to use this function is: -# Call mbedtls_pk_get_psa_attributes() to obtain attributes for the given key. -# If desired, modify the attributes, for example: - To create a persistent key, call psa_set_key_identifier() and optionally psa_set_key_lifetime(). - To import only the public part of a key pair: psa_set_key_type(&attributes, PSA_KEY_TYPE_PUBLIC_KEY_OF_KEY_PAIR( psa_get_key_type(&attributes))); - Restrict the key usage if desired. -# Call mbedtls_pk_import_into_psa().
Create a PK context starting from a key stored in PSA. This key: - must be exportable and - must be an RSA or EC key pair or public key (FFDH is not supported in PK). The resulting PK object will be a transparent type: - #MBEDTLS_PK_RSA for RSA keys or - #MBEDTLS_PK_ECKEY for EC keys. Once this functions returns the PK object will be completely independent from the original PSA key that it was generated from. Calling mbedtls_pk_sign(), mbedtls_pk_verify(), mbedtls_pk_encrypt(), mbedtls_pk_decrypt() on the resulting PK context will perform the corresponding algorithm for that PK context type. * For ECDSA, the choice of deterministic vs randomized will be based on the compile-time setting #MBEDTLS_ECDSA_DETERMINISTIC. * For an RSA key, the output PK context will allow both encrypt/decrypt and sign/verify regardless of the original key's policy. The original key's policy determines the output key's padding mode: PCKS1 v2.1 is set if the PSA key policy is OAEP or PSS, otherwise PKCS1 v1.5 is set.
Create a PK context for the public key of a PSA key. The key must be an RSA or ECC key. It can be either a public key or a key pair, and only the public key is copied. The resulting PK object will be a transparent type: - #MBEDTLS_PK_RSA for RSA keys or - #MBEDTLS_PK_ECKEY for EC keys. Once this functions returns the PK object will be completely independent from the original PSA key that it was generated from. Calling mbedtls_pk_verify() or mbedtls_pk_encrypt() on the resulting PK context will perform the corresponding algorithm for that PK context type. For an RSA key, the output PK context will allow both encrypt and verify regardless of the original key's policy. The original key's policy determines the output key's padding mode: PCKS1 v2.1 is set if the PSA key policy is OAEP or PSS, otherwise PKCS1 v1.5 is set.
Parse a single DER formatted certificate and add it to the end of the provided chained list.
Parse a single DER formatted certificate and add it to the end of the provided chained list. This is a variant of mbedtls_x509_crt_parse_der() which takes temporary ownership of the CRT buffer until the CRT is destroyed.
Load one or more certificate files from a path and add them to the chained list. Parses permissively. If some certificates can be parsed, the result is the number of failed certificates it encountered. If none complete correctly, the first error is returned.
Verify a chain of certificates with respect to a configurable security profile.
Set the version for a Certificate Default: MBEDTLS_X509_CRT_VERSION_3
Set the validity period for a Certificate Timestamps should be in string format for UTC timezone i.e. "YYYYMMDDhhmmss" e.g. "20131231235959" for December 31st 2013 at 23:59:59
Set the issuer name for a Certificate Issuer names should contain a comma-separated list of OID types and values: e.g. "C=UK,O=ARM,CN=Mbed TLS CA"
Set the subject name for a Certificate Subject names should contain a comma-separated list of OID types and values: e.g. "C=UK,O=ARM,CN=Mbed TLS Server 1"
Set the subject public key for the certificate
Set the issuer key used for signing the certificate
Set the MD algorithm to use for the signature (e.g. MBEDTLS_MD_SHA1)
Set the basicConstraints extension for a CRT
Set the subjectKeyIdentifier extension for a CRT Requires that mbedtls_x509write_crt_set_subject_key() has been called before
Set the authorityKeyIdentifier extension for a CRT Requires that mbedtls_x509write_crt_set_issuer_key() has been called before
Set the Key Usage Extension flags (e.g. MBEDTLS_X509_KU_DIGITAL_SIGNATURE | MBEDTLS_X509_KU_KEY_CERT_SIGN)
Set the Extended Key Usage Extension (e.g. MBEDTLS_OID_SERVER_AUTH)
Set the Netscape Cert Type flags (e.g. MBEDTLS_X509_NS_CERT_TYPE_SSL_CLIENT | MBEDTLS_X509_NS_CERT_TYPE_EMAIL)
Create a receiving socket on bind_ip:port in the chosen protocol. If bind_ip == NULL, all interfaces are bound.
Read at most 'len' characters, blocking for at most 'timeout' seconds. If no error occurs, the actual amount read is returned.
Read and update a seed file. Seed is added to this instance. No more than MBEDTLS_ENTROPY_MAX_SEED_SIZE bytes are read from the seed file. The rest is ignored.
Checkup routine This module self-test also calls the entropy self-test, mbedtls_entropy_source_self_test();
This function sets the reseed interval. The reseed interval is the number of calls to mbedtls_ctr_drbg_random() or mbedtls_ctr_drbg_random_with_add() after which the entropy function is called again. The default value is #MBEDTLS_CTR_DRBG_RESEED_INTERVAL.
This function reads and updates a seed file. The seed is added to this instance.
The SHA-1 checkup routine. \warning SHA-1 is considered a weak message digest and its use constitutes a security risk. We recommend considering stronger message digests instead.
Checkup routine \warning MD5 is considered a weak message digest and its use constitutes a security risk. We recommend considering stronger message digests instead.
Disable and dealloc the certification bundle Removes the certificate verification callback and deallocates used resources
Set the default certificate bundle used for verification Overrides the default certificate bundle only in case of successful initialization. In most use cases the bundle should be set through menuconfig. The bundle needs to be sorted by subject name since binary search is used to find certificates.
Check if the given CA certificate chain is the default "dummy" certificate chain attached by the esp_crt_bundle
Perform some consistency checks on the user-provided bundle data to try and make sure it actually is a certificate bundle.
Return an offset into a read-only buffer. Similar to mbedtls_buffer_offset(), but for const pointers.
This function returns the PSA algorithm identifier associated with the given digest type. \warning If \p md_type is \c MBEDTLS_MD_NONE, this function will not return \c PSA_ALG_NONE, but an invalid algorithm. \warning This function does not check if the algorithm is supported, it always returns the corresponding identifier.
Write an enum tag (#MBEDTLS_ASN1_ENUMERATED) and value in ASN.1 format.
Write a string in ASN.1 format using the PrintableString string encoding tag (#MBEDTLS_ASN1_PRINTABLE_STRING).
Write a UTF8 string in ASN.1 format using the UTF8String string encoding tag (#MBEDTLS_ASN1_UTF8_STRING).
Write a string in ASN.1 format using the IA5String string encoding tag (#MBEDTLS_ASN1_IA5_STRING).
Convert an ECDSA signature from raw format to DER ASN.1 format.
Convert an ECDSA signature from DER ASN.1 format to raw format.
Return PSA EC info for the specified TLS ID.
This function parses and processes a TLS ServerKeyExchange payload. This is the first function used by a TLS client for ECDHE ciphersuites. \see ecp.h
Boolean "less than or equal" operation. Functionally equivalent to: \p x <= \p y
Returns the number of limbs of working memory required for a call to `mbedtls_mpi_core_montmul()`.
Conditional addition of two fixed-size large unsigned integers, returning the carry. Functionally equivalent to ``` if( cond ) X += A; return carry; ``` This function operates modulo `2^(biL*limbs)`. \warning If \p cond is neither 0 nor 1, the result of this function is unspecified, and the resulting value in \p X might be neither its original value nor \p X + \p A.
This function sets the amount of entropy grabbed on each seed or reseed. See the documentation of mbedtls_hmac_drbg_seed() for the default value.
Set the reseed interval. The reseed interval is the number of calls to mbedtls_hmac_drbg_random() or mbedtls_hmac_drbg_random_with_add() after which the entropy function is called again. The default value is #MBEDTLS_HMAC_DRBG_RESEED_INTERVAL.
This function reads and updates a seed file. The seed is added to this instance.
Verification of PKCS #7 signature against a caller-supplied certificate. For each signer in the PKCS structure, this function computes a signature over the supplied data, using the supplied certificate and the same digest algorithm as specified by the signer. It then compares this signature against the signer's signature; verification succeeds if any comparison matches. This function does not use the certificates held within the PKCS #7 structure itself, and does not check that the certificate is signed by a trusted certification authority.
Verification of PKCS #7 signature against a caller-supplied certificate. For each signer in the PKCS structure, this function validates a signature over the supplied hash, using the supplied certificate and the same digest algorithm as specified by the signer. Verification succeeds if any signature is good. This function does not use the certificates held within the PKCS #7 structure itself, and does not check that the certificate is signed by a trusted certification authority.
This function imports an LMS public key into a public LMS context.
This function exports an LMS public key from a LMS public context that already contains a public key.
This function verifies a LMS signature, using a LMS context that contains a public key.
This function imports an LMOTS public key into a LMOTS context.
This function exports an LMOTS public key from a LMOTS context that already contains a public key.
This function verifies a LMOTS signature, using a LMOTS context that contains a public key. \warning This function is **not intended for use in production**, due to as-yet unsolved problems with handling stateful keys. The API for this function may change considerably in future versions.
Calculate the key buffer size required to store the key material of a key associated with an opaque driver from input key data.
Return an offset into a buffer. This is just the addition of an offset to a pointer, except that this function also accepts an offset of 0 into a buffer whose pointer is null. (`p + n` has undefined behavior when `p` is null, even when `n == 0`. A null pointer is a valid buffer pointer when the size is 0, for example as the result of `malloc(0)` on some platforms.)
Test whether a key identifier is a volatile key identifier.
Configure entropy sources. This function may only be called before a call to psa_crypto_init(), or after a call to mbedtls_psa_crypto_free() and before any subsequent call to psa_crypto_init(). This function is only intended for test purposes. The functionality it provides is also useful for system integrators, but system integrators should configure entropy drivers instead of breaking through to the Mbed TLS API.
Copy from a local output buffer into a user-supplied one.
Test whether a policy permits an algorithm. The caller must test usage flags separately.
Validate that a key policy is internally well-formed. This function only rejects invalid policies. It does not validate the consistency of the policy with respect to other attributes of the key such as the key type.
Validate the internal consistency of key attributes. This function only rejects invalid attribute values. If does not validate the consistency of the attributes with any key data that may be involved in the creation of the key. Call this function early in the key creation process.
Set the maximum number of ops allowed to be executed by an interruptible function in a single call.
Check whether the given key type is acceptable for the given input step of a key derivation. Secret inputs must have the type #PSA_KEY_TYPE_DERIVE. Non-secret inputs must have the type #PSA_KEY_TYPE_RAW_DATA. Both secret and non-secret inputs can alternatively have the type #PSA_KEY_TYPE_NONE, which is never the type of a key object, meaning that the input was passed as a buffer rather than via a key object.
Initialize the PSA random generator. Note: the mbedtls_threading_psa_rngdata_mutex should be held when calling this function if mutexes are enabled.
Deinitialize the PSA random generator. Note: the mbedtls_threading_psa_rngdata_mutex should be held when calling this function if mutexes are enabled.
Validate the key type and size for key generation
Process input for which the algorithm is set to ECB mode. This requires manual processing, since the PSA API is defined as being able to process arbitrary-length calls to psa_cipher_update() with ECB mode, but the underlying mbedtls_cipher_update only takes full blocks.
Store persistent data for the given key slot number. This function stores the given data buffer to a persistent storage.
Get data length for given key slot number.
Load persistent data for the given key slot number. This function reads data from a storage backend and returns the data in a buffer.
This function performs the unpadding part of a PKCS#1 v1.5 decryption operation (EME-PKCS1-v1_5 decoding).
Check if support for a feature was compiled into this Mbed TLS binary. This allows you to see at runtime if the library was for instance compiled with or without Multi-threading support.
Set a pair of delays to watch (See \c mbedtls_timing_get_delay().)
Get the status of delays (Memory helper: number of delays passed.)
Obtain exclusive access to a particular SHA engine Blocks until engine is available. Note: Can block indefinitely while a TLS connection is open, suggest using esp_sha_try_lock_engine() and failing over to software SHA.
Calculate the number of words needed to represent the input word in hardware
Cache get callback implementation (Thread-safe if MBEDTLS_THREADING_C is enabled)
Cache set callback implementation (Thread-safe if MBEDTLS_THREADING_C is enabled)
Remove the cache entry by the session ID (Thread-safe if MBEDTLS_THREADING_C is enabled)
Set the cache timeout (Default: MBEDTLS_SSL_CACHE_DEFAULT_TIMEOUT (1 day)) A timeout of 0 indicates no timeout.
Set the maximum number of cache entries (Default: MBEDTLS_SSL_CACHE_DEFAULT_MAX_ENTRIES (50))
Set expiration delay for cookies (Default MBEDTLS_SSL_COOKIE_TIMEOUT)
Initialize a ticket context. (Just make it ready for mbedtls_ssl_ticket_setup() or mbedtls_ssl_ticket_free().)
Rotate session ticket encryption key to new specified key. Provides for external control of session ticket encryption key rotation, e.g. for synchronization between different machines. If this function is not used, or if not called before ticket lifetime expires, then a new session ticket encryption key is generated internally in order to avoid unbounded session ticket encryption key lifetimes.
SignedData ::= SEQUENCE { version Version, digestAlgorithms DigestAlgorithmIdentifiers, contentInfo ContentInfo, certificates [0] IMPLICIT ExtendedCertificatesAndCertificates OPTIONAL, crls [0] IMPLICIT CertificateRevocationLists OPTIONAL, signerInfos SignerInfos }
DigestAlgorithmIdentifiers :: SET of DigestAlgorithmIdentifier
ContentInfo ::= SEQUENCE { contentType ContentType, content [0] EXPLICIT ANY DEFINED BY contentType OPTIONAL }
SignerInfos ::= SET of SignerInfo Return number of signers added to the signed data, 0 or higher is valid. Return negative error code for failure.
certificates :: SET OF ExtendedCertificateOrCertificate, ExtendedCertificateOrCertificate ::= CHOICE { certificate Certificate -- x509, extendedCertificate[0] IMPLICIT ExtendedCertificate } Return number of certificates added to the signed data, 0 or higher is valid. Return negative error code for failure.
Parse a hexstring containing a DER-encoded string.
Load a Certificate Signing Request (CSR) in DER format
Set the subject name for a CSR Subject names should contain a comma-separated list of OID types and values: e.g. "C=UK,O=ARM,CN=Mbed TLS Server 1"
Set the key for a CSR (public key will be included, private key used to sign the CSR when writing it)
Set the MD algorithm to use for the signature (e.g. MBEDTLS_MD_SHA1)
Set the Key Usage Extension flags (e.g. MBEDTLS_X509_KU_DIGITAL_SIGNATURE | MBEDTLS_X509_KU_KEY_CERT_SIGN)
Set the Netscape Cert Type flags (e.g. MBEDTLS_X509_NS_CERT_TYPE_SSL_CLIENT | MBEDTLS_X509_NS_CERT_TYPE_EMAIL)
Write a CSR (Certificate Signing Request) to a PEM string
Set the Diffie-Hellman public P and G values, read from existing context (server-side only)
Set the minimum length for Diffie-Hellman parameters. (Client-side only.) (Default: 1024 bits.)
Set the Maximum Transport Unit (MTU). Special value: 0 means unset (no limit). This represents the maximum size of a datagram payload handled by the transport layer (usually UDP) as determined by the network link and stack. In practice, this controls the maximum size datagram the DTLS layer will pass to the \c f_send() callback set using \c mbedtls_ssl_set_bio().
Manage support for mki(master key id) value in use_srtp extension. MKI is an optional part of SRTP used for key management and re-keying. See RFC3711 section 3.1 for details. The default value is #MBEDTLS_SSL_DTLS_SRTP_MKI_UNSUPPORTED.
Set the supported DTLS-SRTP protection profiles.
Set the mki_value for the current DTLS-SRTP session.
Get the negotiated DTLS-SRTP information: Protection profile and MKI value. \warning This function must be called after the handshake is completed. The value returned by this function must not be trusted or acted upon before the handshake completes.
Enable or disable anti-replay protection for DTLS. (DTLS only, no effect on TLS.) Default: enabled. \warning Disabling this is a security risk unless the application protocol handles duplicated packets in a safe way. You should not disable this without careful consideration. However, if your application already detects duplicated packets and needs information about them to adjust its transmission strategy, then you'll want to disable this.
Allow or disallow packing of multiple handshake records within a single datagram.
Set the PSK callback (server-side only). If set, the PSK callback is called for each handshake where a PSK-based ciphersuite was negotiated. The caller provides the identity received and wants to receive the actual PSK data and length. The callback has the following parameters: - \c void*: The opaque pointer \p p_psk. - \c mbedtls_ssl_context*: The SSL context to which the operation applies. - \c const unsigned char*: The PSK identity selected by the client. - \c size_t: The length of the PSK identity selected by the client. If a valid PSK identity is found, the callback should use \c mbedtls_ssl_set_hs_psk() or \c mbedtls_ssl_set_hs_psk_opaque() on the SSL context to set the correct PSK and return \c 0. Any other return value will result in a denied PSK identity.
Get the first defined PSK by order of precedence: 1. handshake PSK set by \c mbedtls_ssl_set_hs_psk() in the PSK callback 2. static PSK configured by \c mbedtls_ssl_conf_psk() Return a code and update the pair (PSK, PSK length) passed to this function
Set the user data in an SSL configuration to a pointer. You can retrieve this value later with mbedtls_ssl_conf_get_user_data_p().
Return the (D)TLS protocol version negotiated in the given connection.
This function returns a non-zero value if the key length for the given cipher is variable.
This function returns a non-zero value if the IV size for the given cipher is variable.
This function returns the name of the given cipher as a string.
Retrieve the human-readable name for a cipher info structure.
Retrieve the enrollment algorithm policy from key attributes.
Return the SSL configuration structure associated with the given SSL context.
Set the certificate selection callback (server-side only). If set, the callback is always called for each handshake, after `ClientHello` processing has finished.
Set the user data in an SSL configuration to an integer. You can retrieve this value later with mbedtls_ssl_conf_get_user_data_n().
Retrieve the user data in an SSL configuration as a pointer. This is the value last set with mbedtls_ssl_conf_set_user_data_p(), or \c NULL if mbedtls_ssl_conf_set_user_data_p() has not previously been called. The value is undefined if mbedtls_ssl_conf_set_user_data_n() has been called without a subsequent call to mbedtls_ssl_conf_set_user_data_p().
Retrieve the user data in an SSL configuration as an integer. This is the value last set with mbedtls_ssl_conf_set_user_data_n(), or \c 0 if mbedtls_ssl_conf_set_user_data_n() has not previously been called. The value is undefined if mbedtls_ssl_conf_set_user_data_p() has been called without a subsequent call to mbedtls_ssl_conf_set_user_data_n().
Set the user data in an SSL context to a pointer. You can retrieve this value later with mbedtls_ssl_get_user_data_p().
Set the user data in an SSL context to an integer. You can retrieve this value later with mbedtls_ssl_get_user_data_n().
Retrieve the user data in an SSL context as a pointer. This is the value last set with mbedtls_ssl_set_user_data_p(), or \c NULL if mbedtls_ssl_set_user_data_p() has not previously been called. The value is undefined if mbedtls_ssl_set_user_data_n() has been called without a subsequent call to mbedtls_ssl_set_user_data_p().
Retrieve the user data in an SSL context as an integer. This is the value last set with mbedtls_ssl_set_user_data_n(), or \c 0 if mbedtls_ssl_set_user_data_n() has not previously been called. The value is undefined if mbedtls_ssl_set_user_data_p() has been called without a subsequent call to mbedtls_ssl_set_user_data_n().
Get the hostname that checked against the received server certificate. It is used to set the ServerName TLS extension, too, if that extension is enabled. (client-side only)
This function feeds an input buffer into an ongoing SHA-3 checksum calculation.
This function finishes the SHA-3 operation, and writes the result to the output buffer.
This function calculates the SHA-3 checksum of a buffer. The function allocates the context, performs the calculation, and frees the context. The SHA-3 result is calculated as output = SHA-3(id, input buffer, d).
Checkup routine for the algorithms implemented by this module: SHA3-224, SHA3-256, SHA3-384, SHA3-512.
Compare output data from a key derivation operation to an expected value. This function calculates output bytes from a key derivation algorithm and compares those bytes to an expected value in constant time. If you view the key derivation's output as a stream of bytes, this function destructively reads the expected number of bytes from the stream before comparing them. The operation's capacity decreases by the number of bytes read. This is functionally equivalent to the following code:
psa_key_derivation_output_bytes(operation, tmp, output_length);
if (memcmp(output, tmp, output_length) != 0)
return PSA_ERROR_INVALID_SIGNATURE;
except (1) it works even if the key's policy does not allow outputting the bytes, and (2) the comparison will be done in constant time. If this function returns an error status other than #PSA_ERROR_INSUFFICIENT_DATA or #PSA_ERROR_INVALID_SIGNATURE, the operation enters an error state and must be aborted by calling psa_key_derivation_abort(). Compare output data from a key derivation operation to an expected value stored in a key object. This function calculates output bytes from a key derivation algorithm and compares those bytes to an expected value, provided as key of type #PSA_KEY_TYPE_PASSWORD_HASH. If you view the key derivation's output as a stream of bytes, this function destructively reads the number of bytes corresponding to the length of the expected value from the stream before comparing them. The operation's capacity decreases by the number of bytes read. This is functionally equivalent to exporting the key and calling psa_key_derivation_verify_bytes() on the result, except that it works even if the key cannot be exported. If this function returns an error status other than #PSA_ERROR_INSUFFICIENT_DATA or #PSA_ERROR_INVALID_SIGNATURE, the operation enters an error state and must be aborted by calling psa_key_derivation_abort().
This function encrypts or decrypts data. Since ChaCha20 is a stream cipher, the same operation is used for encrypting and decrypting data.
This function encrypts or decrypts data with ChaCha20 and the given key and nonce. Since ChaCha20 is a stream cipher, the same operation is used for encrypting and decrypting data. \warning You must never use the same (key, nonce) pair more than once. This would void any confidentiality guarantees for the messages encrypted with the same nonce and key.
This function initializes the specified ChaCha20-Poly1305 context. It must be the first API called before using the context. It must be followed by a call to \c mbedtls_chachapoly_setkey() before any operation can be done, and to \c mbedtls_chachapoly_free() once all operations with that context have been finished. In order to encrypt or decrypt full messages at once, for each message you should make a single call to \c mbedtls_chachapoly_crypt_and_tag() or \c mbedtls_chachapoly_auth_decrypt(). In order to encrypt messages piecewise, for each message you should make a call to \c mbedtls_chachapoly_starts(), then 0 or more calls to \c mbedtls_chachapoly_update_aad(), then 0 or more calls to \c mbedtls_chachapoly_update(), then one call to \c mbedtls_chachapoly_finish(). \warning Decryption with the piecewise API is discouraged! Always use \c mbedtls_chachapoly_auth_decrypt() when possible! If however this is not possible because the data is too large to fit in memory, you need to: - call \c mbedtls_chachapoly_starts() and (if needed) \c mbedtls_chachapoly_update_aad() as above, - call \c mbedtls_chachapoly_update() multiple times and ensure its output (the plaintext) is NOT used in any other way than placing it in temporary storage at this point, - call \c mbedtls_chachapoly_finish() to compute the authentication tag and compared it in constant time to the tag received with the ciphertext. If the tags are not equal, you must immediately discard all previous outputs of \c mbedtls_chachapoly_update(), otherwise you can now safely use the plaintext.
This function releases and clears the specified ChaCha20-Poly1305 context.
This function sets the ChaCha20-Poly1305 symmetric encryption key.
This function starts a ChaCha20-Poly1305 encryption or decryption operation. \warning You must never use the same nonce twice with the same key. This would void any confidentiality and authenticity guarantees for the messages encrypted with the same nonce and key. \warning Decryption with the piecewise API is discouraged, see the warning on \c mbedtls_chachapoly_init().
This function feeds additional data to be authenticated into an ongoing ChaCha20-Poly1305 operation. The Additional Authenticated Data (AAD), also called Associated Data (AD) is only authenticated but not encrypted nor included in the encrypted output. It is usually transmitted separately from the ciphertext or computed locally by each party. You may call this function multiple times to process an arbitrary amount of AAD. It is permitted to call this function 0 times, if no AAD is used. This function cannot be called any more if data has been processed by \c mbedtls_chachapoly_update(), or if the context has been finished. \warning Decryption with the piecewise API is discouraged, see the warning on \c mbedtls_chachapoly_init().
Thus function feeds data to be encrypted or decrypted into an on-going ChaCha20-Poly1305 operation. The direction (encryption or decryption) depends on the mode that was given when calling \c mbedtls_chachapoly_starts(). You may call this function multiple times to process an arbitrary amount of data. It is permitted to call this function 0 times, if no data is to be encrypted or decrypted. \warning Decryption with the piecewise API is discouraged, see the warning on \c mbedtls_chachapoly_init().
This function finished the ChaCha20-Poly1305 operation and generates the MAC (authentication tag). \warning Decryption with the piecewise API is discouraged, see the warning on \c mbedtls_chachapoly_init().
This function performs a complete ChaCha20-Poly1305 authenticated encryption with the previously-set key. \warning You must never use the same nonce twice with the same key. This would void any confidentiality and authenticity guarantees for the messages encrypted with the same nonce and key.
This function performs a complete ChaCha20-Poly1305 authenticated decryption with the previously-set key.
RIPEMD-160 process data block (internal use only)
This is a wrapper for the main mbedtls/bignum.h. This wrapper provides a few additional ESP32-only functions. This is because we don't set MBEDTLS_BIGNUM_ALT in the same way we do for AES, SHA, etc. Because we still use most of the bignum.h implementation and just replace a few hardware accelerated functions (see MBEDTLS_MPI_EXP_MOD_ALT & MBEDTLS_MPI_MUL_MPI_ALT in esp_config.h). Lock access to RSA Accelerator (MPI/bignum operations) RSA Accelerator hardware unit can only be used by one consumer at a time.
Unlock access to RSA Accelerator (MPI/bignum operations) Has to be called once for each call to esp_mpi_acquire_hardware().
This function initializes the specified Poly1305 context. It must be the first API called before using the context. It is usually followed by a call to \c mbedtls_poly1305_starts(), then one or more calls to \c mbedtls_poly1305_update(), then one call to \c mbedtls_poly1305_finish(), then finally \c mbedtls_poly1305_free().
This function releases and clears the specified Poly1305 context.
This function sets the one-time authentication key. \warning The key must be unique and unpredictable for each invocation of Poly1305.
This functions feeds an input buffer into an ongoing Poly1305 computation. It is called between \c mbedtls_cipher_poly1305_starts() and \c mbedtls_cipher_poly1305_finish(). It can be called repeatedly to process a stream of data.
This function generates the Poly1305 Message Authentication Code (MAC).
This function calculates the Poly1305 MAC of the input buffer with the provided key. \warning The key must be unique and unpredictable for each invocation of Poly1305.
This function initializes the specified ChaCha20 context. It must be the first API called before using the context. It is usually followed by calls to \c mbedtls_chacha20_setkey() and \c mbedtls_chacha20_starts(), then one or more calls to to \c mbedtls_chacha20_update(), and finally to \c mbedtls_chacha20_free().
This function releases and clears the specified ChaCha20 context.
This function sets the nonce and initial counter value. \warning You must never use the same nonce twice with the same key. This would void any confidentiality guarantees for the messages encrypted with the same nonce and key.
Inject an initial entropy seed for the random generator into secure storage. This function injects data to be used as a seed for the random generator used by the PSA Crypto implementation. On devices that lack a trusted entropy source (preferably a hardware random number generator), the Mbed PSA Crypto implementation uses this value to seed its random generator. On devices without a trusted entropy source, this function must be called exactly once in the lifetime of the device. On devices with a trusted entropy source, calling this function is optional. In all cases, this function may only be called before calling any other function in the PSA Crypto API, including psa_crypto_init(). When this function returns successfully, it populates a file in persistent storage. Once the file has been created, this function can no longer succeed. If any error occurs, this function does not change the system state. You can call this function again after correcting the reason for the error if possible. \warning This function **can** fail! Callers MUST check the return status. \warning If you use this function, you should use it as part of a factory provisioning process. The value of the injected seed is critical to the security of the device. It must be *secret*, *unpredictable* and (statistically) *unique per device*. You should be generate it randomly using a cryptographically secure random generator seeded from trusted entropy sources. You should transmit it securely to the device and ensure that its value is not leaked or stored anywhere beyond the needs of transmitting it from the point of generation to the call of this function, and erase all copies of the value once this function returns. This is an Mbed TLS extension.
MD5 context setup \warning MD5 is considered a weak message digest and its use constitutes a security risk. We recommend considering stronger message digests instead.
Set the threshold error level to handle globally all debug output. Debug messages that have a level over the threshold value are discarded. (Default value: 0 = No debug )
This function releases and clears the specified key wrapping context and underlying cipher sub-context.
Initialize DES context \warning DES/3DES are considered weak ciphers and their use constitutes a security risk. We recommend considering stronger ciphers instead.
Clear DES context \warning DES/3DES are considered weak ciphers and their use constitutes a security risk. We recommend considering stronger ciphers instead.
Initialize Triple-DES context \warning DES/3DES are considered weak ciphers and their use constitutes a security risk. We recommend considering stronger ciphers instead.
Clear Triple-DES context \warning DES/3DES are considered weak ciphers and their use constitutes a security risk. We recommend considering stronger ciphers instead.
Set key parity on the given key to odd. DES keys are 56 bits long, but each byte is padded with a parity bit to allow verification. \warning DES/3DES are considered weak ciphers and their use constitutes a security risk. We recommend considering stronger ciphers instead.
This function initializes the specified key wrapping context to make references valid and prepare the context for mbedtls_nist_kw_setkey() or mbedtls_nist_kw_free().
This function initializes the key wrapping context set in the \p ctx parameter and sets the encryption key.
Internal function for key expansion. (Only exposed to allow overriding it, see MBEDTLS_DES_SETKEY_ALT) \warning DES/3DES are considered weak ciphers and their use constitutes a security risk. We recommend considering stronger ciphers instead.
This function generates a public key and a TLS ServerKeyExchange payload. This is the first function used by a TLS server for x25519.
This function parses and processes a TLS ServerKeyExchange payload.
This function sets up an x25519 context from an EC key. It is used by clients and servers in place of the ServerKeyEchange for static ECDH, and imports ECDH parameters from the EC key information of a certificate. \see ecp.h
This function derives and exports the shared secret. This is the last function used by both TLS client and servers.
This function generates a public key and a TLS ClientKeyExchange payload. This is the second function used by a TLS client for x25519. \see ecp.h
This function generates a public key and a TLS ClientKeyExchange payload. This is the second function used by a TLS client for ECDH(E) ciphersuites. \see ecp.h
This function parses and processes a TLS ClientKeyExchange payload. This is the third function used by a TLS server for ECDH(E) ciphersuites. (It is called after mbedtls_ecdh_setup() and mbedtls_ecdh_make_params().) \see ecp.h
This function derives and exports the shared secret. This is the last function used by both TLS client and servers. \see ecp.h
This function parses and processes a TLS ClientKeyExchange payload. This is the second function used by a TLS server for x25519. \see ecp.h
This function sets up the ECDH context with the information given. This function should be called after mbedtls_ecdh_init() but before mbedtls_ecdh_make_params(). There is no need to call this function before mbedtls_ecdh_read_params(). This is the first function used by a TLS server for ECDHE ciphersuites.
This function generates a public key and a TLS ServerKeyExchange payload. This is the second function used by a TLS server for ECDHE ciphersuites. (It is called after mbedtls_ecdh_setup().) \see ecp.h
This function sets up an ECDH context from an EC key. It is used by clients and servers in place of the ServerKeyEchange for static ECDH, and imports ECDH parameters from the EC key information of a certificate. \see ecp.h
Initialize the context. This must be the first API call before using the context.
Encrypt one block (16 bytes) with the configured key.
Set the block cipher to use with this context. This must be called after mbedtls_block_cipher_init().
Setup a residue structure. The residue will be set up with the buffer \p p and modulus \p N. The memory pointed to by \p p will be used by the resulting residue structure. The value at the pointed-to memory will be the initial value of \p r and must hold a value that is less than the modulus. This value will be used as-is and interpreted according to the value of the `N->int_rep` field. The modulus \p N will be the modulus associated with \p r. The residue \p r should only be used in operations where the modulus is \p N.
Unbind elements of a residue structure. This function removes the reference to the limb array that was passed to mbedtls_mpi_mod_residue_setup() to make it safe to free or use again. This function invalidates \p r and it must not be used until after mbedtls_mpi_mod_residue_setup() is called on it again.
Setup an optimised-reduction compatible modulus structure.
Free elements of a modulus structure. This function frees any memory allocated by mbedtls_mpi_mod_modulus_setup(). \warning This function does not free the limb array passed to mbedtls_mpi_mod_modulus_setup() only removes the reference to it, making it safe to free or to use it again.
Multiply two residues, returning the residue modulo the specified modulus. The size of the operation is determined by \p N. \p A, \p B and \p X must all be associated with the modulus \p N and must all have the same number of limbs as \p N. \p X may be aliased to \p A or \p B, or even both, but may not overlap either otherwise. They may not alias \p N (since they must be in canonical form, they cannot == \p N).
Perform a fixed-size modular subtraction. Calculate `A - B modulo N`. \p A, \p B and \p X must all have the same number of limbs as \p N. \p X may be aliased to \p A or \p B, or even both, but may not overlap either otherwise.
Perform modular inversion of an MPI with respect to a modulus \p N. \p A and \p X must be associated with the modulus \p N and will therefore have the same number of limbs as \p N. \p X may be aliased to \p A. \warning Currently only supports prime moduli, but does not check for them.
Perform a fixed-size modular addition. Calculate `A + B modulo N`. \p A, \p B and \p X must all be associated with the modulus \p N and must all have the same number of limbs as \p N. \p X may be aliased to \p A or \p B, or even both, but may not overlap either otherwise.
Generate a random number uniformly in a range. This function generates a random number between \p min inclusive and \p N exclusive. The procedure complies with RFC 6979 §3.3 (deterministic ECDSA) when the RNG is a suitably parametrized instance of HMAC_DRBG and \p min is \c 1.
Read a residue from a byte buffer. The residue will be automatically converted to the internal representation based on the value of the `N->int_rep` field. The modulus \p N will be the modulus associated with \p r. The residue \p r should only be used in operations where the modulus is \p N or a modulus equivalent to \p N (in the sense that all their fields or memory pointed by their fields hold the same value).
Write a residue into a byte buffer. The modulus \p N must be the modulus associated with \p r (see mbedtls_mpi_mod_residue_setup() and mbedtls_mpi_mod_read()). The residue will be automatically converted from the internal representation based on the value of `N->int_rep` field. \warning If the buffer is smaller than `N->bits`, the number of leading zeroes is leaked through timing. If \p r is secret, the caller must ensure that \p buflen is at least (`N->bits`+7)/8.
Return an offset into a read-only buffer. Similar to mbedtls_buffer_offset(), but for const pointers.
Unregister all secure element drivers. \warning Do not call this function while the library is in the initialized state. This function is only intended to be called at the end of mbedtls_psa_crypto_free().
Initialize all secure element drivers. Called from psa_crypto_init().
Return the secure element driver information for a lifetime value.
Return the secure element driver table entry for a lifetime value.
Return the method table for a secure element driver.
Find a free slot for a key that is to be created. This function calls the relevant method in the driver to find a suitable slot for a key with the given attributes.
Destroy a key in a secure element. This function calls the relevant driver method to destroy a key and updates the driver's persistent data.
Load the persistent data of a secure element driver.
Save the persistent data of a secure element driver.
Destroy the persistent data of a secure element driver. This is currently only used for testing.
Register an external cryptoprocessor (secure element) driver. This function is only intended to be used by driver code, not by application code. In implementations with separation between the PSA cryptography module and applications, this function should only be available to callers that run in the same memory space as the cryptography module, and should not be exposed to applications running in a different memory space. This function may be called before psa_crypto_init(). It is implementation-defined whether this function may be called after psa_crypto_init().
Get the maximum number of ops allowed to be executed by an interruptible function in a single call.
Perform a CAMELLIA key schedule operation for encryption.
Perform a CAMELLIA key schedule operation for decryption.
Perform a CAMELLIA-ECB block encryption/decryption operation.
Perform a CAMELLIA-CBC buffer encryption/decryption operation.
Perform a CAMELLIA-CFB128 buffer encryption/decryption operation.
Perform a CAMELLIA-CTR buffer encryption/decryption operation. *note Due to the nature of CTR mode, you should use the same key for both encryption and decryption. In particular, calls to this function should be preceded by a key-schedule via mbedtls_camellia_setkey_enc() regardless of whether the mode is #MBEDTLS_CAMELLIA_ENCRYPT or #MBEDTLS_CAMELLIA_DECRYPT. \warning You must never reuse a nonce value with the same key. Doing so would void the encryption for the two messages encrypted with the same nonce and key. There are two common strategies for managing nonces with CTR: 1. You can handle everything as a single message processed over successive calls to this function. In that case, you want to set \p nonce_counter and \p nc_off to 0 for the first call, and then preserve the values of \p nonce_counter, \p nc_off and \p stream_block across calls to this function as they will be updated by this function. With this strategy, you must not encrypt more than 2**128 blocks of data with the same key. 2. You can encrypt separate messages by dividing the \p nonce_counter buffer in two areas: the first one used for a per-message nonce, handled by yourself, and the second one updated by this function internally. For example, you might reserve the first \c 12 Bytes for the per-message nonce, and the last \c 4 Bytes for internal use. In that case, before calling this function on a new message you need to set the first \c 12 Bytes of \p nonce_counter to your chosen nonce value, the last four to \c 0, and \p nc_off to \c 0 (which will cause \p stream_block to be ignored). That way, you can encrypt at most \c 2**96 messages of up to \c 2**32 blocks each with the same key. The per-message nonce (or information sufficient to reconstruct it) needs to be communicated with the ciphertext and must be unique. The recommended way to ensure uniqueness is to use a message counter. An alternative is to generate random nonces, but this limits the number of messages that can be securely encrypted: for example, with 96-bit random nonces, you should not encrypt more than 2**32 messages with the same key. Note that for both strategies, sizes are measured in blocks and that a CAMELLIA block is \c 16 Bytes. \warning Upon return, \p stream_block contains sensitive data. Its content must not be written to insecure storage and should be securely discarded as soon as it's no longer needed.
Wait for the SHA engine to finish any current operation
Get the cache timeout A timeout of 0 indicates no timeout.
Print a field of the ECDH structure in the SSL context to the debug output. This function is always used through the MBEDTLS_SSL_DEBUG_ECDH() macro, which supplies the ssl context, file and line number parameters. \attention This function is intended for INTERNAL usage within the library only.
Print a message to the debug output. This function is always used through the MBEDTLS_SSL_DEBUG_MSG() macro, which supplies the ssl context, file and line number parameters. \attention This function is intended for INTERNAL usage within the library only.
Print the return value of a function to the debug output. This function is always used through the MBEDTLS_SSL_DEBUG_RET() macro, which supplies the ssl context, file and line number parameters. \attention This function is intended for INTERNAL usage within the library only.
Output a buffer of size len bytes to the debug output. This function is always used through the MBEDTLS_SSL_DEBUG_BUF() macro, which supplies the ssl context, file and line number parameters. \attention This function is intended for INTERNAL usage within the library only.
Print a MPI variable to the debug output. This function is always used through the MBEDTLS_SSL_DEBUG_MPI() macro, which supplies the ssl context, file and line number parameters. \attention This function is intended for INTERNAL usage within the library only.
Print an ECP point to the debug output. This function is always used through the MBEDTLS_SSL_DEBUG_ECP() macro, which supplies the ssl context, file and line number parameters. \attention This function is intended for INTERNAL usage within the library only.
Print a X.509 certificate structure to the debug output. This function is always used through the MBEDTLS_SSL_DEBUG_CRT() macro, which supplies the ssl context, file and line number parameters. \attention This function is intended for INTERNAL usage within the library only.
Sign an already-calculated hash with a private key using p256-m's ECDSA implementation
Verify the signature of a hash using a SECP256R1 public key using p256-m's ECDSA implementation.
Export SECP256R1 public key, from the private key.
Generate SECP256R1 ECC Key Pair. Interface function which calls the p256-m key generation function and places it in the key buffer provided by the caller (Mbed TLS) in the correct format. For a SECP256R1 curve this is the 32 bit private key.
Perform raw key agreement using p256-m's ECDH implementation
Set the EC J-PAKE opaque password for current handshake.
Other commonly used symbols
Name
Location
Summary
Function return status. This is either #PSA_SUCCESS (which is zero), indicating success, or a small negative value indicating that an error occurred. Errors are encoded as one of the \c PSA_ERROR_xxx values defined here.
Encoding of a cryptographic algorithm. Values of this type are generally constructed by macros called `PSA_ALG_xxx`. For algorithms that can be applied to multiple key types, this type does not encode the key type. For example, for symmetric ciphers based on a block cipher, #psa_algorithm_t encodes the block cipher mode and the padding mode while the block cipher itself is encoded via #psa_key_type_t.
The type of a structure containing key attributes. This is an opaque structure that can represent the metadata of a key object. Metadata that can be stored in attributes includes: - The location of the key in storage, indicated by its key identifier and its lifetime. - The key's policy, comprising usage flags and a specification of the permitted algorithm(s). - Information about the key itself: the key type and its size. - Additional implementation-defined attributes. The actual key material is not considered an attribute of a key. Key attributes do not contain information that is generally considered highly confidential. An attribute structure works like a simple data structure where each function `psa_set_key_xxx` sets a field and the corresponding function `psa_get_key_xxx` retrieves the value of the corresponding field. However, a future version of the library may report values that are equivalent to the original one, but have a different encoding. Invalid values may be mapped to different, also invalid values. An attribute structure may contain references to auxiliary resources, for example pointers to allocated memory or indirect references to pre-calculated values. In order to free such resources, the application must call psa_reset_key_attributes(). As an exception, calling psa_reset_key_attributes() on an attribute structure is optional if the structure has only been modified by the following functions since it was initialized or last reset with psa_reset_key_attributes(): - psa_set_key_id() - psa_set_key_lifetime() - psa_set_key_type() - psa_set_key_bits() - psa_set_key_usage_flags() - psa_set_key_algorithm() Before calling any function on a key attribute structure, the application must initialize it by any of the following means: - Set the structure to all-bits-zero, for example:
psa_key_attributes_t attributes;
memset(&attributes, 0, sizeof(attributes));
- Initialize the structure to logical zero values, for example:
psa_key_attributes_t attributes = {0};
- Initialize the structure to the initializer #PSA_KEY_ATTRIBUTES_INIT, for example:
psa_key_attributes_t attributes = PSA_KEY_ATTRIBUTES_INIT;
- Assign the result of the function psa_key_attributes_init() to the structure, for example:
psa_key_attributes_t attributes;
attributes = psa_key_attributes_init();
A freshly initialized attribute structure contains the following values: - lifetime: #PSA_KEY_LIFETIME_VOLATILE. - key identifier: 0 (which is not a valid key identifier). - type: \c 0 (meaning that the type is unspecified). - key size: \c 0 (meaning that the size is unspecified). - usage flags: \c 0 (which allows no usage except exporting a public key). - algorithm: \c 0 (which allows no cryptographic usage, but allows exporting). A typical sequence to create a key is as follows: -# Create and initialize an attribute structure. -# If the key is persistent, call psa_set_key_id(). Also call psa_set_key_lifetime() to place the key in a non-default location. -# Set the key policy with psa_set_key_usage_flags() and psa_set_key_algorithm(). -# Set the key type with psa_set_key_type(). Skip this step if copying an existing key with psa_copy_key(). -# When generating a random key with psa_generate_key() or deriving a key with psa_key_derivation_output_key(), set the desired key size with psa_set_key_bits(). -# Call a key creation function: psa_import_key(), psa_generate_key(), psa_key_derivation_output_key() or psa_copy_key(). This function reads the attribute structure, creates a key with these attributes, and outputs a key identifier to the newly created key. -# The attribute structure is now no longer necessary. You may call psa_reset_key_attributes(), although this is optional with the workflow presented here because the attributes currently defined in this specification do not require any additional resources beyond the structure itself. A typical sequence to query a key's attributes is as follows: -# Call psa_get_key_attributes(). -# Call `psa_get_key_xxx` functions to retrieve the attribute(s) that you are interested in. -# Call psa_reset_key_attributes() to free any resources that may be used by the attribute structure. Once a key has been created, it is impossible to change its attributes. Container for an X.509 certificate. The certificate may be chained. Some fields of this structure are publicly readable. Do not modify them except via Mbed TLS library functions: the effect of modifying those fields or the data that those fields points to is unspecified.
The ECP group structure. We consider two types of curve equations: Short Weierstrass: y^2 = x^3 + A x + B mod P (SEC1 + RFC-4492) Montgomery: y^2 = x^3 + A x^2 + x mod P (Curve25519, Curve448) In both cases, the generator (\p G) for a prime-order subgroup is fixed. For Short Weierstrass, this subgroup is the whole curve, and its cardinality is denoted by \p N. Our code requires that \p N is an odd prime as mbedtls_ecp_mul() requires an odd number, and mbedtls_ecdsa_sign() requires that it is prime for blinding purposes. The default implementation only initializes \p A without setting it to the authentic value for curves with A = -3(SECP256R1, etc), in which case you need to load \p A by yourself when using domain parameters directly, for example:
mbedtls_mpi_init(&A);
mbedtls_ecp_group_init(&grp);
CHECK_RETURN(mbedtls_ecp_group_load(&grp, grp_id));
if (mbedtls_ecp_group_a_is_minus_3(&grp)) {
CHECK_RETURN(mbedtls_mpi_sub_int(&A, &grp.P, 3));
} else {
CHECK_RETURN(mbedtls_mpi_copy(&A, &grp.A));
}
do_something_with_a(&A);
cleanup:
mbedtls_mpi_free(&A);
mbedtls_ecp_group_free(&grp);
For Montgomery curves, we do not store \p A, but (A + 2) / 4, which is the quantity used in the formulas. Additionally, \p nbits is not the size of \p N but the required size for private keys. If \p modp is NULL, reduction modulo \p P is done using a generic algorithm. Otherwise, \p modp must point to a function that takes an \p mbedtls_mpi in the range of 0..2^(2*pbits)-1, and transforms it in-place to an integer which is congruent mod \p P to the given MPI, and is close enough to \p pbits in size, so that it may be efficiently brought in the 0..P-1 range by a few additions or subtractions. Therefore, it is only an approximate modular reduction. It must return 0 on success and non-zero on failure. SSL/TLS configuration to be shared between mbedtls_ssl_context structures.
Combines a high-level and low-level error code together. Wrapper macro for mbedtls_error_add(). See that function for more details.
Encoding of a key type. Values of this type are generally constructed by macros called `PSA_KEY_TYPE_xxx`.
The ECP key-pair structure. A generic key-pair that may be used for ECDSA and fixed ECDH, for example.
Critical-failure function This macro appearing at the beginning of the declaration of a function indicates that its return value should be checked in all applications. Omitting the check is very likely to indicate a bug in the application and will result in a compile-time warning if #MBEDTLS_CHECK_RETURN is implemented for the compiler in use.
A tampering attempt was detected. If an application receives this error code, there is no guarantee that previously accessed or computed data was correct and remains confidential. Applications should not perform any security function and should enter a safe failure state. Implementations may return this error code if they detect an invalid state that cannot happen during normal operation and that indicates that the implementation's security guarantees no longer hold. Depending on the implementation architecture and on its security and safety goals, the implementation may forcibly terminate the application. This error code is intended as a last resort when a security breach is detected and it is unsure whether the keystore data is still protected. Implementations shall only return this error code to report an alarm from a tampering detector, to indicate that the confidentiality of stored data can no longer be guaranteed, or to indicate that the integrity of previously returned data is now considered compromised. Implementations shall not use this error code to indicate a hardware failure that merely makes it impossible to perform the requested operation (use #PSA_ERROR_COMMUNICATION_FAILURE, #PSA_ERROR_STORAGE_FAILURE, #PSA_ERROR_HARDWARE_FAILURE, #PSA_ERROR_INSUFFICIENT_ENTROPY or other applicable error code instead). This error indicates an attack against the application. Implementations shall not return this error code as a consequence of the behavior of
Encoding of key identifiers as seen inside the PSA Crypto implementation. When PSA Crypto is built as a library inside an application, this type is identical to #psa_key_id_t. When PSA Crypto is built as a service that can store keys on behalf of multiple clients, this type encodes the #psa_key_id_t value seen by each client application as well as extra information that identifies the client that owns the key.
Cipher information. Allows calling cipher functions in a generic way.
The parameters passed to the function are invalid. Implementations may return this error any time a parameter or combination of parameters are recognized as invalid. Implementations shall not return this error code to indicate that a key identifier is invalid, but shall return #PSA_ERROR_INVALID_HANDLE instead.
The data structure representing a key slot, containing key material and metadata for one key.
This structure is used for storing ciphersuite information
Encoding of key location indicators. If an integration of Mbed TLS can make calls to external cryptoprocessors such as secure elements, the location of a key indicates which secure element performs the operations on the key. Depending on the design of the secure element, the key material may be stored either in the secure element, or in wrapped (encrypted) form alongside the key metadata in the primary local storage. The PSA Cryptography API specification defines the following values of location indicators: - \c 0: primary local storage. This location is always available. The primary local storage is typically the same storage area that contains the key metadata. - \c 1: primary secure element. Integrations of Mbed TLS should support this value if there is a secure element attached to the operating environment. As a guideline, secure elements may provide higher resistance against side channel and physical attacks than the primary local storage, but may have restrictions on supported key types, sizes, policies and operations and may have different performance characteristics. - \c 2-0x7fffff: other locations defined by a PSA specification. The PSA Cryptography API does not currently assign any meaning to these locations, but future versions of that specification or other PSA specifications may do so. - \c 0x800000-0xffffff: vendor-defined locations. No PSA specification will assign a meaning to locations in this range.
The requested operation or a parameter is not supported by this implementation. Implementations should return this error code when an enumeration parameter such as a key type, algorithm, etc. is not recognized. If a combination of parameters is recognized and identified as
\def MBEDTLS_SSL_EARLY_DATA Enable support for RFC 8446 TLS 1.3 early data. Requires: MBEDTLS_SSL_SESSION_TICKETS and either MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_PSK_ENABLED or MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_PSK_EPHEMERAL_ENABLED Comment this to disable support for early data. If MBEDTLS_SSL_PROTO_TLS1_3 is not enabled, this option does not have any effect on the build. \def MBEDTLS_SSL_PROTO_DTLS Enable support for DTLS (all available versions). Enable this and MBEDTLS_SSL_PROTO_TLS1_2 to enable DTLS 1.2. Requires: MBEDTLS_SSL_PROTO_TLS1_2 Comment this macro to disable support for DTLS
Message digest information. Allows message digest functions to be called in a generic way.
\def MBEDTLS_SSL_PROTO_TLS1_3 Enable support for TLS 1.3. Requires: MBEDTLS_SSL_KEEP_PEER_CERTIFICATE Requires: MBEDTLS_PSA_CRYPTO_C Uncomment this macro to enable the support for TLS 1.3.
The requested action cannot be performed in the current state. Multipart operations return this error when one of the functions is called out of sequence. Refer to the function descriptions for permitted sequencing of functions. Implementations shall not return this error code to indicate that a key either exists or not, but shall instead return #PSA_ERROR_ALREADY_EXISTS or #PSA_ERROR_DOES_NOT_EXIST as applicable. Implementations shall not return this error code to indicate that a key identifier is invalid, but shall return #PSA_ERROR_INVALID_HANDLE
Encoding of permitted usage on a key. Values of this type are generally constructed as bitwise-ors of macros called `PSA_KEY_USAGE_xxx`.
The type of the state data structure for key derivation operations. Before calling any function on a key derivation operation object, the application must initialize it by any of the following means: - Set the structure to all-bits-zero, for example:
psa_key_derivation_operation_t operation;
memset(&operation, 0, sizeof(operation));
- Initialize the structure to logical zero values, for example:
psa_key_derivation_operation_t operation = {0};
- Initialize the structure to the initializer #PSA_KEY_DERIVATION_OPERATION_INIT, for example:
psa_key_derivation_operation_t operation = PSA_KEY_DERIVATION_OPERATION_INIT;
- Assign the result of the function psa_key_derivation_operation_init() to the structure, for example:
psa_key_derivation_operation_t operation;
operation = psa_key_derivation_operation_init();
This is an implementation-defined \c struct. Applications should not make any assumptions about the content of this structure. Implementation details can change in future versions without notice. \def MBEDTLS_SSL_RECORD_SIZE_LIMIT Enable support for RFC 8449 record_size_limit extension in SSL (TLS 1.3 only). Requires: MBEDTLS_SSL_PROTO_TLS1_3 Uncomment this macro to enable support for the record_size_limit extension \def MBEDTLS_SSL_PROTO_TLS1_2 Enable support for TLS 1.2 (and DTLS 1.2 if DTLS is enabled). Requires: Without MBEDTLS_USE_PSA_CRYPTO: MBEDTLS_MD_C and (MBEDTLS_SHA256_C or MBEDTLS_SHA384_C or SHA-256 or SHA-512 provided by a PSA driver) With MBEDTLS_USE_PSA_CRYPTO: PSA_WANT_ALG_SHA_256 or PSA_WANT_ALG_SHA_384 \warning If building with MBEDTLS_USE_PSA_CRYPTO, or if the hash(es) used are only provided by PSA drivers, you must call psa_crypto_init() before doing any TLS operations. Comment this macro to disable support for TLS 1.2 / DTLS 1.2
\def MBEDTLS_SSL_SRV_C Enable the SSL/TLS server code. Module: library/ssl*_server.c Caller: Requires: MBEDTLS_SSL_TLS_C This module is required for SSL/TLS server support.
Encoding of identifiers of persistent keys. - Applications may freely choose key identifiers in the range #PSA_KEY_ID_USER_MIN to #PSA_KEY_ID_USER_MAX. - The implementation may define additional key identifiers in the range #PSA_KEY_ID_VENDOR_MIN to #PSA_KEY_ID_VENDOR_MAX. - 0 is reserved as an invalid key identifier. - Key identifiers outside these ranges are reserved for future use.
Sign: -1 if the mpi is negative, 1 otherwise. The number 0 must be represented with `s = +1`. Although many library functions treat all-limbs-zero as equivalent to a valid representation of 0 regardless of the sign bit, there are exceptions, so bignum functions and external callers must always set \c s to +1 for the number zero. Note that this implies that calloc() or `... = {0}` does not create a valid MPI representation. You must call mbedtls_mpi_init().
\warning Performing multiple operations concurrently on the same ECDSA context is not supported; objects of this type should not be shared between multiple threads. The ECDH context structure.
The CCM context-type definition. The CCM context is passed to the APIs called.
Certificate revocation list structure. Every CRL may have multiple entries.
\def MBEDTLS_RSA_C Enable the RSA public-key cryptosystem. Module: library/rsa.c library/rsa_alt_helpers.c Caller: library/pk.c library/psa_crypto.c library/ssl_tls.c library/ssl*_client.c library/ssl*_server.c This module is used by the following key exchanges: RSA, DHE-RSA, ECDHE-RSA, RSA-PSK Requires: MBEDTLS_BIGNUM_C, MBEDTLS_OID_C
The type of the state data structure for multipart AEAD operations. Before calling any function on an AEAD operation object, the application must initialize it by any of the following means: - Set the structure to all-bits-zero, for example:
psa_aead_operation_t operation;
memset(&operation, 0, sizeof(operation));
- Initialize the structure to logical zero values, for example:
psa_aead_operation_t operation = {0};
- Initialize the structure to the initializer #PSA_AEAD_OPERATION_INIT, for example:
psa_aead_operation_t operation = PSA_AEAD_OPERATION_INIT;
- Assign the result of the function psa_aead_operation_init() to the structure, for example:
psa_aead_operation_t operation;
operation = psa_aead_operation_init();
This is an implementation-defined \c struct. Applications should not make any assumptions about the content of this structure. Implementation details can change in future versions without notice. The type of the state data structure for multipart hash operations. Before calling any function on a hash operation object, the application must initialize it by any of the following means: - Set the structure to all-bits-zero, for example:
psa_hash_operation_t operation;
memset(&operation, 0, sizeof(operation));
- Initialize the structure to logical zero values, for example:
psa_hash_operation_t operation = {0};
- Initialize the structure to the initializer #PSA_HASH_OPERATION_INIT, for example:
psa_hash_operation_t operation = PSA_HASH_OPERATION_INIT;
- Assign the result of the function psa_hash_operation_init() to the structure, for example:
psa_hash_operation_t operation;
operation = psa_hash_operation_init();
This is an implementation-defined \c struct. Applications should not make any assumptions about the content of this structure. Implementation details can change in future versions without notice. The type of PSA elliptic curve family identifiers. Values of this type are generally constructed by macros called `PSA_ECC_FAMILY_xxx`. The curve identifier is required to create an ECC key using the PSA_KEY_TYPE_ECC_KEY_PAIR() or PSA_KEY_TYPE_ECC_PUBLIC_KEY() macros. Values defined by this standard will never be in the range 0x80-0xff. Vendors who define additional families must use an encoding in this range.
The type of the state data structure for PAKE operations. Before calling any function on a PAKE operation object, the application must initialize it by any of the following means: - Set the structure to all-bits-zero, for example:
psa_pake_operation_t operation;
memset(&operation, 0, sizeof(operation));
- Initialize the structure to logical zero values, for example:
psa_pake_operation_t operation = {0};
- Initialize the structure to the initializer #PSA_PAKE_OPERATION_INIT, for example:
psa_pake_operation_t operation = PSA_PAKE_OPERATION_INIT;
- Assign the result of the function psa_pake_operation_init() to the structure, for example:
psa_pake_operation_t operation;
operation = psa_pake_operation_init();
This is an implementation-defined \c struct. Applications should not make any assumptions about the content of this structure. Implementation details can change in future versions without notice. EC J-PAKE context structure. J-PAKE is a symmetric protocol, except for the identifiers used in Zero-Knowledge Proofs, and the serialization of the second message (KeyExchange) as defined by the Thread spec. In order to benefit from this symmetry, we choose a different naming convention from the Thread v1.0 spec. Correspondence is indicated in the description as a pair C: client name, S: server name
\def MBEDTLS_X509_CRT_PARSE_C Enable X.509 certificate parsing. Module: library/x509_crt.c Caller: library/ssl_tls.c library/ssl*_client.c library/ssl*_server.c Requires: MBEDTLS_X509_USE_C This module is required for X.509 certificate parsing.
Byte Reading Macros Given a multi-byte integer \p x, MBEDTLS_BYTE_n retrieves the n-th byte from x, where byte 0 is the least significant byte.
Uncomment to enable p256-m. This is an alternative implementation of key generation, ECDH and (randomized) ECDSA on the curve SECP256R1. Compared to the default implementation: - p256-m has a much smaller code size and RAM footprint. - p256-m is only available via the PSA API. This includes the pk module when #MBEDTLS_USE_PSA_CRYPTO is enabled. - p256-m does not support deterministic ECDSA, EC-JPAKE, custom protocols over the core arithmetic, or deterministic derivation of keys. We recommend enabling this option if your application uses the PSA API and the only elliptic curve support it needs is ECDH and ECDSA over SECP256R1. If you enable this option, you do not need to enable any ECC-related MBEDTLS_xxx option. You do need to separately request support for the cryptographic mechanisms through the PSA API: - #MBEDTLS_PSA_CRYPTO_C and #MBEDTLS_PSA_CRYPTO_CONFIG for PSA-based configuration; - #MBEDTLS_USE_PSA_CRYPTO if you want to use p256-m from PK, X.509 or TLS; - #PSA_WANT_ECC_SECP_R1_256; - #PSA_WANT_ALG_ECDH and/or #PSA_WANT_ALG_ECDSA as needed; - #PSA_WANT_KEY_TYPE_ECC_PUBLIC_KEY, #PSA_WANT_KEY_TYPE_ECC_KEY_PAIR_BASIC, #PSA_WANT_KEY_TYPE_ECC_KEY_PAIR_IMPORT, #PSA_WANT_KEY_TYPE_ECC_KEY_PAIR_EXPORT and/or #PSA_WANT_KEY_TYPE_ECC_KEY_PAIR_GENERATE as needed. \def MBEDTLS_PSA_INJECT_ENTROPY Enable support for entropy injection at first boot. This feature is required on systems that do not have a built-in entropy source (TRNG). This feature is currently not supported on systems that have a built-in entropy source. Requires: MBEDTLS_PSA_CRYPTO_STORAGE_C, MBEDTLS_ENTROPY_NV_SEED \def MBEDTLS_PSA_ASSUME_EXCLUSIVE_BUFFERS Assume all buffers passed to PSA functions are owned exclusively by the PSA function and are not stored in shared memory. This option may be enabled if all buffers passed to any PSA function reside in memory that is accessible only to the PSA function during its execution. This option MUST be disabled whenever buffer arguments are in memory shared with an untrusted party, for example where arguments to PSA calls are passed across a trust boundary. \def MBEDTLS_RSA_NO_CRT Do not use the Chinese Remainder Theorem for the RSA private operation. Uncomment this macro to disable the use of CRT in RSA. \def MBEDTLS_SELF_TEST Enable the checkup functions (*_self_test).
\def MBEDTLS_NO_UDBL_DIVISION The platform lacks support for double-width integer division (64-bit division on a 32-bit platform, 128-bit division on a 64-bit platform). Used in: include/mbedtls/bignum.h library/bignum.c The bignum code uses double-width division to speed up some operations. Double-width division is often implemented in software that needs to be linked with the program. The presence of a double-width integer type is usually detected automatically through preprocessor macros, but the automatic detection cannot know whether the code needs to and can be linked with an implementation of division for that type. By default division is assumed to be usable if the type is present. Uncomment this option to prevent the use of double-width division. Note that division for the native integer type is always required. Furthermore, a 64-bit type is always required even on a 32-bit platform, but it need not support multiplication or division. In some cases it is also desirable to disable some double-width operations. For example, if double-width division is implemented in software, disabling it can reduce code size in some embedded targets. \def MBEDTLS_NO_64BIT_MULTIPLICATION The platform lacks support for 32x32 -> 64-bit multiplication. Used in: library/poly1305.c Some parts of the library may use multiplication of two unsigned 32-bit operands with a 64-bit result in order to speed up computations. On some platforms, this is not available in hardware and has to be implemented in software, usually in a library provided by the toolchain. Sometimes it is not desirable to have to link to that library. This option removes the dependency of that library on platforms that lack a hardware 64-bit multiplier by embedding a software implementation in Mbed TLS. Note that depending on the compiler, this may decrease performance compared to using the library function provided by the toolchain. \def MBEDTLS_HAVE_SSE2 CPU supports SSE2 instruction set. Uncomment if the CPU supports SSE2 (IA-32 specific). \def MBEDTLS_HAVE_TIME System has time.h and time(). The time does not need to be correct, only time differences are used, by contrast with MBEDTLS_HAVE_TIME_DATE Defining MBEDTLS_HAVE_TIME allows you to specify MBEDTLS_PLATFORM_TIME_ALT, MBEDTLS_PLATFORM_TIME_MACRO, MBEDTLS_PLATFORM_TIME_TYPE_MACRO and MBEDTLS_PLATFORM_STD_TIME. Comment if your system does not support time functions.
\def MBEDTLS_SSL_DTLS_CONNECTION_ID Enable support for the DTLS Connection ID (CID) extension, which allows to identify DTLS connections across changes in the underlying transport. The CID functionality is described in RFC 9146. Setting this option enables the SSL APIs `mbedtls_ssl_set_cid()`, mbedtls_ssl_get_own_cid()`, `mbedtls_ssl_get_peer_cid()` and `mbedtls_ssl_conf_cid()`. See the corresponding documentation for more information. The maximum lengths of outgoing and incoming CIDs can be configured through the options - MBEDTLS_SSL_CID_OUT_LEN_MAX - MBEDTLS_SSL_CID_IN_LEN_MAX. Requires: MBEDTLS_SSL_PROTO_DTLS Uncomment to enable the Connection ID extension.
\def MBEDTLS_SSL_RENEGOTIATION Enable support for TLS renegotiation. The two main uses of renegotiation are (1) refresh keys on long-lived connections and (2) client authentication after the initial handshake. If you don't need renegotiation, it's probably better to disable it, since it has been associated with security issues in the past and is easy to misuse/misunderstand. Requires: MBEDTLS_SSL_PROTO_TLS1_2 Comment this to disable support for renegotiation.
The type of the data structure for PAKE cipher suites. This is an implementation-defined \c struct. Applications should not make any assumptions about the content of this structure. Implementation details can change in future versions without notice.
\def MBEDTLS_SSL_CLI_C Enable the SSL/TLS client code. Module: library/ssl*_client.c Caller: Requires: MBEDTLS_SSL_TLS_C This module is required for SSL/TLS client support.
Wrapper type for sockets. Currently backed by just a file descriptor, but might be more in the future (eg two file descriptors for combined IPv4 + IPv6 support, or additional structures for hand-made UDP demultiplexing).
\def MBEDTLS_SSL_SESSION_TICKETS Enable support for RFC 5077 session tickets in SSL. Client-side, provides full support for session tickets (maintenance of a session store remains the responsibility of the application, though). Server-side, you also need to provide callbacks for writing and parsing tickets, including authenticated encryption and key management. Example callbacks are provided by MBEDTLS_SSL_TICKET_C. Comment this macro to disable support for SSL session tickets
The type of the state data structure for multipart MAC operations. Before calling any function on a MAC operation object, the application must initialize it by any of the following means: - Set the structure to all-bits-zero, for example:
psa_mac_operation_t operation;
memset(&operation, 0, sizeof(operation));
- Initialize the structure to logical zero values, for example:
psa_mac_operation_t operation = {0};
- Initialize the structure to the initializer #PSA_MAC_OPERATION_INIT, for example:
psa_mac_operation_t operation = PSA_MAC_OPERATION_INIT;
- Assign the result of the function psa_mac_operation_init() to the structure, for example:
psa_mac_operation_t operation;
operation = psa_mac_operation_init();
This is an implementation-defined \c struct. Applications should not make any assumptions about the content of this structure. Implementation details can change in future versions without notice. The type of the state data structure for multipart cipher operations. Before calling any function on a cipher operation object, the application must initialize it by any of the following means: - Set the structure to all-bits-zero, for example:
psa_cipher_operation_t operation;
memset(&operation, 0, sizeof(operation));
- Initialize the structure to logical zero values, for example:
psa_cipher_operation_t operation = {0};
- Initialize the structure to the initializer #PSA_CIPHER_OPERATION_INIT, for example:
psa_cipher_operation_t operation = PSA_CIPHER_OPERATION_INIT;
- Assign the result of the function psa_cipher_operation_init() to the structure, for example:
psa_cipher_operation_t operation;
operation = psa_cipher_operation_init();
This is an implementation-defined \c struct. Applications should not make any assumptions about the content of this structure. Implementation details can change in future versions without notice. Security profile for certificate verification. All lists are bitfields, built by ORing flags from MBEDTLS_X509_ID_FLAG(). The fields of this structure are part of the public API and can be manipulated directly by applications. Future versions of the library may add extra fields or reorder existing fields. You can create custom profiles by starting from a copy of an existing profile, such as mbedtls_x509_crt_profile_default or mbedtls_x509_ctr_profile_none and then tune it to your needs. For example to allow SHA-224 in addition to the default: mbedtls_x509_crt_profile my_profile = mbedtls_x509_crt_profile_default; my_profile.allowed_mds |= MBEDTLS_X509_ID_FLAG( MBEDTLS_MD_SHA224 ); Or to allow only RSA-3072+ with SHA-256: mbedtls_x509_crt_profile my_profile = mbedtls_x509_crt_profile_none; my_profile.allowed_mds = MBEDTLS_X509_ID_FLAG( MBEDTLS_MD_SHA256 ); my_profile.allowed_pks = MBEDTLS_X509_ID_FLAG( MBEDTLS_PK_RSA ); my_profile.rsa_min_bitlen = 3072;
\def MBEDTLS_KEY_EXCHANGE_ECJPAKE_ENABLED Enable the ECJPAKE based ciphersuite modes in SSL / TLS. \warning This is currently experimental. EC J-PAKE support is based on the Thread v1.0.0 specification; incompatible changes to the specification might still happen. For this reason, this is disabled by default. Requires: MBEDTLS_ECJPAKE_C MBEDTLS_SHA256_C MBEDTLS_ECP_DP_SECP256R1_ENABLED This enables the following ciphersuites (if other requisites are enabled as well): MBEDTLS_TLS_ECJPAKE_WITH_AES_128_CCM_8
Get the unsigned 16 bits integer corresponding to two bytes in big-endian order (MSB first).
Driver context structure Driver functions receive a pointer to this structure. Each registered driver has one instance of this structure. Implementations must include the fields specified here and may include other fields.
\def MBEDTLS_AES_C Enable the AES block cipher. Module: library/aes.c Caller: library/cipher.c library/pem.c library/ctr_drbg.c This module enables the following ciphersuites (if other requisites are enabled as well): MBEDTLS_TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA MBEDTLS_TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA MBEDTLS_TLS_ECDH_RSA_WITH_AES_128_CBC_SHA MBEDTLS_TLS_ECDH_RSA_WITH_AES_256_CBC_SHA MBEDTLS_TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA256 MBEDTLS_TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA384 MBEDTLS_TLS_ECDH_RSA_WITH_AES_128_CBC_SHA256 MBEDTLS_TLS_ECDH_RSA_WITH_AES_256_CBC_SHA384 MBEDTLS_TLS_ECDH_ECDSA_WITH_AES_128_GCM_SHA256 MBEDTLS_TLS_ECDH_ECDSA_WITH_AES_256_GCM_SHA384 MBEDTLS_TLS_ECDH_RSA_WITH_AES_128_GCM_SHA256 MBEDTLS_TLS_ECDH_RSA_WITH_AES_256_GCM_SHA384 MBEDTLS_TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384 MBEDTLS_TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 MBEDTLS_TLS_DHE_RSA_WITH_AES_256_GCM_SHA384 MBEDTLS_TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384 MBEDTLS_TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384 MBEDTLS_TLS_DHE_RSA_WITH_AES_256_CBC_SHA256 MBEDTLS_TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA MBEDTLS_TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA MBEDTLS_TLS_DHE_RSA_WITH_AES_256_CBC_SHA MBEDTLS_TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 MBEDTLS_TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 MBEDTLS_TLS_DHE_RSA_WITH_AES_128_GCM_SHA256 MBEDTLS_TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256 MBEDTLS_TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 MBEDTLS_TLS_DHE_RSA_WITH_AES_128_CBC_SHA256 MBEDTLS_TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA MBEDTLS_TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA MBEDTLS_TLS_DHE_RSA_WITH_AES_128_CBC_SHA MBEDTLS_TLS_DHE_PSK_WITH_AES_256_GCM_SHA384 MBEDTLS_TLS_ECDHE_PSK_WITH_AES_256_CBC_SHA384 MBEDTLS_TLS_DHE_PSK_WITH_AES_256_CBC_SHA384 MBEDTLS_TLS_ECDHE_PSK_WITH_AES_256_CBC_SHA MBEDTLS_TLS_DHE_PSK_WITH_AES_256_CBC_SHA MBEDTLS_TLS_DHE_PSK_WITH_AES_128_GCM_SHA256 MBEDTLS_TLS_ECDHE_PSK_WITH_AES_128_CBC_SHA256 MBEDTLS_TLS_DHE_PSK_WITH_AES_128_CBC_SHA256 MBEDTLS_TLS_ECDHE_PSK_WITH_AES_128_CBC_SHA MBEDTLS_TLS_DHE_PSK_WITH_AES_128_CBC_SHA MBEDTLS_TLS_RSA_WITH_AES_256_GCM_SHA384 MBEDTLS_TLS_RSA_WITH_AES_256_CBC_SHA256 MBEDTLS_TLS_RSA_WITH_AES_256_CBC_SHA MBEDTLS_TLS_RSA_WITH_AES_128_GCM_SHA256 MBEDTLS_TLS_RSA_WITH_AES_128_CBC_SHA256 MBEDTLS_TLS_RSA_WITH_AES_128_CBC_SHA MBEDTLS_TLS_RSA_PSK_WITH_AES_256_GCM_SHA384 MBEDTLS_TLS_RSA_PSK_WITH_AES_256_CBC_SHA384 MBEDTLS_TLS_RSA_PSK_WITH_AES_256_CBC_SHA MBEDTLS_TLS_RSA_PSK_WITH_AES_128_GCM_SHA256 MBEDTLS_TLS_RSA_PSK_WITH_AES_128_CBC_SHA256 MBEDTLS_TLS_RSA_PSK_WITH_AES_128_CBC_SHA MBEDTLS_TLS_PSK_WITH_AES_256_GCM_SHA384 MBEDTLS_TLS_PSK_WITH_AES_256_CBC_SHA384 MBEDTLS_TLS_PSK_WITH_AES_256_CBC_SHA MBEDTLS_TLS_PSK_WITH_AES_128_GCM_SHA256 MBEDTLS_TLS_PSK_WITH_AES_128_CBC_SHA256 MBEDTLS_TLS_PSK_WITH_AES_128_CBC_SHA PEM_PARSE uses AES for decrypting encrypted keys.
\def MBEDTLS_PSA_CRYPTO_C Enable the Platform Security Architecture cryptography API. Module: library/psa_crypto.c Requires: either MBEDTLS_CTR_DRBG_C and MBEDTLS_ENTROPY_C, or MBEDTLS_HMAC_DRBG_C and MBEDTLS_ENTROPY_C, or MBEDTLS_PSA_CRYPTO_EXTERNAL_RNG. Auto-enables: MBEDTLS_CIPHER_C if any unauthenticated (ie, non-AEAD) cipher is enabled in PSA (unless it's fully accelerated, see docs/driver-only-builds.md about that).
Encoding of the step of a key derivation. Values of this type are generally constructed by macros called `PSA_KEY_DERIVATION_INPUT_xxx`.
\def MBEDTLS_ECDSA_C Enable the elliptic curve DSA library. Module: library/ecdsa.c Caller: This module is used by the following key exchanges: ECDHE-ECDSA Requires: MBEDTLS_ECP_C, MBEDTLS_ASN1_WRITE_C, MBEDTLS_ASN1_PARSE_C, and at least one MBEDTLS_ECP_DP_XXX_ENABLED for a short Weierstrass curve.
\def MBEDTLS_TIMING_ALT Uncomment to provide your own alternate implementation for mbedtls_timing_get_timer(), mbedtls_set_alarm(), mbedtls_set/get_delay() Only works if you have MBEDTLS_TIMING_C enabled. You will need to provide a header "timing_alt.h" and an implementation at compile time. \def MBEDTLS_AES_ALT MBEDTLS__MODULE_NAME__ALT: Uncomment a macro to let Mbed TLS use your alternate core implementation of a symmetric crypto, an arithmetic or hash module (e.g. platform specific assembly optimized implementations). Keep in mind that the function prototypes should remain the same. This replaces the whole module. If you only want to replace one of the functions, use one of the MBEDTLS__FUNCTION_NAME__ALT flags. Example: In case you uncomment MBEDTLS_AES_ALT, Mbed TLS will no longer provide the "struct mbedtls_aes_context" definition and omit the base function declarations and implementations. "aes_alt.h" will be included from "aes.h" to include the new function definitions. Uncomment a macro to enable alternate implementation of the corresponding module. \warning MD5, DES and SHA-1 are considered weak and their use constitutes a security risk. If possible, we recommend avoiding dependencies on them, and considering stronger message digests and ciphers instead. \def MBEDTLS_SHA256_PROCESS_ALT MBEDTLS__FUNCTION_NAME__ALT: Uncomment a macro to let Mbed TLS use you alternate core implementation of symmetric crypto or hash function. Keep in mind that function prototypes should remain the same. This replaces only one function. The header file from Mbed TLS is still used, in contrast to the MBEDTLS__MODULE_NAME__ALT flags. Example: In case you uncomment MBEDTLS_SHA256_PROCESS_ALT, Mbed TLS will no longer provide the mbedtls_sha1_process() function, but it will still provide the other function (using your mbedtls_sha1_process() function) and the definition of mbedtls_sha1_context, so your implementation of mbedtls_sha1_process must be compatible with this definition. Uncomment a macro to enable alternate implementation of the corresponding function. \warning MD5, DES and SHA-1 are considered weak and their use constitutes a security risk. If possible, we recommend avoiding dependencies on them, and considering stronger message digests and ciphers instead. \warning If both MBEDTLS_ECDSA_SIGN_ALT and MBEDTLS_ECDSA_DETERMINISTIC are enabled, then the deterministic ECDH signature functions pass the the static HMAC-DRBG as RNG to mbedtls_ecdsa_sign(). Therefore alternative implementations should use the RNG only for generating the ephemeral key and nothing else. If this is not possible, then MBEDTLS_ECDSA_DETERMINISTIC should be disabled and an alternative implementation should be provided for mbedtls_ecdsa_sign_det_ext(). \def MBEDTLS_ECP_INTERNAL_ALT Expose a part of the internal interface of the Elliptic Curve Point module. MBEDTLS_ECP__FUNCTION_NAME__ALT: Uncomment a macro to let Mbed TLS use your alternative core implementation of elliptic curve arithmetic. Keep in mind that function prototypes should remain the same. This partially replaces one function. The header file from Mbed TLS is still used, in contrast to the MBEDTLS_ECP_ALT flag. The original implementation is still present and it is used for group structures not supported by the alternative. The original implementation can in addition be removed by setting the MBEDTLS_ECP_NO_FALLBACK option, in which case any function for which the corresponding MBEDTLS_ECP__FUNCTION_NAME__ALT macro is defined will not be able to fallback to curves not supported by the alternative implementation. Any of these options become available by defining MBEDTLS_ECP_INTERNAL_ALT and implementing the following functions: unsigned char mbedtls_internal_ecp_grp_capable( const mbedtls_ecp_group *grp ) int mbedtls_internal_ecp_init( const mbedtls_ecp_group *grp ) void mbedtls_internal_ecp_free( const mbedtls_ecp_group *grp ) The mbedtls_internal_ecp_grp_capable function should return 1 if the replacement functions implement arithmetic for the given group and 0 otherwise. The functions mbedtls_internal_ecp_init and mbedtls_internal_ecp_free are called before and after each point operation and provide an opportunity to implement optimized set up and tear down instructions. Example: In case you set MBEDTLS_ECP_INTERNAL_ALT and MBEDTLS_ECP_DOUBLE_JAC_ALT, Mbed TLS will still provide the ecp_double_jac() function, but will use your mbedtls_internal_ecp_double_jac() if the group for the operation is supported by your implementation (i.e. your mbedtls_internal_ecp_grp_capable() function returns 1 for this group). If the group is not supported by your implementation, then the original Mbed TLS implementation of ecp_double_jac() is used instead, unless this fallback behaviour is disabled by setting MBEDTLS_ECP_NO_FALLBACK (in which case ecp_double_jac() will return MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE). The function prototypes and the definition of mbedtls_ecp_group and mbedtls_ecp_point will not change based on MBEDTLS_ECP_INTERNAL_ALT, so your implementation of mbedtls_internal_ecp__function_name__ must be compatible with their definitions. Uncomment a macro to enable alternate implementation of the corresponding function. \def MBEDTLS_ENTROPY_HARDWARE_ALT Uncomment this macro to let Mbed TLS use your own implementation of a hardware entropy collector. Your function must be called \c mbedtls_hardware_poll(), have the same prototype as declared in library/entropy_poll.h, and accept NULL as first argument. Uncomment to use your own hardware entropy collector. \def MBEDTLS_AES_ROM_TABLES Use precomputed AES tables stored in ROM. Uncomment this macro to use precomputed AES tables stored in ROM. Comment this macro to generate AES tables in RAM at runtime. Tradeoff: Using precomputed ROM tables reduces RAM usage by ~8kb (or ~2kb if \c MBEDTLS_AES_FEWER_TABLES is used) and reduces the initialization time before the first AES operation can be performed. It comes at the cost of additional ~8kb ROM use (resp. ~2kb if \c MBEDTLS_AES_FEWER_TABLES below is used), and potentially degraded performance if ROM access is slower than RAM access. This option is independent of \c MBEDTLS_AES_FEWER_TABLES. \def MBEDTLS_AES_FEWER_TABLES Use less ROM/RAM for AES tables. Uncommenting this macro omits 75% of the AES tables from ROM / RAM (depending on the value of \c MBEDTLS_AES_ROM_TABLES) by computing their values on the fly during operations (the tables are entry-wise rotations of one another). Tradeoff: Uncommenting this reduces the RAM / ROM footprint by ~6kb but at the cost of more arithmetic operations during runtime. Specifically, one has to compare 4 accesses within different tables to 4 accesses with additional arithmetic operations within the same table. The performance gain/loss depends on the system and memory details. This option is independent of \c MBEDTLS_AES_ROM_TABLES. \def MBEDTLS_AES_ONLY_128_BIT_KEY_LENGTH Use only 128-bit keys in AES operations to save ROM. Uncomment this macro to remove support for AES operations that use 192- or 256-bit keys. Uncommenting this macro reduces the size of AES code by ~300 bytes on v8-M/Thumb2. Module: library/aes.c Requires: MBEDTLS_AES_C \def MBEDTLS_CAMELLIA_SMALL_MEMORY Use less ROM for the Camellia implementation (saves about 768 bytes). Uncomment this macro to use less memory for Camellia. \def MBEDTLS_CHECK_RETURN_WARNING If this macro is defined, emit a compile-time warning if application code calls a function without checking its return value, but the return value should generally be checked in portable applications. This is only supported on platforms where #MBEDTLS_CHECK_RETURN is implemented. Otherwise this option has no effect. Uncomment to get warnings on using fallible functions without checking their return value. \def MBEDTLS_CIPHER_MODE_CBC Enable Cipher Block Chaining mode (CBC) for symmetric ciphers.
An output buffer is too small. Applications can call the \c PSA_xxx_SIZE macro listed in the function description to determine a sufficient buffer size. Implementations should preferably return this error code only in cases when performing the operation with a larger output buffer would succeed. However implementations may return this error if a function has invalid or unsupported parameters in addition
Certificate Signing Request (CSR) structure. Some fields of this structure are publicly readable. Do not modify them except via Mbed TLS library functions: the effect of modifying those fields or the data that those fields point to is unspecified.
\def MBEDTLS_ECP_C Enable the elliptic curve over GF(p) library. Module: library/ecp.c Caller: library/ecdh.c library/ecdsa.c library/ecjpake.c Requires: MBEDTLS_BIGNUM_C and at least one MBEDTLS_ECP_DP_XXX_ENABLED
\def MBEDTLS_GCM_C Enable the Galois/Counter Mode (GCM). Module: library/gcm.c Requires: MBEDTLS_CIPHER_C, MBEDTLS_AES_C or MBEDTLS_CAMELLIA_C or MBEDTLS_ARIA_C This module enables the AES-GCM and CAMELLIA-GCM ciphersuites, if other requisites are enabled as well.
A structure that describes a registered secure element driver. A secure element driver table entry contains a pointer to the driver's method table as well as the driver context structure.
Curve information, for use by other modules. The fields of this structure are part of the public API and can be accessed directly by applications. Future versions of the library may add extra fields or reorder existing fields.
\def MBEDTLS_CIPHER_MODE_CFB Enable Cipher Feedback mode (CFB) for symmetric ciphers.
\def MBEDTLS_CIPHER_MODE_CTR Enable Counter Block Cipher mode (CTR) for symmetric ciphers.
\def MBEDTLS_CIPHER_C Enable the generic cipher layer. Module: library/cipher.c Caller: library/ccm.c library/cmac.c library/gcm.c library/nist_kw.c library/pkcs12.c library/pkcs5.c library/psa_crypto_aead.c library/psa_crypto_mac.c library/ssl_ciphersuites.c library/ssl_msg.c library/ssl_ticket.c (unless MBEDTLS_USE_PSA_CRYPTO is enabled) Auto-enabled by: MBEDTLS_PSA_CRYPTO_C depending on which ciphers are enabled (see the documentation of that option for details). Uncomment to enable generic cipher wrappers.
The context for PSA interruptible hash signing.
The context for PSA interruptible hash verification.
There is not enough runtime memory. If the action is carried out across multiple security realms, this
Maximum TLS version to be negotiated, then negotiated TLS version. It is initialized as the configured maximum TLS version to be negotiated by mbedtls_ssl_setup(). When renegotiating or resuming a session, it is overwritten in the ClientHello writing preparation stage with the previously negotiated TLS version. On client side, it is updated to the TLS version selected by the server for the handshake when the ServerHello is received. On server side, it is updated to the TLS version the server selects for the handshake when the ClientHello is received.
Build flag from an algorithm/curve identifier (pk, md, ecp) Since 0 is always XXX_NONE, ignore it.
\def MBEDTLS_PLATFORM_C Enable the platform abstraction layer that allows you to re-assign functions like calloc(), free(), snprintf(), printf(), fprintf(), exit(). Enabling MBEDTLS_PLATFORM_C enables to use of MBEDTLS_PLATFORM_XXX_ALT or MBEDTLS_PLATFORM_XXX_MACRO directives, allowing the functions mentioned above to be specified at runtime or compile time respectively. Module: library/platform.c Caller: Most other .c files This module enables abstraction of common (libc) functions.
The next entry in the sequence. The details of memory management for named data sequences are not documented and may change in future versions. Set this field to \p NULL when initializing a structure, and do not modify it except via Mbed TLS library functions.
\def MBEDTLS_CCM_C Enable the Counter with CBC-MAC (CCM) mode for 128-bit block cipher. Module: library/ccm.c Requires: MBEDTLS_CIPHER_C, MBEDTLS_AES_C or MBEDTLS_CAMELLIA_C or MBEDTLS_ARIA_C This module enables the AES-CCM ciphersuites, if other requisites are enabled as well.
\def MBEDTLS_SSL_SERVER_NAME_INDICATION Enable support for RFC 6066 server name indication (SNI) in SSL. Requires: MBEDTLS_X509_CRT_PARSE_C Comment this macro to disable support for server name indication in SSL
The next entry in the sequence. The details of memory management for sequences are not documented and may change in future versions. Set this field to \p NULL when initializing a structure, and do not modify it except via Mbed TLS library functions.
Get the unsigned 32 bits integer corresponding to four bytes in big-endian order (MSB first).
The single version number has the following structure: MMNNPP00 Major version | Minor version | Patch version
\def MBEDTLS_SSL_KEEP_PEER_CERTIFICATE This option controls the availability of the API mbedtls_ssl_get_peer_cert() giving access to the peer's certificate after completion of the handshake. Unless you need mbedtls_ssl_peer_cert() in your application, it is recommended to disable this option for reduced RAM usage. Comment this macro to disable storing the peer's certificate after the handshake.
\def MBEDTLS_SSL_OUT_CONTENT_LEN Maximum outgoing fragment length in bytes. Uncomment to set the size of the outward TLS buffer independently of the inward buffer. It is possible to save RAM by setting a smaller outward buffer, while keeping the default inward 16384 byte buffer to conform to the TLS specification. The minimum required outward buffer size is determined by the handshake protocol's usage. Handshaking will fail if the outward buffer is too small. The specific size requirement depends on the configured ciphers and any certificate data which is sent during the handshake. For absolute minimum RAM usage, it's best to enable MBEDTLS_SSL_MAX_FRAGMENT_LENGTH and reduce MBEDTLS_SSL_MAX_CONTENT_LEN. This reduces both incoming and outgoing buffer sizes. However this is only guaranteed if the other end of the connection also supports the TLS max_fragment_len extension. Otherwise the connection may fail.
\def MBEDTLS_BLOCK_CIPHER_NO_DECRYPT Remove decryption operation for AES, ARIA and Camellia block cipher. Module: library/aes.c library/aesce.c library/aesni.c library/aria.c library/camellia.c library/cipher.c \def MBEDTLS_BIGNUM_C Enable the multi-precision integer library. Module: library/bignum.c library/bignum_core.c library/bignum_mod.c library/bignum_mod_raw.c Caller: library/dhm.c library/ecp.c library/ecdsa.c library/rsa.c library/rsa_alt_helpers.c library/ssl_tls.c This module is required for RSA, DHM and ECC (ECDH, ECDSA) support.
\def MBEDTLS_DES_C Enable the DES block cipher. Module: library/des.c Caller: library/pem.c library/cipher.c PEM_PARSE uses DES/3DES for decrypting encrypted keys. \warning DES/3DES are considered weak ciphers and their use constitutes a security risk. We recommend considering stronger ciphers instead.
\def MBEDTLS_PEM_PARSE_C Enable PEM decoding / parsing. Module: library/pem.c Caller: library/dhm.c library/pkparse.c library/x509_crl.c library/x509_crt.c library/x509_csr.c Requires: MBEDTLS_BASE64_C optionally MBEDTLS_MD5_C, or PSA Crypto with MD5 (see below) \warning When parsing password-protected files, if MD5 is provided only by a PSA driver, you must call psa_crypto_init() before the first file. This modules adds support for decoding / parsing PEM files.
The local storage area for persistent keys. This storage area is available on all systems that can store persistent keys without delegating the storage to a third-party cryptoprocessor. See ::psa_key_location_t for more information.
Get the unsigned 32 bits integer corresponding to four bytes in little-endian order (LSB first).
This macro checks if the remaining size in a buffer is greater or equal than a needed space. If it is not the case, it returns an SSL_BUFFER_TOO_SMALL error.
\def MBEDTLS_CIPHER_MODE_XTS Enable Xor-encrypt-xor with ciphertext stealing mode (XTS) for AES.
\def MBEDTLS_CHACHAPOLY_C Enable the ChaCha20-Poly1305 AEAD algorithm. Module: library/chachapoly.c This module requires: MBEDTLS_CHACHA20_C, MBEDTLS_POLY1305_C
The underlying file descriptor. This field is only guaranteed to be present on POSIX/Unix-like platforms. On other platforms, it may have a different type, have a different meaning, or be absent altogether.
\def MBEDTLS_SSL_MAX_FRAGMENT_LENGTH Enable support for RFC 6066 max_fragment_length extension in SSL. Comment this macro to disable support for the max_fragment_length extension
\def MBEDTLS_MD_C Enable the generic layer for message digest (hashing) and HMAC. Requires: one of: MBEDTLS_MD5_C, MBEDTLS_RIPEMD160_C, MBEDTLS_SHA1_C, MBEDTLS_SHA224_C, MBEDTLS_SHA256_C, MBEDTLS_SHA384_C, MBEDTLS_SHA512_C, or MBEDTLS_PSA_CRYPTO_C with at least one hash. Module: library/md.c Caller: library/constant_time.c library/ecdsa.c library/ecjpake.c library/hkdf.c library/hmac_drbg.c library/pk.c library/pkcs5.c library/pkcs12.c library/psa_crypto_ecp.c library/psa_crypto_rsa.c library/rsa.c library/ssl_cookie.c library/ssl_msg.c library/ssl_tls.c library/x509.c library/x509_crt.c library/x509write_crt.c library/x509write_csr.c Uncomment to enable generic message digest wrappers.
Encoding of key lifetimes. The lifetime of a key indicates where it is stored and what system actions may create and destroy it. Lifetime values have the following structure: - Bits 0-7 (#PSA_KEY_LIFETIME_GET_PERSISTENCE(\c lifetime)): persistence level. This value indicates what device management actions can cause it to be destroyed. In particular, it indicates whether the key is _volatile_ or _persistent_. See ::psa_key_persistence_t for more information. - Bits 8-31 (#PSA_KEY_LIFETIME_GET_LOCATION(\c lifetime)): location indicator. This value indicates which part of the system has access to the key material and can perform operations using the key. See ::psa_key_location_t for more information. Volatile keys are automatically destroyed when the application instance terminates or on a power reset of the device. Persistent keys are preserved until the application explicitly destroys them or until an integration-specific device management event occurs (for example, a factory reset). Persistent keys have a key identifier of type #mbedtls_svc_key_id_t. This identifier remains valid throughout the lifetime of the key, even if the application instance that created the key terminates. The application can call psa_open_key() to open a persistent key that it created previously. The default lifetime of a key is #PSA_KEY_LIFETIME_VOLATILE. The lifetime #PSA_KEY_LIFETIME_PERSISTENT is supported if persistent storage is available. Other lifetime values may be supported depending on the library configuration. Values of this type are generally constructed by macros called `PSA_KEY_LIFETIME_xxx`.
\def MBEDTLS_SHA256_C Enable the SHA-256 cryptographic hash algorithm. Module: library/sha256.c Caller: library/entropy.c library/md.c library/ssl_tls.c library/ssl*_client.c library/ssl*_server.c This module adds support for SHA-256. This module is required for the SSL/TLS 1.2 PRF function.
Custom parameters for key generation or key derivation. This is a structure type with at least the following field: - \c flags: an unsigned integer type. 0 for the default production parameters. Functions that take such a structure as input also take an associated input buffer \c custom_data of length \c custom_data_length. The interpretation of this structure and the associated \c custom_data parameter depend on the type of the created key. - #PSA_KEY_TYPE_RSA_KEY_PAIR: - \c flags: must be 0. - \c custom_data: the public exponent, in little-endian order. This must be an odd integer and must not be 1. Implementations must support 65537, should support 3 and may support other values. When not using a driver, Mbed TLS supports values up to \c INT_MAX. If this is empty, the default value 65537 is used. - Other key types: reserved for future use. \c flags must be 0.
\def MBEDTLS_SHA512_C Enable SHA-512 cryptographic hash algorithms. Module: library/sha512.c Caller: library/entropy.c library/md.c library/ssl_tls.c library/ssl_cookie.c This module adds support for SHA-512.
\def MBEDTLS_KEY_EXCHANGE_ECDHE_ECDSA_ENABLED Enable the ECDHE-ECDSA based ciphersuite modes in SSL / TLS. Requires: MBEDTLS_ECDH_C or (MBEDTLS_USE_PSA_CRYPTO and PSA_WANT_ALG_ECDH) MBEDTLS_ECDSA_C or (MBEDTLS_USE_PSA_CRYPTO and PSA_WANT_ALG_ECDSA) MBEDTLS_X509_CRT_PARSE_C This enables the following ciphersuites (if other requisites are enabled as well): MBEDTLS_TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384 MBEDTLS_TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384 MBEDTLS_TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA MBEDTLS_TLS_ECDHE_ECDSA_WITH_CAMELLIA_256_GCM_SHA384 MBEDTLS_TLS_ECDHE_ECDSA_WITH_CAMELLIA_256_CBC_SHA384 MBEDTLS_TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 MBEDTLS_TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256 MBEDTLS_TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA MBEDTLS_TLS_ECDHE_ECDSA_WITH_CAMELLIA_128_GCM_SHA256 MBEDTLS_TLS_ECDHE_ECDSA_WITH_CAMELLIA_128_CBC_SHA256
\def MBEDTLS_PKCS1_V15 Enable support for PKCS#1 v1.5 encoding. Requires: MBEDTLS_RSA_C This enables support for PKCS#1 v1.5 operations.
\def MBEDTLS_ASN1_PARSE_C Enable the generic ASN1 parser. Module: library/asn1.c Caller: library/x509.c library/dhm.c library/pkcs12.c library/pkcs5.c library/pkparse.c
\def MBEDTLS_CAMELLIA_C Enable the Camellia block cipher. Module: library/camellia.c Caller: library/cipher.c This module enables the following ciphersuites (if other requisites are enabled as well): MBEDTLS_TLS_ECDH_ECDSA_WITH_CAMELLIA_128_CBC_SHA256 MBEDTLS_TLS_ECDH_ECDSA_WITH_CAMELLIA_256_CBC_SHA384 MBEDTLS_TLS_ECDH_RSA_WITH_CAMELLIA_128_CBC_SHA256 MBEDTLS_TLS_ECDH_RSA_WITH_CAMELLIA_256_CBC_SHA384 MBEDTLS_TLS_ECDH_ECDSA_WITH_CAMELLIA_128_GCM_SHA256 MBEDTLS_TLS_ECDH_ECDSA_WITH_CAMELLIA_256_GCM_SHA384 MBEDTLS_TLS_ECDH_RSA_WITH_CAMELLIA_128_GCM_SHA256 MBEDTLS_TLS_ECDH_RSA_WITH_CAMELLIA_256_GCM_SHA384 MBEDTLS_TLS_ECDHE_ECDSA_WITH_CAMELLIA_256_GCM_SHA384 MBEDTLS_TLS_ECDHE_RSA_WITH_CAMELLIA_256_GCM_SHA384 MBEDTLS_TLS_DHE_RSA_WITH_CAMELLIA_256_GCM_SHA384 MBEDTLS_TLS_ECDHE_ECDSA_WITH_CAMELLIA_256_CBC_SHA384 MBEDTLS_TLS_ECDHE_RSA_WITH_CAMELLIA_256_CBC_SHA384 MBEDTLS_TLS_DHE_RSA_WITH_CAMELLIA_256_CBC_SHA256 MBEDTLS_TLS_DHE_RSA_WITH_CAMELLIA_256_CBC_SHA MBEDTLS_TLS_ECDHE_ECDSA_WITH_CAMELLIA_128_GCM_SHA256 MBEDTLS_TLS_ECDHE_RSA_WITH_CAMELLIA_128_GCM_SHA256 MBEDTLS_TLS_DHE_RSA_WITH_CAMELLIA_128_GCM_SHA256 MBEDTLS_TLS_ECDHE_ECDSA_WITH_CAMELLIA_128_CBC_SHA256 MBEDTLS_TLS_ECDHE_RSA_WITH_CAMELLIA_128_CBC_SHA256 MBEDTLS_TLS_DHE_RSA_WITH_CAMELLIA_128_CBC_SHA256 MBEDTLS_TLS_DHE_RSA_WITH_CAMELLIA_128_CBC_SHA MBEDTLS_TLS_DHE_PSK_WITH_CAMELLIA_256_GCM_SHA384 MBEDTLS_TLS_ECDHE_PSK_WITH_CAMELLIA_256_CBC_SHA384 MBEDTLS_TLS_DHE_PSK_WITH_CAMELLIA_256_CBC_SHA384 MBEDTLS_TLS_DHE_PSK_WITH_CAMELLIA_128_GCM_SHA256 MBEDTLS_TLS_DHE_PSK_WITH_CAMELLIA_128_CBC_SHA256 MBEDTLS_TLS_ECDHE_PSK_WITH_CAMELLIA_128_CBC_SHA256 MBEDTLS_TLS_RSA_WITH_CAMELLIA_256_GCM_SHA384 MBEDTLS_TLS_RSA_WITH_CAMELLIA_256_CBC_SHA256 MBEDTLS_TLS_RSA_WITH_CAMELLIA_256_CBC_SHA MBEDTLS_TLS_RSA_WITH_CAMELLIA_128_GCM_SHA256 MBEDTLS_TLS_RSA_WITH_CAMELLIA_128_CBC_SHA256 MBEDTLS_TLS_RSA_WITH_CAMELLIA_128_CBC_SHA MBEDTLS_TLS_RSA_PSK_WITH_CAMELLIA_256_GCM_SHA384 MBEDTLS_TLS_RSA_PSK_WITH_CAMELLIA_256_CBC_SHA384 MBEDTLS_TLS_RSA_PSK_WITH_CAMELLIA_128_GCM_SHA256 MBEDTLS_TLS_RSA_PSK_WITH_CAMELLIA_128_CBC_SHA256 MBEDTLS_TLS_PSK_WITH_CAMELLIA_256_GCM_SHA384 MBEDTLS_TLS_PSK_WITH_CAMELLIA_256_CBC_SHA384 MBEDTLS_TLS_PSK_WITH_CAMELLIA_128_GCM_SHA256 MBEDTLS_TLS_PSK_WITH_CAMELLIA_128_CBC_SHA256
\def MBEDTLS_DHM_C Enable the Diffie-Hellman-Merkle module. Module: library/dhm.c Caller: library/ssl_tls.c library/ssl*_client.c library/ssl*_server.c This module is used by the following key exchanges: DHE-RSA, DHE-PSK \warning Using DHE constitutes a security risk as it is not possible to validate custom DH parameters. If possible, it is recommended users should consider preferring other methods of key exchange. See dhm.h for more details.
A structure for holding the parsed Subject Alternative Name, according to type. Future versions of the library may add new fields to this structure or to its embedded union and structure.
\def MBEDTLS_SSL_DEBUG_ALL Enable the debug messages in SSL module for all issues. Debug messages have been disabled in some places to prevent timing attacks due to (unbalanced) debugging function calls. If you need all error reporting you should enable this during debugging, but remove this for production servers that should log as well. Uncomment this macro to report all debug messages on errors introducing a timing side-channel. \def MBEDTLS_SSL_ENCRYPT_THEN_MAC Enable support for Encrypt-then-MAC, RFC 7366. This allows peers that both support it to use a more robust protection for ciphersuites using CBC, providing deep resistance against timing attacks on the padding or underlying cipher. This only affects CBC ciphersuites, and is useless if none is defined. Requires: MBEDTLS_SSL_PROTO_TLS1_2 Comment this macro to disable support for Encrypt-then-MAC
\def MBEDTLS_DEBUG_C Enable the debug functions. Module: library/debug.c Caller: library/ssl_msg.c library/ssl_tls.c library/ssl_tls12_*.c library/ssl_tls13_*.c This module provides debugging functions.
\def MBEDTLS_SHA224_C Enable the SHA-224 cryptographic hash algorithm. Module: library/sha256.c Caller: library/md.c library/ssl_cookie.c This module adds support for SHA-224.
\def MBEDTLS_SHA256_USE_ARMV8_A_CRYPTO_IF_PRESENT Enable acceleration of the SHA-256 and SHA-224 cryptographic hash algorithms with the ARMv8 cryptographic extensions if they are available at runtime. If not, the library will fall back to the C implementation. \warning MBEDTLS_SHA256_USE_ARMV8_A_CRYPTO_IF_PRESENT cannot be defined at the same time as MBEDTLS_SHA256_USE_ARMV8_A_CRYPTO_ONLY. Requires: MBEDTLS_SHA256_C. Module: library/sha256.c Uncomment to have the library check for the Armv8-A SHA-256 crypto extensions and use them if available. \def MBEDTLS_SHA256_USE_A64_CRYPTO_IF_PRESENT \deprecated This is now known as MBEDTLS_SHA256_USE_ARMV8_A_CRYPTO_IF_PRESENT. This name is now deprecated, but may still be used as an alternative form for this option. \def MBEDTLS_SHA256_USE_ARMV8_A_CRYPTO_ONLY Enable acceleration of the SHA-256 and SHA-224 cryptographic hash algorithms with the ARMv8 cryptographic extensions, which must be available at runtime or else an illegal instruction fault will occur. \warning MBEDTLS_SHA256_USE_ARMV8_A_CRYPTO_ONLY cannot be defined at the same time as MBEDTLS_SHA256_USE_ARMV8_A_CRYPTO_IF_PRESENT. Requires: MBEDTLS_SHA256_C. Module: library/sha256.c Uncomment to have the library use the Armv8-A SHA-256 crypto extensions unconditionally. \def MBEDTLS_SHA256_USE_A64_CRYPTO_ONLY \deprecated This is now known as MBEDTLS_SHA256_USE_ARMV8_A_CRYPTO_ONLY. This name is now deprecated, but may still be used as an alternative form for this option. \def MBEDTLS_SHA384_C Enable the SHA-384 cryptographic hash algorithm. Module: library/sha512.c Caller: library/md.c library/psa_crypto_hash.c library/ssl_tls.c library/ssl*_client.c library/ssl*_server.c Comment to disable SHA-384
The context used by the default ECDH implementation. Later versions might change the structure of this context, therefore users should not make any assumptions about the structure of mbedtls_ecdh_context_mbed.
\def MBEDTLS_CIPHER_MODE_OFB Enable Output Feedback mode (OFB) for symmetric ciphers.
\def MBEDTLS_ARIA_C Enable the ARIA block cipher. Module: library/aria.c Caller: library/cipher.c This module enables the following ciphersuites (if other requisites are enabled as well): MBEDTLS_TLS_RSA_WITH_ARIA_128_CBC_SHA256 MBEDTLS_TLS_RSA_WITH_ARIA_256_CBC_SHA384 MBEDTLS_TLS_DHE_RSA_WITH_ARIA_128_CBC_SHA256 MBEDTLS_TLS_DHE_RSA_WITH_ARIA_256_CBC_SHA384 MBEDTLS_TLS_ECDHE_ECDSA_WITH_ARIA_128_CBC_SHA256 MBEDTLS_TLS_ECDHE_ECDSA_WITH_ARIA_256_CBC_SHA384 MBEDTLS_TLS_ECDH_ECDSA_WITH_ARIA_128_CBC_SHA256 MBEDTLS_TLS_ECDH_ECDSA_WITH_ARIA_256_CBC_SHA384 MBEDTLS_TLS_ECDHE_RSA_WITH_ARIA_128_CBC_SHA256 MBEDTLS_TLS_ECDHE_RSA_WITH_ARIA_256_CBC_SHA384 MBEDTLS_TLS_ECDH_RSA_WITH_ARIA_128_CBC_SHA256 MBEDTLS_TLS_ECDH_RSA_WITH_ARIA_256_CBC_SHA384 MBEDTLS_TLS_RSA_WITH_ARIA_128_GCM_SHA256 MBEDTLS_TLS_RSA_WITH_ARIA_256_GCM_SHA384 MBEDTLS_TLS_DHE_RSA_WITH_ARIA_128_GCM_SHA256 MBEDTLS_TLS_DHE_RSA_WITH_ARIA_256_GCM_SHA384 MBEDTLS_TLS_ECDHE_ECDSA_WITH_ARIA_128_GCM_SHA256 MBEDTLS_TLS_ECDHE_ECDSA_WITH_ARIA_256_GCM_SHA384 MBEDTLS_TLS_ECDH_ECDSA_WITH_ARIA_128_GCM_SHA256 MBEDTLS_TLS_ECDH_ECDSA_WITH_ARIA_256_GCM_SHA384 MBEDTLS_TLS_ECDHE_RSA_WITH_ARIA_128_GCM_SHA256 MBEDTLS_TLS_ECDHE_RSA_WITH_ARIA_256_GCM_SHA384 MBEDTLS_TLS_ECDH_RSA_WITH_ARIA_128_GCM_SHA256 MBEDTLS_TLS_ECDH_RSA_WITH_ARIA_256_GCM_SHA384 MBEDTLS_TLS_PSK_WITH_ARIA_128_CBC_SHA256 MBEDTLS_TLS_PSK_WITH_ARIA_256_CBC_SHA384 MBEDTLS_TLS_DHE_PSK_WITH_ARIA_128_CBC_SHA256 MBEDTLS_TLS_DHE_PSK_WITH_ARIA_256_CBC_SHA384 MBEDTLS_TLS_RSA_PSK_WITH_ARIA_128_CBC_SHA256 MBEDTLS_TLS_RSA_PSK_WITH_ARIA_256_CBC_SHA384 MBEDTLS_TLS_PSK_WITH_ARIA_128_GCM_SHA256 MBEDTLS_TLS_PSK_WITH_ARIA_256_GCM_SHA384 MBEDTLS_TLS_DHE_PSK_WITH_ARIA_128_GCM_SHA256 MBEDTLS_TLS_DHE_PSK_WITH_ARIA_256_GCM_SHA384 MBEDTLS_TLS_RSA_PSK_WITH_ARIA_128_GCM_SHA256 MBEDTLS_TLS_RSA_PSK_WITH_ARIA_256_GCM_SHA384 MBEDTLS_TLS_ECDHE_PSK_WITH_ARIA_128_CBC_SHA256 MBEDTLS_TLS_ECDHE_PSK_WITH_ARIA_256_CBC_SHA384
For Short Weierstrass: The number of bits in \p P. For Montgomery curves: the number of bits in the private keys.
Base cipher information. The non-mode specific functions and values.
LMS public context structure. A LMS public key is the hash output that is the root of the Merkle tree, and the applicable parameter set The context must be initialized before it is used. A public key must either be imported or generated from a private context. \dot digraph lms_public_t { UNINITIALIZED -> INIT [label="init"]; HAVE_PUBLIC_KEY -> INIT [label="free"]; INIT -> HAVE_PUBLIC_KEY [label="import_public_key"]; INIT -> HAVE_PUBLIC_KEY [label="calculate_public_key from private key"]; HAVE_PUBLIC_KEY -> HAVE_PUBLIC_KEY [label="export_public_key"]; } \enddot
LMOTS public context structure. A LMOTS public key is a hash output, and the applicable parameter set. The context must be initialized before it is used. A public key must either be imported or generated from a private context. \dot digraph lmots_public_t { UNINITIALIZED -> INIT [label="init"]; HAVE_PUBLIC_KEY -> INIT [label="free"]; INIT -> HAVE_PUBLIC_KEY [label="import_public_key"]; INIT -> HAVE_PUBLIC_KEY [label="calculate_public_key from private key"]; HAVE_PUBLIC_KEY -> HAVE_PUBLIC_KEY [label="export_public_key"]; } \enddot
\name PEM Error codes These error codes are returned in case of errors reading the PEM data.
An internal designation of a key slot between the core part of the PSA Crypto implementation and the driver. The meaning of this value is driver-dependent.
\def MBEDTLS_SSL_TLS_C Enable the generic SSL/TLS code. Module: library/ssl_tls.c Caller: library/ssl*_client.c library/ssl*_server.c Requires: MBEDTLS_CIPHER_C, MBEDTLS_MD_C and at least one of the MBEDTLS_SSL_PROTO_XXX defines This module is required for SSL/TLS.
\def MBEDTLS_PKCS1_V21 Enable support for PKCS#1 v2.1 encoding. Requires: MBEDTLS_RSA_C \warning If using a hash that is only provided by PSA drivers, you must call psa_crypto_init() before doing any PKCS#1 v2.1 operation. This enables support for RSAES-OAEP and RSASSA-PSS operations.
\def MBEDTLS_SSL_ALPN Enable support for RFC 7301 Application Layer Protocol Negotiation. Comment this macro to disable support for ALPN.
The buffer for the unstructured types. rfc822Name, dnsName and uniformResourceIdentifier are currently supported.
Domain parameters for the 256-bit curve defined by FIPS 186-4 and SEC1.
\def MBEDTLS_PSA_CRYPTO_BUILTIN_KEYS Enable support for platform built-in keys. If you enable this feature, you must implement the function mbedtls_psa_platform_get_builtin_key(). See the documentation of that function for more information. Built-in keys are typically derived from a hardware unique key or stored in a secure element. Requires: MBEDTLS_PSA_CRYPTO_C. \warning This interface is experimental and may change or be removed without notice. \def MBEDTLS_PSA_CRYPTO_CLIENT Enable support for PSA crypto client. \warning This interface is experimental and may change or be removed without notice. \def MBEDTLS_PSA_CRYPTO_EXTERNAL_RNG Make the PSA Crypto module use an external random generator provided by a driver, instead of Mbed TLS's entropy and DRBG modules. If you enable this option, you must configure the type ::mbedtls_psa_external_random_context_t in psa/crypto_platform.h and define a function called mbedtls_psa_external_get_random() with the following prototype: ``` psa_status_t mbedtls_psa_external_get_random( mbedtls_psa_external_random_context_t *context, uint8_t *output, size_t output_size, size_t *output_length); ); ``` The \c context value is initialized to 0 before the first call. The function must fill the \c output buffer with \c output_size bytes of random data and set \c *output_length to \c output_size. Requires: MBEDTLS_PSA_CRYPTO_C \warning If you enable this option, code that uses the PSA cryptography interface will not use any of the entropy sources set up for the entropy module, nor the NV seed that MBEDTLS_ENTROPY_NV_SEED enables. \def MBEDTLS_PSA_CRYPTO_SPM When MBEDTLS_PSA_CRYPTO_SPM is defined, the code is built for SPM (Secure Partition Manager) integration which separates the code into two parts: a NSPE (Non-Secure Process Environment) and an SPE (Secure Process Environment). If you enable this option, your build environment must include a header file `"crypto_spe.h"` (either in the `psa` subdirectory of the Mbed TLS header files, or in another directory on the compiler's include search path). Alternatively, your platform may customize the header `psa/crypto_platform.h`, in which case it can skip or replace the inclusion of `"crypto_spe.h"`. Module: library/psa_crypto.c Requires: MBEDTLS_PSA_CRYPTO_C \def MBEDTLS_PSA_KEY_STORE_DYNAMIC Dynamically resize the PSA key store to accommodate any number of volatile keys (until the heap memory is exhausted). If this option is disabled, the key store has a fixed size #MBEDTLS_PSA_KEY_SLOT_COUNT for volatile keys and loaded persistent keys together. This option has no effect when #MBEDTLS_PSA_CRYPTO_C is disabled. Module: library/psa_crypto.c Requires: MBEDTLS_PSA_CRYPTO_C
\def MBEDTLS_SSL_DTLS_SRTP Enable support for negotiation of DTLS-SRTP (RFC 5764) through the use_srtp extension. Setting this option enables the runtime API mbedtls_ssl_conf_dtls_srtp_protection_profiles() through which the supported DTLS-SRTP protection profiles can be configured. You must call this API at runtime if you wish to negotiate the use of DTLS-SRTP. Requires: MBEDTLS_SSL_PROTO_DTLS Uncomment this to enable support for use_srtp extension.
Macro to build a shortened AEAD algorithm. A shortened AEAD algorithm is similar to the corresponding AEAD algorithm, but has an authentication tag that consists of fewer bytes. Depending on the algorithm, the tag length may affect the calculation of the ciphertext.
\name ASN1 Error codes These error codes are combined with other error codes for higher error granularity. e.g. X.509 and PKCS #7 error codes ASN1 is a standard to specify data structures.
Put in memory a 32 bits unsigned integer in little-endian order.
\def MBEDTLS_KEY_EXCHANGE_ECDHE_PSK_ENABLED Enable the ECDHE-PSK based ciphersuite modes in SSL / TLS. Requires: MBEDTLS_ECDH_C or (MBEDTLS_USE_PSA_CRYPTO and PSA_WANT_ALG_ECDH) This enables the following ciphersuites (if other requisites are enabled as well): MBEDTLS_TLS_ECDHE_PSK_WITH_AES_256_CBC_SHA384 MBEDTLS_TLS_ECDHE_PSK_WITH_AES_256_CBC_SHA MBEDTLS_TLS_ECDHE_PSK_WITH_CAMELLIA_256_CBC_SHA384 MBEDTLS_TLS_ECDHE_PSK_WITH_AES_128_CBC_SHA256 MBEDTLS_TLS_ECDHE_PSK_WITH_AES_128_CBC_SHA MBEDTLS_TLS_ECDHE_PSK_WITH_CAMELLIA_128_CBC_SHA256
\def MBEDTLS_SSL_EXTENDED_MASTER_SECRET Enable support for RFC 7627: Session Hash and Extended Master Secret Extension. This was introduced as "the proper fix" to the Triple Handshake family of attacks, but it is recommended to always use it (even if you disable renegotiation), since it actually fixes a more fundamental issue in the original SSL/TLS design, and has implications beyond Triple Handshake. Requires: MBEDTLS_SSL_PROTO_TLS1_2 Comment this macro to disable support for Extended Master Secret.
\def MBEDTLS_SSL_DTLS_ANTI_REPLAY Enable support for the anti-replay mechanism in DTLS. Requires: MBEDTLS_SSL_TLS_C MBEDTLS_SSL_PROTO_DTLS \warning Disabling this is often a security risk! See mbedtls_ssl_conf_dtls_anti_replay() for details. Comment this to disable anti-replay in DTLS.
\def MBEDTLS_PK_C Enable the generic public (asymmetric) key layer. Module: library/pk.c Caller: library/psa_crypto_rsa.c library/ssl_tls.c library/ssl*_client.c library/ssl*_server.c library/x509.c Requires: MBEDTLS_MD_C, MBEDTLS_RSA_C or MBEDTLS_ECP_C Uncomment to enable generic public key wrappers.
Encoding of input and output indicators for PAKE. Some PAKE algorithms need to exchange more data than just a single key share. This type is for encoding additional input and output data for such algorithms.
Certificate revocation list entry. Contains the CA-specific serial numbers and revocation dates. Some fields of this structure are publicly readable. Do not modify them except via Mbed TLS library functions: the effect of modifying those fields or the data that those fields points to is unspecified.
The signature, MAC or hash is incorrect. Verification functions return this error if the verification calculations completed successfully, and the value to be verified was determined to be incorrect. If the value to verify has an invalid size, implementations may return
The CCM authenticated encryption algorithm. The underlying block cipher is determined by the key type.
LMOTS parameters structure. This contains the metadata associated with an LMOTS key, detailing the algorithm type, the key ID, and the leaf identifier should be key be part of a LMS key.
\def MBEDTLS_KEY_EXCHANGE_RSA_PSK_ENABLED Enable the RSA-PSK based ciphersuite modes in SSL / TLS. Requires: MBEDTLS_RSA_C, MBEDTLS_PKCS1_V15, MBEDTLS_X509_CRT_PARSE_C This enables the following ciphersuites (if other requisites are enabled as well): MBEDTLS_TLS_RSA_PSK_WITH_AES_256_GCM_SHA384 MBEDTLS_TLS_RSA_PSK_WITH_AES_256_CBC_SHA384 MBEDTLS_TLS_RSA_PSK_WITH_AES_256_CBC_SHA MBEDTLS_TLS_RSA_PSK_WITH_CAMELLIA_256_GCM_SHA384 MBEDTLS_TLS_RSA_PSK_WITH_CAMELLIA_256_CBC_SHA384 MBEDTLS_TLS_RSA_PSK_WITH_AES_128_GCM_SHA256 MBEDTLS_TLS_RSA_PSK_WITH_AES_128_CBC_SHA256 MBEDTLS_TLS_RSA_PSK_WITH_AES_128_CBC_SHA MBEDTLS_TLS_RSA_PSK_WITH_CAMELLIA_128_GCM_SHA256 MBEDTLS_TLS_RSA_PSK_WITH_CAMELLIA_128_CBC_SHA256
\def MBEDTLS_KEY_EXCHANGE_DHE_RSA_ENABLED Enable the DHE-RSA based ciphersuite modes in SSL / TLS. Requires: MBEDTLS_DHM_C, MBEDTLS_RSA_C, MBEDTLS_PKCS1_V15, MBEDTLS_X509_CRT_PARSE_C This enables the following ciphersuites (if other requisites are enabled as well): MBEDTLS_TLS_DHE_RSA_WITH_AES_256_GCM_SHA384 MBEDTLS_TLS_DHE_RSA_WITH_AES_256_CBC_SHA256 MBEDTLS_TLS_DHE_RSA_WITH_AES_256_CBC_SHA MBEDTLS_TLS_DHE_RSA_WITH_CAMELLIA_256_GCM_SHA384 MBEDTLS_TLS_DHE_RSA_WITH_CAMELLIA_256_CBC_SHA256 MBEDTLS_TLS_DHE_RSA_WITH_CAMELLIA_256_CBC_SHA MBEDTLS_TLS_DHE_RSA_WITH_AES_128_GCM_SHA256 MBEDTLS_TLS_DHE_RSA_WITH_AES_128_CBC_SHA256 MBEDTLS_TLS_DHE_RSA_WITH_AES_128_CBC_SHA MBEDTLS_TLS_DHE_RSA_WITH_CAMELLIA_128_GCM_SHA256 MBEDTLS_TLS_DHE_RSA_WITH_CAMELLIA_128_CBC_SHA256 MBEDTLS_TLS_DHE_RSA_WITH_CAMELLIA_128_CBC_SHA \warning Using DHE constitutes a security risk as it is not possible to validate custom DH parameters. If possible, it is recommended users should consider preferring other methods of key exchange. See dhm.h for more details.
\def MBEDTLS_X509_TRUSTED_CERTIFICATE_CALLBACK If set, this enables the X.509 API `mbedtls_x509_crt_verify_with_ca_cb()` and the SSL API `mbedtls_ssl_conf_ca_cb()` which allow users to configure the set of trusted certificates through a callback instead of a linked list. This is useful for example in environments where a large number of trusted certificates is present and storing them in a linked list isn't efficient enough, or when the set of trusted certificates changes frequently. See the documentation of `mbedtls_x509_crt_verify_with_ca_cb()` and `mbedtls_ssl_conf_ca_cb()` for more information. Requires: MBEDTLS_X509_CRT_PARSE_C Uncomment to enable trusted certificate callbacks. \def MBEDTLS_X509_REMOVE_INFO Disable mbedtls_x509_*_info() and related APIs. Uncomment to omit mbedtls_x509_*_info(), as well as mbedtls_debug_print_crt() and other functions/constants only used by these functions, thus reducing the code footprint by several KB. \def MBEDTLS_X509_RSASSA_PSS_SUPPORT Enable parsing and verification of X.509 certificates, CRLs and CSRS signed with RSASSA-PSS (aka PKCS#1 v2.1). Requires: MBEDTLS_PKCS1_V21 Comment this macro to disallow using RSASSA-PSS in certificates.
\def MBEDTLS_PEM_WRITE_C Enable PEM encoding / writing. Module: library/pem.c Caller: library/pkwrite.c library/x509write_crt.c library/x509write_csr.c Requires: MBEDTLS_BASE64_C This modules adds support for encoding / writing PEM files.
The random generator state for the PSA subsystem. This macro always expands to NULL because the `p_rng` parameter is unused in mbedtls_psa_get_random(), but it's kept for interface's backward compatibility.
Triple-DES context structure \warning DES/3DES are considered weak ciphers and their use constitutes a security risk. We recommend considering stronger ciphers instead.
\def MBEDTLS_SHA1_C Enable the SHA1 cryptographic hash algorithm. Module: library/sha1.c Caller: library/md.c library/psa_crypto_hash.c This module is required for TLS 1.2 depending on the handshake parameters, and for SHA1-signed certificates. \warning SHA-1 is considered a weak message digest and its use constitutes a security risk. If possible, we recommend avoiding dependencies on it, and considering stronger message digests instead.
\def MBEDTLS_KEY_EXCHANGE_DHE_PSK_ENABLED Enable the DHE-PSK based ciphersuite modes in SSL / TLS. Requires: MBEDTLS_DHM_C This enables the following ciphersuites (if other requisites are enabled as well): MBEDTLS_TLS_DHE_PSK_WITH_AES_256_GCM_SHA384 MBEDTLS_TLS_DHE_PSK_WITH_AES_256_CBC_SHA384 MBEDTLS_TLS_DHE_PSK_WITH_AES_256_CBC_SHA MBEDTLS_TLS_DHE_PSK_WITH_CAMELLIA_256_GCM_SHA384 MBEDTLS_TLS_DHE_PSK_WITH_CAMELLIA_256_CBC_SHA384 MBEDTLS_TLS_DHE_PSK_WITH_AES_128_GCM_SHA256 MBEDTLS_TLS_DHE_PSK_WITH_AES_128_CBC_SHA256 MBEDTLS_TLS_DHE_PSK_WITH_AES_128_CBC_SHA MBEDTLS_TLS_DHE_PSK_WITH_CAMELLIA_128_GCM_SHA256 MBEDTLS_TLS_DHE_PSK_WITH_CAMELLIA_128_CBC_SHA256 \warning Using DHE constitutes a security risk as it is not possible to validate custom DH parameters. If possible, it is recommended users should consider preferring other methods of key exchange. See dhm.h for more details.
\def MBEDTLS_KEY_EXCHANGE_ECDHE_RSA_ENABLED Enable the ECDHE-RSA based ciphersuite modes in SSL / TLS. Requires: MBEDTLS_ECDH_C or (MBEDTLS_USE_PSA_CRYPTO and PSA_WANT_ALG_ECDH) MBEDTLS_RSA_C MBEDTLS_PKCS1_V15 MBEDTLS_X509_CRT_PARSE_C This enables the following ciphersuites (if other requisites are enabled as well): MBEDTLS_TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 MBEDTLS_TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384 MBEDTLS_TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA MBEDTLS_TLS_ECDHE_RSA_WITH_CAMELLIA_256_GCM_SHA384 MBEDTLS_TLS_ECDHE_RSA_WITH_CAMELLIA_256_CBC_SHA384 MBEDTLS_TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 MBEDTLS_TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 MBEDTLS_TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA MBEDTLS_TLS_ECDHE_RSA_WITH_CAMELLIA_128_GCM_SHA256 MBEDTLS_TLS_ECDHE_RSA_WITH_CAMELLIA_128_CBC_SHA256
\def MBEDTLS_SSL_DTLS_HELLO_VERIFY Enable support for HelloVerifyRequest on DTLS servers. This feature is highly recommended to prevent DTLS servers being used as amplifiers in DoS attacks against other hosts. It should always be enabled unless you know for sure amplification cannot be a problem in the environment in which your server operates. \warning Disabling this can be a security risk! (see above) Requires: MBEDTLS_SSL_PROTO_DTLS Comment this to disable support for HelloVerifyRequest.
Unique ID indicating which driver got assigned to do the operation. Since driver contexts are driver-specific, swapping drivers halfway through the operation is not supported. ID values are auto-generated in psa_crypto_driver_wrappers.h ID value zero means the context is not valid or not assigned to any driver (i.e. none of the driver contexts are active).
\def MBEDTLS_LMS_PRIVATE Enable LMS private-key operations and signing code. Functions enabled by this option are experimental, and should not be used in production. Requires: MBEDTLS_LMS_C Uncomment to enable the LMS signature algorithm and private key operations. \def MBEDTLS_NIST_KW_C Enable the Key Wrapping mode for 128-bit block ciphers, as defined in NIST SP 800-38F. Only KW and KWP modes are supported. At the moment, only AES is approved by NIST. Module: library/nist_kw.c Requires: MBEDTLS_AES_C and MBEDTLS_CIPHER_C
\def MBEDTLS_KEY_EXCHANGE_RSA_ENABLED Enable the RSA-only based ciphersuite modes in SSL / TLS. Requires: MBEDTLS_RSA_C, MBEDTLS_PKCS1_V15, MBEDTLS_X509_CRT_PARSE_C This enables the following ciphersuites (if other requisites are enabled as well): MBEDTLS_TLS_RSA_WITH_AES_256_GCM_SHA384 MBEDTLS_TLS_RSA_WITH_AES_256_CBC_SHA256 MBEDTLS_TLS_RSA_WITH_AES_256_CBC_SHA MBEDTLS_TLS_RSA_WITH_CAMELLIA_256_GCM_SHA384 MBEDTLS_TLS_RSA_WITH_CAMELLIA_256_CBC_SHA256 MBEDTLS_TLS_RSA_WITH_CAMELLIA_256_CBC_SHA MBEDTLS_TLS_RSA_WITH_AES_128_GCM_SHA256 MBEDTLS_TLS_RSA_WITH_AES_128_CBC_SHA256 MBEDTLS_TLS_RSA_WITH_AES_128_CBC_SHA MBEDTLS_TLS_RSA_WITH_CAMELLIA_128_GCM_SHA256 MBEDTLS_TLS_RSA_WITH_CAMELLIA_128_CBC_SHA256 MBEDTLS_TLS_RSA_WITH_CAMELLIA_128_CBC_SHA
\def MBEDTLS_KEY_EXCHANGE_ECDH_ECDSA_ENABLED Enable the ECDH-ECDSA based ciphersuite modes in SSL / TLS. Requires: MBEDTLS_ECDH_C or (MBEDTLS_USE_PSA_CRYPTO and PSA_WANT_ALG_ECDH) MBEDTLS_ECDSA_C or (MBEDTLS_USE_PSA_CRYPTO and PSA_WANT_ALG_ECDSA) MBEDTLS_X509_CRT_PARSE_C This enables the following ciphersuites (if other requisites are enabled as well): MBEDTLS_TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA MBEDTLS_TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA MBEDTLS_TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA256 MBEDTLS_TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA384 MBEDTLS_TLS_ECDH_ECDSA_WITH_AES_128_GCM_SHA256 MBEDTLS_TLS_ECDH_ECDSA_WITH_AES_256_GCM_SHA384 MBEDTLS_TLS_ECDH_ECDSA_WITH_CAMELLIA_128_CBC_SHA256 MBEDTLS_TLS_ECDH_ECDSA_WITH_CAMELLIA_256_CBC_SHA384 MBEDTLS_TLS_ECDH_ECDSA_WITH_CAMELLIA_128_GCM_SHA256 MBEDTLS_TLS_ECDH_ECDSA_WITH_CAMELLIA_256_GCM_SHA384
\def MBEDTLS_KEY_EXCHANGE_ECDH_RSA_ENABLED Enable the ECDH-RSA based ciphersuite modes in SSL / TLS. Requires: MBEDTLS_ECDH_C or (MBEDTLS_USE_PSA_CRYPTO and PSA_WANT_ALG_ECDH) MBEDTLS_RSA_C MBEDTLS_X509_CRT_PARSE_C This enables the following ciphersuites (if other requisites are enabled as well): MBEDTLS_TLS_ECDH_RSA_WITH_AES_128_CBC_SHA MBEDTLS_TLS_ECDH_RSA_WITH_AES_256_CBC_SHA MBEDTLS_TLS_ECDH_RSA_WITH_AES_128_CBC_SHA256 MBEDTLS_TLS_ECDH_RSA_WITH_AES_256_CBC_SHA384 MBEDTLS_TLS_ECDH_RSA_WITH_AES_128_GCM_SHA256 MBEDTLS_TLS_ECDH_RSA_WITH_AES_256_GCM_SHA384 MBEDTLS_TLS_ECDH_RSA_WITH_CAMELLIA_128_CBC_SHA256 MBEDTLS_TLS_ECDH_RSA_WITH_CAMELLIA_256_CBC_SHA384 MBEDTLS_TLS_ECDH_RSA_WITH_CAMELLIA_128_GCM_SHA256 MBEDTLS_TLS_ECDH_RSA_WITH_CAMELLIA_256_GCM_SHA384
\def MBEDTLS_CHACHA20_C Enable the ChaCha20 stream cipher. Module: library/chacha20.c
The SHA-3 context structure. The structure is used SHA-3 checksum calculations.
The type of computation stage for J-PAKE operations.
The GCM authenticated encryption algorithm. The underlying block cipher is determined by the key type.
The key size in bytes used by the cipher. Compile-time choice: 32 bytes (256 bits) because \c MBEDTLS_CTR_DRBG_USE_128_BIT_KEY is disabled.
The uncompressed point format for Short Weierstrass curves (MBEDTLS_ECP_DP_SECP_XXX and MBEDTLS_ECP_DP_BP_XXX).
\def MBEDTLS_HAVE_TIME_DATE System has time.h, time(), and an implementation for mbedtls_platform_gmtime_r() (see below). The time needs to be correct (not necessarily very accurate, but at least the date should be correct). This is used to verify the validity period of X.509 certificates. Comment if your system does not have a correct clock.
\def MBEDTLS_CIPHER_NULL_CIPHER Enable NULL cipher. Warning: Only do so when you know what you are doing. This allows for encryption or channels without any security! To enable the following ciphersuites: MBEDTLS_TLS_ECDH_ECDSA_WITH_NULL_SHA MBEDTLS_TLS_ECDH_RSA_WITH_NULL_SHA MBEDTLS_TLS_ECDHE_ECDSA_WITH_NULL_SHA MBEDTLS_TLS_ECDHE_RSA_WITH_NULL_SHA MBEDTLS_TLS_ECDHE_PSK_WITH_NULL_SHA384 MBEDTLS_TLS_ECDHE_PSK_WITH_NULL_SHA256 MBEDTLS_TLS_ECDHE_PSK_WITH_NULL_SHA MBEDTLS_TLS_DHE_PSK_WITH_NULL_SHA384 MBEDTLS_TLS_DHE_PSK_WITH_NULL_SHA256 MBEDTLS_TLS_DHE_PSK_WITH_NULL_SHA MBEDTLS_TLS_RSA_WITH_NULL_SHA256 MBEDTLS_TLS_RSA_WITH_NULL_SHA MBEDTLS_TLS_RSA_WITH_NULL_MD5 MBEDTLS_TLS_RSA_PSK_WITH_NULL_SHA384 MBEDTLS_TLS_RSA_PSK_WITH_NULL_SHA256 MBEDTLS_TLS_RSA_PSK_WITH_NULL_SHA MBEDTLS_TLS_PSK_WITH_NULL_SHA384 MBEDTLS_TLS_PSK_WITH_NULL_SHA256 MBEDTLS_TLS_PSK_WITH_NULL_SHA Uncomment this macro to enable the NULL cipher and ciphersuites \def MBEDTLS_CIPHER_PADDING_PKCS7 MBEDTLS_CIPHER_PADDING_XXX: Uncomment or comment macros to add support for specific padding modes in the cipher layer with cipher modes that support padding (e.g. CBC) If you disable all padding modes, only full blocks can be used with CBC. Enable padding modes in the cipher layer.
\def MBEDTLS_CTR_DRBG_USE_128_BIT_KEY Uncomment this macro to use a 128-bit key in the CTR_DRBG module. Without this, CTR_DRBG uses a 256-bit key unless \c MBEDTLS_AES_ONLY_128_BIT_KEY_LENGTH is set. Enable the verified implementations of ECDH primitives from Project Everest (currently only Curve25519). This feature changes the layout of ECDH contexts and therefore is a compatibility break for applications that access fields of a mbedtls_ecdh_context structure directly. See also MBEDTLS_ECDH_LEGACY_CONTEXT in include/mbedtls/ecdh.h. The Everest code is provided under the Apache 2.0 license only; therefore enabling this option is not compatible with taking the library under the GPL v2.0-or-later license. \def MBEDTLS_ECP_DP_SECP192R1_ENABLED MBEDTLS_ECP_XXXX_ENABLED: Enables specific curves within the Elliptic Curve module. By default all supported curves are enabled. Comment macros to disable the curve and functions for it
\def MBEDTLS_CTR_DRBG_USE_128_BIT_KEY Uncomment this macro to use a 128-bit key in the CTR_DRBG module. Without this, CTR_DRBG uses a 256-bit key unless \c MBEDTLS_AES_ONLY_128_BIT_KEY_LENGTH is set. Enable the verified implementations of ECDH primitives from Project Everest (currently only Curve25519). This feature changes the layout of ECDH contexts and therefore is a compatibility break for applications that access fields of a mbedtls_ecdh_context structure directly. See also MBEDTLS_ECDH_LEGACY_CONTEXT in include/mbedtls/ecdh.h. The Everest code is provided under the Apache 2.0 license only; therefore enabling this option is not compatible with taking the library under the GPL v2.0-or-later license. \def MBEDTLS_ECP_DP_SECP192R1_ENABLED MBEDTLS_ECP_XXXX_ENABLED: Enables specific curves within the Elliptic Curve module. By default all supported curves are enabled. Comment macros to disable the curve and functions for it
\def MBEDTLS_CTR_DRBG_C Enable the CTR_DRBG AES-based random generator. The CTR_DRBG generator uses AES-256 by default. To use AES-128 instead, enable \c MBEDTLS_CTR_DRBG_USE_128_BIT_KEY above. AES support can either be achieved through builtin (MBEDTLS_AES_C) or PSA. Builtin is the default option when MBEDTLS_AES_C is defined otherwise PSA is used. \warning When using PSA, the user should call `psa_crypto_init()` before using any CTR_DRBG operation (except `mbedtls_ctr_drbg_init()`). Module: library/ctr_drbg.c Caller: Requires: MBEDTLS_AES_C or (PSA_WANT_KEY_TYPE_AES and PSA_WANT_ALG_ECB_NO_PADDING and MBEDTLS_PSA_CRYPTO_C) This module provides the CTR_DRBG AES random number generator.
\def MBEDTLS_SHA3_C Enable the SHA3 cryptographic hash algorithm. Module: library/sha3.c This module adds support for SHA3.
The Password-authenticated key exchange by juggling (J-PAKE) algorithm. This is J-PAKE as defined by RFC 8236, instantiated with the following parameters: - The group can be either an elliptic curve or defined over a finite field. - Schnorr NIZK proof as defined by RFC 8235 and using the same group as the J-PAKE algorithm. - A cryptographic hash function. To select these parameters and set up the cipher suite, call these functions in any order:
psa_pake_cs_set_algorithm(cipher_suite, PSA_ALG_JPAKE);
psa_pake_cs_set_primitive(cipher_suite,
PSA_PAKE_PRIMITIVE(type, family, bits));
psa_pake_cs_set_hash(cipher_suite, hash);
For more information on how to set a specific curve or field, refer to the documentation of the individual \c PSA_PAKE_PRIMITIVE_TYPE_XXX constants. After initializing a J-PAKE operation, call
psa_pake_setup(operation, cipher_suite);
psa_pake_set_user(operation, ...);
psa_pake_set_peer(operation, ...);
psa_pake_set_password_key(operation, ...);
The password is provided as a key. This can be the password text itself, in an agreed character encoding, or some value derived from the password as required by a higher level protocol. (The implementation converts the key material to a number as described in Section 2.3.8 of _SEC 1: Elliptic Curve Cryptography_ (https://www.secg.org/sec1-v2.pdf), before reducing it modulo \c q. Here \c q is order of the group defined by the primitive set in the cipher suite. The \c psa_pake_set_password_key() function returns an error if the result of the reduction is 0.) The key exchange flow for J-PAKE is as follows: -# To get the first round data that needs to be sent to the peer, call
// Get g1
psa_pake_output(operation, #PSA_PAKE_STEP_KEY_SHARE, ...);
// Get the ZKP public key for x1
psa_pake_output(operation, #PSA_PAKE_STEP_ZK_PUBLIC, ...);
// Get the ZKP proof for x1
psa_pake_output(operation, #PSA_PAKE_STEP_ZK_PROOF, ...);
// Get g2
psa_pake_output(operation, #PSA_PAKE_STEP_KEY_SHARE, ...);
// Get the ZKP public key for x2
psa_pake_output(operation, #PSA_PAKE_STEP_ZK_PUBLIC, ...);
// Get the ZKP proof for x2
psa_pake_output(operation, #PSA_PAKE_STEP_ZK_PROOF, ...);
-# To provide the first round data received from the peer to the operation, call
// Set g3
psa_pake_input(operation, #PSA_PAKE_STEP_KEY_SHARE, ...);
// Set the ZKP public key for x3
psa_pake_input(operation, #PSA_PAKE_STEP_ZK_PUBLIC, ...);
// Set the ZKP proof for x3
psa_pake_input(operation, #PSA_PAKE_STEP_ZK_PROOF, ...);
// Set g4
psa_pake_input(operation, #PSA_PAKE_STEP_KEY_SHARE, ...);
// Set the ZKP public key for x4
psa_pake_input(operation, #PSA_PAKE_STEP_ZK_PUBLIC, ...);
// Set the ZKP proof for x4
psa_pake_input(operation, #PSA_PAKE_STEP_ZK_PROOF, ...);
-# To get the second round data that needs to be sent to the peer, call
// Get A
psa_pake_output(operation, #PSA_PAKE_STEP_KEY_SHARE, ...);
// Get ZKP public key for x2*s
psa_pake_output(operation, #PSA_PAKE_STEP_ZK_PUBLIC, ...);
// Get ZKP proof for x2*s
psa_pake_output(operation, #PSA_PAKE_STEP_ZK_PROOF, ...);
-# To provide the second round data received from the peer to the operation, call
// Set B
psa_pake_input(operation, #PSA_PAKE_STEP_KEY_SHARE, ...);
// Set ZKP public key for x4*s
psa_pake_input(operation, #PSA_PAKE_STEP_ZK_PUBLIC, ...);
// Set ZKP proof for x4*s
psa_pake_input(operation, #PSA_PAKE_STEP_ZK_PROOF, ...);
-# To access the shared secret call
// Get Ka=Kb=K
psa_pake_get_implicit_key()
For more information consult the documentation of the individual \c PSA_PAKE_STEP_XXX constants. At this point there is a cryptographic guarantee that only the authenticated party who used the same password is able to compute the key. But there is no guarantee that the peer is the party it claims to be and was able to do so. That is, the authentication is only implicit (the peer is not authenticated at this point, and no action should be taken that assume that they are - like for example accessing restricted files). To make the authentication explicit there are various methods, see Section 5 of RFC 8236 for two examples. \def MBEDTLS_KEY_EXCHANGE_PSK_ENABLED Enable the PSK based ciphersuite modes in SSL / TLS. This enables the following ciphersuites (if other requisites are enabled as well): MBEDTLS_TLS_PSK_WITH_AES_256_GCM_SHA384 MBEDTLS_TLS_PSK_WITH_AES_256_CBC_SHA384 MBEDTLS_TLS_PSK_WITH_AES_256_CBC_SHA MBEDTLS_TLS_PSK_WITH_CAMELLIA_256_GCM_SHA384 MBEDTLS_TLS_PSK_WITH_CAMELLIA_256_CBC_SHA384 MBEDTLS_TLS_PSK_WITH_AES_128_GCM_SHA256 MBEDTLS_TLS_PSK_WITH_AES_128_CBC_SHA256 MBEDTLS_TLS_PSK_WITH_AES_128_CBC_SHA MBEDTLS_TLS_PSK_WITH_CAMELLIA_128_GCM_SHA256 MBEDTLS_TLS_PSK_WITH_CAMELLIA_128_CBC_SHA256
\def MBEDTLS_PKCS12_C Enable PKCS#12 PBE functions. Adds algorithms for parsing PKCS#8 encrypted private keys Module: library/pkcs12.c Caller: library/pkparse.c Requires: MBEDTLS_ASN1_PARSE_C and either MBEDTLS_MD_C or MBEDTLS_PSA_CRYPTO_C. \warning If using a hash that is only provided by PSA drivers, you must call psa_crypto_init() before doing any PKCS12 operations. This module enables PKCS#12 functions.
\def MBEDTLS_PSA_CRYPTO_SE_C Enable dynamic secure element support in the Platform Security Architecture cryptography API. \deprecated This feature is deprecated. Please switch to the PSA driver interface. \warning This feature is not thread-safe, and should not be used in a multi-threaded environment. Module: library/psa_crypto_se.c Requires: MBEDTLS_PSA_CRYPTO_C, MBEDTLS_PSA_CRYPTO_STORAGE_C \def MBEDTLS_PSA_CRYPTO_STORAGE_C Enable the Platform Security Architecture persistent key storage. Module: library/psa_crypto_storage.c Requires: MBEDTLS_PSA_CRYPTO_C, either MBEDTLS_PSA_ITS_FILE_C or a native implementation of the PSA ITS interface
Options for RSASSA-PSS signature verification. See \c mbedtls_rsa_rsassa_pss_verify_ext()
Next certificate in the linked list that constitutes the CA chain. \p NULL indicates the end of the list. Do not modify this field directly.
Asking for an item that doesn't exist Implementations should return this error, if a requested item (like
SEC random curves over prime fields. This family comprises the following curves: secp192r1, secp224r1, secp256r1, secp384r1, secp521r1. They are defined in _Standards for Efficient Cryptography_, _SEC 2: Recommended Elliptic Curve Domain Parameters_. https://www.secg.org/sec2-v2.pdf
DES context structure \warning DES/3DES are considered weak ciphers and their use constitutes a security risk. We recommend considering stronger ciphers instead.
\def MBEDTLS_ENTROPY_C Enable the platform-specific entropy code. Module: library/entropy.c Caller: Requires: MBEDTLS_SHA512_C or MBEDTLS_SHA256_C This module provides a generic entropy pool
\def MBEDTLS_MD5_C Enable the MD5 hash algorithm. Module: library/md5.c Caller: library/md.c library/pem.c library/ssl_tls.c This module is required for TLS 1.2 depending on the handshake parameters. Further, it is used for checking MD5-signed certificates, and for PBKDF1 when decrypting PEM-encoded encrypted keys. \warning MD5 is considered a weak message digest and its use constitutes a security risk. If possible, we recommend avoiding dependencies on it, and considering stronger message digests instead.
\def MBEDTLS_RIPEMD160_C Enable the RIPEMD-160 hash algorithm. Module: library/ripemd160.c Caller: library/md.c
For Short Weierstrass: \p A in the equation. Note that \p A is not set to the authentic value in some cases. Refer to detailed description of ::mbedtls_ecp_group if using domain parameters in the structure. For Montgomery curves: (A + 2) / 4.
Unique ID indicating which driver got assigned to do the operation. Since driver contexts are driver-specific, swapping drivers halfway through the operation is not supported. ID values are auto-generated in psa_driver_wrappers.h. ID value zero means the context is not valid or not assigned to any driver (i.e. the driver context is not active, in use).
Unique ID indicating which driver got assigned to do the operation. Since driver contexts are driver-specific, swapping drivers halfway through the operation is not supported. ID values are auto-generated in psa_crypto_driver_wrappers.h ID value zero means the context is not valid or not assigned to any driver (i.e. none of the driver contexts are active).
\def MBEDTLS_ECP_RESTARTABLE Enable "non-blocking" ECC operations that can return early and be resumed. This allows various functions to pause by returning #MBEDTLS_ERR_ECP_IN_PROGRESS (or, for functions in the SSL module, #MBEDTLS_ERR_SSL_CRYPTO_IN_PROGRESS) and then be called later again in order to further progress and eventually complete their operation. This is controlled through mbedtls_ecp_set_max_ops() which limits the maximum number of ECC operations a function may perform before pausing; see mbedtls_ecp_set_max_ops() for more information. This is useful in non-threaded environments if you want to avoid blocking for too long on ECC (and, hence, X.509 or SSL/TLS) operations. This option: - Adds xxx_restartable() variants of existing operations in the following modules, with corresponding restart context types: - ECP (for Short Weierstrass curves only): scalar multiplication (mul), linear combination (muladd); - ECDSA: signature generation & verification; - PK: signature generation & verification; - X509: certificate chain verification. - Adds mbedtls_ecdh_enable_restart() in the ECDH module. - Changes the behaviour of TLS 1.2 clients (not servers) when using the ECDHE-ECDSA key exchange (not other key exchanges) to make all ECC computations restartable: - ECDH operations from the key exchange, only for Short Weierstrass curves, only when MBEDTLS_USE_PSA_CRYPTO is not enabled. - verification of the server's key exchange signature; - verification of the server's certificate chain; - generation of the client's signature if client authentication is used, with an ECC key/certificate. Requires: MBEDTLS_ECP_C Uncomment this macro to enable restartable ECC computations. Uncomment to enable using new bignum code in the ECC modules. \warning This is currently experimental, incomplete and therefore should not be used in production. \def MBEDTLS_ECDSA_DETERMINISTIC Enable deterministic ECDSA (RFC 6979). Standard ECDSA is "fragile" in the sense that lack of entropy when signing may result in a compromise of the long-term signing key. This is avoided by the deterministic variant. Requires: MBEDTLS_HMAC_DRBG_C, MBEDTLS_ECDSA_C Comment this macro to disable deterministic ECDSA.
\def MBEDTLS_ASN1_WRITE_C Enable the generic ASN1 writer. Module: library/asn1write.c Caller: library/ecdsa.c library/pkwrite.c library/x509_create.c library/x509write_crt.c library/x509write_csr.c
\def MBEDTLS_PKCS5_C Enable PKCS#5 functions. Module: library/pkcs5.c Auto-enables: MBEDTLS_MD_C \warning If using a hash that is only provided by PSA drivers, you must call psa_crypto_init() before doing any PKCS5 operations. This module adds support for the PKCS#5 functions.
\def MBEDTLS_X509_USE_C Enable X.509 core for using certificates. Module: library/x509.c Caller: library/x509_crl.c library/x509_crt.c library/x509_csr.c Requires: MBEDTLS_ASN1_PARSE_C, MBEDTLS_BIGNUM_C, MBEDTLS_OID_C, MBEDTLS_PK_PARSE_C, (MBEDTLS_MD_C or MBEDTLS_USE_PSA_CRYPTO) \warning If building with MBEDTLS_USE_PSA_CRYPTO, you must call psa_crypto_init() before doing any X.509 operation. This module is required for the X.509 parsing modules.
\def MBEDTLS_SSL_IN_CONTENT_LEN Maximum incoming fragment length in bytes. Uncomment to set the size of the inward TLS buffer independently of the outward buffer.
Encoding of key persistence levels. What distinguishes different persistence levels is what device management events may cause keys to be destroyed. _Volatile_ keys are destroyed by a power reset. Persistent keys may be destroyed by events such as a transfer of ownership or a factory reset. What management events actually affect persistent keys at different levels is outside the scope of the PSA Cryptography specification. The PSA Cryptography specification defines the following values of persistence levels: - \c 0 = #PSA_KEY_PERSISTENCE_VOLATILE: volatile key. A volatile key is automatically destroyed by the implementation when the application instance terminates. In particular, a volatile key is automatically destroyed on a power reset of the device. - \c 1 = #PSA_KEY_PERSISTENCE_DEFAULT: persistent key with a default lifetime. - \c 2-254: currently not supported by Mbed TLS. - \c 255 = #PSA_KEY_PERSISTENCE_READ_ONLY: read-only or write-once key. A key with this persistence level cannot be destroyed. Mbed TLS does not currently offer a way to create such keys, but integrations of Mbed TLS can use it for built-in keys that the application cannot modify (for example, a hardware unique key (HUK)).
Sufficient buffer size for exporting any asymmetric public key. This macro expands to a compile-time constant integer. This value is a sufficient buffer size when calling psa_export_key() or psa_export_public_key() to export any asymmetric public key, regardless of the exact key type and key size. See also #PSA_EXPORT_PUBLIC_KEY_OUTPUT_SIZE(\p key_type, \p key_bits).
Unique ID indicating which driver got assigned to do the operation. Since driver contexts are driver-specific, swapping drivers halfway through the operation is not supported. ID values are auto-generated in psa_driver_wrappers.h ID value zero means the context is not valid or not assigned to any driver (i.e. none of the driver contexts are active).
The key wrapping context-type definition. The key wrapping context is passed to the APIs called.
\def MBEDTLS_NO_DEFAULT_ENTROPY_SOURCES Do not add default entropy sources in mbedtls_entropy_init(). This is useful to have more control over the added entropy sources in an application. Uncomment this macro to prevent loading of default entropy functions. \def MBEDTLS_NO_PLATFORM_ENTROPY Do not use built-in platform entropy functions. This is useful if your platform does not support standards like the /dev/urandom or Windows CryptoAPI. Uncomment this macro to disable the built-in platform entropy functions. \def MBEDTLS_ENTROPY_FORCE_SHA256 Force the entropy accumulator to use a SHA-256 accumulator instead of the default SHA-512 based one (if both are available). Requires: MBEDTLS_SHA256_C On 32-bit systems SHA-256 can be much faster than SHA-512. Use this option if you have performance concerns. This option is only useful if both MBEDTLS_SHA256_C and MBEDTLS_SHA512_C are defined. Otherwise the available hash module is used. \def MBEDTLS_ENTROPY_NV_SEED Enable the non-volatile (NV) seed file-based entropy source. (Also enables the NV seed read/write functions in the platform layer) This is crucial (if not required) on systems that do not have a cryptographic entropy source (in hardware or kernel) available. Requires: MBEDTLS_ENTROPY_C, MBEDTLS_PLATFORM_C \def MBEDTLS_MEMORY_DEBUG Enable debugging of buffer allocator memory issues. Automatically prints (to stderr) all (fatal) messages on memory allocation issues. Enables function for 'debug output' of allocated memory. Requires: MBEDTLS_MEMORY_BUFFER_ALLOC_C Uncomment this macro to let the buffer allocator print out error messages. \def MBEDTLS_MEMORY_BACKTRACE Include backtrace information with each allocated block. Requires: MBEDTLS_MEMORY_BUFFER_ALLOC_C GLIBC-compatible backtrace() and backtrace_symbols() support Uncomment this macro to include backtrace information \def MBEDTLS_PK_RSA_ALT_SUPPORT Support external private RSA keys (eg from a HSM) in the PK layer. Comment this macro to disable support for external private RSA keys.
\def MBEDTLS_OID_C Enable the OID database. Module: library/oid.c Caller: library/asn1write.c library/pkcs5.c library/pkparse.c library/pkwrite.c library/rsa.c library/x509.c library/x509_create.c library/x509_crl.c library/x509_crt.c library/x509_csr.c library/x509write_crt.c library/x509write_csr.c This modules translates between OIDs and internal values.
\def MBEDTLS_PK_PARSE_C Enable the generic public (asymmetric) key parser. Module: library/pkparse.c Caller: library/x509_crt.c library/x509_csr.c Requires: MBEDTLS_ASN1_PARSE_C, MBEDTLS_OID_C, MBEDTLS_PK_C Uncomment to enable generic public key parse functions.
\def MBEDTLS_X509_CREATE_C Enable X.509 core for creating certificates. Module: library/x509_create.c Requires: MBEDTLS_BIGNUM_C, MBEDTLS_OID_C, MBEDTLS_PK_PARSE_C, (MBEDTLS_MD_C or MBEDTLS_USE_PSA_CRYPTO) \warning If building with MBEDTLS_USE_PSA_CRYPTO, you must call psa_crypto_init() before doing any X.509 create operation. This module is the basis for creating X.509 certificates and CSRs.
Custom parameters for key generation or key derivation. This is a structure type with at least the following fields: - \c flags: an unsigned integer type. 0 for the default production parameters. - \c data: a flexible array of bytes. The interpretation of this structure depend on the type of the created key. - #PSA_KEY_TYPE_RSA_KEY_PAIR: - \c flags: must be 0. - \c data: the public exponent, in little-endian order. This must be an odd integer and must not be 1. Implementations must support 65537, should support 3 and may support other values. When not using a driver, Mbed TLS supports values up to \c INT_MAX. If this is empty or if the custom production parameters are omitted altogether, the default value 65537 is used. - Other key types: reserved for future use. \c flags must be 0.
From RFC 5280 section 4.2.1.6: OtherName ::= SEQUENCE { type-id OBJECT IDENTIFIER, value [0] EXPLICIT ANY DEFINED BY type-id } Future versions of the library may add new fields to this structure or to its embedded union and structure.
Verification chain as built by \c mbedtls_crt_verify_chain()
Data read from storage is not valid for the implementation. This error indicates that some data read from storage does not have a valid format. It does not indicate the following situations, which have specific error codes: - When the storage or stored data is corrupted - use #PSA_ERROR_DATA_CORRUPT - When the storage fails for other reasons - use #PSA_ERROR_STORAGE_FAILURE - An invalid argument to the API - use #PSA_ERROR_INVALID_ARGUMENT This error is typically a result of either storage corruption on a cleartext storage backend, or an attempt to read data that was written by an incompatible version of the library.
Whether a key type is a key pair containing a private part and a public
Macro to build the base MAC algorithm corresponding to a truncated MAC algorithm.
Get the unsigned 24 bits integer corresponding to three bytes in big-endian order (MSB first).
This macro checks if the remaining length in an input buffer is greater or equal than a needed length. If it is not the case, it returns #MBEDTLS_ERR_SSL_DECODE_ERROR error and pends a #MBEDTLS_SSL_ALERT_MSG_DECODE_ERROR alert message. This is a function-like macro. It is guaranteed to evaluate each argument exactly once.
\def MBEDTLS_CMAC_C Enable the CMAC (Cipher-based Message Authentication Code) mode for block ciphers. Module: library/cmac.c Requires: MBEDTLS_CIPHER_C, MBEDTLS_AES_C or MBEDTLS_DES_C
Domain parameters for the 384-bit curve defined by FIPS 186-4 and SEC1.
\def MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_EPHEMERAL_ENABLED Enable TLS 1.3 ephemeral key exchange mode. Requires: PSA_WANT_ALG_ECDH or PSA_WANT_ALG_FFDH MBEDTLS_X509_CRT_PARSE_C and at least one of: MBEDTLS_ECDSA_C or (MBEDTLS_USE_PSA_CRYPTO and PSA_WANT_ALG_ECDSA) MBEDTLS_PKCS1_V21 Comment to disable support for the ephemeral key exchange mode in TLS 1.3. If MBEDTLS_SSL_PROTO_TLS1_3 is not enabled, this option does not have any effect on the build.
\def MBEDTLS_SSL_DTLS_SRTP Enable support for negotiation of DTLS-SRTP (RFC 5764) through the use_srtp extension. Setting this option enables the runtime API mbedtls_ssl_conf_dtls_srtp_protection_profiles() through which the supported DTLS-SRTP protection profiles can be configured. You must call this API at runtime if you wish to negotiate the use of DTLS-SRTP. Requires: MBEDTLS_SSL_PROTO_DTLS Uncomment this to enable support for use_srtp extension. \def MBEDTLS_SSL_DTLS_CLIENT_PORT_REUSE Enable server-side support for clients that reconnect from the same port. Some clients unexpectedly close the connection and try to reconnect using the same source port. This needs special support from the server to handle the new connection securely, as described in section 4.2.8 of RFC 6347. This flag enables that support. Requires: MBEDTLS_SSL_DTLS_HELLO_VERIFY Comment this to disable support for clients reusing the source port.
\def MBEDTLS_LMS_C Enable the LMS stateful-hash asymmetric signature algorithm. Module: library/lms.c Caller: Requires: MBEDTLS_PSA_CRYPTO_C Uncomment to enable the LMS verification algorithm and public key operations.
Encoding of the primitive associated with the PAKE. For more information see the documentation of the #PSA_PAKE_PRIMITIVE macro.
Next element in the linked list of CRL. \p NULL indicates the end of the list. Do not modify this field directly.
Whether a key lifetime indicates that the key is volatile. A volatile key is automatically destroyed by the implementation when the application instance terminates. In particular, a volatile key is automatically destroyed on a power reset of the device. A key that is not volatile is persistent. Persistent keys are preserved until the application explicitly destroys them or until an implementation-specific device management event occurs (for example, a factory reset).
Compares an mbedtls_asn1_buf structure to a reference OID. Only works for 'defined' oid_str values (MBEDTLS_OID_HMAC_SHA1), you cannot use a 'unsigned char *oid' here!
Unaligned data buffer. This buffer can hold 32 extra Bytes, which can be used for one of the following purposes: Alignment if VIA padlock is used. Simplifying key expansion in the 256-bit case by generating an extra round key.
Domain parameters for the 521-bit curve defined by FIPS 186-4 and SEC1.
\def MBEDTLS_SSL_ASYNC_PRIVATE Enable asynchronous external private key operations in SSL. This allows you to configure an SSL connection to call an external cryptographic module to perform private key operations instead of performing the operation inside the library. Requires: MBEDTLS_X509_CRT_PARSE_C \def MBEDTLS_SSL_CONTEXT_SERIALIZATION Enable serialization of the TLS context structures, through use of the functions mbedtls_ssl_context_save() and mbedtls_ssl_context_load(). This pair of functions allows one side of a connection to serialize the context associated with the connection, then free or re-use that context while the serialized state is persisted elsewhere, and finally deserialize that state to a live context for resuming read/write operations on the connection. From a protocol perspective, the state of the connection is unaffected, in particular this is entirely transparent to the peer. Note: this is distinct from TLS session resumption, which is part of the protocol and fully visible by the peer. TLS session resumption enables establishing new connections associated to a saved session with shorter, lighter handshakes, while context serialization is a local optimization in handling a single, potentially long-lived connection. Enabling these APIs makes some SSL structures larger, as 64 extra bytes are saved after the handshake to allow for more efficient serialization, so if you don't need this feature you'll save RAM by disabling it. Requires: MBEDTLS_GCM_C or MBEDTLS_CCM_C or MBEDTLS_CHACHAPOLY_C Comment to disable the context serialization APIs.
\def MBEDTLS_AESNI_C Enable AES-NI support on x86-64 or x86-32. Module: library/aesni.c Caller: library/aes.c Requires: MBEDTLS_HAVE_ASM (on some platforms, see note) This modules adds support for the AES-NI instructions on x86.
\def MBEDTLS_ECDH_C Enable the elliptic curve Diffie-Hellman library. Module: library/ecdh.c Caller: library/psa_crypto.c library/ssl_tls.c library/ssl*_client.c library/ssl*_server.c This module is used by the following key exchanges: ECDHE-ECDSA, ECDHE-RSA, DHE-PSK Requires: MBEDTLS_ECP_C
\def MBEDTLS_PLATFORM_MEMORY Enable the memory allocation layer. By default mbed TLS uses the system-provided calloc() and free(). This allows different allocators (self-implemented or provided) to be provided to the platform abstraction layer. Enabling MBEDTLS_PLATFORM_MEMORY without the MBEDTLS_PLATFORM_{FREE,CALLOC}_MACROs will provide "mbedtls_platform_set_calloc_free()" allowing you to set an alternative calloc() and free() function pointer at runtime. Enabling MBEDTLS_PLATFORM_MEMORY and specifying MBEDTLS_PLATFORM_{CALLOC,FREE}_MACROs will allow you to specify the alternate function at compile time. Requires: MBEDTLS_PLATFORM_C Enable this layer to allow use of alternative memory allocators.
Item in a verification chain: cert and flags for it
From RFC 4108 section 5: HardwareModuleName ::= SEQUENCE { hwType OBJECT IDENTIFIER, hwSerialNum OCTET STRING }
There was a storage failure that may have led to data loss. This error indicates that some persistent storage is corrupted. It should not be used for a corruption of volatile memory (use #PSA_ERROR_CORRUPTION_DETECTED), for a communication error between the cryptoprocessor and its external storage (use #PSA_ERROR_COMMUNICATION_FAILURE), or when the storage is in a valid state but is full (use #PSA_ERROR_INSUFFICIENT_STORAGE). Note that a storage failure does not indicate that any data that was previously read is invalid. However this previously read data may no longer be readable from storage. When a storage failure occurs, it is no longer possible to ensure the global integrity of the keystore. Depending on the global integrity guarantees offered by the implementation, access to other data may or may not fail even if the data is still readable but its integrity cannot be guaranteed. Implementations should only use this error code to report a permanent storage corruption. However application writers should keep in mind that transient errors while reading the storage may be
RSA key pair (private and public key). The size of an RSA key is the bit size of the modulus.
In a hash-and-sign algorithm policy, allow any hash algorithm. This value may be used to form the algorithm usage field of a policy for a signature algorithm that is parametrized by a hash. The key may then be used to perform operations using the same signature algorithm parametrized with any supported hash. That is, suppose that `PSA_xxx_SIGNATURE` is one of the following macros: - #PSA_ALG_RSA_PKCS1V15_SIGN, #PSA_ALG_RSA_PSS, #PSA_ALG_RSA_PSS_ANY_SALT, - #PSA_ALG_ECDSA, #PSA_ALG_DETERMINISTIC_ECDSA. Then you may create and use a key as follows: - Set the key usage field using #PSA_ALG_ANY_HASH, for example: ``` psa_set_key_usage_flags(&attributes, PSA_KEY_USAGE_SIGN_HASH); // or VERIFY psa_set_key_algorithm(&attributes, PSA_xxx_SIGNATURE(PSA_ALG_ANY_HASH)); ``` - Import or generate key material. - Call psa_sign_hash() or psa_verify_hash(), passing an algorithm built from `PSA_xxx_SIGNATURE` and a specific hash. Each call to sign or verify a message may use a different hash. ``` psa_sign_hash(key, PSA_xxx_SIGNATURE(PSA_ALG_SHA_256), ...); psa_sign_hash(key, PSA_xxx_SIGNATURE(PSA_ALG_SHA_512), ...); psa_sign_hash(key, PSA_xxx_SIGNATURE(PSA_ALG_SHA3_256), ...); ``` This value may not be used to build other algorithms that are parametrized over a hash. For any valid use of this macro to build an algorithm \c alg, #PSA_ALG_IS_HASH_AND_SIGN(\c alg) is true. This value may not be used to build an algorithm specification to perform an operation. It is only valid to build policies.
Whether the specified algorithm is a signature algorithm that can be used with psa_sign_hash() and psa_verify_hash(). This encompasses all strict hash-and-sign algorithms categorized by PSA_ALG_IS_HASH_AND_SIGN(), as well as algorithms that follow the paradigm more loosely: - #PSA_ALG_RSA_PKCS1V15_SIGN_RAW (expects its input to be an encoded hash) - #PSA_ALG_ECDSA_ANY (doesn't specify what kind of hash the input is)
Get the hash used by a hash-and-sign signature algorithm. A hash-and-sign algorithm is a signature algorithm which is composed of two phases: first a hashing phase which does not use the key and produces a hash of the input message, then a signing phase which only uses the hash and the key and not the message itself.
Whether the key may be used to encrypt a message. This flag allows the key to be used for a symmetric encryption operation, for an AEAD encryption-and-authentication operation, or for an asymmetric encryption operation, if otherwise permitted by the key's type and policy. For a key pair, this concerns the public key.
Whether the key may be used to verify a message. This flag allows the key to be used for a MAC verification operation or for an asymmetric message signature verification operation, if otherwise permitted by the key’s type and policy. For a key pair, this concerns the public key.
Sufficient buffer size for exporting any asymmetric key pair. This macro expands to a compile-time constant integer. This value is a sufficient buffer size when calling psa_export_key() to export any asymmetric key pair, regardless of the exact key type and key size. See also #PSA_EXPORT_KEY_OUTPUT_SIZE(\p key_type, \p key_bits).
pkcs-1 OBJECT IDENTIFIER ::= { iso(1) member-body(2) us(840) rsadsi(113549) pkcs(1) 1 }
Cumulative size of heap allocated buffers used for message buffering.
\def MBEDTLS_SSL_COOKIE_C Enable basic implementation of DTLS cookies for hello verification. Module: library/ssl_cookie.c Caller:
\def MBEDTLS_ECJPAKE_C Enable the elliptic curve J-PAKE library. Module: library/ecjpake.c Caller: This module is used by the following key exchanges: ECJPAKE Requires: MBEDTLS_ECP_C and either MBEDTLS_MD_C or MBEDTLS_PSA_CRYPTO_C \warning If using a hash that is only provided by PSA drivers, you must call psa_crypto_init() before doing any EC J-PAKE operations.
\def MBEDTLS_HMAC_DRBG_C Enable the HMAC_DRBG random generator. Module: library/hmac_drbg.c Caller: Requires: MBEDTLS_MD_C Uncomment to enable the HMAC_DRBG random number generator.
\def MBEDTLS_X509_CRL_PARSE_C Enable X.509 CRL parsing. Module: library/x509_crl.c Caller: library/x509_crt.c Requires: MBEDTLS_X509_USE_C This module is required for X.509 CRL parsing.
The requested action is denied by a policy. Implementations should return this error code when the parameters are recognized as valid and supported, and a policy explicitly denies the requested operation. If a subset of the parameters of a function call identify a forbidden operation, and another subset of the parameters are not valid or not supported, it is unspecified whether the function returns #PSA_ERROR_NOT_PERMITTED, #PSA_ERROR_NOT_SUPPORTED or
The key identifier is not valid. See also :ref:\`key-handles\`.
Brainpool P random curves. This family comprises the following curves: brainpoolP160r1, brainpoolP192r1, brainpoolP224r1, brainpoolP256r1, brainpoolP320r1, brainpoolP384r1, brainpoolP512r1. It is defined in RFC 5639.
The block size of a block cipher. \warning This macro may evaluate its argument multiple times.
Whether the specified algorithm is an authenticated encryption with associated data (AEAD) algorithm.
Whether the key may be used to decrypt a message. This flag allows the key to be used for a symmetric decryption operation, for an AEAD decryption-and-verification operation, or for an asymmetric decryption operation, if otherwise permitted by the key's type and policy. For a key pair, this concerns the private key.
Whether the key may be used to sign a message. This flag allows the key to be used for a MAC calculation operation or for an asymmetric message signature operation, if otherwise permitted by the key’s type and policy. For a key pair, this concerns the private key.
Whether the key may be used to sign a message. This flag allows the key to be used for a MAC calculation operation or for an asymmetric signature operation, if otherwise permitted by the key's type and policy. For a key pair, this concerns the private key.
Whether the key may be used to verify a message signature. This flag allows the key to be used for a MAC verification operation or for an asymmetric signature verification operation, if otherwise permitted by the key's type and policy. For a key pair, this concerns the public key.
The size of the output of psa_hash_finish(), in bytes. This is also the hash size that psa_hash_verify() expects.
Current IV or NONCE_COUNTER for CTR-mode, data unit (or sector) number for XTS-mode.
Unique ID indicating which driver got assigned to do the operation. Since driver contexts are driver-specific, swapping drivers halfway through the operation is not supported. ID values are auto-generated in psa_crypto_driver_wrappers.h ID value zero means the context is not valid or not assigned to any driver (i.e. none of the driver contexts are active).
Unprocessed data - either data that was not block aligned and is still pending processing, or the final block.
Unique ID indicating which driver got assigned to do the operation. Since driver contexts are driver-specific, swapping drivers halfway through the operation is not supported. ID values are auto-generated in psa_crypto_driver_wrappers.h ID value zero means the context is not valid or not assigned to any driver (i.e. none of the driver contexts are active).
TLS version negotiated in the session. Used if and when renegotiating or resuming a session instead of the configured minor TLS version.
LMS parameters structure. This contains the metadata associated with an LMS key, detailing the algorithm type, the type of the underlying OTS algorithm, and the key ID.
The PKCS #7 content info is invalid or cannot be parsed.
A structure containing pointers to all the entry points of a secure element driver. Future versions of this specification may add extra substructures at the end of this structure.
\def MBEDTLS_ENTROPY_HARDWARE_ALT Uncomment this macro to let mbed TLS use your own implementation of a hardware entropy collector. Your function must be called \c mbedtls_hardware_poll(), have the same prototype as declared in entropy_poll.h, and accept NULL as first argument. Uncomment to use your own hardware entropy collector.
\def MBEDTLS_HAVE_ASM The compiler has support for asm(). Requires support for asm() in compiler. Used in: library/aesni.h library/aria.c library/bn_mul.h library/constant_time.c library/padlock.h Required by: MBEDTLS_AESCE_C MBEDTLS_AESNI_C (on some platforms) MBEDTLS_PADLOCK_C Comment to disable the use of assembly code.
\def MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_PSK_EPHEMERAL_ENABLED Enable TLS 1.3 PSK ephemeral key exchange mode. Requires: PSA_WANT_ALG_ECDH or PSA_WANT_ALG_FFDH Comment to disable support for the PSK ephemeral key exchange mode in TLS 1.3. If MBEDTLS_SSL_PROTO_TLS1_3 is not enabled, this option does not have any effect on the build.
\def MBEDTLS_AESCE_C Enable AES cryptographic extension support on Armv8. Module: library/aesce.c Caller: library/aes.c Requires: MBEDTLS_AES_C \warning Runtime detection only works on Linux. For non-Linux operating system, Armv8-A Cryptographic Extensions must be supported by the CPU when this option is enabled. This module adds support for the AES Armv8-A Cryptographic Extensions on Armv8 systems.
\def MBEDTLS_BASE64_C Enable the Base64 module. Module: library/base64.c Caller: library/pem.c This module is required for PEM support (required by X.509).
\def MBEDTLS_GCM_LARGE_TABLE Enable large pre-computed tables for Galois/Counter Mode (GCM). Can significantly increase throughput on systems without GCM hardware acceleration (e.g., AESNI, AESCE). The mbedtls_gcm_context size will increase by 3840 bytes. The code size will increase by roughly 344 bytes. Module: library/gcm.c Requires: MBEDTLS_GCM_C \def MBEDTLS_HKDF_C Enable the HKDF algorithm (RFC 5869). Module: library/hkdf.c Caller: Requires: MBEDTLS_MD_C This module adds support for the Hashed Message Authentication Code (HMAC)-based key derivation function (HKDF).
\def MBEDTLS_MEMORY_BUFFER_ALLOC_C Enable the buffer allocator implementation that makes use of a (stack) based buffer to 'allocate' dynamic memory. (replaces calloc() and free() calls) Module: library/memory_buffer_alloc.c Requires: MBEDTLS_PLATFORM_C MBEDTLS_PLATFORM_MEMORY (to use it within Mbed TLS) Enable this module to enable the buffer memory allocator. \def MBEDTLS_NET_C Enable the TCP and UDP over IPv6/IPv4 networking routines. Module: library/net_sockets.c This module provides networking routines.
Domain parameters for the 192-bit curve defined by FIPS 186-4 and SEC1.
Next element in the linked list of entries. \p NULL indicates the end of the list. Do not modify this field directly.
An error occurred that does not correspond to any defined failure cause. Implementations may use this error code if none of the other standard
SEC Koblitz curves over prime fields. This family comprises the following curves: secp192k1, secp224k1, secp256k1. They are defined in _Standards for Efficient Cryptography_, _SEC 2: Recommended Elliptic Curve Domain Parameters_. https://www.secg.org/sec2-v2.pdf
Whether the specified algorithm is an HMAC algorithm. HMAC is a family of MAC algorithms that are based on a hash function.
A secret input for key derivation. This should be a key of type #PSA_KEY_TYPE_DERIVE (passed to psa_key_derivation_input_key()) or the shared secret resulting from a key agreement (obtained via psa_key_derivation_key_agreement()). The secret can also be a direct input (passed to key_derivation_input_bytes()). In this case, the derivation operation may not be used to derive keys: the operation will only allow psa_key_derivation_output_bytes(), psa_key_derivation_verify_bytes(), or psa_key_derivation_verify_key(), but not psa_key_derivation_output_key().
Maximum size of the output from psa_raw_key_agreement(). This macro expands to a compile-time constant integer. This value is the maximum size of the output any raw key agreement algorithm, in bytes. See also #PSA_RAW_KEY_AGREEMENT_OUTPUT_SIZE(\p key_type, \p key_bits).
\def MBEDTLS_GENPRIME Enable the prime-number generation code. Requires: MBEDTLS_BIGNUM_C
\def MBEDTLS_SSL_DTLS_CONNECTION_ID_COMPAT Defines whether RFC 9146 (default) or the legacy version (version draft-ietf-tls-dtls-connection-id-05, https://tools.ietf.org/html/draft-ietf-tls-dtls-connection-id-05) is used. Set the value to 0 for the standard version, and 1 for the legacy draft version. \deprecated Support for the legacy version of the DTLS Connection ID feature is deprecated. Please switch to the standardized version defined in RFC 9146 enabled by utilizing MBEDTLS_SSL_DTLS_CONNECTION_ID without use of MBEDTLS_SSL_DTLS_CONNECTION_ID_COMPAT. Requires: MBEDTLS_SSL_DTLS_CONNECTION_ID
\def MBEDTLS_ERROR_C Enable error code to error string conversion. Module: library/error.c Caller: This module enables mbedtls_strerror().
\def MBEDTLS_PADLOCK_C Enable VIA Padlock support on x86. Module: library/padlock.c Caller: library/aes.c Requires: MBEDTLS_HAVE_ASM This modules adds support for the VIA PadLock on x86.
\def MBEDTLS_PK_WRITE_C Enable the generic public (asymmetric) key writer. Module: library/pkwrite.c Caller: library/x509write.c Requires: MBEDTLS_ASN1_WRITE_C, MBEDTLS_OID_C, MBEDTLS_PK_C Uncomment to enable generic public key write functions.
\def MBEDTLS_PKCS7_C Enable PKCS #7 core for using PKCS #7-formatted signatures. RFC Link - https://tools.ietf.org/html/rfc2315 Module: library/pkcs7.c Requires: MBEDTLS_ASN1_PARSE_C, MBEDTLS_OID_C, MBEDTLS_PK_PARSE_C, MBEDTLS_X509_CRT_PARSE_C MBEDTLS_X509_CRL_PARSE_C, MBEDTLS_BIGNUM_C, MBEDTLS_MD_C This module is required for the PKCS #7 parsing modules.
\def MBEDTLS_POLY1305_C Enable the Poly1305 MAC algorithm. Module: library/poly1305.c Caller: library/chachapoly.c
\def MBEDTLS_PSA_ITS_FILE_C Enable the emulation of the Platform Security Architecture Internal Trusted Storage (PSA ITS) over files. Module: library/psa_its_file.c Requires: MBEDTLS_FS_IO
\def MBEDTLS_SSL_TICKET_C Enable an implementation of TLS server-side callbacks for session tickets. Module: library/ssl_ticket.c Caller: Requires: (MBEDTLS_CIPHER_C || MBEDTLS_USE_PSA_CRYPTO) && (MBEDTLS_GCM_C || MBEDTLS_CCM_C || MBEDTLS_CHACHAPOLY_C)
\def MBEDTLS_VERSION_C Enable run-time version information. Module: library/version.c This module provides run-time version information.
\def MBEDTLS_X509_CSR_PARSE_C Enable X.509 Certificate Signing Request (CSR) parsing. Module: library/x509_csr.c Caller: library/x509_crt_write.c Requires: MBEDTLS_X509_USE_C This module is used for reading X.509 certificate request.
\def MBEDTLS_X509_CRT_WRITE_C Enable creating X.509 certificates. Module: library/x509_crt_write.c Requires: MBEDTLS_X509_CREATE_C This module is required for X.509 certificate creation.
\def MBEDTLS_X509_CSR_WRITE_C Enable creating X.509 Certificate Signing Requests (CSR). Module: library/x509_csr_write.c Requires: MBEDTLS_X509_CREATE_C This module is required for X.509 certificate request writing.
\name SECTION: mbed TLS feature support This section sets support for features that are or are not needed within the modules that are enabled.
Domain parameters for the 224-bit curve defined by FIPS 186-4 and SEC1.
Statistics about resource consumption related to the PSA keystore.
The compressed point format for Short Weierstrass curves (MBEDTLS_ECP_DP_SECP_XXX and MBEDTLS_ECP_DP_BP_XXX). \warning While this format is supported for all concerned curves for writing, when it comes to parsing, it is not supported for all curves. Specifically, parsing compressed points on MBEDTLS_ECP_DP_SECP224R1 and MBEDTLS_ECP_DP_SECP224K1 is not supported.
There is not enough entropy to generate random data needed for the requested action. This error indicates a failure of a hardware random generator. Application writers should note that this error can be returned not only by functions whose purpose is to generate random data, such as key, IV or nonce generation, but also by functions that execute an algorithm with a randomized result, as well as functions that use randomization of intermediate computations as a countermeasure to certain attacks. Implementations should avoid returning this error after psa_crypto_init() has succeeded. Implementations should generate sufficient entropy during initialization and subsequently use a cryptographically secure pseudorandom generator (PRNG). However implementations may return this error at any time if a policy requires the PRNG to be reseeded
An invalid key type value. Zero is not the encoding of any key type.
RSA public key. The size of an RSA key is the bit size of the modulus.
Curve25519 and Curve448. This family comprises the following Montgomery curves: - 255-bit: Bernstein et al., _Curve25519: new Diffie-Hellman speed records_, LNCS 3958, 2006. The algorithm #PSA_ALG_ECDH performs X25519 when used with this curve. - 448-bit: Hamburg, _Ed448-Goldilocks, a new elliptic curve_, NIST ECC Workshop, 2015. The algorithm #PSA_ALG_ECDH performs X448 when used with this curve.
Whether the specified algorithm is a key agreement algorithm.
Retrieve the tag length of a specified AEAD algorithm
Whether the specified algorithm is RSA PSS. This includes any of the RSA PSS algorithm variants, regardless of the constraints on salt length.
The minimum value for a key identifier chosen by the implementation.
Whether the key may be used to derive other keys or produce a password hash. This flag allows the key to be used for a key derivation operation or for a key agreement operation, if otherwise permitted by the key's type and policy. If this flag is present on all keys used in calls to psa_key_derivation_input_key() for a key derivation operation, then it permits calling psa_key_derivation_output_bytes() or psa_key_derivation_output_key() at the end of the operation.
The size of the output of psa_mac_sign_finish(), in bytes. This is also the MAC size that psa_mac_verify_finish() expects. \warning This macro may evaluate its arguments multiple times or zero times, so you should not pass arguments that contain side effects.
\def PSA_SIGNATURE_MAX_SIZE Maximum size of an asymmetric signature. This macro expands to a compile-time constant integer. This value is the maximum size of a signature in bytes.
The key share being sent to or received from the peer. The format for both input and output at this step is the same as for public keys on the group determined by the primitive (::psa_pake_primitive_t) would be. For more information on the format, consult the documentation of psa_export_public_key(). For information regarding how the group is determined, consult the documentation #PSA_PAKE_PRIMITIVE.
The certificate is signed with an unacceptable key (eg bad curve, RSA too short).
pkcs-7 OBJECT IDENTIFIER ::= { iso(1) member-body(2) us(840) rsadsi(113549) pkcs(1) 7 }
Lifetime of the key in seconds. This is also the lifetime of the tickets created under that key.
\def MBEDTLS_NO_PLATFORM_ENTROPY Do not use built-in platform entropy functions. This is useful if your platform does not support standards like the /dev/urandom or Windows CryptoAPI. Uncomment this macro to disable the built-in platform entropy functions.
\def MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_PSK_ENABLED Enable TLS 1.3 PSK key exchange mode. Comment to disable support for the PSK key exchange mode in TLS 1.3. If MBEDTLS_SSL_PROTO_TLS1_3 is not enabled, this option does not have any effect on the build.
\def MBEDTLS_THREADING_C Enable the threading abstraction layer. By default Mbed TLS assumes it is used in a non-threaded environment or that contexts are not shared between threads. If you do intend to use contexts between threads, you will need to enable this layer to prevent race conditions. See also our Knowledge Base article about threading: https://mbed-tls.readthedocs.io/en/latest/kb/development/thread-safety-and-multi-threading Module: library/threading.c This allows different threading implementations (self-implemented or provided). You will have to enable either MBEDTLS_THREADING_ALT or MBEDTLS_THREADING_PTHREAD. Enable this layer to allow use of mutexes within Mbed TLS \def MBEDTLS_TIMING_C Enable the semi-portable timing interface. Module: library/timing.c
The expected length of the salt, in bytes. This may be #MBEDTLS_RSA_SALT_LEN_ANY to accept any salt length.
The type of certificate extension callbacks. Callbacks of this type are passed to and used by the mbedtls_x509_crt_parse_der_with_ext_cb() routine when it encounters either an unsupported extension or a "certificate policies" extension containing any unsupported certificate policies. Future versions of the library may invoke the callback in other cases, if and when the need arises.
Callback type: server-side session cache getter The session cache is logically a key value store, with keys being session IDs and values being instances of mbedtls_ssl_session. This callback retrieves an entry in this key-value store.
Callback type: server-side session cache setter The session cache is logically a key value store, with keys being session IDs and values being instances of mbedtls_ssl_session. This callback sets an entry in this key-value store.
Callback type: Export key alongside random values for session identification, and PRF for implementation of TLS key exporters.
A secret for key derivation. This key type is for high-entropy secrets only. For low-entropy secrets, #PSA_KEY_TYPE_PASSWORD should be used instead. These keys can be used as the #PSA_KEY_DERIVATION_INPUT_SECRET or #PSA_KEY_DERIVATION_INPUT_PASSWORD input of key derivation algorithms. The key policy determines which key derivation algorithm the key can be used for.
Whether the specified algorithm is a symmetric cipher algorithm.
The Electronic Code Book (ECB) mode of a block cipher, with no padding. \warning ECB mode does not protect the confidentiality of the encrypted data except in extremely narrow circumstances. It is recommended that applications only use ECB if they need to construct an operating mode that the implementation does not provide. Implementations are encouraged to provide the modes that applications need in preference to supporting direct access to ECB. The underlying block cipher is determined by the key type. This symmetric cipher mode can only be used with messages whose lengths are a multiple of the block size of the chosen block cipher. ECB mode does not accept an initialization vector (IV). When using a multi-part cipher operation with this algorithm, psa_cipher_generate_iv() and psa_cipher_set_iv() must not be called.
The CBC block cipher chaining mode, with no padding. The underlying block cipher is determined by the key type. This symmetric cipher mode can only be used with messages whose lengths are whole number of blocks for the chosen block cipher.
Whether the specified algorithm is a TLS-1.2 PRF algorithm.
Whether the specified algorithm is a TLS-1.2 PSK to MS algorithm.
The maximum value for a key identifier chosen by the implementation.
The certificate is not correctly signed by the trusted CA.
pkcs OBJECT IDENTIFIER ::= { iso(1) member-body(2) us(840) rsadsi(113549) 1 }
Unique ID indicating which driver got assigned to do the operation. Since driver contexts are driver-specific, swapping drivers halfway through the operation is not supported. ID values are auto-generated in psa_crypto_driver_wrappers.h ID value zero means the context is not valid or not assigned to any driver (i.e. none of the driver contexts are active).
Merge next item into the current one? This field exists for the sake of Mbed TLS's X.509 certificate parsing code and may change in future versions of the library.
Minimum TLS version to be negotiated. It is set up in the ClientHello writing preparation stage and used throughout the ClientHello writing. Not relevant anymore as soon as the protocol version has been negotiated thus as soon as the ServerHello is received. For a fresh handshake not linked to any previous handshake, it is equal to the configured minimum minor version to be negotiated. When renegotiating or resuming a session, it is equal to the previously negotiated minor version. There is no maximum TLS version field in this handshake context. From the start of the handshake, we need to define a current protocol version for the record layer which we define as the maximum TLS version to be negotiated. The `tls_version` field of the SSL context is used to store this maximum value until it contains the actual negotiated value.
Get the unsigned 64 bits integer corresponding to eight bytes in big-endian order (MSB first).
Unavailable feature, e.g. anything other than signed data.
The type of certificate extension callbacks. Callbacks of this type are passed to and used by the mbedtls_x509_csr_parse_der_with_ext_cb() routine when it encounters either an unsupported extension. Future versions of the library may invoke the callback in other cases, if and when the need arises.
\def MBEDTLS_CIPHER_NULL_CIPHER Enable NULL cipher. Warning: Only do so when you know what you are doing. This allows for encryption or channels without any security! To enable the following ciphersuites: MBEDTLS_TLS_ECDH_ECDSA_WITH_NULL_SHA MBEDTLS_TLS_ECDH_RSA_WITH_NULL_SHA MBEDTLS_TLS_ECDHE_ECDSA_WITH_NULL_SHA MBEDTLS_TLS_ECDHE_RSA_WITH_NULL_SHA MBEDTLS_TLS_ECDHE_PSK_WITH_NULL_SHA384 MBEDTLS_TLS_ECDHE_PSK_WITH_NULL_SHA256 MBEDTLS_TLS_ECDHE_PSK_WITH_NULL_SHA MBEDTLS_TLS_DHE_PSK_WITH_NULL_SHA384 MBEDTLS_TLS_DHE_PSK_WITH_NULL_SHA256 MBEDTLS_TLS_DHE_PSK_WITH_NULL_SHA MBEDTLS_TLS_RSA_WITH_NULL_SHA256 MBEDTLS_TLS_RSA_WITH_NULL_SHA MBEDTLS_TLS_RSA_WITH_NULL_MD5 MBEDTLS_TLS_RSA_PSK_WITH_NULL_SHA384 MBEDTLS_TLS_RSA_PSK_WITH_NULL_SHA256 MBEDTLS_TLS_RSA_PSK_WITH_NULL_SHA MBEDTLS_TLS_PSK_WITH_NULL_SHA384 MBEDTLS_TLS_PSK_WITH_NULL_SHA256 MBEDTLS_TLS_PSK_WITH_NULL_SHA Uncomment this macro to enable the NULL cipher and ciphersuites \def MBEDTLS_CIPHER_PADDING_PKCS7 MBEDTLS_CIPHER_PADDING_XXX: Uncomment or comment macros to add support for specific padding modes in the cipher layer with cipher modes that support padding (e.g. CBC) If you disable all padding modes, only full blocks can be used with CBC. Enable padding modes in the cipher layer.
\def MBEDTLS_ECP_NIST_OPTIM Enable specific 'modulo p' routines for each NIST prime. Depending on the prime and architecture, makes operations 4 to 8 times faster on the corresponding curve. Comment this macro to disable NIST curves optimisation.
\def MBEDTLS_KEY_EXCHANGE_ECJPAKE_ENABLED Enable the ECJPAKE based ciphersuite modes in SSL / TLS. \warning This is currently experimental. EC J-PAKE support is based on the Thread v1.0.0 specification; incompatible changes to the specification might still happen. For this reason, this is disabled by default. Requires: MBEDTLS_ECJPAKE_C or (MBEDTLS_USE_PSA_CRYPTO and PSA_WANT_ALG_JPAKE) SHA-256 (via MBEDTLS_SHA256_C or a PSA driver) MBEDTLS_ECP_DP_SECP256R1_ENABLED \warning If SHA-256 is provided only by a PSA driver, you must call psa_crypto_init() before the first handshake (even if MBEDTLS_USE_PSA_CRYPTO is disabled). This enables the following ciphersuites (if other requisites are enabled as well): MBEDTLS_TLS_ECJPAKE_WITH_AES_128_CCM_8 \def MBEDTLS_PK_PARSE_EC_EXTENDED Enhance support for reading EC keys using variants of SEC1 not allowed by RFC 5915 and RFC 5480. Currently this means parsing the SpecifiedECDomain choice of EC parameters (only known groups are supported, not arbitrary domains, to avoid validation issues). Disable if you only need to support RFC 5915 + 5480 key formats.
\def MBEDTLS_PK_PARSE_EC_COMPRESSED Enable the support for parsing public keys of type Short Weierstrass (MBEDTLS_ECP_DP_SECP_XXX and MBEDTLS_ECP_DP_BP_XXX) which are using the compressed point format. This parsing is done through ECP module's functions.
\def MBEDTLS_SHA256_SMALLER Enable an implementation of SHA-256 that has lower ROM footprint but also lower performance. The default implementation is meant to be a reasonable compromise between performance and size. This version optimizes more aggressively for size at the expense of performance. Eg on Cortex-M4 it reduces the size of mbedtls_sha256_process() from ~2KB to ~0.5KB for a performance hit of about 30%. Uncomment to enable the smaller implementation of SHA256. \def MBEDTLS_SHA512_SMALLER Enable an implementation of SHA-512 that has lower ROM footprint but also lower performance. Uncomment to enable the smaller implementation of SHA512. \def MBEDTLS_SSL_ALL_ALERT_MESSAGES Enable sending of alert messages in case of encountered errors as per RFC. If you choose not to send the alert messages, Mbed TLS can still communicate with other servers, only debugging of failures is harder. The advantage of not sending alert messages, is that no information is given about reasons for failures thus preventing adversaries of gaining intel. Enable sending of all alert messages
\def MBEDTLS_SSL_VARIABLE_BUFFER_LENGTH When this option is enabled, the SSL buffer will be resized automatically based on the negotiated maximum fragment length in each direction. Requires: MBEDTLS_SSL_MAX_FRAGMENT_LENGTH \def MBEDTLS_TEST_CONSTANT_FLOW_MEMSAN Enable testing of the constant-flow nature of some sensitive functions with clang's MemorySanitizer. This causes some existing tests to also test this non-functional property of the code under test. This setting requires compiling with clang -fsanitize=memory. The test suites can then be run normally. \warning This macro is only used for extended testing; it is not considered part of the library's API, so it may change or disappear at any time. Uncomment to enable testing of the constant-flow nature of selected code. \def MBEDTLS_TEST_CONSTANT_FLOW_VALGRIND Enable testing of the constant-flow nature of some sensitive functions with valgrind's memcheck tool. This causes some existing tests to also test this non-functional property of the code under test. This setting requires valgrind headers for building, and is only useful for testing if the tests suites are run with valgrind's memcheck. This can be done for an individual test suite with 'valgrind ./test_suite_xxx', or when using CMake, this can be done for all test suites with 'make memcheck'. \warning This macro is only used for extended testing; it is not considered part of the library's API, so it may change or disappear at any time. Uncomment to enable testing of the constant-flow nature of selected code. \def MBEDTLS_TEST_HOOKS Enable features for invasive testing such as introspection functions and hooks for fault injection. This enables additional unit tests. Merely enabling this feature should not change the behavior of the product. It only adds new code, and new branching points where the default behavior is the same as when this feature is disabled. However, this feature increases the attack surface: there is an added risk of vulnerabilities, and more gadgets that can make exploits easier. Therefore this feature must never be enabled in production. See `docs/architecture/testing/mbed-crypto-invasive-testing.md` for more information. Uncomment to enable invasive tests. \def MBEDTLS_THREADING_ALT Provide your own alternate threading implementation. Requires: MBEDTLS_THREADING_C Uncomment this to allow your own alternate threading implementation. \def MBEDTLS_THREADING_PTHREAD Enable the pthread wrapper layer for the threading layer. Requires: MBEDTLS_THREADING_C Uncomment this to enable pthread mutexes. \def MBEDTLS_USE_PSA_CRYPTO Make the X.509 and TLS libraries use PSA for cryptographic operations as much as possible, and enable new APIs for using keys handled by PSA Crypto. \warning If you enable this option, you need to call `psa_crypto_init()` before calling any function from the SSL/TLS, X.509 or PK modules, except for the various mbedtls_xxx_init() functions which can be called at any time. Requires: MBEDTLS_PSA_CRYPTO_C. Uncomment this to enable internal use of PSA Crypto and new associated APIs. \def MBEDTLS_PSA_CRYPTO_CONFIG This setting allows support for cryptographic mechanisms through the PSA API to be configured separately from support through the mbedtls API. When this option is disabled, the PSA API exposes the cryptographic mechanisms that can be implemented on top of the `mbedtls_xxx` API configured with `MBEDTLS_XXX` symbols. When this option is enabled, the PSA API exposes the cryptographic mechanisms requested by the `PSA_WANT_XXX` symbols defined in include/psa/crypto_config.h. The corresponding `MBEDTLS_XXX` settings are automatically enabled if required (i.e. if no PSA driver provides the mechanism). You may still freely enable additional `MBEDTLS_XXX` symbols in mbedtls_config.h. If the symbol #MBEDTLS_PSA_CRYPTO_CONFIG_FILE is defined, it specifies an alternative header to include instead of include/psa/crypto_config.h. \warning This option is experimental, in that the set of `PSA_WANT_XXX` symbols is not completely finalized yet, and the configuration tooling is not ideally adapted to having two separate configuration files. Future minor releases of Mbed TLS may make minor changes to those symbols, but we will endeavor to provide a transition path. Nonetheless, this option is considered mature enough to use in production, as long as you accept that you may need to make minor changes to psa/crypto_config.h when upgrading Mbed TLS. \def MBEDTLS_VERSION_FEATURES Allow run-time checking of compile-time enabled features. Thus allowing users to check at run-time if the library is for instance compiled with threading support via mbedtls_version_check_feature(). Requires: MBEDTLS_VERSION_C Comment this to disable run-time checking and save ROM space
\def MBEDTLS_PLATFORM_MS_TIME_ALT Define platform specific function to get time since boot up in milliseconds.
\def MBEDTLS_SSL_EARLY_DATA Enable support for RFC 8446 TLS 1.3 early data. Requires: MBEDTLS_SSL_SESSION_TICKETS and either MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_PSK_ENABLED or MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_PSK_EPHEMERAL_ENABLED Comment this to disable support for early data. If MBEDTLS_SSL_PROTO_TLS1_3 is not enabled, this option does not have any effect on the build. This feature is experimental, not completed and thus not ready for production. \def MBEDTLS_SSL_MAX_EARLY_DATA_SIZE The default maximum amount of 0-RTT data. See the documentation of \c mbedtls_ssl_tls13_conf_max_early_data_size() for more information. It must be positive and smaller than UINT32_MAX. If MBEDTLS_SSL_EARLY_DATA is not defined, this default value does not have any impact on the build. This feature is experimental, not completed and thus not ready for production.
Encoding of the application role of PAKE Encodes the application's role in the algorithm is being executed. For more information see the documentation of individual \c PSA_PAKE_ROLE_XXX constants.
Encoding of the type of the PAKE's primitive. Values defined by this standard will never be in the range 0x80-0xff. Vendors who define additional types must use an encoding in this range. For more information see the documentation of individual \c PSA_PAKE_PRIMITIVE_TYPE_XXX constants.
Encoding of the family of the primitive associated with the PAKE. For more information see the documentation of individual \c PSA_PAKE_PRIMITIVE_TYPE_XXX constants.
Optional list of raw entries of Subject Alternative Names extension. These can be later parsed by mbedtls_x509_parse_subject_alt_name.
Stored data has been corrupted. This error indicates that some persistent storage has suffered corruption. It does not indicate the following situations, which have specific error codes: - A corruption of volatile memory - use #PSA_ERROR_CORRUPTION_DETECTED. - A communication error between the cryptoprocessor and its external storage - use #PSA_ERROR_COMMUNICATION_FAILURE. - When the storage is in a valid state but is full - use #PSA_ERROR_INSUFFICIENT_STORAGE. - When the storage fails for other reasons - use #PSA_ERROR_STORAGE_FAILURE. - When the stored data is not valid - use #PSA_ERROR_DATA_INVALID. When a storage failure occurs, it is no longer possible to ensure the global integrity of the keystore.
The public key type corresponding to a key pair type. You may also pass a public key type as \p type, it will be left unchanged.
Key for a cipher, AEAD or MAC algorithm based on the AES block cipher. The size of the key can be 16 bytes (AES-128), 24 bytes (AES-192) or 32 bytes (AES-256).
Key for the ChaCha20 stream cipher or the Chacha20-Poly1305 AEAD algorithm. ChaCha20 and the ChaCha20_Poly1305 construction are defined in RFC 7539.
Elliptic curve public key. The size of an elliptic curve public key is the same as the corresponding private key (see #PSA_KEY_TYPE_ECC_KEY_PAIR and the documentation of `PSA_ECC_FAMILY_xxx` curve families).
The CBC block cipher chaining mode with PKCS#7 padding. The underlying block cipher is determined by the key type. This is the padding method defined by PKCS#7 (RFC 2315) §10.3.
The Chacha20-Poly1305 AEAD algorithm. The ChaCha20_Poly1305 construction is defined in RFC 7539. Implementations must support 12-byte nonces, may support 8-byte nonces, and should reject other sizes. Implementations must support 16-byte tags and should reject other sizes.
RSA PKCS#1 v1.5 encryption. \warning Calling psa_asymmetric_decrypt() with this algorithm as a parameter is considered an inherently dangerous function (CWE-242). Unless it is used in a side channel free and safe way (eg. implementing the TLS protocol as per 7.4.7.1 of RFC 5246), the calling code is vulnerable.
The elliptic curve Diffie-Hellman (ECDH) key agreement algorithm. The shared secret produced by key agreement is the x-coordinate of the shared secret point. It is always `ceiling(m / 8)` bytes long where `m` is the bit size associated with the curve, i.e. the bit size of the order of the curve's coordinate field. When `m` is not a multiple of 8, the byte containing the most significant bit of the shared secret is padded with zero bits. The byte order is either little-endian or big-endian depending on the curve type. - For Montgomery curves (curve types `PSA_ECC_FAMILY_CURVEXXX`), the shared secret is the x-coordinate of `d_A Q_B = d_B Q_A` in little-endian byte order. The bit size is 448 for Curve448 and 255 for Curve25519. - For Weierstrass curves over prime fields (curve types `PSA_ECC_FAMILY_SECPXXX` and `PSA_ECC_FAMILY_BRAINPOOL_PXXX`), the shared secret is the x-coordinate of `d_A Q_B = d_B Q_A` in big-endian byte order. The bit size is `m = ceiling(log_2(p))` for the field `F_p`. - For Weierstrass curves over binary fields (curve types `PSA_ECC_FAMILY_SECTXXX`), the shared secret is the x-coordinate of `d_A Q_B = d_B Q_A` in big-endian byte order. The bit size is `m` for the field `F_{2^m}`.
Whether the key may be exported. A public key or the public part of a key pair may always be exported regardless of the value of this permission flag. If a key does not have export permission, implementations shall not allow the key to be exported in plain form from the cryptoprocessor, whether through psa_export_key() or through a proprietary interface. The key may however be exportable in a wrapped form, i.e. in a form where it is encrypted by another key.
The default IV size for a cipher algorithm, in bytes. The IV that is generated as part of a call to #psa_cipher_encrypt() is always the default IV length for the algorithm. This macro can be used to allocate a buffer of sufficient size to store the IV output from #psa_cipher_generate_iv() when using a multi-part cipher operation. See also #PSA_CIPHER_IV_MAX_SIZE. \warning This macro may evaluate its arguments multiple times or zero times, so you should not pass arguments that contain side effects.
The maximum IV size for all supported cipher algorithms, in bytes. See also #PSA_CIPHER_IV_LENGTH().
The minimum value for a key identifier that is built into the implementation. The range of key identifiers from #MBEDTLS_PSA_KEY_ID_BUILTIN_MIN to #MBEDTLS_PSA_KEY_ID_BUILTIN_MAX within the range from #PSA_KEY_ID_VENDOR_MIN and #PSA_KEY_ID_VENDOR_MAX and must not intersect with any other set of implementation-chosen key identifiers. This value is part of the library's API since changing it would invalidate the values of built-in key identifiers in applications.
The certificate is signed with an unacceptable PK alg (eg RSA vs ECDSA).
Full cipher identifier (as per mbedtls_cipher_type_t). For example, MBEDTLS_CIPHER_AES_256_CBC. This could be 7 bits, but 8 bits retains byte alignment for the next field, which reduces code size to access that field.
Bitflag comprised of MBEDTLS_CIPHER_VARIABLE_IV_LEN and MBEDTLS_CIPHER_VARIABLE_KEY_LEN indicating whether the cipher supports variable IV or variable key sizes, respectively.
When a ticket is created by a TLS server as part of an established TLS session, the ticket creation time may need to be saved for the ticket module to be able to check the ticket age when the ticket is used. That's the purpose of this field. Before creating a new ticket, an Mbed TLS server set this field with its current time in milliseconds. This time may then be saved in the session ticket data by the session ticket writing function and recovered by the ticket parsing function later when the ticket is used. The ticket module may then use this time to compute the ticket age and determine if it has expired or not. The Mbed TLS implementations of the session ticket writing and parsing functions save and retrieve the ticket creation time as part of the session ticket data. The session ticket parsing function relies on the mbedtls_ssl_session_get_ticket_creation_time() API to get the ticket creation time from the session ticket data.
used to check if CertificateRequest has been received from server side. If CertificateRequest has been received, Certificate and CertificateVerify should be sent to server
The certificate tag or value is invalid or cannot be parsed.
A struct containing all of the function pointers needed to implement cipher operations using secure elements. PSA Crypto API implementations should populate instances of the table as appropriate upon startup or at build time. If one of the functions is not implemented (such as `psa_drv_se_cipher_ecb_t`), it should be set to NULL.
A struct containing all of the function pointers needed to perform secure element MAC operations PSA Crypto API implementations should populate the table as appropriate upon startup. If one of the functions is not implemented (such as `psa_drv_se_mac_generate_t`), it should be set to NULL. Driver implementers should ensure that they implement all of the functions that make sense for their hardware, and that they provide a full solution (for example, if they support `p_setup`, they should also support `p_update` and at least one of `p_finish` or `p_finish_verify`).
A struct containing all of the function pointers needed to implement secure element Authenticated Encryption with Additional Data operations PSA Crypto API implementations should populate instances of the table as appropriate upon startup. If one of the functions is not implemented, it should be set to NULL.
A struct containing all of the function pointers needed to implement asymmetric cryptographic operations using secure elements. PSA Crypto API implementations should populate instances of the table as appropriate upon startup or at build time. If one of the functions is not implemented, it should be set to NULL.
A struct containing all of the function pointers needed to for secure element key derivation and agreement PSA Crypto API implementations should populate instances of the table as appropriate upon startup. If one of the functions is not implemented, it should be set to NULL.
A struct containing all of the function pointers needed to for secure element key management PSA Crypto API implementations should populate instances of the table as appropriate upon startup or at build time. If one of the functions is not implemented, it should be set to NULL.
Range of volatile key identifiers. The first #MBEDTLS_PSA_KEY_SLOT_COUNT identifiers of the implementation range of key identifiers are reserved for volatile key identifiers. If \c id is a a volatile key identifier, #PSA_KEY_ID_VOLATILE_MIN - \c id indicates the key slot containing the volatile key definition. See psa_crypto_slot_management.c for details. The minimum value for a volatile key identifier.
The maximum value for a volatile key identifier.
\def MBEDTLS_ERROR_STRERROR_DUMMY Enable a dummy error function to make use of mbedtls_strerror() in third party libraries easier when MBEDTLS_ERROR_C is disabled (no effect when MBEDTLS_ERROR_C is enabled). You can safely disable this if MBEDTLS_ERROR_C is enabled, or if you're not using mbedtls_strerror() or error_strerror() in your application. Disable if you run into name conflicts and want to really remove the mbedtls_strerror()
\def MBEDTLS_SSL_TLS1_3_COMPATIBILITY_MODE Enable TLS 1.3 middlebox compatibility mode. As specified in Section D.4 of RFC 8446, TLS 1.3 offers a compatibility mode to make a TLS 1.3 connection more likely to pass through middle boxes expecting TLS 1.2 traffic. Turning on the compatibility mode comes at the cost of a few added bytes on the wire, but it doesn't affect compatibility with TLS 1.3 implementations that don't use it. Therefore, unless transmission bandwidth is critical and you know that middlebox compatibility issues won't occur, it is therefore recommended to set this option. Comment to disable compatibility mode for TLS 1.3. If MBEDTLS_SSL_PROTO_TLS1_3 is not enabled, this option does not have any effect on the build.
\def MBEDTLS_SHA512_USE_A64_CRYPTO_IF_PRESENT Enable acceleration of the SHA-512 and SHA-384 cryptographic hash algorithms with the ARMv8 cryptographic extensions if they are available at runtime. If not, the library will fall back to the C implementation. \warning MBEDTLS_SHA512_USE_A64_CRYPTO_IF_PRESENT cannot be defined at the same time as MBEDTLS_SHA512_USE_A64_CRYPTO_ONLY. Requires: MBEDTLS_SHA512_C. Module: library/sha512.c Uncomment to have the library check for the A64 SHA-512 crypto extensions and use them if available. \def MBEDTLS_SHA512_USE_A64_CRYPTO_ONLY Enable acceleration of the SHA-512 and SHA-384 cryptographic hash algorithms with the ARMv8 cryptographic extensions, which must be available at runtime or else an illegal instruction fault will occur. \warning MBEDTLS_SHA512_USE_A64_CRYPTO_ONLY cannot be defined at the same time as MBEDTLS_SHA512_USE_A64_CRYPTO_IF_PRESENT. Requires: MBEDTLS_SHA512_C. Module: library/sha512.c Uncomment to have the library use the A64 SHA-512 crypto extensions unconditionally. \def MBEDTLS_SSL_CACHE_C Enable simple SSL cache implementation. Module: library/ssl_cache.c Caller: Requires: MBEDTLS_SSL_CACHE_C
\def MBEDTLS_AES_ROM_TABLES Store the AES tables in ROM. Uncomment this macro to store the AES tables in ROM.
\def MBEDTLS_SSL_TLS1_3_TICKET_NONCE_LENGTH Size in bytes of a ticket nonce. This is not used in TLS 1.2. This must be less than 256.
A slot number identifying a key in a driver. Values of this type are used to identify built-in keys.
Optional list of certificate policies (Only anyPolicy is printed and enforced, however the rest of the policies are still listed).
Default security profile. Should provide a good balance between security and compatibility with current deployments. This profile permits: - SHA2 hashes with at least 256 bits: SHA-256, SHA-384, SHA-512. - Elliptic curves with 255 bits and above except secp256k1. - RSA with 2048 bits and above. New minor versions of Mbed TLS may extend this profile, for example if new algorithms are added to the library. New minor versions of Mbed TLS will not reduce this profile unless serious security concerns require it.
There is not enough persistent storage. Functions that modify the key storage return this error code if there is insufficient storage space on the host media. In addition, many functions that do not otherwise access storage may return this error code if the implementation requires a mandatory log entry for
A hardware failure was detected. A hardware failure may be transient or permanent depending on the
The decrypted padding is incorrect. \warning In some protocols, when decrypting data, it is essential that the behavior of the application does not depend on whether the padding is correct, down to precise timing. Applications should prefer protocols that use authenticated encryption rather than plain encryption. If the application must perform a decryption of unauthenticated data, the application writer should take care not to reveal whether the padding is invalid. Implementations should strive to make valid and invalid padding as close as possible to indistinguishable to an external observer. In particular, the timing of a decryption operation should not
HMAC key. The key policy determines which underlying hash algorithm the key can be used for. HMAC keys should generally have the same size as the underlying hash. This size can be calculated with #PSA_HASH_LENGTH(\c alg) where
A low-entropy secret for password hashing or key derivation. This key type is suitable for passwords and passphrases which are typically intended to be memorizable by humans, and have a low entropy relative to their size. It can be used for randomly generated or derived keys with maximum or near-maximum entropy, but #PSA_KEY_TYPE_DERIVE is more suitable for such keys. It is not suitable for passwords with extremely low entropy, such as numerical PINs. These keys can be used as the #PSA_KEY_DERIVATION_INPUT_PASSWORD input of key derivation algorithms. Algorithms that accept such an input were designed to accept low-entropy secret and are known as password hashing or key stretching algorithms. These keys cannot be used as the #PSA_KEY_DERIVATION_INPUT_SECRET input of key derivation algorithms, as the algorithms that take such an input expect it to be high-entropy. The key policy determines which key derivation algorithm the key can be used for, among the permissible subset defined above.
Elliptic curve key pair. The size of an elliptic curve key is the bit size associated with the curve, i.e. the bit size of *q* for a curve over a field *Fq*. See the documentation of `PSA_ECC_FAMILY_xxx` curve families for details.
The stream cipher mode of a stream cipher algorithm. The underlying stream cipher is determined by the key type. - To use ChaCha20, use a key type of #PSA_KEY_TYPE_CHACHA20.
The CTR stream cipher mode. CTR is a stream cipher which is built from a block cipher. The underlying block cipher is determined by the key type. For example, to use AES-128-CTR, use this algorithm with a key of type #PSA_KEY_TYPE_AES and a length of 128 bits (16 bytes).
The CFB stream cipher mode. The underlying block cipher is determined by the key type.
The OFB stream cipher mode. The underlying block cipher is determined by the key type.
The XTS cipher mode. XTS is a cipher mode which is built from a block cipher. It requires at least one full block of input, but beyond this minimum the input does not need to be a whole number of blocks.
The CCM* cipher mode without authentication. This is CCM* as specified in IEEE 802.15.4 §7, with a tag length of 0. For CCM* with a nonzero tag length, use the AEAD algorithm #PSA_ALG_CCM. The underlying block cipher is determined by the key type. Currently only 13-byte long IV's are supported.
Whether the specified algorithm is a raw key agreement algorithm. A raw key agreement algorithm is one that does not specify a key derivation function. Usually, raw key agreement algorithms are constructed directly with a \c PSA_ALG_xxx macro while non-raw key agreement algorithms are constructed with #PSA_ALG_KEY_AGREEMENT().
The minimum value for a key identifier chosen by the application.
The maximum value for a key identifier chosen by the application.
Whether the key may be copied. This flag allows the use of psa_copy_key() to make a copy of the key with the same policy or a more restrictive policy. For lifetimes for which the key is located in a secure element which enforce the non-exportability of keys, copying a key outside the secure element also requires the usage flag #PSA_KEY_USAGE_EXPORT. Copying the key inside the secure element is permitted with just #PSA_KEY_USAGE_COPY if the secure element supports it. For keys with the lifetime #PSA_KEY_LIFETIME_VOLATILE or #PSA_KEY_LIFETIME_PERSISTENT, the usage flag #PSA_KEY_USAGE_COPY is sufficient to permit the copy.
Check if two AEAD algorithm identifiers refer to the same AEAD algorithm regardless of the tag length they encode.
\def PSA_MAC_MAX_SIZE Maximum size of a MAC. This macro expands to a compile-time constant integer. This value is the maximum size of a MAC in bytes.
The maximum value for a key identifier that is built into the implementation. See #MBEDTLS_PSA_KEY_ID_BUILTIN_MIN for more information.
The certificate Common Name (CN) does not match with the expected CN.
id-domainComponent AttributeType:= {itu-t(0) data(9) pss(2342) ucl(19200300) pilot(100) pilotAttributeType(1) domainComponent(25)} id-ce-authorityKeyIdentifier OBJECT IDENTIFIER ::= { id-ce 35 }
id-ce-subjectKeyIdentifier OBJECT IDENTIFIER ::= { id-ce 14 }
Encodes two booleans, one stating whether TLS 1.2 session tickets are enabled or not, the other one whether the handling of TLS 1.3 NewSessionTicket messages is enabled or not. They are respectively set by mbedtls_ssl_conf_session_tickets() and mbedtls_ssl_conf_tls13_enable_signal_new_session_tickets().
The data structure holding the cryptographic material (key and IV) used for record protection in TLS 1.3.
Put in memory a 16 bits unsigned integer in little-endian order.
The PKCS #7 version element is invalid or cannot be parsed.
Optional list of raw entries of Subject Alternative Names extension. These can be later parsed by mbedtls_x509_parse_subject_alt_name.
BASIC -> IMPORT+EXPORT (Implementation-specific, may change in the future.)
DES cipher with EDE3 ECB mode. \warning 3DES is considered weak.
DES cipher with EDE3 CBC mode. \warning 3DES is considered weak.
Aria cipher with 128-bit key and CCM_STAR_NO_TAG mode.
Aria cipher with 192-bit key and CCM_STAR_NO_TAG mode.
Aria cipher with 256-bit key and CCM_STAR_NO_TAG mode.
The type_id is an OID as defined in RFC 5280. To check the value of the type id, you should use \p MBEDTLS_OID_CMP with a known OID mbedtls_x509_buf. The type id.
The type of trusted certificate callbacks. Callbacks of this type are passed to and used by the CRT verification routine mbedtls_x509_crt_verify_with_ca_cb() when looking for trusted signers of a given certificate. On success, the callback returns a list of trusted certificates to be considered as potential signers for the input certificate.
Asking for an item that already exists Implementations should return this error, when attempting
Return this error when there's insufficient data when attempting
The function that returns this status is defined as interruptible and still has work to do, thus the user should call the function again with the same operation context until it either returns #PSA_SUCCESS or any other error. This is not an error per se, more a notification of status.
Whether a key type is an unstructured array of bytes. This encompasses both symmetric keys and non-key data.
Raw data. A "key" of this type cannot be used for any cryptographic operation.
A secret value that can be used to verify a password hash. The key policy determines which key derivation algorithm the key can be used for, among the same permissible subset as for #PSA_KEY_TYPE_PASSWORD.
Key for a cipher or MAC algorithm based on DES or 3DES (Triple-DES). The size of the key can be 64 bits (single DES), 128 bits (2-key 3DES) or 192 bits (3-key 3DES). Note that single DES and 2-key 3DES are weak and strongly deprecated and should only be used to decrypt legacy data. 3-key 3DES is weak and deprecated and should only be used in legacy protocols.
Macro to build a truncated MAC algorithm. A truncated MAC algorithm is identical to the corresponding MAC algorithm except that the MAC value for the truncated algorithm consists of only the first \p mac_length bytes of the MAC value for the untruncated algorithm.
Whether the specified algorithm is a MAC algorithm based on a block cipher.
Whether the specified algorithm is a stream cipher. A stream cipher is a symmetric cipher that encrypts or decrypts messages by applying a bitwise-xor with a stream of bytes that is generated from a key.
Whether the specified algorithm is RSA PSS with any salt.
Whether the specified algorithm is a hash-and-sign algorithm. Hash-and-sign algorithms are asymmetric (public-key) signature algorithms structured in two parts: first the calculation of a hash in a way that does not depend on the key, then the calculation of a signature from the hash value and the key. Hash-and-sign algorithms encode the hash used for the hashing step, and you can call #PSA_ALG_SIGN_GET_HASH to extract this algorithm. Thus, for a hash-and-sign algorithm, `psa_sign_message(key, alg, input, ...)` is equivalent to ``` psa_hash_compute(PSA_ALG_SIGN_GET_HASH(alg), input, ..., hash, ...); psa_sign_hash(key, alg, hash, ..., signature, ...); ``` Most usefully, separating the hash from the signature allows the hash to be calculated in multiple steps with psa_hash_setup(), psa_hash_update() and psa_hash_finish(). Likewise psa_verify_message() is equivalent to calculating the hash and then calling psa_verify_hash().
The finite-field Diffie-Hellman (DH) key agreement algorithm. The shared secret produced by key agreement is `g^{ab}` in big-endian format. It is `ceiling(m / 8)` bytes long where `m` is the size of the prime `p` in bits.
Whether the specified algorithm encoding is a wildcard. Wildcard values may only be used to set the usage algorithm field in a policy, not to perform an operation.
The default lifetime for persistent keys. A persistent key remains in storage until it is explicitly destroyed or until the corresponding storage area is wiped. This specification does not define any mechanism to wipe a storage area, but integrations may provide their own mechanism (for example to perform a factory reset, to prepare for device refurbishment, or to uninstall an application). This lifetime value is the default storage area for the calling application. Integrations of Mbed TLS may support other persistent lifetimes. See ::psa_key_lifetime_t for more information.
Whether a key lifetime indicates that the key is read-only. Read-only keys cannot be created or destroyed through the PSA Crypto API. They must be created through platform-specific means that bypass the API. Some platforms may offer ways to destroy read-only keys. For example, consider a platform with multiple levels of privilege, where a low-privilege application can use a key but is not allowed to destroy it, and the platform exposes the key to the application with a read-only lifetime. High-privilege code can destroy the key even though the application sees the key as read-only.
A low-entropy secret input for password hashing / key stretching. This is usually a key of type #PSA_KEY_TYPE_PASSWORD (passed to psa_key_derivation_input_key()) or a direct input (passed to psa_key_derivation_input_bytes()) that is a password or passphrase. It can also be high-entropy secret such as a key of type #PSA_KEY_TYPE_DERIVE or the shared secret resulting from a key agreement. The secret can also be a direct input (passed to key_derivation_input_bytes()). In this case, the derivation operation may not be used to derive keys: the operation will only allow psa_key_derivation_output_bytes(), psa_key_derivation_verify_bytes(), or psa_key_derivation_verify_key(), but not psa_key_derivation_output_key().
A high-entropy additional secret input for key derivation. This is typically the shared secret resulting from a key agreement obtained via `psa_key_derivation_key_agreement()`. It may alternatively be a key of type `PSA_KEY_TYPE_DERIVE` passed to `psa_key_derivation_input_key()`, or a direct input passed to `psa_key_derivation_input_bytes()`.
A label for key derivation. This should be a direct input. It can also be a key of type #PSA_KEY_TYPE_RAW_DATA.
A seed for key derivation. This should be a direct input. It can also be a key of type #PSA_KEY_TYPE_RAW_DATA.
The input block size of a hash algorithm, in bytes. Hash algorithms process their input data in blocks. Hash operations will retain any partial blocks until they have enough input to fill the block or until the operation is finished. This affects the output from psa_hash_suspend().
Whether the specified algorithm is a password-authenticated key exchange.
The PAKE primitive type indicating the use of elliptic curves. The values of the \c family and \c bits fields of the cipher suite identify a specific elliptic curve, using the same mapping that is used for ECC (::psa_ecc_family_t) keys. (Here \c family means the value returned by psa_pake_cs_get_family() and \c bits means the value returned by psa_pake_cs_get_bits().) Input and output during the operation can involve group elements and scalar values: -# The format for group elements is the same as for public keys on the specific curve would be. For more information, consult the documentation of psa_export_public_key(). -# The format for scalars is the same as for private keys on the specific curve would be. For more information, consult the documentation of psa_export_key().
A Schnorr NIZKP public key. This is the ephemeral public key in the Schnorr Non-Interactive Zero-Knowledge Proof (the value denoted by the letter 'V' in RFC 8235). The format for both input and output at this step is the same as for public keys on the group determined by the primitive (::psa_pake_primitive_t) would be. For more information on the format, consult the documentation of psa_export_public_key(). For information regarding how the group is determined, consult the documentation #PSA_PAKE_PRIMITIVE.
A Schnorr NIZKP proof. This is the proof in the Schnorr Non-Interactive Zero-Knowledge Proof (the value denoted by the letter 'r' in RFC 8235). Both for input and output, the value at this step is an integer less than the order of the group selected in the cipher suite. The format depends on the group as well: - For Montgomery curves, the encoding is little endian. - For everything else the encoding is big endian (see Section 2.3.8 of _SEC 1: Elliptic Curve Cryptography_ at https://www.secg.org/sec1-v2.pdf). In both cases leading zeroes are allowed as long as the length in bytes does not exceed the byte length of the group order. For information regarding how the group is determined, consult the documentation #PSA_PAKE_PRIMITIVE.
\name DER constants These constants comply with the DER encoded ASN.1 type tags. DER encoding uses hexadecimal representation. An example DER sequence is:\n - 0x02 -- tag indicating INTEGER - 0x01 -- length in octets - 0x05 -- value Such sequences are typically read into \c ::mbedtls_x509_buf.
Maximum number of intermediate CAs in a verification chain. That is, maximum length of the chain, excluding the end-entity certificate and the trusted root certificate. Set this to a low value to prevent an adversary from making you waste resources verifying an overlong certificate chain.
The CRL is signed with an unacceptable PK alg (eg RSA vs ECDSA).
Max size of verification chain: end-entity + intermediates + trusted root
\def MBEDTLS_CTR_DRBG_ENTROPY_LEN The amount of entropy used per seed by default, in bytes. This is 48 bytes because the entropy module uses SHA-512.
{ joint-iso-itu-t(2) country(16) us(840) organization(1) gov(101) csor(3) nistAlgorithm(4) Private Internet Extensions { iso(1) identified-organization(3) dod(6) internet(1) security(5) mechanisms(5) pkix(7) }
id-ce-certificatePolicies OBJECT IDENTIFIER ::= { id-ce 32 }
pkcs-5 OBJECT IDENTIFIER ::= { iso(1) member-body(2) us(840) rsadsi(113549) pkcs(1) 5 }
pkcs-9 OBJECT IDENTIFIER ::= { iso(1) member-body(2) us(840) rsadsi(113549) pkcs(1) 9 }
Largest key id value among open keys in internal persistent storage.
Largest key id value among open keys in secure elements.
Get the unsigned 16 bits integer corresponding to two bytes in little-endian order (LSB first).
Get the unsigned 64 bits integer corresponding to eight bytes in little-endian order (LSB first).
Put in memory a 64 bits unsigned integer in little-endian order.
The storage representation of a key whose data is in a secure element.
A function that exports a secure element key in binary format The output of this function can be passed to psa_import_key() to create an equivalent object. If a key is created with `psa_import_key()` and then exported with this function, it is not guaranteed that the resulting data is identical: the implementation may choose a different representation of the same key if the format permits it. This function should generate output in the same format that `psa_export_key()` does. Refer to the documentation of `psa_export_key()` for the format for each key type.
Optional Netscape certificate type extension value: See the values in x509.h
Allow library to access its structs' private members. Although structs defined in header files are publicly available, their members are private and should not be accessed by the user.
The version number x.y.z is split into three parts. Major, Minor, Patchlevel
\def MBEDTLS_SSL_TLS1_3_TICKET_AGE_TOLERANCE Maximum time difference in milliseconds tolerated between the age of a ticket from the server and client point of view. From the client point of view, the age of a ticket is the time difference between the time when the client proposes to the server to use the ticket (time of writing of the Pre-Shared Key Extension including the ticket) and the time the client received the ticket from the server. From the server point of view, the age of a ticket is the time difference between the time when the server receives a proposition from the client to use the ticket and the time when the ticket was created by the server. The server age is expected to be always greater than the client one and MBEDTLS_SSL_TLS1_3_TICKET_AGE_TOLERANCE defines the maximum difference tolerated for the server to accept the ticket. This is not used in TLS 1.2.
\def MBEDTLS_SSL_TLS1_3_DEFAULT_NEW_SESSION_TICKETS Default number of NewSessionTicket messages to be sent by a TLS 1.3 server after handshake completion. This is not used in TLS 1.2 and relevant only if the MBEDTLS_SSL_SESSION_TICKETS option is enabled.
DES cipher with EDE CBC mode. \warning 3DES is considered weak.
PK algs for public keys; this applies to all certificates in the provided chain.
Direct access to the list of CRL entry extensions (an ASN.1 constructed sequence). If there are no extensions, `entry_ext.len == 0` and `entry_ext.p == NULL`.
Expected next default profile. Recommended for new deployments. Currently targets a 128-bit security level, except for allowing RSA-2048. This profile may change at any time.
Empty profile that allows nothing. Useful as a basis for constructing custom profiles.
There was a communication failure inside the implementation. This can indicate a communication failure between the application and an external cryptoprocessor or between the cryptoprocessor and an external volatile or persistent memory. A communication failure may be transient or permanent depending on the cause. \warning If a function returns this error, it is undetermined whether the requested action has completed or not. Implementations should return #PSA_SUCCESS on successful completion whenever possible, however functions may return #PSA_ERROR_COMMUNICATION_FAILURE if the requested action was completed successfully in an external cryptoprocessor but there was a breakdown of communication before the cryptoprocessor could report the status to the application.
Whether the specified algorithm is a key derivation algorithm.
Macro to build an HMAC algorithm. For example, #PSA_ALG_HMAC(#PSA_ALG_SHA_256) is HMAC-SHA-256.
Macro to build a MAC minimum-MAC-length wildcard algorithm. A minimum-MAC-length MAC wildcard algorithm permits all MAC algorithms sharing the same base algorithm, and where the (potentially truncated) MAC length of the specific algorithm is equal to or larger then the wildcard algorithm's minimum MAC length.
Calculate the corresponding AEAD algorithm with the default tag length.
Macro to build an AEAD minimum-tag-length wildcard algorithm. A minimum-tag-length AEAD wildcard algorithm permits all AEAD algorithms sharing the same base algorithm, and where the tag length of the specific algorithm is equal to or larger then the minimum tag length specified by the wildcard algorithm.
RSA PKCS#1 v1.5 signature with hashing. This is the signature scheme defined by RFC 8017 (PKCS#1: RSA Cryptography Specifications) under the name RSASSA-PKCS1-v1_5.
Raw PKCS#1 v1.5 signature. The input to this algorithm is the DigestInfo structure used by RFC 8017 (PKCS#1: RSA Cryptography Specifications), §9.2 steps 3–6.
RSA PSS signature with hashing with relaxed verification. This algorithm has the same behavior as #PSA_ALG_RSA_PSS when signing, but allows an arbitrary salt length (including \c 0) when verifying a signature.
Whether the specified algorithm is RSA PSS with standard salt.
Deterministic ECDSA signature with hashing. This is the deterministic ECDSA signature scheme defined by RFC 6979. The representation of a signature is the same as with #PSA_ALG_ECDSA(). Note that when this algorithm is used for verification, signatures made with randomized ECDSA (#PSA_ALG_ECDSA(\p hash_alg)) with the same private key are accepted. In other words, #PSA_ALG_DETERMINISTIC_ECDSA(\p hash_alg) differs from #PSA_ALG_ECDSA(\p hash_alg) only for signature, not for verification.
Edwards-curve digital signature algorithm without prehashing (PureEdDSA), using standard parameters. Contexts are not supported in the current version of this specification because there is no suitable signature interface that can take the context as a parameter. A future version of this specification may add suitable functions and extend this algorithm to support contexts. PureEdDSA requires an elliptic curve key on a twisted Edwards curve. In this specification, the following curves are supported: - #PSA_ECC_FAMILY_TWISTED_EDWARDS, 255-bit: Ed25519 as specified in RFC 8032. The curve is Edwards25519. The hash function used internally is SHA-512. - #PSA_ECC_FAMILY_TWISTED_EDWARDS, 448-bit: Ed448 as specified in RFC 8032. The curve is Edwards448. The hash function used internally is the first 114 bytes of the SHAKE256 output. This algorithm can be used with psa_sign_message() and psa_verify_message(). Since there is no prehashing, it cannot be used with psa_sign_hash() or psa_verify_hash(). The signature format is the concatenation of R and S as defined by RFC 8032 §5.1.6 and §5.2.6 (a 64-byte string for Ed25519, a 114-byte string for Ed448).
Whether the specified algorithm is a signature algorithm that can be used with psa_sign_message() and psa_verify_message().
RSA OAEP encryption. This is the encryption scheme defined by RFC 8017 (PKCS#1: RSA Cryptography Specifications) under the name RSAES-OAEP, with the message generation function MGF1.
Whether the specified algorithm is an elliptic curve Diffie-Hellman algorithm. This includes the raw elliptic curve Diffie-Hellman algorithm as well as elliptic curve Diffie-Hellman followed by any supporter key derivation algorithm.
The default lifetime for volatile keys. A volatile key only exists as long as the identifier to it is not destroyed. The key material is guaranteed to be erased on a power reset. A key with this lifetime is typically stored in the RAM area of the PSA Crypto subsystem. However this is an implementation choice. If an implementation stores data about the key in a non-volatile memory, it must release all the resources associated with the key and erase the key material if the calling application terminates.
The persistence level of volatile keys. See ::psa_key_persistence_t for more information.
A persistence level indicating that a key is never destroyed. See ::psa_key_persistence_t for more information.
Construct a lifetime from a persistence level and a location.
Whether the key may be used to verify the result of a key derivation, including password hashing. This flag allows the key to be used: This flag allows the key to be used in a key derivation operation, if otherwise permitted by the key's type and policy. If this flag is present on all keys used in calls to psa_key_derivation_input_key() for a key derivation operation, then it permits calling psa_key_derivation_verify_bytes() or psa_key_derivation_verify_key() at the end of the operation.
A salt for key derivation. This should be a direct input. It can also be a key of type #PSA_KEY_TYPE_RAW_DATA or #PSA_KEY_TYPE_PEPPER.
An information string for key derivation. This should be a direct input. It can also be a key of type #PSA_KEY_TYPE_RAW_DATA.
Maximum value for use with \c psa_interruptible_set_max_ops() to determine the maximum number of ops allowed to be executed by an interruptible function in a single call.
The maximum tag size for all supported AEAD algorithms, in bytes. See also #PSA_AEAD_TAG_LENGTH(\p key_type, \p key_bits, \p alg).
This macro returns the maximum supported length of the PSK for the TLS-1.2 PSK-to-MS key derivation (#PSA_ALG_TLS12_PSK_TO_MS(\c hash_alg)). The maximum supported length does not depend on the chosen hash algorithm. Quoting RFC 4279, Sect 5.3: TLS implementations supporting these ciphersuites MUST support arbitrary PSK identities up to 128 octets in length, and arbitrary PSKs up to 64 octets in length. Supporting longer identities and keys is RECOMMENDED. Therefore, no implementation should define a value smaller than 64 for #PSA_TLS12_PSK_TO_MS_PSK_MAX_SIZE.
The default nonce size for an AEAD algorithm, in bytes. This macro can be used to allocate a buffer of sufficient size to store the nonce output from #psa_aead_generate_nonce(). See also #PSA_AEAD_NONCE_MAX_SIZE. \warning This macro may evaluate its arguments multiple times or zero times, so you should not pass arguments that contain side effects.
The maximum default nonce size among all supported pairs of key types and AEAD algorithms, in bytes. This is equal to or greater than any value that #PSA_AEAD_NONCE_LENGTH() may return.
Sufficient output buffer size for psa_export_key() or psa_export_public_key(). This macro returns a compile-time constant if its arguments are compile-time constants. \warning This macro may evaluate its arguments multiple times or zero times, so you should not pass arguments that contain side effects. The following code illustrates how to allocate enough memory to export a key by querying the key type and size at runtime.
{c}
psa_key_attributes_t attributes = PSA_KEY_ATTRIBUTES_INIT;
psa_status_t status;
status = psa_get_key_attributes(key, &attributes);
if (status != PSA_SUCCESS) handle_error(...);
psa_key_type_t key_type = psa_get_key_type(&attributes);
size_t key_bits = psa_get_key_bits(&attributes);
size_t buffer_size = PSA_EXPORT_KEY_OUTPUT_SIZE(key_type, key_bits);
psa_reset_key_attributes(&attributes);
uint8_t *buffer = malloc(buffer_size);
if (buffer == NULL) handle_error(...);
size_t buffer_length;
status = psa_export_key(key, buffer, buffer_size, &buffer_length);
if (status != PSA_SUCCESS) handle_error(...);
Sufficient output buffer size for psa_raw_key_agreement(). This macro returns a compile-time constant if its arguments are compile-time constants. \warning This macro may evaluate its arguments multiple times or zero times, so you should not pass arguments that contain side effects. See also #PSA_RAW_KEY_AGREEMENT_OUTPUT_MAX_SIZE.
The default production parameters for key generation or key derivation. Calling psa_generate_key_custom() or psa_key_derivation_output_key_custom() with `custom=PSA_CUSTOM_KEY_PARAMETERS_INIT` and `custom_data_length=0` is equivalent to calling psa_generate_key() or psa_key_derivation_output_key() respectively.
DSA public key. The import and export format is the representation of the public key `y = g^x mod p` as a big-endian byte string. The length of the byte string is the length of the base prime `p` in bytes.
DSA key pair (private and public key). The import and export format is the representation of the private key `x` as a big-endian byte string. The length of the byte string is the private key size in bytes (leading zeroes are not stripped). Deterministic DSA key derivation with psa_generate_derived_key follows FIPS 186-4 §B.1.2: interpret the byte string as integer in big-endian order. Discard it if it is not in the range [0, *N* - 2] where *N* is the boundary of the private key domain (the prime *p* for Diffie-Hellman, the subprime *q* for DSA, or the order of the curve's base point for ECC). Add 1 to the resulting integer and use this as the private key *x*.
A value to indicate no role in a PAKE algorithm. This value can be used in a call to psa_pake_set_role() for symmetric PAKE algorithms which do not assign roles.
A sufficient input buffer size for psa_pake_input(). The value returned by this macro is guaranteed to be large enough for any valid input to psa_pake_input() in an operation with the specified parameters. See also #PSA_PAKE_INPUT_MAX_SIZE
Returns a suitable initializer for a PAKE cipher suite object of type psa_pake_cipher_suite_t.
The CRL is signed with an unacceptable key (eg bad curve, RSA too short).
Early data has been received as part of an on-going handshake. This error code can be returned only on server side if and only if early data has been enabled by means of the mbedtls_ssl_conf_early_data() API. This error code can then be returned by mbedtls_ssl_handshake(), mbedtls_ssl_handshake_step(), mbedtls_ssl_read() or mbedtls_ssl_write() if early data has been received as part of the handshake sequence they triggered. To read the early data, call mbedtls_ssl_read_early_data().
Maximum size in bytes of a protocol name in alpn ext., RFC 7301
The default length of the nonce read from the entropy source. This is \c 0 because a single read from the entropy source is sufficient to include a nonce. See the documentation of mbedtls_ctr_drbg_seed() for more information.
anyExtendedKeyUsage OBJECT IDENTIFIER ::= { id-ce-extKeyUsage 0 }
Wi-SUN Alliance Field Area Network { iso(1) identified-organization(3) dod(6) internet(1) private(4) enterprise(1) WiSUN(45605) FieldAreaNetwork(1) }
pkcs-12 OBJECT IDENTIFIER ::= { iso(1) member-body(2) us(840) rsadsi(113549) pkcs(1) 12 }
id-mbedtls_md5 OBJECT IDENTIFIER ::= { iso(1) member-body(2) us(840) rsadsi(113549) digestAlgorithm(2) 5 }
id-sha224 OBJECT IDENTIFIER ::= { joint-iso-itu-t(2) country(16) us(840) organization(1) gov(101) csor(3) nistalgorithm(4) hashalgs(2) 4 }
id-mbedtls_sha256 OBJECT IDENTIFIER ::= { joint-iso-itu-t(2) country(16) us(840) organization(1) gov(101) csor(3) nistalgorithm(4) hashalgs(2) 1 }
id-sha384 OBJECT IDENTIFIER ::= { joint-iso-itu-t(2) country(16) us(840) organization(1) gov(101) csor(3) nistalgorithm(4) hashalgs(2) 2 }
id-mbedtls_sha512 OBJECT IDENTIFIER ::= { joint-iso-itu-t(2) country(16) us(840) organization(1) gov(101) csor(3) nistalgorithm(4) hashalgs(2) 3 }
id-hmacWithSHA1 OBJECT IDENTIFIER ::= { iso(1) member-body(2) us(840) rsadsi(113549) digestAlgorithm(2) 7 }
id-hmacWithSHA224 OBJECT IDENTIFIER ::= { iso(1) member-body(2) us(840) rsadsi(113549) digestAlgorithm(2) 8 }
id-hmacWithSHA256 OBJECT IDENTIFIER ::= { iso(1) member-body(2) us(840) rsadsi(113549) digestAlgorithm(2) 9 }
id-hmacWithSHA384 OBJECT IDENTIFIER ::= { iso(1) member-body(2) us(840) rsadsi(113549) digestAlgorithm(2) 10 }
id-hmacWithSHA512 OBJECT IDENTIFIER ::= { iso(1) member-body(2) us(840) rsadsi(113549) digestAlgorithm(2) 11 }
des-ede3-cbc OBJECT IDENTIFIER ::= { iso(1) member-body(2) -- us(840) rsadsi(113549) encryptionAlgorithm(3) 7 }
id-aes256-wrap-pad OBJECT IDENTIFIER ::= { aes 48 } id-PBKDF2 OBJECT IDENTIFIER ::= {pkcs-5 12}
Content type is Signed Data OBJECT IDENTIFIER ::= {pkcs-7 2}
Content type is Enveloped Data OBJECT IDENTIFIER ::= {pkcs-7 3}
Content type is Signed and Enveloped Data OBJECT IDENTIFIER ::= {pkcs-7 4}
Content type is Digested Data OBJECT IDENTIFIER ::= {pkcs-7 5}
Content type is Encrypted Data OBJECT IDENTIFIER ::= {pkcs-7 6}
pbeWithSHAAnd3-KeyTripleDES-CBC OBJECT IDENTIFIER ::= {pkcs-12PbeIds 3}
pbeWithSHAAnd2-KeyTripleDES-CBC OBJECT IDENTIFIER ::= {pkcs-12PbeIds 4}
Number of slots containing key material for a key which is in internal persistent storage.
Number of slots containing a reference to a key in a secure element.
\def ARRAY_LENGTH Return the number of elements of a static or stack array.
\file entropy_poll.h Platform-specific and custom entropy polling functions
Functions above this separator are part of MBEDTLS_MD_LIGHT, * functions below are only available when MBEDTLS_MD_C is set. *
A function that continues a previously started secure element cipher operation
A function that completes a previously started secure element cipher operation
A function that aborts a previously started secure element cipher operation
A function that performs the ECB block mode for secure element cipher operations Note: this function should only be used with implementations that do not provide a needed higher-level operation.
A function that signs a hash or short message with a private key in a secure element
A function that starts a secure element MAC operation for a PSA Crypto Driver implementation
A function that continues a previously started secure element MAC operation
a function that completes a previously started secure element MAC operation by returning the resulting MAC.
A function that completes a previously started secure element MAC operation by comparing the resulting MAC against a provided value
A function that aborts a previous started secure element MAC operation
A function that performs a secure element MAC operation in one command and returns the calculated MAC
A function that performs a secure element MAC operation in one command and compares the resulting MAC against a provided value
A function that provides the cipher setup function for a secure element driver
A function that sets the initialization vector (if necessary) for a secure element cipher operation Rationale: The `psa_se_cipher_*` operation in the PSA Cryptographic API has two IV functions: one to set the IV, and one to generate it internally. The generate function is not necessary for the drivers to implement as the PSA Crypto implementation can do the generation using its RNG features.
A function that performs a secure element authenticated decryption operation
A function that allocates a slot for a key. To create a key in a specific slot in a secure element, the core first calls this function to determine a valid slot number, then calls a function to create the key material in that slot. In nominal conditions (that is, if no error occurs), the effect of a call to a key creation function in the PSA Cryptography API with a lifetime that places the key in a secure element is the following: -# The core calls psa_drv_se_key_management_t::p_allocate (or in some implementations psa_drv_se_key_management_t::p_validate_slot_number). The driver selects (or validates) a suitable slot number given the key attributes and the state of the secure element. -# The core calls a key creation function in the driver. The key creation functions in the PSA Cryptography API are: - psa_import_key(), which causes a call to `p_allocate` with \p method = #PSA_KEY_CREATION_IMPORT then a call to psa_drv_se_key_management_t::p_import. - psa_generate_key(), which causes a call to `p_allocate` with \p method = #PSA_KEY_CREATION_GENERATE then a call to psa_drv_se_key_management_t::p_import. - psa_key_derivation_output_key(), which causes a call to `p_allocate` with \p method = #PSA_KEY_CREATION_DERIVE then a call to psa_drv_se_key_derivation_t::p_derive. - psa_copy_key(), which causes a call to `p_allocate` with \p method = #PSA_KEY_CREATION_COPY then a call to psa_drv_se_key_management_t::p_export. In case of errors, other behaviors are possible. - If the PSA Cryptography subsystem dies after the first step, for example because the device has lost power abruptly, the second step may never happen, or may happen after a reset and re-initialization. Alternatively, after a reset and re-initialization, the core may call psa_drv_se_key_management_t::p_destroy on the slot number that was allocated (or validated) instead of calling a key creation function. - If an error occurs, the core may call psa_drv_se_key_management_t::p_destroy on the slot number that was allocated (or validated) instead of calling a key creation function. Errors and system resets also have an impact on the driver's persistent data. If a reset happens before the overall key creation process is completed (before or after the second step above), it is unspecified whether the persistent data after the reset is identical to what it was before or after the call to `p_allocate` (or `p_validate_slot_number`).
A function that determines whether a slot number is valid for a key. To create a key in a specific slot in a secure element, the core first calls this function to validate the choice of slot number, then calls a function to create the key material in that slot. See the documentation of #psa_drv_se_allocate_key_t for more details. As of the PSA Cryptography API specification version 1.0, there is no way for applications to trigger a call to this function. However some implementations offer the capability to create or declare a key in a specific slot via implementation-specific means, generally for the sake of initial device provisioning or onboarding. Such a mechanism may be added to a future version of the PSA Cryptography API specification. This function may update the driver's persistent data through \p persistent_data. The core will save the updated persistent data at the end of the key creation process. See the description of ::psa_drv_se_allocate_key_t for more information.
A function that imports a key into a secure element in binary format This function can support any output from psa_export_key(). Refer to the documentation of psa_export_key() for the format for each key type.
A function that destroys a secure element key and restore the slot to its default state This function destroys the content of the key from a secure element. Implementations shall make a best effort to ensure that any previous content of the slot is unrecoverable. This function returns the specified slot to its default state.
A function that verifies the signature a hash or short message using an asymmetric public key in a secure element
A function that encrypts a short message with an asymmetric public key in a secure element
A function that decrypts a short message with an asymmetric private key in a secure element.
A function that performs a secure element authenticated encryption operation
A function that generates a symmetric or asymmetric key on a secure element If the key type \c type recorded in \p attributes is asymmetric (#PSA_KEY_TYPE_IS_ASYMMETRIC(\c type) = 1), the driver may export the public key at the time of generation, in the format documented for psa_export_public_key() by writing it to the \p pubkey buffer. This is optional, intended for secure elements that output the public key at generation time and that cannot export the public key later. Drivers that do not need this feature should leave \p *pubkey_length set to 0 and should implement the psa_drv_key_management_t::p_export_public function. Some implementations do not support this feature, in which case \p pubkey is \c NULL and \p pubkey_size is 0.
A function that Sets up a secure element key derivation operation by specifying the algorithm and the source key sot
A function that provides collateral (parameters) needed for a secure element key derivation or key agreement operation Since many key derivation algorithms require multiple parameters, it is expected that this function may be called multiple times for the same operation, each with a different algorithm-specific `collateral_id`
A function that performs the final secure element key derivation step and place the generated key material in a slot
A function that performs the final step of a secure element key agreement and place the generated key material in a buffer
RFC 3526, RFC 5114 and RFC 7919 standardize a number of Diffie-Hellman groups, some of which are included here for use within the SSL/TLS module and the user's convenience when configuring the Diffie-Hellman parameters by hand through \c mbedtls_ssl_conf_dh_param. The following lists the source of the above groups in the standards: - RFC 5114 section 2.2: 2048-bit MODP Group with 224-bit Prime Order Subgroup - RFC 3526 section 3: 2048-bit MODP Group - RFC 3526 section 4: 3072-bit MODP Group - RFC 3526 section 5: 4096-bit MODP Group - RFC 7919 section A.1: ffdhe2048 - RFC 7919 section A.2: ffdhe3072 - RFC 7919 section A.3: ffdhe4096 - RFC 7919 section A.4: ffdhe6144 - RFC 7919 section A.5: ffdhe8192 The constants with suffix "_p" denote the chosen prime moduli, while the constants with suffix "_g" denote the chosen generator of the associated prime field. The constants further suffixed with "_bin" are provided in binary format, while all other constants represent null-terminated strings holding the hexadecimal presentation of the respective numbers. The primes from RFC 3526 and RFC 7919 have been generating by the following trust-worthy procedure: - Fix N in { 2048, 3072, 4096, 6144, 8192 } and consider the N-bit number the first and last 64 bits are all 1, and the remaining N - 128 bits of which are 0x7ff...ff. - Add the smallest multiple of the first N - 129 bits of the binary expansion of pi (for RFC 5236) or e (for RFC 7919) to this intermediate bit-string such that the resulting integer is a safe-prime. - The result is the respective RFC 3526 / 7919 prime, and the corresponding generator is always chosen to be 2 (which is a square for these prime, hence the corresponding subgroup has order (p-1)/2 and avoids leaking a bit in the private exponent).
Default expiration delay of DTLS cookies, in seconds if HAVE_TIME, or in number of cookies issued
\def MBEDTLS_SSL_EXPORT_KEYS Enable support for exporting key block and master secret. This is required for certain users of TLS, e.g. EAP-TLS. Comment this macro to disable support for key export
\file sha256.h This file contains SHA-224 and SHA-256 definitions and functions. The Secure Hash Algorithms 224 and 256 (SHA-224 and SHA-256) cryptographic hash functions are defined in FIPS 180-4: Secure Hash Standard (SHS).
\file private_access.h Macro wrapper for struct's members.
\file mbedtls/build_info.h Build-time configuration info Include this file if you need to depend on the configuration options defined in mbedtls_config.h or MBEDTLS_CONFIG_FILE
Default mbedTLS configuration options for ESP-IDF This set of compile-time options may be used to enable or disable features selectively, and reduce the global memory footprint.
\def MBEDTLS_SSL_FALLBACK_SCSV Enable support for RFC 7507: Fallback Signaling Cipher Suite Value (SCSV) for Preventing Protocol Downgrade Attacks. For servers, it is recommended to always enable this, unless you support only one version of TLS, or know for sure that none of your clients implements a fallback strategy. For clients, you only need this if you're using a fallback strategy, which is not recommended in the first place, unless you absolutely need it to interoperate with buggy (version-intolerant) servers. Comment this macro to disable support for FALLBACK_SCSV
\def MBEDTLS_CERTS_C Enable the test certificates. Module: library/certs.c Caller: This module is used for testing (ssl_client/server).
Allow SHA-1 in the default TLS configuration for TLS 1.2 handshake signature and ciphersuite selection. Without this build-time option, SHA-1 support must be activated explicitly through mbedtls_ssl_conf_sig_hashes. The use of SHA-1 in TLS <= 1.1 and in HMAC-SHA-1 is always allowed by default. At the time of writing, there is no practical attack on the use of SHA-1 in handshake signatures, hence this option is turned on by default for compatibility with existing peers. \warning SHA-1 is considered a weak message digest and its use constitutes a security risk. If possible, we recommend avoiding dependencies on it, and considering stronger message digests instead.
\file mbedtls/config_psa.h PSA crypto configuration options (set of defines) This set of compile-time options takes settings defined in include/mbedtls/mbedtls_config.h and include/psa/crypto_config.h and uses those definitions to define symbols used in the library code. Users and integrators should not edit this file, please edit include/mbedtls/mbedtls_config.h for MBEDTLS_XXX settings or include/psa/crypto_config.h for PSA_WANT_XXX settings.
\file psa/crypto_legacy.h Add temporary suppport for deprecated symbols before they are removed from the library. PSA_WANT_KEY_TYPE_xxx_KEY_PAIR and MBEDTLS_PSA_ACCEL_KEY_TYPE_xxx_KEY_PAIR symbols are deprecated. New symols add a suffix to that base name in order to clearly state what is the expected use for the key (use, import, export, generate, derive). Here we define some backward compatibility support for uses stil using the legacy symbols.
\file psa/crypto_adjust_config_synonyms.h Adjust PSA configuration: enable quasi-synonyms This is an internal header. Do not include it directly. When two features require almost the same code, we automatically enable both when either one is requested, to reduce the combinatorics of possible configurations.
\file psa/crypto_adjust_config_dependencies.h Adjust PSA configuration by resolving some dependencies. This is an internal header. Do not include it directly. See docs/proposed/psa-conditional-inclusion-c.md. If the Mbed TLS implementation of a cryptographic mechanism A depends on a cryptographic mechanism B then if the cryptographic mechanism A is enabled and not accelerated enable B. Note that if A is enabled and accelerated, it is not necessary to enable B for A support.
\file mbedtls/config_adjust_psa_superset_legacy.h Adjust PSA configuration: automatic enablement from legacy This is an internal header. Do not include it directly. To simplify some edge cases, we automatically enable certain cryptographic mechanisms in the PSA API if they are enabled in the legacy API. The general idea is that if legacy module M uses mechanism A internally, and A has both a legacy and a PSA implementation, we enable A through PSA whenever it's enabled through legacy. This facilitates the transition to PSA implementations of A for users of M.
\file mbedtls/config_adjust_psa_from_legacy.h Adjust PSA configuration: construct PSA configuration from legacy This is an internal header. Do not include it directly. When MBEDTLS_PSA_CRYPTO_CONFIG is disabled, we automatically enable cryptographic mechanisms through the PSA interface when the corresponding legacy mechanism is enabled. In many cases, this just enables the PSA wrapper code around the legacy implementation, but we also do this for some mechanisms where PSA has its own independent implementation so that high-level modules that can use either cryptographic API have the same feature set in both cases.
\file psa/crypto_adjust_config_key_pair_types.h Adjust PSA configuration for key pair types. This is an internal header. Do not include it directly. See docs/proposed/psa-conditional-inclusion-c.md. - Support non-basic operations in a keypair type implicitly enables basic support for that keypair type. - Support for a keypair type implicitly enables the corresponding public key type. - Basic support for a keypair type implicilty enables import/export support for that keypair type. Warning: this is implementation-specific (mainly for the benefit of testing) and may change in the future!
\file psa/crypto_adjust_auto_enabled.h Adjust PSA configuration: enable always-on features This is an internal header. Do not include it directly. Always enable certain features which require a negligible amount of code to implement, to avoid some edge cases in the configuration combinatorics.
\file mbedtls/config_adjust_legacy_crypto.h Adjust legacy configuration configuration This is an internal header. Do not include it directly. Automatically enable certain dependencies. Generally, MBEDTLS_xxx configurations need to be explicitly enabled by the user: enabling MBEDTLS_xxx_A but not MBEDTLS_xxx_B when A requires B results in a compilation error. However, we do automatically enable certain options in some circumstances. One case is if MBEDTLS_xxx_B is an internal option used to identify parts of a module that are used by other module, and we don't want to make the symbol MBEDTLS_xxx_B part of the public API. Another case is if A didn't depend on B in earlier versions, and we want to use B in A but we need to preserve backward compatibility with configurations that explicitly activate MBEDTLS_xxx_A but not MBEDTLS_xxx_B.
\file mbedtls/config_adjust_x509.h Adjust X.509 configuration This is an internal header. Do not include it directly. Automatically enable certain dependencies. Generally, MBEDTLS_xxx configurations need to be explicitly enabled by the user: enabling MBEDTLS_xxx_A but not MBEDTLS_xxx_B when A requires B results in a compilation error. However, we do automatically enable certain options in some circumstances. One case is if MBEDTLS_xxx_B is an internal option used to identify parts of a module that are used by other module, and we don't want to make the symbol MBEDTLS_xxx_B part of the public API. Another case is if A didn't depend on B in earlier versions, and we want to use B in A but we need to preserve backward compatibility with configurations that explicitly activate MBEDTLS_xxx_A but not MBEDTLS_xxx_B.
\file mbedtls/config_adjust_ssl.h Adjust TLS configuration This is an internal header. Do not include it directly. Automatically enable certain dependencies. Generally, MBEDTLS_xxx configurations need to be explicitly enabled by the user: enabling MBEDTLS_xxx_A but not MBEDTLS_xxx_B when A requires B results in a compilation error. However, we do automatically enable certain options in some circumstances. One case is if MBEDTLS_xxx_B is an internal option used to identify parts of a module that are used by other module, and we don't want to make the symbol MBEDTLS_xxx_B part of the public API. Another case is if A didn't depend on B in earlier versions, and we want to use B in A but we need to preserve backward compatibility with configurations that explicitly activate MBEDTLS_xxx_A but not MBEDTLS_xxx_B.
\file check_config.h Consistency checks for configuration options This is an internal header. Do not include it directly. This header is included automatically by all public Mbed TLS headers (via mbedtls/build_info.h). Do not include it directly in a configuration file such as mbedtls/mbedtls_config.h or #MBEDTLS_USER_CONFIG_FILE! It would run at the wrong time due to missing derived symbols.
The type of PSA Diffie-Hellman group family identifiers. Values of this type are generally constructed by macros called `PSA_DH_FAMILY_xxx`. The group identifier is required to create a Diffie-Hellman key using the PSA_KEY_TYPE_DH_KEY_PAIR() or PSA_KEY_TYPE_DH_PUBLIC_KEY() macros. Values defined by this standard will never be in the range 0x80-0xff. Vendors who define additional families must use an encoding in this range.
DES cipher with EDE ECB mode. \warning 3DES is considered weak.
Camellia cipher with 128-bit CCM_STAR_NO_TAG mode.
Camellia cipher with 192-bit CCM_STAR_NO_TAG mode.
Camellia cipher with 256-bit CCM_STAR_NO_TAG mode.
Key length, in bits (including parity), for DES keys. \warning DES is considered weak.
Key length in bits, including parity, for DES in two-key EDE. \warning 3DES is considered weak.
Key length in bits, including parity, for DES in three-key EDE. \warning 3DES is considered weak.
\file platform_util.h Common and shared functions used by multiple modules in the Mbed TLS library.
Benign-failure function This macro appearing at the beginning of the declaration of a function indicates that it is rarely useful to check its return value. This macro has an empty expansion. It exists for documentation purposes: a #MBEDTLS_CHECK_RETURN_OPTIONAL annotation indicates that the function has been analyzed for return-check usefulness, whereas the lack of an annotation indicates that the function has not been analyzed and its return-check usefulness is unknown.
\def MBEDTLS_IGNORE_RETURN Call this macro with one argument, a function call, to suppress a warning from #MBEDTLS_CHECK_RETURN due to that function call.
\file ecp.h This file provides an API for Elliptic Curves over GF(P) (ECP). The use of ECP in cryptography and TLS is defined in Standards for Efficient Cryptography Group (SECG): SEC1 Elliptic Curve Cryptography and RFC-4492: Elliptic Curve Cryptography (ECC) Cipher Suites for Transport Layer Security (TLS). RFC-2409: The Internet Key Exchange (IKE) defines ECP group types.
\file ssl_ciphersuites.h SSL Ciphersuites for Mbed TLS
\file md.h This file contains the generic functions for message-digest (hashing) and HMAC. \author Adriaan de Jong <dejong@fox-it.com>
\file rsa.h This file provides an API for the RSA public-key cryptosystem. The RSA public-key cryptosystem is defined in Public-Key Cryptography Standards (PKCS) #1 v1.5: RSA Encryption and Public-Key Cryptography Standards (PKCS) #1 v2.1: RSA Cryptography Specifications.
\file ecdsa.h This file contains ECDSA definitions and functions. The Elliptic Curve Digital Signature Algorithm (ECDSA) is defined in Standards for Efficient Cryptography Group (SECG): SEC1 Elliptic Curve Cryptography. The use of ECDSA for TLS is defined in RFC-4492: Elliptic Curve Cryptography (ECC) Cipher Suites for Transport Layer Security (TLS).
\file psa/crypto_platform.h PSA cryptography module: Mbed TLS platform definitions This file contains platform-dependent type definitions. In implementations with isolation between the application and the cryptography module, implementers should take care to ensure that the definitions that are exposed to applications match what the module implements.
\file psa/build_info.h Build-time PSA configuration info Include this file if you need to depend on the configuration options defined in mbedtls_config.h or MBEDTLS_CONFIG_FILE in PSA cryptography core specific files.
\file psa/crypto_types.h PSA cryptography module: type aliases. This file contains portable definitions of integral types for properties of cryptographic keys, designations of cryptographic algorithms, and error codes returned by the library. This header file does not declare any function.
The major version of this implementation of the PSA Crypto API
The minor version of this implementation of the PSA Crypto API
\file psa/crypto_values.h PSA cryptography module: macros to build and analyze integer values. This file contains portable definitions of macros to build and analyze values of integral types that encode properties of cryptographic keys, designations of cryptographic algorithms, and error codes returned by the library. Note that many of the constants defined in this file are embedded in the persistent key store, as part of key metadata (including usage policies). As a consequence, they must not be changed (unless the storage format version changes). This header file only defines preprocessor macros.
This can be returned if a function can no longer operate correctly. For example, if an essential initialization operation failed or
Vendor-defined key type flag. Key types defined by this standard will never have the #PSA_KEY_TYPE_VENDOR_FLAG bit set. Vendors who define additional key types must use an encoding with the #PSA_KEY_TYPE_VENDOR_FLAG bit set and should respect the bitwise structure used by standard encodings whenever practical.
Whether a key type is vendor-defined. See also #PSA_KEY_TYPE_VENDOR_FLAG.
The key pair type corresponding to a public key type. You may also pass a key pair type as \p type, it will be left unchanged.
A secret value that can be used in when computing a password hash. The key policy determines which key derivation algorithm the key can be used for, among the subset of algorithms that can use pepper.
SEC Koblitz curves over binary fields. This family comprises the following curves: sect163k1, sect233k1, sect239k1, sect283k1, sect409k1, sect571k1. They are defined in _Standards for Efficient Cryptography_, _SEC 2: Recommended Elliptic Curve Domain Parameters_. https://www.secg.org/sec2-v2.pdf
SEC random curves over binary fields. This family comprises the following curves: sect163r1, sect233r1, sect283r1, sect409r1, sect571r1. They are defined in _Standards for Efficient Cryptography_, _SEC 2: Recommended Elliptic Curve Domain Parameters_. https://www.secg.org/sec2-v2.pdf
SEC additional random curves over binary fields. This family comprises the following curve: sect163r2. It is defined in _Standards for Efficient Cryptography_, _SEC 2: Recommended Elliptic Curve Domain Parameters_. https://www.secg.org/sec2-v2.pdf
The twisted Edwards curves Ed25519 and Ed448. These curves are suitable for EdDSA (#PSA_ALG_PURE_EDDSA for both curves, #PSA_ALG_ED25519PH for the 255-bit curve, #PSA_ALG_ED448PH for the 448-bit curve). This family comprises the following twisted Edwards curves: - 255-bit: Edwards25519, the twisted Edwards curve birationally equivalent to Curve25519. Bernstein et al., _Twisted Edwards curves_, Africacrypt 2008. - 448-bit: Edwards448, the twisted Edwards curve birationally equivalent to Curve448. Hamburg, _Ed448-Goldilocks, a new elliptic curve_, NIST ECC Workshop, 2015.
Diffie-Hellman groups defined in RFC 7919 Appendix A. This family includes groups with the following key sizes (in bits): 2048, 3072, 4096, 6144, 8192. A given implementation may support all of these sizes or only a subset.
Vendor-defined algorithm flag. Algorithms defined by this standard will never have the #PSA_ALG_VENDOR_FLAG bit set. Vendors who define additional algorithms must use an encoding with the #PSA_ALG_VENDOR_FLAG bit set and should respect the bitwise structure used by standard encodings whenever practical.
Whether an algorithm is vendor-defined. See also #PSA_ALG_VENDOR_FLAG.
Whether the specified algorithm is an asymmetric signature algorithm, also known as public-key signature algorithm.
Whether the specified algorithm is an asymmetric encryption algorithm, also known as public-key encryption algorithm.
Whether the specified algorithm is a key stretching / password hashing algorithm. A key stretching / password hashing algorithm is a key derivation algorithm that is suitable for use with a low-entropy secret such as a password. Equivalently, it's a key derivation algorithm that uses a #PSA_KEY_DERIVATION_INPUT_PASSWORD input step.
The first 512 bits (64 bytes) of the SHAKE256 output. This is the prehashing for Ed448ph (see #PSA_ALG_ED448PH). For other scenarios where a hash function based on SHA3/SHAKE is desired, SHA3-512 has the same output size and a (theoretically) higher security strength.
The CBC-MAC construction over a block cipher \warning CBC-MAC is insecure in many cases. A more secure mode, such as #PSA_ALG_CMAC, is recommended.
Whether the specified algorithm is an AEAD mode on a block cipher.
RSA PSS signature with hashing. This is the signature scheme defined by RFC 8017 (PKCS#1: RSA Cryptography Specifications) under the name RSASSA-PSS, with the message generation function MGF1, and with a salt length equal to the length of the hash, or the largest possible salt length for the algorithm and key size if that is smaller than the hash length. The specified hash algorithm is used to hash the input message, to create the salted hash, and for the mask generation.
ECDSA signature with hashing. This is the ECDSA signature scheme defined by ANSI X9.62, with a random per-message secret number (*k*). The representation of the signature as a byte string consists of the concatenation of the signature values *r* and *s*. Each of *r* and *s* is encoded as an *N*-octet string, where *N* is the length of the base point of the curve in octets. Each value is represented in big-endian order (most significant octet first).
ECDSA signature without hashing. This is the same signature scheme as #PSA_ALG_ECDSA(), but without specifying a hash algorithm. This algorithm may only be used to sign or verify a sequence of bytes that should be an already-calculated hash. Note that the input is padded with zeros on the left or truncated on the left as required to fit the curve size.
Edwards-curve digital signature algorithm with prehashing (HashEdDSA), using SHA-512 and the Edwards25519 curve. See #PSA_ALG_PURE_EDDSA regarding context support and the signature format. This algorithm is Ed25519 as specified in RFC 8032. The curve is Edwards25519. The prehash is SHA-512. The hash function used internally is SHA-512. This is a hash-and-sign algorithm: to calculate a signature, you can either: - call psa_sign_message() on the message; - or calculate the SHA-512 hash of the message with psa_hash_compute() or with a multi-part hash operation started with psa_hash_setup(), using the hash algorithm #PSA_ALG_SHA_512, then sign the calculated hash with psa_sign_hash(). Verifying a signature is similar, using psa_verify_message() or psa_verify_hash() instead of the signature function.
Edwards-curve digital signature algorithm with prehashing (HashEdDSA), using SHAKE256 and the Edwards448 curve. See #PSA_ALG_PURE_EDDSA regarding context support and the signature format. This algorithm is Ed448 as specified in RFC 8032. The curve is Edwards448. The prehash is the first 64 bytes of the SHAKE256 output. The hash function used internally is the first 114 bytes of the SHAKE256 output. This is a hash-and-sign algorithm: to calculate a signature, you can either: - call psa_sign_message() on the message; - or calculate the first 64 bytes of the SHAKE256 output of the message with psa_hash_compute() or with a multi-part hash operation started with psa_hash_setup(), using the hash algorithm #PSA_ALG_SHAKE256_512, then sign the calculated hash with psa_sign_hash(). Verifying a signature is similar, using psa_verify_message() or psa_verify_hash() instead of the signature function.
Macro to build an HKDF algorithm. For example, `PSA_ALG_HKDF(PSA_ALG_SHA_256)` is HKDF using HMAC-SHA-256. This key derivation algorithm uses the following inputs: - #PSA_KEY_DERIVATION_INPUT_SALT is the salt used in the "extract" step. It is optional; if omitted, the derivation uses an empty salt. - #PSA_KEY_DERIVATION_INPUT_SECRET is the secret key used in the "extract" step. - #PSA_KEY_DERIVATION_INPUT_INFO is the info string used in the "expand" step. You must pass #PSA_KEY_DERIVATION_INPUT_SALT before #PSA_KEY_DERIVATION_INPUT_SECRET. You may pass #PSA_KEY_DERIVATION_INPUT_INFO at any time after steup and before starting to generate output. \warning HKDF processes the salt as follows: first hash it with hash_alg if the salt is longer than the block size of the hash algorithm; then pad with null bytes up to the block size. As a result, it is possible for distinct salt inputs to result in the same outputs. To ensure unique outputs, it is recommended to use a fixed length for salt values.
Whether the specified algorithm is an HKDF algorithm. HKDF is a family of key derivation algorithms that are based on a hash function and the HMAC construction.
Macro to build an HKDF-Extract algorithm. For example, `PSA_ALG_HKDF_EXTRACT(PSA_ALG_SHA_256)` is HKDF-Extract using HMAC-SHA-256. This key derivation algorithm uses the following inputs: - PSA_KEY_DERIVATION_INPUT_SALT is the salt. - PSA_KEY_DERIVATION_INPUT_SECRET is the input keying material used in the "extract" step. The inputs are mandatory and must be passed in the order above. Each input may only be passed once. \warning HKDF-Extract is not meant to be used on its own. PSA_ALG_HKDF should be used instead if possible. PSA_ALG_HKDF_EXTRACT is provided as a separate algorithm for the sake of protocols that use it as a building block. It may also be a slight performance optimization in applications that use HKDF with the same salt and key but many different info strings. \warning HKDF processes the salt as follows: first hash it with hash_alg if the salt is longer than the block size of the hash algorithm; then pad with null bytes up to the block size. As a result, it is possible for distinct salt inputs to result in the same outputs. To ensure unique outputs, it is recommended to use a fixed length for salt values.
Whether the specified algorithm is an HKDF-Extract algorithm. HKDF-Extract is a family of key derivation algorithms that are based on a hash function and the HMAC construction.
Macro to build an HKDF-Expand algorithm. For example, `PSA_ALG_HKDF_EXPAND(PSA_ALG_SHA_256)` is HKDF-Expand using HMAC-SHA-256. This key derivation algorithm uses the following inputs: - PSA_KEY_DERIVATION_INPUT_SECRET is the pseudorandom key (PRK). - PSA_KEY_DERIVATION_INPUT_INFO is the info string. The inputs are mandatory and must be passed in the order above. Each input may only be passed once. \warning HKDF-Expand is not meant to be used on its own. `PSA_ALG_HKDF` should be used instead if possible. `PSA_ALG_HKDF_EXPAND` is provided as a separate algorithm for the sake of protocols that use it as a building block. It may also be a slight performance optimization in applications that use HKDF with the same salt and key but many different info strings.
Whether the specified algorithm is an HKDF-Expand algorithm. HKDF-Expand is a family of key derivation algorithms that are based on a hash function and the HMAC construction.
Whether the specified algorithm is an HKDF or HKDF-Extract or HKDF-Expand algorithm.
Macro to build a TLS-1.2 PRF algorithm. TLS 1.2 uses a custom pseudorandom function (PRF) for key schedule, specified in Section 5 of RFC 5246. It is based on HMAC and can be used with either SHA-256 or SHA-384. This key derivation algorithm uses the following inputs, which must be passed in the order given here: - #PSA_KEY_DERIVATION_INPUT_SEED is the seed. - #PSA_KEY_DERIVATION_INPUT_SECRET is the secret key. - #PSA_KEY_DERIVATION_INPUT_LABEL is the label. For the application to TLS-1.2 key expansion, the seed is the concatenation of ServerHello.Random + ClientHello.Random, and the label is "key expansion". For example, `PSA_ALG_TLS12_PRF(PSA_ALG_SHA_256)` represents the TLS 1.2 PRF using HMAC-SHA-256.
Macro to build a TLS-1.2 PSK-to-MasterSecret algorithm. In a pure-PSK handshake in TLS 1.2, the master secret is derived from the PreSharedKey (PSK) through the application of padding (RFC 4279, Section 2) and the TLS-1.2 PRF (RFC 5246, Section 5). The latter is based on HMAC and can be used with either SHA-256 or SHA-384. This key derivation algorithm uses the following inputs, which must be passed in the order given here: - #PSA_KEY_DERIVATION_INPUT_SEED is the seed. - #PSA_KEY_DERIVATION_INPUT_OTHER_SECRET is the other secret for the computation of the premaster secret. This input is optional; if omitted, it defaults to a string of null bytes with the same length as the secret (PSK) input. - #PSA_KEY_DERIVATION_INPUT_SECRET is the secret key. - #PSA_KEY_DERIVATION_INPUT_LABEL is the label. For the application to TLS-1.2, the seed (which is forwarded to the TLS-1.2 PRF) is the concatenation of the ClientHello.Random + ServerHello.Random, the label is "master secret" or "extended master secret" and the other secret depends on the key exchange specified in the cipher suite: - for a plain PSK cipher suite (RFC 4279, Section 2), omit PSA_KEY_DERIVATION_INPUT_OTHER_SECRET - for a DHE-PSK (RFC 4279, Section 3) or ECDHE-PSK cipher suite (RFC 5489, Section 2), the other secret should be the output of the PSA_ALG_FFDH or PSA_ALG_ECDH key agreement performed with the peer. The recommended way to pass this input is to use a key derivation algorithm constructed as PSA_ALG_KEY_AGREEMENT(ka_alg, PSA_ALG_TLS12_PSK_TO_MS(hash_alg)) and to call psa_key_derivation_key_agreement(). Alternatively, this input may be an output of `psa_raw_key_agreement()` passed with psa_key_derivation_input_bytes(), or an equivalent input passed with psa_key_derivation_input_bytes() or psa_key_derivation_input_key(). - for a RSA-PSK cipher suite (RFC 4279, Section 4), the other secret should be the 48-byte client challenge (the PreMasterSecret of (RFC 5246, Section 7.4.7.1)) concatenation of the TLS version and a 46-byte random string chosen by the client. On the server, this is typically an output of psa_asymmetric_decrypt() using PSA_ALG_RSA_PKCS1V15_CRYPT, passed to the key derivation operation with `psa_key_derivation_input_bytes()`. For example, `PSA_ALG_TLS12_PSK_TO_MS(PSA_ALG_SHA_256)` represents the TLS-1.2 PSK to MasterSecret derivation PRF using HMAC-SHA-256.
Macro to build a PBKDF2-HMAC password hashing / key stretching algorithm. PBKDF2 is defined by PKCS#5, republished as RFC 8018 (section 5.2). This macro specifies the PBKDF2 algorithm constructed using a PRF based on HMAC with the specified hash. For example, `PSA_ALG_PBKDF2_HMAC(PSA_ALG_SHA_256)` specifies PBKDF2 using the PRF HMAC-SHA-256. This key derivation algorithm uses the following inputs, which must be provided in the following order: - #PSA_KEY_DERIVATION_INPUT_COST is the iteration count. This input step must be used exactly once. - #PSA_KEY_DERIVATION_INPUT_SALT is the salt. This input step must be used one or more times; if used several times, the inputs will be concatenated. This can be used to build the final salt from multiple sources, both public and secret (also known as pepper). - #PSA_KEY_DERIVATION_INPUT_PASSWORD is the password to be hashed. This input step must be used exactly once.
Whether the specified algorithm is a PBKDF2-HMAC algorithm.
The PBKDF2-AES-CMAC-PRF-128 password hashing / key stretching algorithm. PBKDF2 is defined by PKCS#5, republished as RFC 8018 (section 5.2). This macro specifies the PBKDF2 algorithm constructed using the AES-CMAC-PRF-128 PRF specified by RFC 4615. This key derivation algorithm uses the same inputs as #PSA_ALG_PBKDF2_HMAC() with the same constraints.
Macro to build a combined algorithm that chains a key agreement with a key derivation.
Whether the specified algorithm is a finite field Diffie-Hellman algorithm. This includes the raw finite field Diffie-Hellman algorithm as well as finite-field Diffie-Hellman followed by any supporter key derivation algorithm.
The default persistence level for persistent keys. See ::psa_key_persistence_t for more information.
A cost parameter for password hashing / key stretching. This must be a direct input, passed to psa_key_derivation_input_integer().
Use the maximum possible capacity for a key derivation operation. Use this value as the capacity argument when setting up a key derivation to indicate that the operation should have the maximum possible capacity. The value of the maximum possible capacity depends on the key derivation algorithm.
\file psa/crypto_sizes.h PSA cryptography module: Mbed TLS buffer size macros This file contains the definitions of macros that are useful to compute buffer sizes. The signatures and semantics of these macros are standardized, but the definitions are not, because they depend on the available algorithms and, in some cases, on permitted tolerances on buffer sizes. In implementations with isolation between the application and the cryptography module, implementers should take care to ensure that the definitions that are exposed to applications match what the module implements. Macros that compute sizes whose values do not depend on the implementation are in crypto.h.
The length of a tag for an AEAD algorithm, in bytes. This macro can be used to allocate a buffer of sufficient size to store the tag output from psa_aead_finish(). See also #PSA_AEAD_TAG_MAX_SIZE.
The maximum size of the output of psa_aead_encrypt(), in bytes. If the size of the ciphertext buffer is at least this large, it is guaranteed that psa_aead_encrypt() will not fail due to an insufficient buffer size. Depending on the algorithm, the actual size of the ciphertext may be smaller. See also #PSA_AEAD_ENCRYPT_OUTPUT_MAX_SIZE(\p plaintext_length). \warning This macro may evaluate its arguments multiple times or zero times, so you should not pass arguments that contain side effects.
A sufficient output buffer size for psa_aead_encrypt(), for any of the supported key types and AEAD algorithms. If the size of the ciphertext buffer is at least this large, it is guaranteed that psa_aead_encrypt() will not fail due to an insufficient buffer size. See also #PSA_AEAD_ENCRYPT_OUTPUT_SIZE(\p key_type, \p alg, \p plaintext_length).
The maximum size of the output of psa_aead_decrypt(), in bytes. If the size of the plaintext buffer is at least this large, it is guaranteed that psa_aead_decrypt() will not fail due to an insufficient buffer size. Depending on the algorithm, the actual size of the plaintext may be smaller. See also #PSA_AEAD_DECRYPT_OUTPUT_MAX_SIZE(\p ciphertext_length). \warning This macro may evaluate its arguments multiple times or zero times, so you should not pass arguments that contain side effects.
A sufficient output buffer size for psa_aead_decrypt(), for any of the supported key types and AEAD algorithms. If the size of the plaintext buffer is at least this large, it is guaranteed that psa_aead_decrypt() will not fail due to an insufficient buffer size. See also #PSA_AEAD_DECRYPT_OUTPUT_SIZE(\p key_type, \p alg, \p ciphertext_length).
A sufficient output buffer size for psa_aead_update(). If the size of the output buffer is at least this large, it is guaranteed that psa_aead_update() will not fail due to an insufficient buffer size. The actual size of the output may be smaller in any given call. See also #PSA_AEAD_UPDATE_OUTPUT_MAX_SIZE(\p input_length). \warning This macro may evaluate its arguments multiple times or zero times, so you should not pass arguments that contain side effects.
A sufficient output buffer size for psa_aead_update(), for any of the supported key types and AEAD algorithms. If the size of the output buffer is at least this large, it is guaranteed that psa_aead_update() will not fail due to an insufficient buffer size. See also #PSA_AEAD_UPDATE_OUTPUT_SIZE(\p key_type, \p alg, \p input_length).
A sufficient ciphertext buffer size for psa_aead_finish(). If the size of the ciphertext buffer is at least this large, it is guaranteed that psa_aead_finish() will not fail due to an insufficient ciphertext buffer size. The actual size of the output may be smaller in any given call. See also #PSA_AEAD_FINISH_OUTPUT_MAX_SIZE.
A sufficient ciphertext buffer size for psa_aead_finish(), for any of the supported key types and AEAD algorithms. See also #PSA_AEAD_FINISH_OUTPUT_SIZE(\p key_type, \p alg).
A sufficient plaintext buffer size for psa_aead_verify(). If the size of the plaintext buffer is at least this large, it is guaranteed that psa_aead_verify() will not fail due to an insufficient plaintext buffer size. The actual size of the output may be smaller in any given call. See also #PSA_AEAD_VERIFY_OUTPUT_MAX_SIZE.
A sufficient plaintext buffer size for psa_aead_verify(), for any of the supported key types and AEAD algorithms. See also #PSA_AEAD_VERIFY_OUTPUT_SIZE(\p key_type, \p alg).
Sufficient signature buffer size for psa_sign_hash(). This macro returns a sufficient buffer size for a signature using a key of the specified type and size, with the specified algorithm. Note that the actual size of the signature may be smaller (some algorithms produce a variable-size signature). \warning This function may call its arguments multiple times or zero times, so you should not pass arguments that contain side effects.
Sufficient output buffer size for psa_asymmetric_encrypt(). This macro returns a sufficient buffer size for a ciphertext produced using a key of the specified type and size, with the specified algorithm. Note that the actual size of the ciphertext may be smaller, depending on the algorithm. \warning This function may call its arguments multiple times or zero times, so you should not pass arguments that contain side effects.
A sufficient output buffer size for psa_asymmetric_encrypt(), for any supported asymmetric encryption. See also #PSA_ASYMMETRIC_ENCRYPT_OUTPUT_SIZE(\p key_type, \p key_bits, \p alg).
Sufficient output buffer size for psa_asymmetric_decrypt(). This macro returns a sufficient buffer size for a plaintext produced using a key of the specified type and size, with the specified algorithm. Note that the actual size of the plaintext may be smaller, depending on the algorithm. \warning This function may call its arguments multiple times or zero times, so you should not pass arguments that contain side effects.
A sufficient output buffer size for psa_asymmetric_decrypt(), for any supported asymmetric decryption. This macro assumes that RSA is the only supported asymmetric encryption. See also #PSA_ASYMMETRIC_DECRYPT_OUTPUT_SIZE(\p key_type, \p key_bits, \p alg).
Sufficient output buffer size for psa_export_public_key(). This macro returns a compile-time constant if its arguments are compile-time constants. \warning This macro may evaluate its arguments multiple times or zero times, so you should not pass arguments that contain side effects. The following code illustrates how to allocate enough memory to export a public key by querying the key type and size at runtime.
{c}
psa_key_attributes_t attributes = PSA_KEY_ATTRIBUTES_INIT;
psa_status_t status;
status = psa_get_key_attributes(key, &attributes);
if (status != PSA_SUCCESS) handle_error(...);
psa_key_type_t key_type = psa_get_key_type(&attributes);
size_t key_bits = psa_get_key_bits(&attributes);
size_t buffer_size = PSA_EXPORT_PUBLIC_KEY_OUTPUT_SIZE(key_type, key_bits);
psa_reset_key_attributes(&attributes);
uint8_t *buffer = malloc(buffer_size);
if (buffer == NULL) handle_error(...);
size_t buffer_length;
status = psa_export_public_key(key, buffer, buffer_size, &buffer_length);
if (status != PSA_SUCCESS) handle_error(...);
If the parameters are valid and supported, return the same result as #PSA_EXPORT_KEY_OUTPUT_SIZE( \p #PSA_KEY_TYPE_PUBLIC_KEY_OF_KEY_PAIR(\p key_type), \p key_bits). The maximum size of the output of psa_cipher_encrypt(), in bytes. If the size of the output buffer is at least this large, it is guaranteed that psa_cipher_encrypt() will not fail due to an insufficient buffer size. Depending on the algorithm, the actual size of the output might be smaller. See also #PSA_CIPHER_ENCRYPT_OUTPUT_MAX_SIZE(\p input_length). \warning This macro may evaluate its arguments multiple times or zero times, so you should not pass arguments that contain side effects.
A sufficient output buffer size for psa_cipher_encrypt(), for any of the supported key types and cipher algorithms. If the size of the output buffer is at least this large, it is guaranteed that psa_cipher_encrypt() will not fail due to an insufficient buffer size. See also #PSA_CIPHER_ENCRYPT_OUTPUT_SIZE(\p key_type, \p alg, \p input_length).
The maximum size of the output of psa_cipher_decrypt(), in bytes. If the size of the output buffer is at least this large, it is guaranteed that psa_cipher_decrypt() will not fail due to an insufficient buffer size. Depending on the algorithm, the actual size of the output might be smaller. See also #PSA_CIPHER_DECRYPT_OUTPUT_MAX_SIZE(\p input_length).
A sufficient output buffer size for psa_cipher_decrypt(), for any of the supported key types and cipher algorithms. If the size of the output buffer is at least this large, it is guaranteed that psa_cipher_decrypt() will not fail due to an insufficient buffer size. See also #PSA_CIPHER_DECRYPT_OUTPUT_SIZE(\p key_type, \p alg, \p input_length).
A sufficient output buffer size for psa_cipher_update(). If the size of the output buffer is at least this large, it is guaranteed that psa_cipher_update() will not fail due to an insufficient buffer size. The actual size of the output might be smaller in any given call. See also #PSA_CIPHER_UPDATE_OUTPUT_MAX_SIZE(\p input_length).
A sufficient output buffer size for psa_cipher_update(), for any of the supported key types and cipher algorithms. If the size of the output buffer is at least this large, it is guaranteed that psa_cipher_update() will not fail due to an insufficient buffer size. See also #PSA_CIPHER_UPDATE_OUTPUT_SIZE(\p key_type, \p alg, \p input_length).
A sufficient ciphertext buffer size for psa_cipher_finish(). If the size of the ciphertext buffer is at least this large, it is guaranteed that psa_cipher_finish() will not fail due to an insufficient ciphertext buffer size. The actual size of the output might be smaller in any given call. See also #PSA_CIPHER_FINISH_OUTPUT_MAX_SIZE().
A sufficient ciphertext buffer size for psa_cipher_finish(), for any of the supported key types and cipher algorithms. See also #PSA_CIPHER_FINISH_OUTPUT_SIZE(\p key_type, \p alg).
\file psa/crypto_struct.h PSA cryptography module: Mbed TLS structured type implementations This file contains the definitions of some data structures with implementation-specific definitions. In implementations with isolation between the application and the cryptography module, it is expected that the front-end and the back-end would have different versions of this file. Design notes about multipart operation structures For multipart operations without driver delegation support, each multipart operation structure contains a `psa_algorithm_t alg` field which indicates which specific algorithm the structure is for. When the structure is not in use, `alg` is 0. Most of the structure consists of a union which is discriminated by `alg`. For multipart operations with driver delegation support, each multipart operation structure contains an `unsigned int id` field indicating which driver got assigned to do the operation. When the structure is not in use, 'id' is 0. The structure contains also a driver context which is the union of the contexts of all drivers able to handle the type of multipart operation. Note that when `alg` or `id` is 0, the content of other fields is undefined. In particular, it is not guaranteed that a freshly-initialized structure is all-zero: we initialize structures to something like `{0, 0}`, which is only guaranteed to initializes the first member of the union; GCC and Clang initialize the whole structure to 0 (at the time of writing), but MSVC and CompCert don't. In Mbed TLS, multipart operation structures live independently from the key. This allows Mbed TLS to free the key objects when destroying a key slot. If a multipart operation needs to remember the key after the setup function returns, the operation structure needs to contain a copy of the key.
\file psa/crypto_driver_common.h Definitions for all PSA crypto drivers This file contains common definitions shared by all PSA crypto drivers. Do not include it directly: instead, include the header file(s) for the type(s) of driver that you are implementing. For example, if you are writing a dynamically registered driver for a secure element, include `psa/crypto_se_driver.h`. This file is part of the PSA Crypto Driver Model, containing functions for driver developers to implement to enable hardware to be called in a standardized way by a PSA Cryptographic API implementation. The functions comprising the driver model, which driver authors implement, are not intended to be called by application developers.
\file md5.h MD5 message digest algorithm (hash function) \warning MD5 is considered a weak message digest and its use constitutes a security risk. We recommend considering stronger message digests instead.
\file sha1.h This file contains SHA-1 definitions and functions. The Secure Hash Algorithm 1 (SHA-1) cryptographic hash function is defined in FIPS 180-4: Secure Hash Standard (SHS). \warning SHA-1 is considered a weak message digest and its use constitutes a security risk. We recommend considering stronger message digests instead.
\file sha512.h This file contains SHA-384 and SHA-512 definitions and functions. The Secure Hash Algorithms 384 and 512 (SHA-384 and SHA-512) cryptographic hash functions are defined in FIPS 180-4: Secure Hash Standard (SHS).
\file sha3.h This file contains SHA-3 definitions and functions. The Secure Hash Algorithms cryptographic hash functions are defined in FIPS 202: SHA-3 Standard: Permutation-Based Hash and Extendable-Output Functions .
\file cipher.h This file contains an abstraction interface for use with the cipher primitives provided by the library. It provides a common interface to all of the available cipher operations. \author Adriaan de Jong <dejong@fox-it.com>
\file cmac.h This file contains CMAC definitions and functions. The Cipher-based Message Authentication Code (CMAC) Mode for Authentication is defined in RFC-4493: The AES-CMAC Algorithm. It is supported with AES and DES.
\file gcm.h This file contains GCM definitions and functions. The Galois/Counter Mode (GCM) for 128-bit block ciphers is defined in D. McGrew, J. Viega, The Galois/Counter Mode of Operation (GCM), Natl. Inst. Stand. Technol. For more information on GCM, see NIST SP 800-38D: Recommendation for Block Cipher Modes of Operation: Galois/Counter Mode (GCM) and GMAC.
\file ccm.h This file provides an API for the CCM authenticated encryption mode for block ciphers. CCM combines Counter mode encryption with CBC-MAC authentication for 128-bit block ciphers. Input to CCM includes the following elements: Payload - data that is both authenticated and encrypted. Associated data (Adata) - data that is authenticated but not encrypted, For example, a header. Nonce - A unique value that is assigned to the payload and the associated data. Definition of CCM: http://csrc.nist.gov/publications/nistpubs/800-38C/SP800-38C_updated-July20_2007.pdf RFC 3610 "Counter with CBC-MAC (CCM)" Related: RFC 5116 "An Interface and Algorithms for Authenticated Encryption" Definition of CCM*: IEEE 802.15.4 - IEEE Standard for Local and metropolitan area networks Integer representation is fixed most-significant-octet-first order and the representation of octets is most-significant-bit-first order. This is consistent with RFC 3610.
\file chachapoly.h This file contains the AEAD-ChaCha20-Poly1305 definitions and functions. ChaCha20-Poly1305 is an algorithm for Authenticated Encryption with Associated Data (AEAD) that can be used to encrypt and authenticate data. It is based on ChaCha20 and Poly1305 by Daniel Bernstein and was standardized in RFC 7539. \author Daniel King <damaki.gh@gmail.com>
\file poly1305.h This file contains Poly1305 definitions and functions. Poly1305 is a one-time message authenticator that can be used to authenticate messages. Poly1305-AES was created by Daniel Bernstein https://cr.yp.to/mac/poly1305-20050329.pdf The generic Poly1305 algorithm (not tied to AES) was also standardized in RFC 7539. \author Daniel King <damaki.gh@gmail.com>
\file chacha20.h This file contains ChaCha20 definitions and functions. ChaCha20 is a stream cipher that can encrypt and decrypt information. ChaCha was created by Daniel Bernstein as a variant of its Salsa cipher https://cr.yp.to/chacha/chacha-20080128.pdf ChaCha20 is the variant with 20 rounds, that was also standardized in RFC 7539. \author Daniel King <damaki.gh@gmail.com>
The default production parameters for key generation or key derivation. Calling psa_generate_key_ext() or psa_key_derivation_output_key_ext() with `params=PSA_KEY_PRODUCTION_PARAMETERS_INIT` and `params_data_length == 0` is equivalent to calling psa_generate_key() or psa_key_derivation_output_key() respectively.
\file psa/crypto_extra.h PSA cryptography module: Mbed TLS vendor extensions This file is reserved for vendor-specific definitions.
\file psa/crypto_compat.h PSA cryptography module: Backward compatibility aliases This header declares alternative names for macro and functions. New application code should not use these names. These names may be removed in a future version of Mbed TLS.
DSA signature with hashing. This is the signature scheme defined by FIPS 186-4, with a random per-message secret number (*k*).
Deterministic DSA signature with hashing. This is the deterministic variant defined by RFC 6979 of the signature scheme defined by FIPS 186-4.
The first peer in a balanced PAKE. Although balanced PAKE algorithms are symmetric, some of them needs an ordering of peers for the transcript calculations. If the algorithm does not need this, both #PSA_PAKE_ROLE_FIRST and #PSA_PAKE_ROLE_SECOND are accepted.
The second peer in a balanced PAKE. Although balanced PAKE algorithms are symmetric, some of them needs an ordering of peers for the transcript calculations. If the algorithm does not need this, either #PSA_PAKE_ROLE_FIRST or #PSA_PAKE_ROLE_SECOND are accepted.
The client in an augmented PAKE. Augmented PAKE algorithms need to differentiate between client and server.
The server in an augmented PAKE. Augmented PAKE algorithms need to differentiate between client and server.
The PAKE primitive type indicating the use of Diffie-Hellman groups. The values of the \c family and \c bits fields of the cipher suite identify a specific Diffie-Hellman group, using the same mapping that is used for Diffie-Hellman (::psa_dh_family_t) keys. (Here \c family means the value returned by psa_pake_cs_get_family() and \c bits means the value returned by psa_pake_cs_get_bits().) Input and output during the operation can involve group elements and scalar values: -# The format for group elements is the same as for public keys on the specific group would be. For more information, consult the documentation of psa_export_public_key(). -# The format for scalars is the same as for private keys on the specific group would be. For more information, consult the documentation of psa_export_key().
A sufficient output buffer size for psa_pake_output(). If the size of the output buffer is at least this large, it is guaranteed that psa_pake_output() will not fail due to an insufficient output buffer size. The actual size of the output might be smaller in any given call. See also #PSA_PAKE_OUTPUT_MAX_SIZE
Output buffer size for psa_pake_output() for any of the supported PAKE algorithm and primitive suites and output step. This macro must expand to a compile-time constant integer. The value of this macro must be at least as large as the largest value returned by PSA_PAKE_OUTPUT_SIZE() See also #PSA_PAKE_OUTPUT_SIZE(\p alg, \p primitive, \p output_step).
Input buffer size for psa_pake_input() for any of the supported PAKE algorithm and primitive suites and input step. This macro must expand to a compile-time constant integer. The value of this macro must be at least as large as the largest value returned by PSA_PAKE_INPUT_SIZE() See also #PSA_PAKE_INPUT_SIZE(\p alg, \p primitive, \p output_step).
\file ecdh.h This file contains ECDH definitions and functions. The Elliptic Curve Diffie-Hellman (ECDH) protocol is an anonymous key agreement protocol allowing two parties to establish a shared secret over an insecure channel. Each party must have an elliptic-curve public–private key pair. For more information, see NIST SP 800-56A Rev. 2: Recommendation for Pair-Wise Key Establishment Schemes Using Discrete Logarithm Cryptography.
Pure-PSK TLS 1.3 key exchange, encompassing both externally agreed PSKs as well as resumption PSKs.
Pure-Ephemeral TLS 1.3 key exchanges, including for example ECDHE and DHE key exchanges.
PSK-Ephemeral TLS 1.3 key exchanges, using both a PSK and an ephemeral key exchange.
\file platform.h This file contains the definitions and functions of the Mbed TLS platform abstraction layer. The platform abstraction layer removes the need for the library to directly link to standard C library functions or operating system services, making the library easier to port and embed. Application developers and users of the library can provide their own implementations of these functions, or implementations specific to their platform, which can be statically linked to the library or dynamically configured at runtime. When all compilation options related to platform abstraction are disabled, this header just defines `mbedtls_xxx` function names as aliases to the standard `xxx` function. Most modules in the library and example programs are expected to include this header.
\file net_sockets.h Network sockets abstraction layer to integrate Mbed TLS into a BSD-style sockets API. The network sockets module provides an example integration of the Mbed TLS library into a BSD sockets implementation. The module is intended to be an example of how Mbed TLS can be integrated into a networking stack, as well as to be Mbed TLS's network integration for its supported platforms. The module is intended only to be used with the Mbed TLS library and is not intended to be used by third party application software directly. The supported platforms are as follows: * Microsoft Windows and Windows CE * POSIX/Unix platforms including Linux, OS X
\file ctr_drbg.h This file contains definitions and functions for the CTR_DRBG pseudorandom generator. CTR_DRBG is a standardized way of building a PRNG from a block-cipher in counter mode operation, as defined in NIST SP 800-90A: Recommendation for Random Number Generation Using Deterministic Random Bit Generators. The Mbed TLS implementation of CTR_DRBG uses AES-256 (default) or AES-128 (if \c MBEDTLS_CTR_DRBG_USE_128_BIT_KEY is enabled at compile time) as the underlying block cipher, with a derivation function. The security strength as defined in NIST SP 800-90A is 128 bits when AES-128 is used (\c MBEDTLS_CTR_DRBG_USE_128_BIT_KEY enabled) and 256 bits otherwise, provided that #MBEDTLS_CTR_DRBG_ENTROPY_LEN is kept at its default value (and not overridden in mbedtls_config.h) and that the DRBG instance is set up with default parameters. See the documentation of mbedtls_ctr_drbg_seed() for more information.
\file aes.h This file contains AES definitions and functions. The Advanced Encryption Standard (AES) specifies a FIPS-approved cryptographic algorithm that can be used to protect electronic data. The AES algorithm is a symmetric block cipher that can encrypt and decrypt information. For more information, see FIPS Publication 197: Advanced Encryption Standard and ISO/IEC 18033-2:2006: Information technology -- Security techniques -- Encryption algorithms -- Part 2: Asymmetric ciphers. The AES-XTS block mode is standardized by NIST SP 800-38E and described in detail by IEEE P1619 .
\file aes_alt.h AES block cipher Copyright (C) 2006-2015, ARM Limited, All Rights Reserved SPDX-License-Identifier: Apache-2.0 Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
id-ce-subjectDirectoryAttributes OBJECT IDENTIFIER ::= { id-ce 9 }
id-ce-cRLDistributionPoints OBJECT IDENTIFIER ::= { id-ce 31 }
id-ripemd160 OBJECT IDENTIFIER :: { iso(1) identified-organization(3) teletrust(36) algorithm(3) hashAlgorithm(2) ripemd160(1) }
id-sha3-224 OBJECT IDENTIFIER ::= { joint-iso-itu-t(2) country(16) us(840) organization(1) gov(101) csor(3) nistAlgorithms(4) hashalgs(2) sha3-224(7) }
id-sha3-256 OBJECT IDENTIFIER ::= { joint-iso-itu-t(2) country(16) us(840) organization(1) gov(101) csor(3) nistAlgorithms(4) hashalgs(2) sha3-256(8) }
id-sha3-384 OBJECT IDENTIFIER ::= { joint-iso-itu-t(2) country(16) us(840) organization(1) gov(101) csor(3) nistAlgorithms(4) hashalgs(2) sha3-384(9) }
id-sha3-512 OBJECT IDENTIFIER ::= { joint-iso-itu-t(2) country(16) us(840) organization(1) gov(101) csor(3) nistAlgorithms(4) hashalgs(2) sha3-512(10) }
id-hmacWithSHA3-512 OBJECT IDENTIFIER ::= { joint-iso-itu-t(2) country(16) us(840) organization(1) gov(101) csor(3) nistAlgorithms(4) hashalgs(2) hmacWithSHA3-224(13) }
id-hmacWithSHA3-512 OBJECT IDENTIFIER ::= { joint-iso-itu-t(2) country(16) us(840) organization(1) gov(101) csor(3) nistAlgorithms(4) hashalgs(2) hmacWithSHA3-256(14) }
id-hmacWithSHA3-512 OBJECT IDENTIFIER ::= { joint-iso-itu-t(2) country(16) us(840) organization(1) gov(101) csor(3) nistAlgorithms(4) hashalgs(2) hmacWithSHA3-384(15) }
id-hmacWithSHA3-512 OBJECT IDENTIFIER ::= { joint-iso-itu-t(2) country(16) us(840) organization(1) gov(101) csor(3) nistAlgorithms(4) hashalgs(2) hmacWithSHA3-512(16) }
id-hmacWithSHA1 OBJECT IDENTIFIER ::= {iso(1) iso-identified-organization(3) dod(6) internet(1) security(5) mechanisms(5) ipsec(8) isakmpOakley(1) hmacRIPEMD160(4)}
aes256-cbc-pad OBJECT IDENTIFIER ::= { joint-iso-itu-t(2) country(16) us(840) organization(1) gov(101) csor(3) nistAlgorithms(4) aes(1) aes256-CBC-PAD(42) }
pbeWithSHA1AndDES-CBC OBJECT IDENTIFIER ::= {pkcs-5 10}
pbeWithSHA1AndRC2-CBC OBJECT IDENTIFIER ::= {pkcs-5 11}
pbeWithSHAAnd128BitRC2-CBC OBJECT IDENTIFIER ::= {pkcs-12PbeIds 5}
pbeWithSHAAnd40BitRC2-CBC OBJECT IDENTIFIER ::= {pkcs-12PbeIds 6}
Number of slots which are occupied, but do not contain key material yet.
\file ssl_ciphersuites_internal.h Internal part of the public "ssl_ciphersuites.h".
\file pk_internal.h Public Key abstraction layer: internal (i.e. library only) functions and definitions.
\file psa_util_internal.h Internal utility functions for use of PSA Crypto.
\file psa_util.h Utility functions for the use of the PSA Crypto library.
\file alignment.h Utility code for dealing with unaligned memory accesses
Get the unsigned 24 bits integer corresponding to three bytes in little-endian order (LSB first).
Put in memory a 24 bits unsigned integer in little-endian order.
\file debug.h Functions for controlling and providing debug output from the library.
\file pkcs5.h PKCS#5 functions \author Mathias Olsson <mathias@kompetensum.com>
\file nist_kw.h This file provides an API for key wrapping (KW) and key wrapping with padding (KWP) as defined in NIST SP 800-38F. https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-38F.pdf Key wrapping specifies a deterministic authenticated-encryption mode of operation, according to NIST SP 800-38F: Recommendation for Block Cipher Modes of Operation: Methods for Key Wrapping. Its purpose is to protect cryptographic keys. Its equivalent is RFC 3394 for KW, and RFC 5649 for KWP. https://tools.ietf.org/html/rfc3394 https://tools.ietf.org/html/rfc5649
\file des.h DES block cipher \warning DES/3DES are considered weak ciphers and their use constitutes a security risk. We recommend considering stronger ciphers instead.
\file padlock.h VIA PadLock ACE for HW encryption/decryption supported by some processors \warning These functions are only for internal use by other library functions; you must not call them directly.
\file aesni.h AES-NI for hardware AES acceleration on some Intel processors \warning These functions are only for internal use by other library functions; you must not call them directly.
\file aesce.h Support hardware AES acceleration on Armv8-A processors with the Armv8-A Cryptographic Extension. \warning These functions are only for internal use by other library functions; you must not call them directly.
\file ctr.h This file contains common functionality for counter algorithms. Copyright The Mbed TLS Contributors SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later
\file aria.h ARIA block cipher The ARIA algorithm is a symmetric block cipher that can encrypt and decrypt information. It is defined by the Korean Agency for Technology and Standards (KATS) in KS X 1213:2004 (in Korean, but see http://210.104.33.10/ARIA/index-e.html in English) and also described by the IETF in RFC 5794.
\file base64_internal.h RFC 1521 base64 encoding/decoding: interfaces for invasive testing
Constant-time functions Copyright The Mbed TLS Contributors SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later
Constant-time functions Copyright The Mbed TLS Contributors SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later
Core bignum functions This interface should only be used by the legacy bignum module (bignum.h) and the modular bignum modules (bignum_mod.c, bignum_mod_raw.c). All other modules should use the high-level modular bignum interface (bignum_mod.h) or the legacy bignum interface (bignum.h). This module is about processing non-negative integers with a fixed upper bound that's of the form 2^n-1 where n is a multiple of #biL. These can be thought of integers written in base 2^#biL with a fixed number of digits. Digits in this base are called *limbs*. Many operations treat these numbers as the principal representation of a number modulo 2^n or a smaller bound. The functions in this module obey the following conventions unless explicitly indicated otherwise: - **Overflow**: some functions indicate overflow from the range [0, 2^n-1] by returning carry parameters, while others operate modulo and so cannot overflow. This should be clear from the function documentation. - **Bignum parameters**: Bignums are passed as pointers to an array of limbs. A limb has the type #mbedtls_mpi_uint. Unless otherwise specified: - Bignum parameters called \p A, \p B, ... are inputs, and are not modified by the function. - For operations modulo some number, the modulus is called \p N and is input-only. - Bignum parameters called \p X, \p Y are outputs or input-output. The initial content of output-only parameters is ignored. - Some functions use different names that reflect traditional naming of operands of certain operations (e.g. divisor/dividend/quotient/remainder). - \p T is a temporary storage area. The initial content of such parameter is ignored and the final content is unspecified. - **Bignum sizes**: bignum sizes are always expressed in limbs. Most functions work on bignums of a given size and take a single \p limbs parameter that applies to all parameters that are limb arrays. All bignum sizes must be at least 1 and must be significantly less than #SIZE_MAX. The behavior if a size is 0 is undefined. The behavior if the total size of all parameters overflows #SIZE_MAX is undefined. - **Parameter ordering**: for bignum parameters, outputs come before inputs. Temporaries come last. - **Aliasing**: in general, output bignums may be aliased to one or more inputs. As an exception, parameters that are documented as a modulus value may not be aliased to an output. Outputs may not be aliased to one another. Temporaries may not be aliased to any other parameter. - **Overlap**: apart from aliasing of limb array pointers (where two arguments are equal pointers), overlap is not supported and may result in undefined behavior. - **Error handling**: This is a low-level module. Functions generally do not try to protect against invalid arguments such as nonsensical sizes or null pointers. Note that some functions that operate on bignums of different sizes have constraints about their size, and violating those constraints may lead to buffer overflows. - **Modular representatives**: functions that operate modulo \p N expect all modular inputs to be in the range [0, \p N - 1] and guarantee outputs in the range [0, \p N - 1]. If an input is out of range, outputs are fully unspecified, though bignum values out of range should not cause buffer overflows (beware that this is not extensively tested).
\file bignum_internal.h Internal-only bignum public-key cryptosystem API. This file declares bignum-related functions that are to be used only from within the Mbed TLS library itself.
\file block_cipher_internal.h Lightweight abstraction layer for block ciphers with 128 bit blocks, for use by the GCM and CCM modules.
\file cipher_wrap.h Cipher wrappers. \author Adriaan de Jong <dejong@fox-it.com>
\file hmac_drbg.h The HMAC_DRBG pseudorandom generator. This module implements the HMAC_DRBG pseudorandom generator described in NIST SP 800-90A: Recommendation for Random Number Generation Using Deterministic Random Bit Generators.
Representation not chosen (makes the modulus structure invalid).
\file ecp_invasive.h ECP module: interfaces for invasive testing only. The interfaces in this file are intended for testing purposes only. They SHOULD NOT be made available in library integrations except when building the library for testing.
Modular bignum functions This module implements operations on integers modulo some fixed modulus. The functions in this module obey the following conventions unless explicitly indicated otherwise: - **Modulus parameters**: the modulus is passed as a pointer to a structure of type #mbedtls_mpi_mod_modulus. The structure must be set up with an array of limbs storing the bignum value of the modulus. The modulus must be odd and is assumed to have no leading zeroes. The modulus is usually named \c N and is usually input-only. Functions which take a parameter of type \c const #mbedtls_mpi_mod_modulus* must not modify its value. - **Bignum parameters**: Bignums are passed as pointers to an array of limbs or to a #mbedtls_mpi_mod_residue structure. A limb has the type #mbedtls_mpi_uint. Residues must be initialized before use, and must be associated with the modulus \c N. Unless otherwise specified: - Bignum parameters called \c A, \c B, ... are inputs and are not modified by the function. Functions which take a parameter of type \c const #mbedtls_mpi_mod_residue* must not modify its value. - Bignum parameters called \c X, \c Y, ... are outputs or input-output. The initial bignum value of output-only parameters is ignored, but they must be set up and associated with the modulus \c N. Some functions (typically constant-flow) require that the limbs in an output residue are initialized. - Bignum parameters called \c p are inputs used to set up a modulus or residue. These must be pointers to an array of limbs. - \c T is a temporary storage area. The initial content of such a parameter is ignored and the final content is unspecified. - Some functions use different names, such as \c r for the residue. - **Bignum sizes**: bignum sizes are always expressed in limbs. Both #mbedtls_mpi_mod_modulus and #mbedtls_mpi_mod_residue have a \c limbs member storing its size. All bignum parameters must have the same number of limbs as the modulus. All bignum sizes must be at least 1 and must be significantly less than #SIZE_MAX. The behavior if a size is 0 is undefined. - **Bignum representation**: the representation of inputs and outputs is specified by the \c int_rep field of the modulus. - **Parameter ordering**: for bignum parameters, outputs come before inputs. The modulus is passed after residues. Temporaries come last. - **Aliasing**: in general, output bignums may be aliased to one or more inputs. Modulus values may not be aliased to any other parameter. Outputs may not be aliased to one another. Temporaries may not be aliased to any other parameter. - **Overlap**: apart from aliasing of residue pointers (where two residue arguments are equal pointers), overlap is not supported and may result in undefined behavior. - **Error handling**: functions generally check compatibility of input sizes. Most functions will not check that input values are in canonical form (i.e. that \c A < \c N), this is only checked during setup of a residue structure. - **Modular representatives**: all functions expect inputs to be in the range [0, \c N - 1] and guarantee outputs in the range [0, \c N - 1]. Residues are set up with an associated modulus, and operations are only guaranteed to work if the modulus is associated with all residue parameters. If a residue is passed with a modulus other than the one it is associated with, then it may be out of range. If an input is out of range, outputs are fully unspecified, though bignum values out of range should not cause buffer overflows (beware that this is not extensively tested).
\file ecp_internal_alt.h Function declarations for alternative implementation of elliptic curve point arithmetic.
\file lms.h This file provides an API for the LMS post-quantum-safe stateful-hash public-key signature scheme as defined in RFC8554 and NIST.SP.200-208. This implementation currently only supports a single parameter set MBEDTLS_LMS_SHA256_M32_H10 in order to reduce complexity. This is one of the signature schemes recommended by the IETF draft SUIT standard for IOT firmware upgrades (RFC9019).
\file pkcs7.h PKCS #7 generic defines and structures https://tools.ietf.org/html/rfc2315 Note: For the time being, this implementation of the PKCS #7 cryptographic message syntax is a partial implementation of RFC 2315. Differences include: - The RFC specifies 6 different content types. The only type currently supported in Mbed TLS is the signed-data content type. - The only supported PKCS #7 Signed Data syntax version is version 1 - The RFC specifies support for BER. This implementation is limited to DER only. - The RFC specifies that multiple digest algorithms can be specified in the Signed Data type. Only one digest algorithm is supported in Mbed TLS. - The RFC specifies the Signed Data type can contain multiple X.509 or PKCS #6 extended certificates. In Mbed TLS, this list can only contain 0 or 1 certificates and they must be in X.509 format. - The RFC specifies the Signed Data type can contain certificate-revocation lists (CRLs). This implementation has no support for CRLs so it is assumed to be an empty list. - The RFC allows for SignerInfo structure to optionally contain unauthenticatedAttributes and authenticatedAttributes. In Mbed TLS it is assumed these fields are empty. - The RFC allows for the signed Data type to contain contentInfo. This implementation assumes the type is DATA and the content is empty.
\file lmots.h This file provides an API for the LM-OTS post-quantum-safe one-time public-key signature scheme as defined in RFC8554 and NIST.SP.200-208. This implementation currently only supports a single parameter set MBEDTLS_LMOTS_SHA256_N32_W8 in order to reduce complexity.
\file md_wrap.h Message digest wrappers. \warning This in an internal header. Do not include directly. \author Adriaan de Jong <dejong@fox-it.com>
Translation between MD and PSA identifiers (algorithms, errors). Note: this internal module will go away when everything becomes based on PSA Crypto; it is a helper for the transition period. Copyright The Mbed TLS Contributors SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later
\file rsa_internal.h Internal-only RSA public-key cryptosystem API. This file declares RSA-related functions that are to be used only from within the Mbed TLS library itself.
The size in bytes of the hardware-specific secure element cipher context structure
Function that performs ECB mode for a cipher operation (Danger: ECB mode should not be used directly by clients of the PSA Crypto Client API)
A read-only pointer to the driver's persistent data. Drivers typically use this persistent data to keep track of which slot numbers are available. This is only a guideline: drivers may use the persistent data for any purpose, keeping in mind the restrictions on when the persistent data is saved to storage: the persistent data is only saved after calling certain functions that receive a writable pointer to the persistent data. The core allocates a memory buffer for the persistent data. The pointer is guaranteed to be suitably aligned for any data type, like a pointer returned by `malloc` (but the core can use any method to allocate the buffer, not necessarily `malloc`). The size of this buffer is in the \c persistent_data_size field of this structure. Before the driver is initialized for the first time, the content of the persistent data is all-bits-zero. After a driver upgrade, if the size of the persistent data has increased, the original data is padded on the right with zeros; if the size has decreased, the original data is truncated to the new size. This pointer is to read-only data. Only a few driver functions are allowed to modify the persistent data. These functions receive a writable pointer. These functions are: - psa_drv_se_t::p_init - psa_drv_se_key_management_t::p_allocate - psa_drv_se_key_management_t::p_destroy The PSA Cryptography core saves the persistent data from one session to the next. It does this before returning from API functions that call a driver method that is allowed to modify the persistent data, specifically: - psa_crypto_init() causes a call to psa_drv_se_t::p_init, and may call psa_drv_se_key_management_t::p_destroy to complete an action that was interrupted by a power failure. - Key creation functions cause a call to psa_drv_se_key_management_t::p_allocate, and may cause a call to psa_drv_se_key_management_t::p_destroy in case an error occurs. - psa_destroy_key() causes a call to psa_drv_se_key_management_t::p_destroy.
The size of \c persistent_data in bytes. This is always equal to the value of the `persistent_data_size` field of the ::psa_drv_se_t structure when the driver is registered.
Driver transient data. The core initializes this value to 0 and does not read or modify it afterwards. The driver may store whatever it wants in this field.
The size in bytes of the hardware-specific secure element MAC context structure
A key is being registered with mbedtls_psa_register_se_key(). The core only passes this value to psa_drv_se_key_management_t::p_validate_slot_number, not to psa_drv_se_key_management_t::p_allocate. The call to `p_validate_slot_number` is not followed by any other call to the driver: the key is considered successfully registered if the call to `p_validate_slot_number` succeeds, or if `p_validate_slot_number` is null. With this creation method, the driver must return #PSA_SUCCESS if the given attributes are compatible with the existing key in the slot, and #PSA_ERROR_DOES_NOT_EXIST if the driver can determine that there is no key with the specified slot number. This is an Mbed TLS extension.
Function that performs a final key derivation or agreement and exports the key
The version of the driver HAL that this driver implements. This is a protection against loading driver binaries built against a different version of this specification. Use #PSA_DRV_SE_HAL_VERSION.
The size of the driver's persistent data in bytes. This can be 0 if the driver does not need persistent data. See the documentation of psa_drv_se_context_t::persistent_data for more information about why and how a driver can use persistent data.
The driver initialization function. This function is called once during the initialization of the PSA Cryptography subsystem, before any other function of the driver is called. If this function returns a failure status, the driver will be unusable, at least until the next system reset. If this field is \c NULL, it is equivalent to a function that does nothing and returns #PSA_SUCCESS.
Function that checks the validity of a slot for a key.
\file psa_crypto_core_common.h Utility macros for internal use in the PSA cryptography core.
\file psa/crypto_se_driver.h PSA external cryptoprocessor driver module This header declares types and function signatures for cryptography drivers that access key material via opaque references. This is meant for cryptoprocessors that have a separate key storage from the space in which the PSA Crypto implementation runs, typically secure elements (SEs). This file is part of the PSA Crypto Driver HAL (hardware abstraction layer), containing functions for driver developers to implement to enable hardware to be called in a standardized way by a PSA Cryptography API implementation. The functions comprising the driver HAL, which driver authors implement, are not intended to be called by application developers.
The current version of the secure element driver HAL.
\file psa_crypto_invasive.h PSA cryptography module: invasive interfaces for test only. The interfaces in this file are intended for testing purposes only. They MUST NOT be made available to clients over IPC in integrations with isolation, and they SHOULD NOT be made available in library integrations except when building the library for testing.
The maximum location value that this implementation supports for a secure element. This is not a characteristic that each PSA implementation has, but a limitation of the current implementation due to the constraints imposed by storage. See #PSA_CRYPTO_SE_DRIVER_ITS_UID_BASE. The minimum location value for a secure element is 1, like on any PSA implementation (0 means a transparent key).
The base of the range of ITS file identifiers for secure element driver persistent data. We use a slice of the implementation reserved range 0xffff0000..0xffffffff, specifically the range 0xfffffe00..0xfffffeff. The length of this range drives the value of #PSA_MAX_SE_LOCATION. The identifier 0xfffffe00 is actually not used since it corresponds to #PSA_KEY_LOCATION_LOCAL_STORAGE which doesn't have a driver.
\file psa_crypto_storage.h PSA cryptography module: Mbed TLS key storage
The maximum permitted persistent slot number. In Mbed Crypto 0.1.0b: - Using the file backend, all key ids are ok except 0. - Using the ITS backend, all key ids are ok except 0xFFFFFF52 (#PSA_CRYPTO_ITS_RANDOM_SEED_UID) for which the file contains the device's random seed (if this feature is enabled). - Only key ids from 1 to #MBEDTLS_PSA_KEY_SLOT_COUNT are actually used. Since we need to preserve the random seed, avoid using that key slot. Reserve a whole range of key slots just in case something else comes up. This limitation will probably become moot when we implement client separation for key storage.
\file psa_crypto_random_impl.h PSA crypto random generator implementation abstraction.
\file dhm.h This file contains Diffie-Hellman-Merkle (DHM) key exchange definitions and functions. Diffie-Hellman-Merkle (DHM) key exchange is defined in RFC-2631: Diffie-Hellman Key Agreement Method and Public-Key Cryptography Standards (PKCS) #3: Diffie Hellman Key Agreement Standard. RFC-3526: More Modular Exponential (MODP) Diffie-Hellman groups for Internet Key Exchange (IKE) defines a number of standardized Diffie-Hellman groups for IKE. RFC-5114: Additional Diffie-Hellman Groups for Use with IETF Standards defines a number of standardized Diffie-Hellman groups that can be used. \warning The security of the DHM key exchange relies on the proper choice of prime modulus - optimally, it should be a safe prime. The usage of non-safe primes both decreases the difficulty of the underlying discrete logarithm problem and can lead to small subgroup attacks leaking private exponent bits when invalid public keys are used and not detected. This is especially relevant if the same DHM parameters are reused for multiple key exchanges as in static DHM, while the criticality of small-subgroup attacks is lower for ephemeral DHM. \warning For performance reasons, the code does neither perform primality nor safe primality tests, nor the expensive checks for invalid subgroups. Moreover, even if these were performed, non-standardized primes cannot be trusted because of the possibility of backdoors that can't be effectively checked for. \warning Diffie-Hellman-Merkle is therefore a security risk when not using standardized primes generated using a trustworthy ("nothing up my sleeve") method, such as the RFC 3526 / 7919 primes. In the TLS protocol, DH parameters need to be negotiated, so using the default primes systematically is not always an option. If possible, use Elliptic Curve Diffie-Hellman (ECDH), which has better performance, and for which the TLS protocol mandates the use of standard parameters.
\file psa_crypto_its.h Interface of trusted storage that crypto is built on.
The data associated with the uid will not be able to be modified or deleted. Intended to be used to set bits in `psa_storage_create_flags_t`
The major version number of the PSA ITS API. It will be incremented on significant updates that may include breaking changes
The minor version number of the PSA ITS API. It will be incremented in small updates that are unlikely to include breaking changes
\file rsa_alt_helpers.h Context-independent RSA helper functions This module declares some RSA-related helper functions useful when implementing the RSA interface. These functions are provided in a separate compilation unit in order to make it easy for designers of alternative RSA implementations to use them in their own code, as it is conceived that the functionality they provide will be necessary for most complete implementations. End-users of Mbed TLS who are not providing their own alternative RSA implementations should not use these functions directly, and should instead use only the functions declared in rsa.h. The interface provided by this module will be maintained through LTS (Long Term Support) branches of Mbed TLS, but may otherwise be subject to change, and must be considered an internal interface of the library. There are two classes of helper functions: (1) Parameter-generating helpers. These are: - mbedtls_rsa_deduce_primes - mbedtls_rsa_deduce_private_exponent - mbedtls_rsa_deduce_crt Each of these functions takes a set of core RSA parameters and generates some other, or CRT related parameters. (2) Parameter-checking helpers. These are: - mbedtls_rsa_validate_params - mbedtls_rsa_validate_crt They take a set of core or CRT related RSA parameters and check their validity.
\file timing.h Portable interface to timeouts and to the CPU cycle counter
\file debug_internal.h Internal part of the public "debug.h".
TLS 1.2 and 1.3 client-side functions Copyright The Mbed TLS Contributors SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later
\file ssl_debug_helpers.h Automatically generated helper functions for debugging
\file x509_csr.h X.509 certificate signing request parsing and writing
Dependencies
mbedTLS depends on the following libraries: