This section describes the M2MB APIs for Transport Layer Security (TLS) and the Secure Socket Layer (SSL). More...

#define	M2MB_SSL_INVALID_HANDLE (0)

#define	M2MB_SSL_MAX_CIPHER_COUNT 54

#define	M2MB_SSL_MAX_CERT_NAME_LEN 64

#define	M2MB_SSL_MAX_SNI_NAME_LEN (64)

#define	M2MB_SSL_CIPHER_MAX 0x003FFFFFFFFFFFFF

#define	M2MB_MAX_CERTS 10

#define	M2MB_SSL_MAX_CA_LIST 10

enum	M2MB_SSL_PROTOCOL_VERSION_E { M2MB_SSL_PROTOCOL_TLS_1_0, M2MB_SSL_PROTOCOL_TLS_1_1, M2MB_SSL_PROTOCOL_TLS_1_2, M2MB_SSL_PROTOCOL_DTLS_1_0, M2MB_SSL_PROTOCOL_DTLS_1_2, M2MB_SSL_PROTOCOL_VER_MAX }
	SSL protocol SET Configuration enumeration. More...

enum	M2MB_SSL_CONF_ID { M2MB_SSL_CONF_INVALID = 0, M2MB_SSL_CONF_PROTOCOL = 1, M2MB_SSL_CONF_CACERT = 2, M2MB_SSL_CONF_CERT = 3, M2MB_SSL_CONF_CIPHER = 4, M2MB_SSL_CONF_TX_MAX_FRAG_LEN = 5, M2MB_SSL_CONF_SNI = 6, M2MB_SSL_CONF_DOMAIN = 7, M2MB_SSL_CONF_MAX_FRAG_LEN = 8, M2MB_SSL_CONF_SERVER_AUTH = 9, M2MB_SSL_CONF_TIME_VALIDATE = 10, M2MB_SSL_CONF_GET_PEEK = 11, M2MB_SSL_CONF_GET_CONN_STATUS = 12, M2MB_SSL_CONF_GET_CERT_LOAD_STATUS = 13, M2MB_SSL_CONF_GET_CA_CERT_LOAD_STATUS = 14 }

enum	M2MB_SSL_CIPHER_SUITE_E { M2MB_TLS_PSK_WITH_RC4_128_SHA, M2MB_TLS_PSK_WITH_3DES_EDE_CBC_SHA, M2MB_TLS_PSK_WITH_AES_128_CBC_SHA, M2MB_TLS_PSK_WITH_AES_256_CBC_SHA, M2MB_TLS_PSK_WITH_AES_128_GCM_SHA256, M2MB_TLS_PSK_WITH_AES_256_GCM_SHA384, M2MB_TLS_PSK_WITH_AES_128_CBC_SHA256, M2MB_TLS_PSK_WITH_AES_256_CBC_SHA384, M2MB_TLS_RSA_WITH_AES_128_CBC_SHA, M2MB_TLS_DHE_RSA_WITH_AES_128_CBC_SHA, M2MB_TLS_RSA_WITH_AES_256_CBC_SHA, M2MB_TLS_DHE_RSA_WITH_AES_256_CBC_SHA, M2MB_TLS_RSA_WITH_AES_128_CBC_SHA256, M2MB_TLS_RSA_WITH_AES_256_CBC_SHA256, M2MB_TLS_DHE_RSA_WITH_AES_128_CBC_SHA256, M2MB_TLS_DHE_RSA_WITH_AES_256_CBC_SHA256, M2MB_TLS_RSA_WITH_AES_128_GCM_SHA256, M2MB_TLS_RSA_WITH_AES_256_GCM_SHA384, M2MB_TLS_DHE_RSA_WITH_AES_128_GCM_SHA256, M2MB_TLS_DHE_RSA_WITH_AES_256_GCM_SHA384, M2MB_TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA, M2MB_TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA, M2MB_TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA, M2MB_TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA, M2MB_TLS_ECDH_RSA_WITH_AES_128_CBC_SHA, M2MB_TLS_ECDH_RSA_WITH_AES_256_CBC_SHA, M2MB_TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA, M2MB_TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA, M2MB_TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256, M2MB_TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384, M2MB_TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA256, M2MB_TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA384, M2MB_TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256, M2MB_TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384, M2MB_TLS_ECDH_RSA_WITH_AES_128_CBC_SHA256, M2MB_TLS_ECDH_RSA_WITH_AES_256_CBC_SHA384, M2MB_TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256, M2MB_TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384, M2MB_TLS_ECDH_ECDSA_WITH_AES_128_GCM_SHA256, M2MB_TLS_ECDH_ECDSA_WITH_AES_256_GCM_SHA384, M2MB_TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256, M2MB_TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384, M2MB_TLS_ECDH_RSA_WITH_AES_128_GCM_SHA256, M2MB_TLS_ECDH_RSA_WITH_AES_256_GCM_SHA384, M2MB_TLS_RSA_WITH_AES_128_CCM, M2MB_TLS_RSA_WITH_AES_256_CCM, M2MB_TLS_DHE_RSA_WITH_AES_128_CCM, M2MB_TLS_DHE_RSA_WITH_AES_256_CCM, M2MB_TLS_RSA_WITH_AES_128_CCM_8, M2MB_TLS_RSA_WITH_AES_256_CCM_8, M2MB_TLS_DHE_RSA_WITH_AES_128_CCM_8, M2MB_TLS_DHE_RSA_WITH_AES_256_CCM_8, M2MB_TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256, M2MB_TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256, M2MB_TLS_DHE_RSA_WITH_CHACHA20_POLY1305_SHA256 }
	TLS ciphersuites enum. More...

enum	M2MB_SSL_AUTH_TYPE_E { M2MB_SSL_AUTH_NONE, M2MB_SSL_AUTH_REQUIRED, M2MB_SSL_AUTH_OPTIONAL }
	SSL authentication types enum. More...

enum	M2MB_SSL_SSL_ROLE_E { M2MB_SSL_SSL_ROLE_SERVER_E = 0, M2MB_SSL_SSL_ROLE_CLIENT_E = 1 }
	SSL object role. More...

typedef enum M2MB_SSL_PROTOCOL_VERSION_E	M2MB_SSL_PROTOCOL_VERSION_E
	SSL protocol SET Configuration enumeration. More...

typedef enum M2MB_SSL_CONF_ID	M2MB_SSL_CONF_ID_E

typedef union M2MB_SSL_CONF_PARAMS	M2MB_SSL_CONF_PARAMS_T

typedef HANDLE	M2MB_SSL_CTXT_HANDLE
	SSL context handle. This is obtained from m2mb_ssl_open API and then used in subsequent SSL APIs. More...

typedef enum M2MB_SSL_CIPHER_SUITE_E	M2MB_SSL_CIPHER_SUITE_E
	TLS ciphersuites enum. More...

typedef enum M2MB_SSL_AUTH_TYPE_E	M2MB_SSL_AUTH_TYPE_E
	SSL authentication types enum. More...

typedef enum M2MB_SSL_SSL_ROLE_E	M2MB_SSL_SSL_ROLE_E
	SSL object role. More...

typedef struct M2MB_SSL_OPEN_PARAMS	M2MB_SSL_OPEN_PARAMS_T

typedef struct M2MB_SSL_CONFIG_VERIFY_POLICY	M2MB_SSL_CONFIG_VERIFY_POLICY_T
	Structure to specify the certificate verification policy. More...

typedef struct M2MB_SSL_CONFIG	M2MB_SSL_CONFIG_T
	Structure to configure an SSL connection. More...

M2MB_STATUS_T	m2mb_ssl_open (HANDLE handle, M2MB_SSL_OPEN_PARAMS_T openParams)
	Initialize SSL TLS context. More...

M2MB_STATUS_T	m2mb_ssl_set_cfg (HANDLE handle, M2MB_SSL_CONF_ID_E conf_id, M2MB_SSL_CONF_PARAMS_T *conf_params)
	Set SSL configuration on the previously created SSL context. More...

M2MB_STATUS_T	m2mb_ssl_get_cfg (HANDLE handle, M2MB_SSL_CONF_ID_E conf_id, M2MB_SSL_CONF_PARAMS_T *conf_params)
	Get SSL configuration on the previously created SSL context. More...

M2MB_STATUS_T	m2mb_ssl_close (HANDLE handle)
	deletes an m2mb SSL context created during m2mb_ssl_open() More...

M2MB_STATUS_T	m2mb_ssl_connect (HANDLE handle, M2MB_SOCKET_BSD_SOCKET socket_fd)
	Performs SSL Client connection. More...

INT32	m2mb_ssl_write (HANDLE handle, void *buf, UINT32 len)
	Writes data to the SSL connection. More...

INT32	m2mb_ssl_read (HANDLE handle, void *buf, UINT32 len)
	Read len bytes from SSL connection into buf. More...

M2MB_STATUS_T	m2mb_ssl_accept (M2MB_SSL_CTXT_HANDLE sslSvrContextHndl, M2MB_SOCKET_BSD_SOCKET socket_fd, M2MB_SSL_CTXT_HANDLE *sslClientCtxHndl)
	Accepts an incoming SSL connection from the client. More...

Detailed Description

This section describes the M2MB APIs for Transport Layer Security (TLS) and the Secure Socket Layer (SSL).

SSL/TLS module provides secure connection at L4 layer. To establish a secure connection the following steps are to be followed.

To allocate resource for the SSL connection, user calls the m2mb_ssl_open. The handle returned in this API is used in other APIs to operate on the same connection.
To secure higher layer protocols like HTTP, MQTT, the handle returned in the above API is passed in the open API of respective protocols.
To configure SSL parameter user must use m2mb_ssl_set_cfg.
User needs to create the socket either UDP/TCP by calling socket API i.e. m2mb_socket_bsd_socket.
To connect to a server, it calls m2mb_socket_bsd_connect to connect at TCP level and calls m2mb_ssl_connect with the SSL handle from the m2mb_ssl_open and the socket descriptor returned in m2mb_socket_bsd_socket API to initiate the SSL connection.
If user wants a secured server, it uses the BSD socket API to listen and use the m2mb_socket_bsd_accept to accept the TCP connection and then calls m2mb_ssl_accept API to accept secured connection by passing the client socket descriptor.

To establish a secure connection the following steps are followed.

As client:
----------

SSL Client

To connect to a server, use the following API sequence:

First to allocate resources for SSL connection, m2mb_ssl_open should get called with role as M2MB_SSL_SSL_ROLE_CLIENT_E.
To secure higher layer protocols like HTTP, MQTT, the handle returned in the above API is passed in the open API of respective protocols.
To configure SSL parameter user must use m2mb_ssl_set_cfg.
User needs to create the socket either TCP by calling socket API i.e. m2mb_socket_bsd_socket. The socket descripter is used subsequent APIs.
use m2mb_socket_bsd_connect to connect at TCP level using socket descripter.
use m2mb_ssl_connect to do ssl handshake with the SSL handle and the socket descriptor.
- For information of the ssl connection information m2mb_ssl_get_cfg can be used.

As server:

SSL Server

To start a server, use the following API sequence:
- First to allocate resources for SSL connection, m2mb_ssl_open should get 
called with M2MB_SSL_SSL_ROLE_SERVER_E flag in M2MB_SSL_OPEN_PARAMS_T.
- To configure SSL parameter user must use m2mb_ssl_set_cfg.
- User needs to create the socket either UDP/TCP by calling socket API  i.e. m2mb_socket_bsd_socket
- Next user needs to bind should be performed on specified local port and IP
address by using m2mb_socket_bsd_bind. This might be optional.
- Next user needs to listen for connections on that socket by calling socket API i.e m2mb_socket_bsd_listen.
- when client connectes to the ssl server, The ssl server must do m2mb_bsd_socket_accept,
    to accept the TCP connection.
- Server will use the newly accepted client socket id for doing ssl handshake 
    by calling the m2mb_ssl_accepts API.
- For information of the ssl connection information m2mb_ssl_get_cfg can be used.

Macro Definition Documentation

◆ M2MB_MAX_CERTS

#define M2MB_MAX_CERTS 10

Definition at line 106 of file m2mb_ssl.h.

◆ M2MB_SSL_CIPHER_MAX

#define M2MB_SSL_CIPHER_MAX 0x003FFFFFFFFFFFFF

Definition at line 105 of file m2mb_ssl.h.

◆ M2MB_SSL_INVALID_HANDLE

#define M2MB_SSL_INVALID_HANDLE (0)

Macro for invalid SSL handle

Definition at line 101 of file m2mb_ssl.h.

◆ M2MB_SSL_MAX_CA_LIST

#define M2MB_SSL_MAX_CA_LIST 10

Macro for mavimum number of CA certs

Definition at line 107 of file m2mb_ssl.h.

◆ M2MB_SSL_MAX_CERT_NAME_LEN

#define M2MB_SSL_MAX_CERT_NAME_LEN 64

Macro for Maximum length of name of a certificate

Definition at line 103 of file m2mb_ssl.h.

◆ M2MB_SSL_MAX_CIPHER_COUNT

#define M2MB_SSL_MAX_CIPHER_COUNT 54

Macro for Maximum ciphers

Definition at line 102 of file m2mb_ssl.h.

◆ M2MB_SSL_MAX_SNI_NAME_LEN

#define M2MB_SSL_MAX_SNI_NAME_LEN (64)

Macro for Maximum length of SNI name

Definition at line 104 of file m2mb_ssl.h.

Typedef Documentation

◆ M2MB_SSL_AUTH_TYPE_E

typedef enum M2MB_SSL_AUTH_TYPE_E M2MB_SSL_AUTH_TYPE_E

SSL authentication types enum.

◆ M2MB_SSL_CIPHER_SUITE_E

typedef enum M2MB_SSL_CIPHER_SUITE_E M2MB_SSL_CIPHER_SUITE_E

TLS ciphersuites enum.

◆ M2MB_SSL_CONF_ID_E

typedef enum M2MB_SSL_CONF_ID M2MB_SSL_CONF_ID_E

◆ M2MB_SSL_CONF_PARAMS_T

typedef union M2MB_SSL_CONF_PARAMS M2MB_SSL_CONF_PARAMS_T

◆ M2MB_SSL_CONFIG_T

typedef struct M2MB_SSL_CONFIG M2MB_SSL_CONFIG_T

Structure to configure an SSL connection.

◆ M2MB_SSL_CONFIG_VERIFY_POLICY_T

typedef struct M2MB_SSL_CONFIG_VERIFY_POLICY M2MB_SSL_CONFIG_VERIFY_POLICY_T

Structure to specify the certificate verification policy.

◆ M2MB_SSL_CTXT_HANDLE

typedef HANDLE M2MB_SSL_CTXT_HANDLE

SSL context handle.
This is obtained from m2mb_ssl_open API and then used in subsequent SSL APIs.

Definition at line 165 of file m2mb_ssl.h.

◆ M2MB_SSL_OPEN_PARAMS_T

typedef struct M2MB_SSL_OPEN_PARAMS M2MB_SSL_OPEN_PARAMS_T

◆ M2MB_SSL_PROTOCOL_VERSION_E

typedef enum M2MB_SSL_PROTOCOL_VERSION_E M2MB_SSL_PROTOCOL_VERSION_E

SSL protocol SET Configuration enumeration.

This enum defines macros for various SET Configuration for MDNS module.

◆ M2MB_SSL_SSL_ROLE_E

typedef enum M2MB_SSL_SSL_ROLE_E M2MB_SSL_SSL_ROLE_E

SSL object role.

Enumeration Type Documentation

◆ M2MB_SSL_AUTH_TYPE_E

enum M2MB_SSL_AUTH_TYPE_E

SSL authentication types enum.

Enumerator
M2MB_SSL_AUTH_NONE
M2MB_SSL_AUTH_REQUIRED
M2MB_SSL_AUTH_OPTIONAL

Definition at line 230 of file m2mb_ssl.h.

◆ M2MB_SSL_CIPHER_SUITE_E

enum M2MB_SSL_CIPHER_SUITE_E

TLS ciphersuites enum.

Enumerator
M2MB_TLS_PSK_WITH_RC4_128_SHA	0: Cipher TLS_PSK_WITH_RC4_128_SHA.
M2MB_TLS_PSK_WITH_3DES_EDE_CBC_SHA	1: Cipher TLS_PSK_WITH_3DES_EDE_CBC_SHA
M2MB_TLS_PSK_WITH_AES_128_CBC_SHA	2: Cipher TLS_PSK_WITH_AES_128_CBC_SHA
M2MB_TLS_PSK_WITH_AES_256_CBC_SHA	3: Cipher TLS_PSK_WITH_AES_256_CBC_SHA
M2MB_TLS_PSK_WITH_AES_128_GCM_SHA256	4: Cipher TLS_PSK_WITH_AES_128_GCM_SHA256
M2MB_TLS_PSK_WITH_AES_256_GCM_SHA384	5: Cipher TLS_PSK_WITH_AES_256_GCM_SHA384
M2MB_TLS_PSK_WITH_AES_128_CBC_SHA256	6: Cipher TLS_PSK_WITH_AES_128_CBC_SHA256
M2MB_TLS_PSK_WITH_AES_256_CBC_SHA384	7: Cipher TLS_PSK_WITH_AES_256_CBC_SHA384
M2MB_TLS_RSA_WITH_AES_128_CBC_SHA	8: Cipher TLS_RSA_WITH_AES_128_CBC_SHA
M2MB_TLS_DHE_RSA_WITH_AES_128_CBC_SHA	9: Cipher TLS_DHE_RSA_WITH_AES_128_CBC_SHA
M2MB_TLS_RSA_WITH_AES_256_CBC_SHA	10: Cipher TLS_RSA_WITH_AES_256_CBC_SHA
M2MB_TLS_DHE_RSA_WITH_AES_256_CBC_SHA	11: Cipher TLS_DHE_RSA_WITH_AES_256_CBC_SHA
M2MB_TLS_RSA_WITH_AES_128_CBC_SHA256	12: Cipher TLS_RSA_WITH_AES_128_CBC_SHA256
M2MB_TLS_RSA_WITH_AES_256_CBC_SHA256	13: Cipher TLS_RSA_WITH_AES_256_CBC_SHA256
M2MB_TLS_DHE_RSA_WITH_AES_128_CBC_SHA256	14: Cipher TLS_DHE_RSA_WITH_AES_128_CBC_SHA256
M2MB_TLS_DHE_RSA_WITH_AES_256_CBC_SHA256	15: Cipher TLS_DHE_RSA_WITH_AES_256_CBC_SHA256
M2MB_TLS_RSA_WITH_AES_128_GCM_SHA256	16: Cipher TLS_RSA_WITH_AES_128_GCM_SHA256
M2MB_TLS_RSA_WITH_AES_256_GCM_SHA384	17: Cipher TLS_RSA_WITH_AES_256_GCM_SHA384
M2MB_TLS_DHE_RSA_WITH_AES_128_GCM_SHA256	18: Cipher TLS_DHE_RSA_WITH_AES_128_GCM_SHA256
M2MB_TLS_DHE_RSA_WITH_AES_256_GCM_SHA384	19: Cipher TLS_DHE_RSA_WITH_AES_256_GCM_SHA384
M2MB_TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA	20: Cipher TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA
M2MB_TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA	21: Cipher TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA
M2MB_TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA	22: Cipher TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA
M2MB_TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA	23: Cipher TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA
M2MB_TLS_ECDH_RSA_WITH_AES_128_CBC_SHA	24: Cipher TLS_ECDH_RSA_WITH_AES_128_CBC_SHA
M2MB_TLS_ECDH_RSA_WITH_AES_256_CBC_SHA	25: Cipher TLS_ECDH_RSA_WITH_AES_256_CBC_SHA
M2MB_TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA	26: Cipher TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
M2MB_TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA	27: Cipher TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA
M2MB_TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256	28: Cipher TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256
M2MB_TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384	29: Cipher TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384
M2MB_TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA256	30: Cipher TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA256
M2MB_TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA384	31: Cipher TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA384
M2MB_TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256	32: Cipher TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256
M2MB_TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384	33: Cipher TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384
M2MB_TLS_ECDH_RSA_WITH_AES_128_CBC_SHA256	34: Cipher TLS_ECDH_RSA_WITH_AES_128_CBC_SHA256
M2MB_TLS_ECDH_RSA_WITH_AES_256_CBC_SHA384	35: Cipher TLS_ECDH_RSA_WITH_AES_256_CBC_SHA384
M2MB_TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256	36: Cipher TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
M2MB_TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384	37: Cipher TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
M2MB_TLS_ECDH_ECDSA_WITH_AES_128_GCM_SHA256	38: Cipher TLS_ECDH_ECDSA_WITH_AES_128_GCM_SHA256
M2MB_TLS_ECDH_ECDSA_WITH_AES_256_GCM_SHA384	39: Cipher TLS_ECDH_ECDSA_WITH_AES_256_GCM_SHA384
M2MB_TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256	40: Cipher TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
M2MB_TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384	41: Cipher TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
M2MB_TLS_ECDH_RSA_WITH_AES_128_GCM_SHA256	42: Cipher TLS_ECDH_RSA_WITH_AES_128_GCM_SHA256
M2MB_TLS_ECDH_RSA_WITH_AES_256_GCM_SHA384	43: Cipher TLS_ECDH_RSA_WITH_AES_256_GCM_SHA384
M2MB_TLS_RSA_WITH_AES_128_CCM	44: Cipher TLS_RSA_WITH_AES_128_CCM
M2MB_TLS_RSA_WITH_AES_256_CCM	45: Cipher TLS_RSA_WITH_AES_256_CCM
M2MB_TLS_DHE_RSA_WITH_AES_128_CCM	46: Cipher TLS_DHE_RSA_WITH_AES_128_CCM
M2MB_TLS_DHE_RSA_WITH_AES_256_CCM	47: Cipher TLS_DHE_RSA_WITH_AES_256_CCM
M2MB_TLS_RSA_WITH_AES_128_CCM_8	48: Cipher TLS_RSA_WITH_AES_128_CCM_8
M2MB_TLS_RSA_WITH_AES_256_CCM_8	49: Cipher TLS_RSA_WITH_AES_256_CCM_8
M2MB_TLS_DHE_RSA_WITH_AES_128_CCM_8	50: Cipher TLS_DHE_RSA_WITH_AES_128_CCM_8
M2MB_TLS_DHE_RSA_WITH_AES_256_CCM_8	51: Cipher TLS_DHE_RSA_WITH_AES_256_CCM_8
M2MB_TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256	52: Cipher TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256
M2MB_TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256	53: Cipher TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256
M2MB_TLS_DHE_RSA_WITH_CHACHA20_POLY1305_SHA256	54: Cipher TLS_DHE_RSA_WITH_CHACHA20_POLY1305_SHA256

Definition at line 169 of file m2mb_ssl.h.

◆ M2MB_SSL_CONF_ID

enum M2MB_SSL_CONF_ID

Enumerator
M2MB_SSL_CONF_INVALID	Invalid config param
M2MB_SSL_CONF_PROTOCOL	To Set SSL Protocol Vertion
M2MB_SSL_CONF_CACERT	To Set SSL CA Certificate
M2MB_SSL_CONF_CERT	To Set SSL Certificate
M2MB_SSL_CONF_CIPHER	To Set Cipher Information
M2MB_SSL_CONF_TX_MAX_FRAG_LEN	To set the tx max fragment length.
M2MB_SSL_CONF_SNI	To Set the SNI
M2MB_SSL_CONF_DOMAIN	To Set The Domain
M2MB_SSL_CONF_MAX_FRAG_LEN	To Set the Max Fragment Length
M2MB_SSL_CONF_SERVER_AUTH	To Enable/Disable server Authentication
M2MB_SSL_CONF_TIME_VALIDATE	To Enable/Disable Time validation Not supported
M2MB_SSL_CONF_GET_PEEK	To get the PEEK data
M2MB_SSL_CONF_GET_CONN_STATUS	To get the SSL connection status
M2MB_SSL_CONF_GET_CERT_LOAD_STATUS	To get the certificate loading status
M2MB_SSL_CONF_GET_CA_CERT_LOAD_STATUS	To get the certificate loading status

Definition at line 126 of file m2mb_ssl.h.

◆ M2MB_SSL_PROTOCOL_VERSION_E

enum M2MB_SSL_PROTOCOL_VERSION_E

SSL protocol SET Configuration enumeration.

This enum defines macros for various SET Configuration for MDNS module.

Enumerator
M2MB_SSL_PROTOCOL_TLS_1_0	SSL protocol TLS 1.0
M2MB_SSL_PROTOCOL_TLS_1_1	SSL protocol TLS 1.1
M2MB_SSL_PROTOCOL_TLS_1_2	SSL protocol TLS 1.2
M2MB_SSL_PROTOCOL_DTLS_1_0	SSL protocol TLS 1.0
M2MB_SSL_PROTOCOL_DTLS_1_2	SSL protocol DTLS 1.2
M2MB_SSL_PROTOCOL_VER_MAX

Definition at line 116 of file m2mb_ssl.h.

◆ M2MB_SSL_SSL_ROLE_E

enum M2MB_SSL_SSL_ROLE_E

SSL object role.

Enumerator
M2MB_SSL_SSL_ROLE_SERVER_E	Server role.
M2MB_SSL_SSL_ROLE_CLIENT_E	Client role.

Definition at line 238 of file m2mb_ssl.h.

Function Documentation

◆ m2mb_ssl_accept()

M2MB_STATUS_T m2mb_ssl_accept	(	M2MB_SSL_CTXT_HANDLE	sslSvrContextHndl,
		M2MB_SOCKET_BSD_SOCKET	socket_fd,
		M2MB_SSL_CTXT_HANDLE *	sslClientCtxHndl
	)

Accepts an incoming SSL connection from the client.

It creates a client context, sets configuration passed to the incoming client context, links a secure socket connection id to socket fd and accepts the incoming client connection. This should be called only by a server SSL object. This will respond to the incoming client hello message and complete the SSL handshake.

Parameters

[in]	sslSvrContextHndl	specifies the SSL context of the server previously created through m2mb_ssl_open
[in]	socket_fd	specifies the socket fd for the incoming client
[out]	sslClientCtxHndl	client context handle

Returns: Returns M2MB_OK on success, a different value on error.

Note: <Notes>

Example

     int main()
     {
       
     M2MB_STATUS_T status;
     HANDLE sslContextHndl;
     ...
     
     //role: M2MB_SSL_SSL_ROLE_E
     M2MB_SSL_OPEN_PARAMS_T openParams;
     openParams.role = M2MB_SSL_SSL_ROLE_SERVER_E;
     
     M2MB_SSL_CTXT_HANDLE sslContextHndl; 
     status = m2mb_ssl_open(&sslContextHndl, &openParams); 
     if(status != M2MB_OK)
             return M2MB_ERROR;
     ...
     // configure the certificate 
     M2MB_SSL_CONF_PARAMS_T conf_params = {0};
     conf_params.cert = "client_certificate";
     
     status = m2mb_ssl_set_cfg(sslContextHndl, M2MB_SSL_CONF_CERT, &conf_params );
     if( M2MB_OK != status ) 
             return M2MB_ERROR;...
     ...
     //socket descriptor :sd
     // socket creation : family belongs to Socket Address Families defined in m2mb_socket.h
     M2MB_SOCKET_BSD_SOCKADDR_IN_T from = {0};
    INT32 fromlen;
     sd = m2mb_socket_bsd_socket( (INT32 )family, M2MB_SOCKET_BSD_SOCK_STREAM , 0);
     if(sd == -1)
         return -1;
     if (m2mb_socket_bsd_bind(sd, addr, addrlen) == -1)
             return M2MB_ERROR;
     if (m2mb_socket_bsd_listen(sd, backlog) == -1)
             return M2MB_ERROR;
INT32 client_sd = m2mb_socket_bsd_accept(sd, 
                (M2MB_SOCKET_BSD_SOCKADDR_T *)&from, &fromlen);
if(client_sd == -1)
    return M2MB_ERROR;
     status = m2mb_ssl_accept( sslContextHndl, client_sd, &pSsl_ClientInst->sslCtxHndl);
     if (status != M2MB_OK)
     {
        return M2MB_ERROR;
     }
}

◆ m2mb_ssl_close()

M2MB_STATUS_T m2mb_ssl_close ( HANDLE handle )

deletes an m2mb SSL context created during m2mb_ssl_open()

Parameters

[in] handle

Returns: Returns M2MB_OK on success, a different value on error.

Note: <Notes>

Example

int main()
{
  M2MB_STATUS_T status;
  HANDLE sslContextHndl;
  ...
  
  //role: M2MB_SSL_SSL_ROLE_E
  M2MB_SSL_OPEN_PARAMS_T openParams;
  params.role = M2MB_SSL_SSL_ROLE_CLIENT_E;
  
  M2MB_SSL_CTXT_HANDLE sslContextHndl; 
  status = m2mb_ssl_open(&sslContextHndl, &openParams); 
  if(status != M2MB_OK)
          return M2MB_ERROR;
  
  status = m2mb_ssl_close(sslContextHndl);
  if (status != M2MB_OK)
    return M2MB_ERROR;
}

◆ m2mb_ssl_connect()

M2MB_STATUS_T m2mb_ssl_connect	(	HANDLE	handle,
		M2MB_SOCKET_BSD_SOCKET	socket_fd
	)

Performs SSL Client connection.

Performs SSL client connection

Parameters

[in]	handle	Specifies the sslContextHndl previously returned by m2mb_ssl_open
[in]	socket_fd	Specifies the socket ID to make the connection.

Returns: Returns M2MB_OK on success, a different value on error.

Note: Socket must be created and socket connect must be successful prior to this call.

Example

   int main()
{
   M2MB_STATUS_T status;
   HANDLE sslContextHndl;
   ...
   
   //role: M2MB_SSL_SSL_ROLE_E
   M2MB_SSL_OPEN_PARAMS_T openParams;
   params.role = M2MB_SSL_SSL_ROLE_CLIENT_E;
   
   M2MB_SSL_CTXT_HANDLE sslContextHndl; 
   status = m2mb_ssl_open(&sslContextHndl, &openParams); 
   if(status != M2MB_OK)
           return M2MB_ERROR;
   ...
   // configure the certificate 
M2MB_SSL_CONF_PARAMS_T conf_params = {0};
conf_params.cert = "client_certificate";
status = m2mb_ssl_set_cfg(sslContextHndl, M2MB_SSL_CONF_CERT, &conf_params );
if( M2MB_OK != status ) 
   ...
   ...
    //socket descriptor :sd
    // socket creation : family belongs to Socket Address Families defined in m2mb_socket.h
   sd = m2mb_socket_bsd_socket( (INT32 )family, M2MB_SOCKET_BSD_SOCK_STREAM , 0);
   ...
   // connect to server
   status = m2mb_socket_bsd_connect( sd, (struct M2MB_SOCKET_BSD_SOCKADDR *)&serv_addr, sizeof(serv_addr))
   if (status != M2MB_OK)
{
    return M2MB_ERROR;
}
   ...
   status = m2mb_ssl_connect(sslContextHndl, sd);
   if (status != M2MB_OK)
{
    return M2MB_ERROR;
}
   ...
}

◆ m2mb_ssl_get_cfg()

M2MB_STATUS_T m2mb_ssl_get_cfg	(	HANDLE	handle,
		M2MB_SSL_CONF_ID_E	conf_id,
		M2MB_SSL_CONF_PARAMS_T *	conf_params
	)

Get SSL configuration on the previously created SSL context.

Get the SSL/TLS configuration given the specified configuration id.

Parameters

[in]	handle	Specify the SSL context pointer created previously during m2mb_ssl_open();
[in]	conf_id	Specify the confd id as defined in M2MB_SSL_CONF_ID_E.
[out]	conf_params	pointer to structure of type M2MB_SSL_CONF_PARAMS_T

Returns: Returns M2MB_OK on success, a different value on error.

Note: <Notes>

Example

int main()
{
      M2MB_SSL_CTXT_HANDLE sslContextHndl; 
      //role: M2MB_SSL_SSL_ROLE_E
      M2MB_SSL_OPEN_PARAMS_T openParams = {0};
      openParams.role = M2MB_SSL_SSL_ROLE_CLIENT_E;
      
      status = m2mb_ssl_open(&sslContextHndl, &openParams); 
      ...
      
      // configure the certificate 
    M2MB_SSL_CONF_PARAMS_T conf_params = { 0 };
    conf_params.cert = "client_certificate";
    
    status = m2mb_ssl_get_cfg(sslContextHndl, M2MB_SSL_CONF_CERT, &conf_params );
    if( M2MB_OK != status )  
      
      M2MB_SSL_CONF_PARAMS_T sslConfParams = { 0 };
      // To check the connection status                               
      status = m2mb_ssl_get_cfg(sslContextHndl , M2MB_SSL_CONF_GET_CONN_STATUS, &sslConfParams); 
      if ( (status != M2MB_OK) || ( sslConfParams.connStatus != TRUE))
      {
              M2MB_DBG_INFO("\r\n client event %d\n", sslConfParams.connStatus);
              return M2MB_ERROR;
      }
}

◆ m2mb_ssl_open()

M2MB_STATUS_T m2mb_ssl_open	(	HANDLE *	handle,
		M2MB_SSL_OPEN_PARAMS_T *	openParams
	)

Initialize SSL TLS context.

Creates SSL TLS context that which will be used in all the future calls to m2mb SSL module

Parameters

[out]	handle	hndl will be filled on successful completion
[in]	openParams	pointer to openParams structure

Returns: Returns M2MB_OK on success, a different value on error.

Note: <Notes>

Example

int main()
{
  M2MB_STATUS_T status;
  HANDLE sslContextHndl;
  ...
  
  //role: M2MB_SSL_SSL_ROLE_E
  M2MB_SSL_OPEN_PARAMS_T openParams;
  params.role = M2MB_SSL_SSL_ROLE_CLIENT_E;
  
  M2MB_SSL_CTXT_HANDLE sslContextHndl; 
  status = m2mb_ssl_open(&sslContextHndl, &openParams); 
  if(status != M2MB_OK)
          return M2MB_ERROR;
}

◆ m2mb_ssl_read()

INT32 m2mb_ssl_read	(	HANDLE	handle,
		void *	buf,
		UINT32	len
	)

Read len bytes from SSL connection into buf.

Parameters

[in]	handle	Specifies the sslContextHndl previously created during m2mb_ssl_open
[out]	buf	Specifies the read buffer
[in]	len	Specifies the input len

Returns: On success, number of bytes read

Note: <Notes>

Example

int main()
{
   M2MB_SSL_CTXT_HANDLE sslContextHndl;
   M2MB_SOCKET_BSD_SOCKET sd;
   UINT8* buf;
   UINT32 numBytes;
   
   M2MB_OS_RESULT status;
   
   //role: M2MB_SSL_SSL_ROLE_E
   M2MB_SSL_OPEN_PARAMS_T openParams;
   openParams.role = M2MB_SSL_SSL_ROLE_CLIENT_E;
                   
   M2MB_SSL_CTXT_HANDLE sslContextHndl; 
   status = m2mb_ssl_open(&sslContextHndl, &openParams); 
   ...
   
   // configure the certificate 
M2MB_SSL_CONF_PARAMS_T conf_params = {0};
conf_params.cert = "client_certificate";
status = m2mb_ssl_set_cfg(sslContextHndl, M2MB_SSL_CONF_CERT, &conf_params );
if( M2MB_OK != status ) 
   ...
   //socket descriptor :sd
   // socket creation : family belongs to Socket Address Families defined in m2mb_socket.h
   sd = m2mb_socket_bsd_socket( (INT32 )family, M2MB_SOCKET_BSD_SOCK_STREAM , 0);
   ...
   // connect to server
   status = m2mb_socket_bsd_connect( sd, (struct M2MB_SOCKET_BSD_SOCKADDR *)&serv_addr, sizeof(serv_addr));
   if (status != M2MB_OK)
   {
           return M2MB_ERROR;
   }
   ...
   status = m2mb_ssl_connect(sslContextHndl, sd);
   if (status != M2MB_OK)
   {
       return M2MB_ERROR;
   }
   ...
   //numBytes to be read
   status = m2mb_ssl_read(sslContextHndl, (void *)buf, numBytes );
   if (status != M2MB_OK)
{
    return M2MB_ERROR;
}
   ...
 }

◆ m2mb_ssl_set_cfg()

M2MB_STATUS_T m2mb_ssl_set_cfg	(	HANDLE	handle,
		M2MB_SSL_CONF_ID_E	conf_id,
		M2MB_SSL_CONF_PARAMS_T *	conf_params
	)

Set SSL configuration on the previously created SSL context.

Set an SSL TLS configuration with specified configuration parameters and sets the config on the provided SSL context handle.

Parameters

[in]	handle	Specify the SSL context pointer created previously during m2mb_ssl_open();
[in]	conf_id	Specify the confd id as defined below:

0 : Invalid config param 1 : To Set SSL Protocol Vertion 2 : To Set SSL CA Certificate 3 : To Set SSL Certificate 4 : To Set Cipher Information 5 : To set tx max fragment length
6 : To Set the SNI 7 : To set the Domain 8 : To set max fragment length 9.: To Enable/Disable server Authentication 10 : To Enable/Disable Time Validation ( not supported )

Parameters

[in] conf_params pointer to structure of type M2MB_SSL_CONF_PARAMS_T The values in the structure must be set as per the conf_id

Returns: Returns M2MB_OK on success, a different value on error.

Note: <Notes>

Example

int main()
{
  M2MB_STATUS_T status;
  HANDLE sslContextHndl;
  ...
  //role: M2MB_SSL_SSL_ROLE_E
  M2MB_SSL_OPEN_PARAMS_T openParams;
  openParams.role = M2MB_SSL_SSL_ROLE_CLIENT_E;
  ...
  
  status = m2mb_ssl_open(&sslContextHndl, &openParams); 
if( M2MB_OK != status ) 
          return M2MB_ERROR;
// configure the certificate 
M2MB_SSL_CONF_PARAMS_T conf_params = {0};
conf_params.cert = "client_certificate";
status = m2mb_ssl_set_cfg(sslContextHndl, M2MB_SSL_CONF_CERT, &conf_params );
if( M2MB_OK != status ) 
          return M2MB_ERROR;
// configure the cipher suite 
M2MB_SSL_CONF_PARAMS_T conf_params_cipher = {0};
    //To set Cipher Suite to 
//    Bit 5 : "TLS_PSK_WITH_AES_128_GCM_SHA256".
//    Bit 9: Cipher TLS_RSA_WITH_AES_128_CBC_SHA
//    Bit 21: Cipher TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA
    
//    cipherval in Binary: 1 0000 0000 0001 0001 0000    
//    cipherval in hex: 0x100110
conf_params_cipher.cipher =  0x100110;
status = m2mb_ssl_set_cfg(sslContextHndl, M2MB_SSL_CONF_CIPHER, &conf_params );
if( M2MB_OK != status ) 
          return M2MB_ERROR;
    
}

◆ m2mb_ssl_write()

INT32 m2mb_ssl_write	(	HANDLE	handle,
		void *	buf,
		UINT32	len
	)

Writes data to the SSL connection.

Parameters

[in]	handle	Specifies the sslContextHndl
[in]	buf	Specifies the input buffer
[in]	len	Specifies the input len

Returns: On success, number of bytes written

Note: <Notes>

Example

int main()
{
   M2MB_STATUS_T status;
   HANDLE sslContextHndl;
   ...
   
   //role: M2MB_SSL_SSL_ROLE_E
   M2MB_SSL_OPEN_PARAMS_T openParams;
   openParams.role = M2MB_SSL_SSL_ROLE_CLIENT_E;
   
   M2MB_SSL_CTXT_HANDLE sslContextHndl; 
   status = m2mb_ssl_open(&sslContextHndl, &openParams); 
   if(status != M2MB_OK)
           return M2MB_ERROR;
   ...
   // configure the certificate 
M2MB_SSL_CONF_PARAMS_T conf_params = {0};
conf_params.cert = "client_certificate";
status = m2mb_ssl_set_cfg(sslContextHndl, M2MB_SSL_CONF_CERT, &conf_params );
if( M2MB_OK != status ) 
   ...
   ...
    //socket descriptor :sd
    // socket creation : family belongs to Socket Address Families defined in m2mb_socket.h
   sd = m2mb_socket_bsd_socket( (INT32 )family, M2MB_SOCKET_BSD_SOCK_STREAM , 0);
   ...
   // connet to server
   status = m2mb_socket_bsd_connect( sd, (struct M2MB_SOCKET_BSD_SOCKADDR *)&serv_addr, sizeof(serv_addr));
   if (status != M2MB_OK)
{
    return M2MB_ERROR;
}
   ...
   status = m2mb_ssl_connect(sslContextHndl, sd);
   if (status != M2MB_OK)
{
    return M2MB_ERROR;
}
   ...
   status = m2mb_ssl_write( sslContextHndl, buf, sizeof(buf) );
   if (status != M2MB_OK)
{
    return M2MB_ERROR;
}
   ...
}