mbedtls_ssl_handshake() function

SSL context

Send an alert message

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.

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

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.

Notify the peer that the connection is being closed

Free referenced items in an SSL context and clear memory

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

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.

Return the result of the certificate verification

Return the name of the current ciphersuite

Free referenced items in an SSL handshake context and clear memory

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.

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.

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

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

Find the preferred hash for a given signature algorithm.

Validate cipher suite against config in SSL context.

Set the EC J-PAKE password for current handshake.

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

Return the current TLS version

Set the timer callbacks (Mandatory for DTLS.)

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.

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

Given an SSL context and its associated configuration, write the TLS 1.2 specific extensions of the ClientHello message.

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.

Return the (D)TLS protocol version negotiated in the given connection.

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

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.

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 own certificate and key for the current handshake

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

Set DN hints sent to client in CertificateRequest message

Set authmode for the current handshake.

Get the name of the negotiated Application Layer Protocol. This function should be called after the handshake is completed.

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

Return the id of the current ciphersuite

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

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

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.

Allow or disallow packing of multiple handshake records within a single datagram.

Set the pre-shared Key (PSK) for the current handshake.

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

Return the SSL configuration structure associated with the given SSL context.

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)

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.

Set the EC J-PAKE opaque password for current handshake.