TLS Transport

API to create and register TLS transport.The functions below are used to create TLS transport and register the transport to the framework. More...

Data Structures
struct	pjsip_tls_on_accept_fail_param
struct	pjsip_tls_on_verify_param
struct	pjsip_tls_setting
struct	pjsip_tls_state_info

Macros
#define	PJSIP_SSL_DEFAULT_METHOD   PJSIP_TLSV1_METHOD
#define	PJSIP_SSL_DEFAULT_PROTO

Enumerations
enum	pjsip_ssl_method {   PJSIP_SSL_UNSPECIFIED_METHOD = 0 , PJSIP_SSLV2_METHOD = 20 , PJSIP_SSLV3_METHOD = 30 , PJSIP_TLSV1_METHOD = 31 ,   PJSIP_TLSV1_1_METHOD = 32 , PJSIP_TLSV1_2_METHOD = 33 , PJSIP_TLSV1_3_METHOD = 34 , PJSIP_SSLV23_METHOD = 23 }

Functions
void	pjsip_tls_setting_default (pjsip_tls_setting *tls_opt)
void	pjsip_tls_setting_copy (pj_pool_t *pool, pjsip_tls_setting *dst, const pjsip_tls_setting *src)
void	pjsip_tls_setting_wipe_keys (pjsip_tls_setting *opt)
pj_status_t	pjsip_tls_transport_start (pjsip_endpoint *endpt, const pjsip_tls_setting *opt, const pj_sockaddr_in *local, const pjsip_host_port *a_name, unsigned async_cnt, pjsip_tpfactory **p_factory)
pj_status_t	pjsip_tls_transport_start2 (pjsip_endpoint *endpt, const pjsip_tls_setting *opt, const pj_sockaddr *local, const pjsip_host_port *a_name, unsigned async_cnt, pjsip_tpfactory **p_factory)
pj_status_t	pjsip_tls_transport_lis_start (pjsip_tpfactory *factory, const pj_sockaddr *local, const pjsip_host_port *a_name)
pj_status_t	pjsip_tls_transport_restart (pjsip_tpfactory *factory, const pj_sockaddr *local, const pjsip_host_port *a_name)

Detailed Description

Macro Definition Documentation

PJSIP_SSL_DEFAULT_METHOD

#define PJSIP_SSL_DEFAULT_METHOD   PJSIP_TLSV1_METHOD

The default SSL method to be used by PJSIP. Default is PJSIP_TLSV1_METHOD

PJSIP_SSL_DEFAULT_PROTO

#define PJSIP_SSL_DEFAULT_PROTO

Value:

                                     (PJ_SSL_SOCK_PROTO_TLS1 | \
                                     PJ_SSL_SOCK_PROTO_TLS1_1 | \
                                     PJ_SSL_SOCK_PROTO_TLS1_2)

The default enabled SSL proto to be used. Default is all protocol above TLSv1 (TLSv1 & TLS v1.1 & TLS v1.2).

Enumeration Type Documentation

pjsip_ssl_method

enum pjsip_ssl_method

SSL protocol method constants.

Enumerator
PJSIP_SSL_UNSPECIFIED_METHOD	Default protocol method.
PJSIP_SSLV2_METHOD	Use SSLv2 method.
PJSIP_SSLV3_METHOD	Use SSLv3 method.
PJSIP_TLSV1_METHOD	Use TLSv1 method.
PJSIP_TLSV1_1_METHOD	Use TLSv1_1 method.
PJSIP_TLSV1_2_METHOD	Use TLSv1_2 method.
PJSIP_TLSV1_3_METHOD	Use TLSv1_3 method.
PJSIP_SSLV23_METHOD	Use SSLv23 method.

Function Documentation

pjsip_tls_setting_default()

void pjsip_tls_setting_default

(

pjsip_tls_setting *

tls_opt

)

Initialize TLS setting with default values.

Parameters

tls_opt

The TLS setting to be initialized.

References PJ_INLINE, pj_memset(), PJ_QOS_TYPE_BEST_EFFORT, PJ_TRUE, PJSIP_SSL_DEFAULT_PROTO, PJSIP_TLS_TRANSPORT_REUSEADDR, pjsip_tls_setting::proto, pjsip_tls_setting::qos_ignore_error, pjsip_tls_setting::qos_type, pjsip_tls_setting::reuse_addr, and pjsip_tls_setting::sockopt_ignore_error.

pjsip_tls_setting_copy()

void pjsip_tls_setting_copy	(	pj_pool_t *	pool,
		pjsip_tls_setting *	dst,
		const pjsip_tls_setting *	src
	)

Copy TLS setting.

Parameters

pool	The pool to duplicate strings etc.
dst	Destination structure.
src	Source structure.

References pjsip_tls_setting::ca_buf, pjsip_tls_setting::ca_list_file, pjsip_tls_setting::ca_list_path, pjsip_tls_setting::cert_buf, pjsip_tls_setting::cert_file, pjsip_tls_setting::ciphers, pjsip_tls_setting::ciphers_num, pjsip_tls_setting::curves, pjsip_tls_setting::curves_num, pjsip_tls_setting::entropy_path, pjsip_tls_setting::password, PJ_INLINE, pj_memcpy(), pj_pool_calloc(), pj_strdup(), pj_strdup_with_null(), pjsip_tls_setting::privkey_buf, pjsip_tls_setting::privkey_file, and pjsip_tls_setting::sigalgs.

pjsip_tls_setting_wipe_keys()

void pjsip_tls_setting_wipe_keys

(

pjsip_tls_setting *

opt

)

Wipe out certificates and keys in the TLS setting buffer.

Parameters

opt	TLS setting.

pjsip_tls_transport_start()

pj_status_t pjsip_tls_transport_start	(	pjsip_endpoint *	endpt,
		const pjsip_tls_setting *	opt,
		const pj_sockaddr_in *	local,
		const pjsip_host_port *	a_name,
		unsigned	async_cnt,
		pjsip_tpfactory **	p_factory
	)

Register support for SIP TLS transport by creating TLS listener on the specified address and port. This function will create an instance of SIP TLS transport factory and register it to the transport manager.

See also pjsip_tls_transport_start2() which supports IPv6.

Parameters

endpt	The SIP endpoint.
opt	Optional TLS settings.
local	Optional local address to bind, or specify the address to bind the server socket to. Both IP interface address and port fields are optional. If IP interface address is not specified, socket will be bound to PJ_INADDR_ANY. If port is not specified, socket will be bound to any port selected by the operating system.
a_name	Optional published address, which is the address to be advertised as the address of this SIP transport. If this argument is NULL, then the bound address will be used as the published address.
async_cnt	Number of simultaneous asynchronous accept() operations to be supported. It is recommended that the number here corresponds to the number of processors in the system (or the number of SIP worker threads).
p_factory	Optional pointer to receive the instance of the SIP TLS transport factory just created.

Returns

PJ_SUCCESS when the transport has been successfully started and registered to transport manager, or the appropriate error code.

pjsip_tls_transport_start2()

pj_status_t pjsip_tls_transport_start2	(	pjsip_endpoint *	endpt,
		const pjsip_tls_setting *	opt,
		const pj_sockaddr *	local,
		const pjsip_host_port *	a_name,
		unsigned	async_cnt,
		pjsip_tpfactory **	p_factory
	)

Variant of pjsip_tls_transport_start() that supports IPv6. To instantiate IPv6 listener, set the address family of the "local" argument to IPv6 (the host and port part may be left unspecified if not desired, i.e. by filling them with zeroes).

Parameters

endpt	The SIP endpoint.
opt	Optional TLS settings.
local	Optional local address to bind, or specify the address to bind the server socket to. Both IP interface address and port fields are optional. If IP interface address is not specified, socket will be bound to any address. If port is not specified, socket will be bound to any port selected by the operating system.
a_name	Optional published address, which is the address to be advertised as the address of this SIP transport. If this argument is NULL, then the bound address will be used as the published address.
async_cnt	Number of simultaneous asynchronous accept() operations to be supported. It is recommended that the number here corresponds to the number of processors in the system (or the number of SIP worker threads).
p_factory	Optional pointer to receive the instance of the SIP TLS transport factory just created.

Returns

PJ_SUCCESS when the transport has been successfully started and registered to transport manager, or the appropriate error code.

pjsip_tls_transport_lis_start()

pj_status_t pjsip_tls_transport_lis_start	(	pjsip_tpfactory *	factory,
		const pj_sockaddr *	local,
		const pjsip_host_port *	a_name
	)

Start the TLS listener, if the listener is not started yet. This is useful to start the listener manually, if listener was not started when PJSIP_TLS_TRANSPORT_DONT_CREATE_LISTENER is set to 0.

Parameters

factory	The SIP TLS transport factory.
local	The address where the listener should be bound to. Both IP interface address and port fields are optional. If IP interface address is not specified, socket will be bound to PJ_INADDR_ANY. If port is not specified, socket will be bound to any port selected by the operating system.
a_name	The published address for the listener. If this argument is NULL, then the bound address will be used as the published address.

Returns

PJ_SUCCESS when the listener has been successfully started.

pjsip_tls_transport_restart()

pj_status_t pjsip_tls_transport_restart	(	pjsip_tpfactory *	factory,
		const pj_sockaddr *	local,
		const pjsip_host_port *	a_name
	)

Restart the TLS listener. This will close the listener socket and recreate the socket based on the config used when starting the transport.

Parameters

factory	The SIP TLS transport factory.
local	The address where the listener should be bound to. Both IP interface address and port fields are optional. If IP interface address is not specified, socket will be bound to PJ_INADDR_ANY. If port is not specified, socket will be bound to any port selected by the operating system.
a_name	The published address for the listener. If this argument is NULL, then the bound address will be used as the published address.

Returns

PJ_SUCCESS when the listener has been successfully restarted.

References PJ_END_DECL.