Documentation

Documentation

Includes

config.h

#include "config.h"
#include "config.h"

MBEDTLS_CONFIG_FILE

#include MBEDTLS_CONFIG_FILE
#include MBEDTLS_CONFIG_FILE

ssl.h

#include "ssl.h"
#include "ssl.h"

cipher.h

#include "cipher.h"
#include "cipher.h"

md5.h

#include "md5.h"
#include "md5.h"

sha1.h

#include "sha1.h"
#include "sha1.h"

sha256.h

#include "sha256.h"
#include "sha256.h"

sha512.h

#include "sha512.h"
#include "sha512.h"

ecjpake.h

#include "ecjpake.h"
#include "ecjpake.h"

Macros

Marco MBEDTLS_SSL_INTERNAL_H

#define MBEDTLS_SSL_INTERNAL_H


      

Marco inline

#define inline __inline


      

Marco MBEDTLS_SSL_MIN_MAJOR_VERSION

#define MBEDTLS_SSL_MIN_MAJOR_VERSION          MBEDTLS_SSL_MAJOR_VERSION_3
/* Determine minimum supported version */

Marco MBEDTLS_SSL_MIN_MINOR_VERSION

#define MBEDTLS_SSL_MIN_MINOR_VERSION          MBEDTLS_SSL_MINOR_VERSION_0


      

Marco MBEDTLS_SSL_MIN_MINOR_VERSION

#define MBEDTLS_SSL_MIN_MINOR_VERSION          MBEDTLS_SSL_MINOR_VERSION_1


      

Marco MBEDTLS_SSL_MIN_MINOR_VERSION

#define MBEDTLS_SSL_MIN_MINOR_VERSION          MBEDTLS_SSL_MINOR_VERSION_2


      

Marco MBEDTLS_SSL_MIN_MINOR_VERSION

#define MBEDTLS_SSL_MIN_MINOR_VERSION          MBEDTLS_SSL_MINOR_VERSION_3


      

Marco MBEDTLS_SSL_MIN_VALID_MINOR_VERSION

#define MBEDTLS_SSL_MIN_VALID_MINOR_VERSION MBEDTLS_SSL_MINOR_VERSION_1


      

Marco MBEDTLS_SSL_MIN_VALID_MAJOR_VERSION

#define MBEDTLS_SSL_MIN_VALID_MAJOR_VERSION MBEDTLS_SSL_MAJOR_VERSION_3


      

Marco MBEDTLS_SSL_MAX_MAJOR_VERSION

#define MBEDTLS_SSL_MAX_MAJOR_VERSION          MBEDTLS_SSL_MAJOR_VERSION_3
/* Determine maximum supported version */

Marco MBEDTLS_SSL_MAX_MINOR_VERSION

#define MBEDTLS_SSL_MAX_MINOR_VERSION          MBEDTLS_SSL_MINOR_VERSION_3


      

Marco MBEDTLS_SSL_MAX_MINOR_VERSION

#define MBEDTLS_SSL_MAX_MINOR_VERSION          MBEDTLS_SSL_MINOR_VERSION_2


      

Marco MBEDTLS_SSL_MAX_MINOR_VERSION

#define MBEDTLS_SSL_MAX_MINOR_VERSION          MBEDTLS_SSL_MINOR_VERSION_1


      

Marco MBEDTLS_SSL_MAX_MINOR_VERSION

#define MBEDTLS_SSL_MAX_MINOR_VERSION          MBEDTLS_SSL_MINOR_VERSION_0


      

Marco MBEDTLS_SSL__ECP_RESTARTABLE

#define MBEDTLS_SSL__ECP_RESTARTABLE


      

Marco MBEDTLS_SSL_INITIAL_HANDSHAKE

#define MBEDTLS_SSL_INITIAL_HANDSHAKE          0


      

Marco MBEDTLS_SSL_RENEGOTIATION_IN_PROGRESS

#define MBEDTLS_SSL_RENEGOTIATION_IN_PROGRESS  1  /* In progress */


      

Marco MBEDTLS_SSL_RENEGOTIATION_DONE

#define MBEDTLS_SSL_RENEGOTIATION_DONE         2  /* Done or aborted */


      

Marco MBEDTLS_SSL_RENEGOTIATION_PENDING

#define MBEDTLS_SSL_RENEGOTIATION_PENDING      3  /* Requested (server only) */


      

Marco MBEDTLS_SSL_RETRANS_PREPARING

#define MBEDTLS_SSL_RETRANS_PREPARING      0
/*
 * DTLS retransmission states, see RFC 6347 4.2.4
 *
 * The SENDING state is merged in PREPARING for initial sends,
 * but is distinct for resends.
 *
 * Note: initial state is wrong for server, but is not used anyway.
 */

Marco MBEDTLS_SSL_RETRANS_SENDING

#define MBEDTLS_SSL_RETRANS_SENDING        1


      

Marco MBEDTLS_SSL_RETRANS_WAITING

#define MBEDTLS_SSL_RETRANS_WAITING        2


      

Marco MBEDTLS_SSL_RETRANS_FINISHED

#define MBEDTLS_SSL_RETRANS_FINISHED       3


      

Marco MBEDTLS_SSL_COMPRESSION_ADD

#define MBEDTLS_SSL_COMPRESSION_ADD         1024


      

Marco MBEDTLS_SSL_COMPRESSION_ADD

#define MBEDTLS_SSL_COMPRESSION_ADD            0


      

Marco MBEDTLS_SSL_MAC_ADD

#define MBEDTLS_SSL_MAC_ADD                48 /* SHA-384 used for HMAC */


      

Marco MBEDTLS_SSL_MAC_ADD

#define MBEDTLS_SSL_MAC_ADD                32 /* SHA-256 used for HMAC */


      

Marco MBEDTLS_SSL_MAC_ADD

#define MBEDTLS_SSL_MAC_ADD                20 /* SHA-1   used for HMAC */


      

Marco MBEDTLS_SSL_MAC_ADD

#define MBEDTLS_SSL_MAC_ADD                16
/* AEAD ciphersuites: GCM and CCM use a 128 bits tag */

Marco MBEDTLS_SSL_PADDING_ADD

#define MBEDTLS_SSL_PADDING_ADD           256


      

Marco MBEDTLS_SSL_PADDING_ADD

#define MBEDTLS_SSL_PADDING_ADD             0


      

Marco MBEDTLS_SSL_PAYLOAD_OVERHEAD

#define MBEDTLS_SSL_PAYLOAD_OVERHEAD ( MBEDTLS_SSL_COMPRESSION_ADD +   \
                                      MBEDTLS_MAX_IV_LENGTH +         \
                                      MBEDTLS_SSL_MAC_ADD +           \
                                      MBEDTLS_SSL_PADDING_ADD         \
                                      )


      

Marco MBEDTLS_SSL_IN_PAYLOAD_LEN

#define MBEDTLS_SSL_IN_PAYLOAD_LEN ( MBEDTLS_SSL_PAYLOAD_OVERHEAD + \
                                    ( MBEDTLS_SSL_IN_CONTENT_LEN ) )


      

Marco MBEDTLS_SSL_OUT_PAYLOAD_LEN

#define MBEDTLS_SSL_OUT_PAYLOAD_LEN ( MBEDTLS_SSL_PAYLOAD_OVERHEAD + \
                                     ( MBEDTLS_SSL_OUT_CONTENT_LEN ) )


      

Marco MBEDTLS_SSL_MAX_BUFFERED_HS

#define MBEDTLS_SSL_MAX_BUFFERED_HS 4
/* The maximum number of buffered handshake messages. */

Marco MBEDTLS_TLS_EXT_ADV_CONTENT_LEN

#define MBEDTLS_TLS_EXT_ADV_CONTENT_LEN (                           \
       (MBEDTLS_SSL_IN_CONTENT_LEN > MBEDTLS_SSL_OUT_CONTENT_LEN)  \
       ? ( MBEDTLS_SSL_OUT_CONTENT_LEN )                           \
       : ( MBEDTLS_SSL_IN_CONTENT_LEN )                            \
       )
/* Maximum length we can advertise as our max content length for
   RFC 6066 max_fragment_length extension negotiation purposes
   (the lesser of both sizes, if they are unequal.)
 */

Marco MBEDTLS_SSL_HEADER_LEN

#define MBEDTLS_SSL_HEADER_LEN 13
/* Note: Even though the TLS record header is only 5 bytes
   long, we're internally using 8 bytes to store the
   implicit sequence number. */

Marco MBEDTLS_SSL_IN_BUFFER_LEN

#define MBEDTLS_SSL_IN_BUFFER_LEN \
   ( ( MBEDTLS_SSL_HEADER_LEN ) + ( MBEDTLS_SSL_IN_PAYLOAD_LEN ) )


      

Marco MBEDTLS_SSL_OUT_BUFFER_LEN

#define MBEDTLS_SSL_OUT_BUFFER_LEN \
   ( ( MBEDTLS_SSL_HEADER_LEN ) + ( MBEDTLS_SSL_OUT_PAYLOAD_LEN ) )


      

Marco MBEDTLS_SSL_COMPRESS_BUFFER_LEN

#define MBEDTLS_SSL_COMPRESS_BUFFER_LEN (                              \
       ( MBEDTLS_SSL_IN_BUFFER_LEN > MBEDTLS_SSL_OUT_BUFFER_LEN )     \
       ? MBEDTLS_SSL_IN_BUFFER_LEN                                    \
       : MBEDTLS_SSL_OUT_BUFFER_LEN                                   \
       )
/* Compression buffer holds both IN and OUT buffers, so should be size of the larger */

Marco MBEDTLS_TLS_EXT_SUPPORTED_POINT_FORMATS_PRESENT

#define MBEDTLS_TLS_EXT_SUPPORTED_POINT_FORMATS_PRESENT (1 << 0)
/*
 * TLS extension flags (for extensions with outgoing ServerHello content
 * that need it (e.g. for RENEGOTIATION_INFO the server already knows because
 * of state of the renegotiation flag, so no indicator is required)
 */

Marco MBEDTLS_TLS_EXT_ECJPAKE_KKPP_OK

#define MBEDTLS_TLS_EXT_ECJPAKE_KKPP_OK                (1 << 1)

      

Functions

Func mbedtls_ssl_sig_hash_set_add

void mbedtls_ssl_sig_hash_set_add( mbedtls_ssl_sig_hash_set_t *set,
                                  mbedtls_pk_type_t sig_alg,
                                  mbedtls_md_type_t md_alg );
/* Add a signature-hash-pair to a signature-hash set */

Func mbedtls_ssl_sig_hash_set_const_hash

void mbedtls_ssl_sig_hash_set_const_hash( mbedtls_ssl_sig_hash_set_t *set,
                                         mbedtls_md_type_t md_alg );
/* Allow exactly one hash algorithm for each signature. */

Func mbedtls_ssl_transform_free

void mbedtls_ssl_transform_free( mbedtls_ssl_transform *transform );
/**
 * \brief           Free referenced items in an SSL transform context and clear
 *                  memory
 *
 * \param transform SSL transform context
 */

Func mbedtls_ssl_handshake_free

void mbedtls_ssl_handshake_free( mbedtls_ssl_context *ssl );
/**
 * \brief           Free referenced items in an SSL handshake context and clear
 *                  memory
 *
 * \param ssl       SSL context
 */

Func mbedtls_ssl_handshake_client_step

int mbedtls_ssl_handshake_client_step( mbedtls_ssl_context *ssl );


      

Func mbedtls_ssl_handshake_server_step

int mbedtls_ssl_handshake_server_step( mbedtls_ssl_context *ssl );


      

Func mbedtls_ssl_handshake_wrapup

void mbedtls_ssl_handshake_wrapup( mbedtls_ssl_context *ssl );


      

Func mbedtls_ssl_send_fatal_handshake_failure

int mbedtls_ssl_send_fatal_handshake_failure( mbedtls_ssl_context *ssl );


      

Func mbedtls_ssl_reset_checksum

void mbedtls_ssl_reset_checksum( mbedtls_ssl_context *ssl );


      

Func mbedtls_ssl_derive_keys

int mbedtls_ssl_derive_keys( mbedtls_ssl_context *ssl );


      

Func mbedtls_ssl_handle_message_type

int mbedtls_ssl_handle_message_type( mbedtls_ssl_context *ssl );


      

Func mbedtls_ssl_prepare_handshake_record

int mbedtls_ssl_prepare_handshake_record( mbedtls_ssl_context *ssl );


      

Func mbedtls_ssl_update_handshake_status

void mbedtls_ssl_update_handshake_status( mbedtls_ssl_context *ssl );


      

Func mbedtls_ssl_read_record

int mbedtls_ssl_read_record( mbedtls_ssl_context *ssl,
                            unsigned update_hs_digest );
/**
 * \brief       Update record layer
 *
 *              This function roughly separates the implementation
 *              of the logic of (D)TLS from the implementation
 *              of the secure transport.
 *
 * \param  ssl              The SSL context to use.
 * \param  update_hs_digest This indicates if the handshake digest
 *                          should be automatically updated in case
 *                          a handshake message is found.
 *
 * \return      0 or non-zero error code.
 *
 * \note        A clarification on what is called 'record layer' here
 *              is in order, as many sensible definitions are possible:
 *
 *              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.
 *
 * \note        The above tries to give a conceptual picture of the
 *              record layer, but the current implementation deviates
 *              from it in some places. For example, our implementation of
 *              the update functionality through mbedtls_ssl_read_record
 *              discards datagrams depending on the current state, which
 *              wouldn't fall under the record layer's responsibility
 *              following the above definition.
 *
 */

Func mbedtls_ssl_fetch_input

int mbedtls_ssl_fetch_input( mbedtls_ssl_context *ssl, size_t nb_want );


      

Func mbedtls_ssl_write_handshake_msg

int mbedtls_ssl_write_handshake_msg( mbedtls_ssl_context *ssl );


      

Func mbedtls_ssl_write_record

int mbedtls_ssl_write_record( mbedtls_ssl_context *ssl, uint8_t force_flush );


      

Func mbedtls_ssl_flush_output

int mbedtls_ssl_flush_output( mbedtls_ssl_context *ssl );


      

Func mbedtls_ssl_parse_certificate

int mbedtls_ssl_parse_certificate( mbedtls_ssl_context *ssl );


      

Func mbedtls_ssl_write_certificate

int mbedtls_ssl_write_certificate( mbedtls_ssl_context *ssl );


      

Func mbedtls_ssl_parse_change_cipher_spec

int mbedtls_ssl_parse_change_cipher_spec( mbedtls_ssl_context *ssl );


      

Func mbedtls_ssl_write_change_cipher_spec

int mbedtls_ssl_write_change_cipher_spec( mbedtls_ssl_context *ssl );


      

Func mbedtls_ssl_parse_finished

int mbedtls_ssl_parse_finished( mbedtls_ssl_context *ssl );


      

Func mbedtls_ssl_write_finished

int mbedtls_ssl_write_finished( mbedtls_ssl_context *ssl );


      

Func mbedtls_ssl_optimize_checksum

void mbedtls_ssl_optimize_checksum( mbedtls_ssl_context *ssl,
                           const mbedtls_ssl_ciphersuite_t *ciphersuite_info );


      

Func mbedtls_ssl_psk_derive_premaster

int mbedtls_ssl_psk_derive_premaster( mbedtls_ssl_context *ssl, mbedtls_key_exchange_type_t key_ex );


      

Func mbedtls_ssl_set_calc_verify_md

int mbedtls_ssl_set_calc_verify_md( mbedtls_ssl_context *ssl, int md );


      

Func mbedtls_ssl_check_curve

int mbedtls_ssl_check_curve( const mbedtls_ssl_context *ssl, mbedtls_ecp_group_id grp_id );


      

Func mbedtls_ssl_check_sig_hash

int mbedtls_ssl_check_sig_hash( const mbedtls_ssl_context *ssl,
                               mbedtls_md_type_t md );


      

Func mbedtls_ssl_check_cert_usage

int mbedtls_ssl_check_cert_usage( const mbedtls_x509_crt *cert,
                         const mbedtls_ssl_ciphersuite_t *ciphersuite,
                         int cert_endpoint,
                         uint32_t *flags );
/*
 * Check usage of a certificate wrt extensions:
 * keyUsage, extendedKeyUsage (later), and nSCertType (later).
 *
 * Warning: cert_endpoint is the endpoint of the cert (ie, of our peer when we
 * check a cert we received from them)!
 *
 * Return 0 if everything is OK, -1 if not.
 */

Func mbedtls_ssl_write_version

void mbedtls_ssl_write_version( int major, int minor, int transport,
                       unsigned char ver[2] );


      

Func mbedtls_ssl_read_version

void mbedtls_ssl_read_version( int *major, int *minor, int transport,
                      const unsigned char ver[2] );


      

Func mbedtls_ssl_send_flight_completed

void mbedtls_ssl_send_flight_completed( mbedtls_ssl_context *ssl );


      

Func mbedtls_ssl_recv_flight_completed

void mbedtls_ssl_recv_flight_completed( mbedtls_ssl_context *ssl );


      

Func mbedtls_ssl_resend

int mbedtls_ssl_resend( mbedtls_ssl_context *ssl );


      

Func mbedtls_ssl_flight_transmit

int mbedtls_ssl_flight_transmit( mbedtls_ssl_context *ssl );


      

Func mbedtls_ssl_dtls_replay_check

int mbedtls_ssl_dtls_replay_check( mbedtls_ssl_context *ssl );


      

Func mbedtls_ssl_dtls_replay_update

void mbedtls_ssl_dtls_replay_update( mbedtls_ssl_context *ssl );


      

Func return

return( diff );


      

Func mbedtls_ssl_get_key_exchange_md_ssl_tls

int mbedtls_ssl_get_key_exchange_md_ssl_tls( mbedtls_ssl_context *ssl,
                                       unsigned char *output,
                                       unsigned char *data, size_t data_len );


      

Func mbedtls_ssl_get_key_exchange_md_tls1_2

int mbedtls_ssl_get_key_exchange_md_tls1_2( mbedtls_ssl_context *ssl,
                                           unsigned char *hash, size_t *hashlen,
                                           unsigned char *data, size_t data_len,
                                           mbedtls_md_type_t md_alg );

      

Vars

Variable ecrs_n

size_t ecrs_n;


      

Variable out_msg_seq

unsigned int out_msg_seq;


      

Variable in_msg_seq

unsigned int in_msg_seq;
/*!<  Outgoing handshake sequence number */

Variable char

unsigned char *verify_cookie;


      

Variable char

unsigned char verify_cookie_len;
/*!<  Cli: HelloVerifyRequest cookie
                                              Srv: unused                    */

Variable retransmit_timeout

uint32_t retransmit_timeout;


      

Variable char

unsigned char retransmit_state;
/*!<  Current value of timeout       */

Variable flight

mbedtls_ssl_flight_item *flight;
/*!<  Retransmission state           */

Variable cur_msg

mbedtls_ssl_flight_item *cur_msg;
/*!<  Current outgoing flight        */

Variable char

unsigned char *cur_msg_p;
/*!<  Current message in flight      */

Variable in_flight_start_seq

unsigned int in_flight_start_seq;
/*!<  Position in current message    */

Variable alt_transform_out

mbedtls_ssl_transform *alt_transform_out;
/*!<  Minimum message sequence in the
                                              flight being received          */

Variable char

unsigned char alt_out_ctr[8];
/*!<  Alternative transform for
                                              resending messages             */

Variable uint16_t

uint16_t mtu;


      

Variable mbedtls_md5_context

mbedtls_md5_context fin_md5;


      

Variable mbedtls_sha1_context

mbedtls_sha1_context fin_sha1;


      

Variable mbedtls_sha256_context

mbedtls_sha256_context fin_sha256;


      

Variable mbedtls_sha512_context

mbedtls_sha512_context fin_sha512;


      

Variable update_checksum

void (*update_checksum)(mbedtls_ssl_context *, const unsigned char *, size_t);


      

Variable calc_verify

void (*calc_verify)(mbedtls_ssl_context *, unsigned char *);


      

Variable calc_finished

void (*calc_finished)(mbedtls_ssl_context *, unsigned char *, int);


      

Variable tls_prf

int (*tls_prf)(const unsigned char *, size_t, const char *,
                   const unsigned char *, size_t,
                   unsigned char *, size_t);


      

Variable pmslen

size_t pmslen;


      

Variable char

unsigned char randbytes[64];


      

Variable char

unsigned char premaster[MBEDTLS_PREMASTER_SIZE];
/*!<  random bytes            */

Variable resume

int resume;


      

Variable max_major_ver

int max_major_ver;
/*!<  session resume indicator*/

Variable max_minor_ver

int max_minor_ver;
/*!< max. major version client*/

Variable cli_exts

int cli_exts;
/*!< max. minor version client*/

Variable new_session_ticket

int new_session_ticket;


      

Variable extended_ms

int extended_ms;


      

Variable async_in_progress

unsigned int async_in_progress : 1;


      

Variable user_async_ctx

void *user_async_ctx;
/** Asynchronous operation context. This field is meant for use by the
     * asynchronous operation callbacks (mbedtls_ssl_config::f_async_sign_start,
     * mbedtls_ssl_config::f_async_decrypt_start,
     * mbedtls_ssl_config::f_async_resume, mbedtls_ssl_config::f_async_cancel).
     * The library does not use it internally. */

Variable mbedtls_md_type_t

mbedtls_md_type_t mbedtls_ssl_sig_hash_set_find( mbedtls_ssl_sig_hash_set_t *set,
                                                mbedtls_pk_type_t sig_alg );
/* Find an entry in a signature-hash set matching a given hash algorithm. */

Variable char

unsigned char mbedtls_ssl_sig_from_pk( mbedtls_pk_context *pk );


      

Variable char

unsigned char mbedtls_ssl_sig_from_pk_alg( mbedtls_pk_type_t type );


      

Variable mbedtls_pk_type_t

mbedtls_pk_type_t mbedtls_ssl_pk_alg_from_sig( unsigned char sig );


      

Variable mbedtls_md_type_t

mbedtls_md_type_t mbedtls_ssl_md_alg_from_hash( unsigned char hash );


      

Variable char

unsigned char mbedtls_ssl_hash_from_md_alg( int md );

      

Consts

Types

Typedefs

Typedef mbedtls_ssl_hs_buffer

typedef struct mbedtls_ssl_hs_buffer mbedtls_ssl_hs_buffer;