Group PJSIP_TRANSPORT_TLS

group PJSIP_TRANSPORT_TLS

API to create and register TLS transport.

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

Defines

PJSIP_SSL_DEFAULT_METHOD

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

PJSIP_SSL_DEFAULT_PROTO

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

Enums

enum pjsip_ssl_method

SSL protocol method constants.

Values:

enumerator PJSIP_SSL_UNSPECIFIED_METHOD

Default protocol method.

enumerator PJSIP_SSLV2_METHOD

Use SSLv2 method.

enumerator PJSIP_SSLV3_METHOD

Use SSLv3 method.

enumerator PJSIP_TLSV1_METHOD

Use TLSv1 method.

enumerator PJSIP_TLSV1_1_METHOD

Use TLSv1_1 method.

enumerator PJSIP_TLSV1_2_METHOD

Use TLSv1_2 method.

enumerator PJSIP_TLSV1_3_METHOD

Use TLSv1_3 method.

enumerator PJSIP_SSLV23_METHOD

Use SSLv23 method.

Functions

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.

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.

void pjsip_tls_setting_wipe_keys(pjsip_tls_setting *opt)

Wipe out certificates and keys in the TLS setting buffer.

Parameters:

opt – TLS setting.

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. It can be set using IP address or hostname. 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.

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. It can be set using IP address or hostname. 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.

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. It can be set using IP address or hostname. 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.

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. It can be set using IP address or hostname. 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.

struct pjsip_tls_on_accept_fail_param
#include <sip_transport_tls.h>

This structure describe the parameter passed from on_accept_fail_cb().

Public Members

const pj_sockaddr_t *local_addr

Local address of the fail accept operation of the TLS listener.

const pj_sockaddr_t *remote_addr

Remote address of the fail accept operation of the TLS listener.

pj_status_t status

Error status of the fail accept operation of the TLS listener.

pj_status_t last_native_err

Last error code returned by native SSL backend. Note that this may be zero, if the failure is not SSL related (e.g: accept rejection).

struct pjsip_tls_on_verify_param
#include <sip_transport_tls.h>

This structure describe the parameter passed from on_verify_cb().

Public Members

const pj_sockaddr_t *local_addr

Describes local address.

const pj_sockaddr_t *remote_addr

Describes remote address.

pjsip_transport_dir tp_dir

Describes transport direction.

pj_ssl_cert_info *local_cert_info

Describes active local certificate info.

pj_ssl_cert_info *remote_cert_info

Describes active remote certificate info.

pj_ssl_sock_t *ssock

The SSL socket instance.

struct pjsip_tls_setting
#include <sip_transport_tls.h>

TLS transport settings.

Public Members

pj_str_t ca_list_file

Certificate of Authority (CA) list file.

pj_str_t ca_list_path

Certificate of Authority (CA) list directory path.

pj_str_t cert_file

Public endpoint certificate file, which will be used as client- side certificate for outgoing TLS connection, and server-side certificate for incoming TLS connection.

pj_str_t privkey_file

Optional private key of the endpoint certificate to be used.

pj_ssl_cert_buffer ca_buf

Certificate of Authority (CA) buffer. If ca_list_file, ca_list_path, cert_file or privkey_file are set, this setting will be ignored.

pj_ssl_cert_buffer cert_buf

Public endpoint certificate buffer, which will be used as client- side certificate for outgoing TLS connection, and server-side certificate for incoming TLS connection. If ca_list_file, ca_list_path, cert_file or privkey_file are set, this setting will be ignored.

pj_ssl_cert_buffer privkey_buf

Optional private key buffer of the endpoint certificate to be used. If ca_list_file, ca_list_path, cert_file or privkey_file are set, this setting will be ignored.

pj_str_t password

Password to open private key.

pjsip_ssl_method method

TLS protocol method from pjsip_ssl_method. In the future, this field might be deprecated in favor of proto field. For now, this field is only applicable only when proto field is set to zero.

Default is PJSIP_SSL_UNSPECIFIED_METHOD (0), which in turn will use PJSIP_SSL_DEFAULT_METHOD, which default value is PJSIP_TLSV1_METHOD.

pj_uint32_t proto

TLS protocol type from pj_ssl_sock_proto. Use this field to enable specific protocol type. Use bitwise OR operation to combine the protocol type.

Default is PJSIP_SSL_DEFAULT_PROTO.

unsigned ciphers_num

Number of ciphers contained in the specified cipher preference. If this is set to zero, then default cipher list of the backend will be used.

Default: 0 (zero).

pj_ssl_cipher *ciphers

Ciphers and order preference. The pj_ssl_cipher_get_availables() can be used to check the available ciphers supported by backend.

unsigned curves_num

Number of curves contained in the specified curve preference. If this is set to zero, then default curve list of the backend will be used.

Default: 0 (zero).

pj_ssl_curve *curves

Curves and order preference. The pj_ssl_curve_get_availables() can be used to check the available curves supported by backend.

pj_str_t sigalgs

The supported signature algorithms. Set the sigalgs string using this form: “<DIGEST>+<ALGORITHM>:<DIGEST>+<ALGORITHM>” Digests are: “RSA”, “DSA” or “ECDSA” Algorithms are: “MD5”, “SHA1”, “SHA224”, “SHA256”, “SHA384”, “SHA512” Example: “ECDSA+SHA256:RSA+SHA256”

pj_ssl_entropy_t entropy_type

Reseed random number generator. For type PJ_SSL_ENTROPY_FILE, parameter entropy_path must be set to a file. For type PJ_SSL_ENTROPY_EGD, parameter entropy_path must be set to a socket.

Default value is PJ_SSL_ENTROPY_NONE.

pj_str_t entropy_path

When using a file/socket for entropy PJ_SSL_ENTROPY_EGD or PJ_SSL_ENTROPY_FILE, entropy_path must contain the path to entropy socket/file.

Default value is an empty string.

pj_bool_t verify_server

Specifies TLS transport behavior on the server TLS certificate verification result:

  • If verify_server is disabled (set to PJ_FALSE), TLS transport will just notify the application via pjsip_tp_state_callback with state PJSIP_TP_STATE_CONNECTED regardless TLS verification result.

  • If verify_server is enabled (set to PJ_TRUE), TLS transport will be shutdown and application will be notified with state PJSIP_TP_STATE_DISCONNECTED whenever there is any TLS verification error, otherwise PJSIP_TP_STATE_CONNECTED will be notified.

In any cases, application can inspect pjsip_tls_state_info in the callback to see the verification detail.

Default value is PJ_FALSE.

pj_bool_t verify_client

Specifies TLS transport behavior on the client TLS certificate verification result:

  • If verify_client is disabled (set to PJ_FALSE), TLS transport will just notify the application via pjsip_tp_state_callback with state PJSIP_TP_STATE_CONNECTED regardless TLS verification result.

  • If verify_client is enabled (set to PJ_TRUE), TLS transport will be shutdown and application will be notified with state PJSIP_TP_STATE_DISCONNECTED whenever there is any TLS verification error, otherwise PJSIP_TP_STATE_CONNECTED will be notified.

In any cases, application can inspect pjsip_tls_state_info in the callback to see the verification detail.

Default value is PJ_FALSE.

pj_bool_t require_client_cert

When acting as server (incoming TLS connections), reject inocming connection if client doesn’t supply a TLS certificate.

This setting corresponds to SSL_VERIFY_FAIL_IF_NO_PEER_CERT flag. Default value is PJ_FALSE.

pj_time_val timeout

TLS negotiation timeout to be applied for both outgoing and incoming connection. If both sec and msec member is set to zero, the SSL negotiation doesn’t have a timeout.

unsigned initial_timeout

Intial timeout interval to be applied to incoming transports (i.e. server side) when no valid data received after a successful connection.

Default: PJSIP_TRANSPORT_SERVER_IDLE_TIME_FIRST

pj_bool_t reuse_addr

Should SO_REUSEADDR be used for the listener socket. Default value is PJSIP_TLS_TRANSPORT_REUSEADDR.

pj_qos_type qos_type

QoS traffic type to be set on this transport. When application wants to apply QoS tagging to the transport, it’s preferable to set this field rather than qos_param fields since this is more portable.

Default value is PJ_QOS_TYPE_BEST_EFFORT.

pj_qos_params qos_params

Set the low level QoS parameters to the transport. This is a lower level operation than setting the qos_type field and may not be supported on all platforms.

By default all settings in this structure are disabled.

pj_bool_t qos_ignore_error

Specify if the transport should ignore any errors when setting the QoS traffic type/parameters.

Default: PJ_TRUE

pj_sockopt_params sockopt_params

Specify options to be set on the transport.

By default, this is unset, which means that the underlying sockopt params as returned by pj_ssl_sock_param_default() will be used.

pj_bool_t sockopt_ignore_error

Specify if the transport should ignore any errors when setting the sockopt parameters.

Default: PJ_TRUE

pj_bool_t enable_renegotiation

Specify if renegotiation is enabled for TLSv1.2 or earlier.

Default: PJ_TRUE

void (*on_accept_fail_cb)(const pjsip_tls_on_accept_fail_param *param)

Callback to be called when a accept operation of the TLS listener fails.

Param param:

The parameter to the callback.

pj_bool_t (*on_verify_cb)(const pjsip_tls_on_verify_param *param)

Callback to be called to verify a new connection. Currently it’s only implemented for OpenSSL backend.

If this is set, the callback will always be invoked, even when peer verification is disabled (pjsip_tls_setting.verify_server/verify_client set to PJ_FALSE).

Param param:

The parameter to the callback.

Return:

Return PJ_TRUE if succesfully verified. If verification failed, connection will be dropped immediately.

struct pjsip_tls_state_info
#include <sip_transport_tls.h>

This structure defines TLS transport extended info in ext_info field of pjsip_transport_state_info for the transport state notification callback pjsip_tp_state_callback.

Public Members

pj_ssl_sock_info *ssl_sock_info

SSL socket info.