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.

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.

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

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

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

Return the result of the certificate verification

Return the name of the current ciphersuite

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.

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

Free referenced items in an SSL handshake context and clear memory

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_max_frag_len() \sa mbedtls_ssl_get_record_expansion()

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.

Validate cipher suite against config in SSL context.

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 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 Note: Can be NULL in case no certificate was sent during the handshake. Different calls for the same connection can return the same or different pointers for the same certificate and even a different certificate altogether. The peer cert CAN change in a single connection if renegotiation is performed.

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

Set the timer callbacks (Mandatory for DTLS.)

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

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.

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.