mbedtls_ssl_setup() function

SSL context

SSL configuration to use

Send an alert message

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.

Free referenced items in an SSL handshake context and clear memory

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.

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, 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.

Perform a single step of 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, 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.

Return the current maximum outgoing record payload in bytes. This takes into account the config.h setting \c MBEDTLS_SSL_OUT_CONTENT_LEN, the configured and negotiated max fragment length extension if used, and for DTLS the path MTU as configured and current record expansion. \sa mbedtls_ssl_set_mtu() \sa mbedtls_ssl_get_output_max_frag_len() \sa mbedtls_ssl_get_input_max_frag_len() \sa mbedtls_ssl_get_record_expansion()

Validate cipher suite against config in SSL context.

Initialize an SSL context Just makes the context ready for mbedtls_ssl_setup() or mbedtls_ssl_free()

Reset an already initialized SSL context for re-use while retaining application-set variables, function pointers and data.

Get a pointer to the current session structure, for example to serialize it. \warning Ownership of the session remains with the SSL context, and the returned pointer is only guaranteed to be valid until the next API call operating on the same \p ssl context. \see mbedtls_ssl_session_save()

Set the underlying BIO callbacks for write, read and read-with-timeout.

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().

Request resumption of session (client-side only) Session data is copied from presented session structure. \sa mbedtls_ssl_get_session()

Set authmode for the current handshake.

Set the timer callbacks (Mandatory for DTLS.)

Set own certificate and key for the current handshake

Set the data required to verify peer certificate for the current handshake

Save session in order to resume it later (client-side only) Session data is copied to presented session structure. \sa mbedtls_ssl_set_session()

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 or #MBEDTLS_ERR_SSL_CLIENT_RECONNECT, 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 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.

Notify the peer that the connection is being closed

Free referenced items in an SSL context and clear memory

Check if there is data already read from the underlying transport but not yet processed.

Return the number of application data bytes remaining to be read from the current record.

Return the result of the certificate verification

Return the name of the current ciphersuite

Return the current SSL version (SSLv3/TLSv1/etc)

Return the (maximum) number of bytes added by the record layer: header + encryption/MAC overhead (inc. padding)

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.

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.

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.