Group PJ_SSL_SOCK

group PJ_SSL_SOCK

Secure socket provides security on socket operation using standard security protocols such as SSL and TLS.

Secure socket wraps normal socket and applies security features, i.e: privacy and data integrity, on the socket traffic, using standard security protocols such as SSL and TLS.

Secure socket employs active socket operations, which is similar to (and described more detail) in Active socket I/O.

Typedefs

typedef struct pj_ssl_sock_t pj_ssl_sock_t

This opaque structure describes the secure socket.

typedef struct pj_ssl_cert_t pj_ssl_cert_t

Opaque declaration of endpoint certificate or credentials. This may contains certificate, private key, and trusted Certificate Authorities list.

typedef pj_str_t pj_ssl_cert_buffer

The SSL certificate buffer.

Enums

enum pj_ssl_cert_verify_flag_t

Bitwise flag for SSL certificate verification.

Values:

enumerator PJ_SSL_CERT_ESUCCESS

No error in verification.

enumerator PJ_SSL_CERT_EISSUER_NOT_FOUND

The issuer certificate cannot be found.

enumerator PJ_SSL_CERT_EUNTRUSTED

The certificate is untrusted.

enumerator PJ_SSL_CERT_EVALIDITY_PERIOD

The certificate has expired or not yet valid.

enumerator PJ_SSL_CERT_EINVALID_FORMAT

One or more fields of the certificate cannot be decoded due to invalid format.

enumerator PJ_SSL_CERT_EINVALID_PURPOSE

The certificate cannot be used for the specified purpose.

enumerator PJ_SSL_CERT_EISSUER_MISMATCH

The issuer info in the certificate does not match to the (candidate) issuer certificate, e.g: issuer name not match to subject name of (candidate) issuer certificate.

enumerator PJ_SSL_CERT_ECRL_FAILURE

The CRL certificate cannot be found or cannot be read properly.

enumerator PJ_SSL_CERT_EREVOKED

The certificate has been revoked.

enumerator PJ_SSL_CERT_ECHAIN_TOO_LONG

The certificate chain length is too long.

enumerator PJ_SSL_CERT_EWEAK_SIGNATURE

The certificate signature is created using a weak hashing algorithm.

enumerator PJ_SSL_CERT_EIDENTITY_NOT_MATCH

The server identity does not match to any identities specified in the certificate, e.g: subjectAltName extension, subject common name. This flag will only be set by application as SSL socket does not perform server identity verification.

enumerator PJ_SSL_CERT_EUNKNOWN

Unknown verification error.

enum pj_ssl_cert_name_type

Type of SSL certificate name.

Values:

enumerator PJ_SSL_CERT_NAME_UNKNOWN
enumerator PJ_SSL_CERT_NAME_RFC822
enumerator PJ_SSL_CERT_NAME_DNS
enumerator PJ_SSL_CERT_NAME_URI
enumerator PJ_SSL_CERT_NAME_IP
enum pj_ssl_cert_lookup_type

Field type for looking up SSL certificate in the certificate stores.

Values:

enumerator PJ_SSL_CERT_LOOKUP_NONE

No certificate to be looked up.

enumerator PJ_SSL_CERT_LOOKUP_SUBJECT

Lookup by subject, this will lookup any first certificate whose subject containing the specified keyword. Note that subject may not be unique in the store, so the lookup may end up selecting a wrong certificate.

enumerator PJ_SSL_CERT_LOOKUP_FINGERPRINT

Lookup by fingerprint/thumbprint (SHA1 hash), this will lookup any first certificate whose fingerprint matching the specified keyword. The keyword is an array of hash octets.

enumerator PJ_SSL_CERT_LOOKUP_FRIENDLY_NAME

Lookup by friendly name, this will lookup any first certificate whose friendly name containing the specified keyword. Note that friendly name may not be unique in the store, so the lookup may end up selecting a wrong certificate.

enum pj_ssl_cipher

Cipher suites enumeration.

Values:

enumerator PJ_TLS_UNKNOWN_CIPHER
enumerator PJ_TLS_NULL_WITH_NULL_NULL
enumerator PJ_TLS_RSA_WITH_NULL_MD5
enumerator PJ_TLS_RSA_WITH_NULL_SHA
enumerator PJ_TLS_RSA_WITH_NULL_SHA256
enumerator PJ_TLS_RSA_WITH_RC4_128_MD5
enumerator PJ_TLS_RSA_WITH_RC4_128_SHA
enumerator PJ_TLS_RSA_WITH_3DES_EDE_CBC_SHA
enumerator PJ_TLS_RSA_WITH_AES_128_CBC_SHA
enumerator PJ_TLS_RSA_WITH_AES_256_CBC_SHA
enumerator PJ_TLS_RSA_WITH_AES_128_CBC_SHA256
enumerator PJ_TLS_RSA_WITH_AES_256_CBC_SHA256
enumerator PJ_TLS_DH_DSS_WITH_3DES_EDE_CBC_SHA
enumerator PJ_TLS_DH_RSA_WITH_3DES_EDE_CBC_SHA
enumerator PJ_TLS_DHE_DSS_WITH_3DES_EDE_CBC_SHA
enumerator PJ_TLS_DHE_RSA_WITH_3DES_EDE_CBC_SHA
enumerator PJ_TLS_DH_DSS_WITH_AES_128_CBC_SHA
enumerator PJ_TLS_DH_RSA_WITH_AES_128_CBC_SHA
enumerator PJ_TLS_DHE_DSS_WITH_AES_128_CBC_SHA
enumerator PJ_TLS_DHE_RSA_WITH_AES_128_CBC_SHA
enumerator PJ_TLS_DH_DSS_WITH_AES_256_CBC_SHA
enumerator PJ_TLS_DH_RSA_WITH_AES_256_CBC_SHA
enumerator PJ_TLS_DHE_DSS_WITH_AES_256_CBC_SHA
enumerator PJ_TLS_DHE_RSA_WITH_AES_256_CBC_SHA
enumerator PJ_TLS_DH_DSS_WITH_AES_128_CBC_SHA256
enumerator PJ_TLS_DH_RSA_WITH_AES_128_CBC_SHA256
enumerator PJ_TLS_DHE_DSS_WITH_AES_128_CBC_SHA256
enumerator PJ_TLS_DHE_RSA_WITH_AES_128_CBC_SHA256
enumerator PJ_TLS_DH_DSS_WITH_AES_256_CBC_SHA256
enumerator PJ_TLS_DH_RSA_WITH_AES_256_CBC_SHA256
enumerator PJ_TLS_DHE_DSS_WITH_AES_256_CBC_SHA256
enumerator PJ_TLS_DHE_RSA_WITH_AES_256_CBC_SHA256
enumerator PJ_TLS_DH_anon_WITH_RC4_128_MD5
enumerator PJ_TLS_DH_anon_WITH_3DES_EDE_CBC_SHA
enumerator PJ_TLS_DH_anon_WITH_AES_128_CBC_SHA
enumerator PJ_TLS_DH_anon_WITH_AES_256_CBC_SHA
enumerator PJ_TLS_DH_anon_WITH_AES_128_CBC_SHA256
enumerator PJ_TLS_DH_anon_WITH_AES_256_CBC_SHA256
enumerator PJ_TLS_RSA_EXPORT_WITH_RC4_40_MD5
enumerator PJ_TLS_RSA_EXPORT_WITH_RC2_CBC_40_MD5
enumerator PJ_TLS_RSA_WITH_IDEA_CBC_SHA
enumerator PJ_TLS_RSA_EXPORT_WITH_DES40_CBC_SHA
enumerator PJ_TLS_RSA_WITH_DES_CBC_SHA
enumerator PJ_TLS_DH_DSS_EXPORT_WITH_DES40_CBC_SHA
enumerator PJ_TLS_DH_DSS_WITH_DES_CBC_SHA
enumerator PJ_TLS_DH_RSA_EXPORT_WITH_DES40_CBC_SHA
enumerator PJ_TLS_DH_RSA_WITH_DES_CBC_SHA
enumerator PJ_TLS_DHE_DSS_EXPORT_WITH_DES40_CBC_SHA
enumerator PJ_TLS_DHE_DSS_WITH_DES_CBC_SHA
enumerator PJ_TLS_DHE_RSA_EXPORT_WITH_DES40_CBC_SHA
enumerator PJ_TLS_DHE_RSA_WITH_DES_CBC_SHA
enumerator PJ_TLS_DH_anon_EXPORT_WITH_RC4_40_MD5
enumerator PJ_TLS_DH_anon_EXPORT_WITH_DES40_CBC_SHA
enumerator PJ_TLS_DH_anon_WITH_DES_CBC_SHA
enumerator PJ_SSL_FORTEZZA_KEA_WITH_NULL_SHA
enumerator PJ_SSL_FORTEZZA_KEA_WITH_FORTEZZA_CBC_SHA
enumerator PJ_SSL_FORTEZZA_KEA_WITH_RC4_128_SHA
enumerator PJ_SSL_CK_RC4_128_WITH_MD5
enumerator PJ_SSL_CK_RC4_128_EXPORT40_WITH_MD5
enumerator PJ_SSL_CK_RC2_128_CBC_WITH_MD5
enumerator PJ_SSL_CK_RC2_128_CBC_EXPORT40_WITH_MD5
enumerator PJ_SSL_CK_IDEA_128_CBC_WITH_MD5
enumerator PJ_SSL_CK_DES_64_CBC_WITH_MD5
enumerator PJ_SSL_CK_DES_192_EDE3_CBC_WITH_MD5
enum pj_ssl_curve

Elliptic curves enumeration.

Values:

enumerator PJ_TLS_UNKNOWN_CURVE
enumerator PJ_TLS_CURVE_SECT163K1
enumerator PJ_TLS_CURVE_SECT163R1
enumerator PJ_TLS_CURVE_SECT163R2
enumerator PJ_TLS_CURVE_SECT193R1
enumerator PJ_TLS_CURVE_SECT193R2
enumerator PJ_TLS_CURVE_SECT233K1
enumerator PJ_TLS_CURVE_SECT233R1
enumerator PJ_TLS_CURVE_SECT239K1
enumerator PJ_TLS_CURVE_SECT283K1
enumerator PJ_TLS_CURVE_SECT283R1
enumerator PJ_TLS_CURVE_SECT409K1
enumerator PJ_TLS_CURVE_SECT409R1
enumerator PJ_TLS_CURVE_SECT571K1
enumerator PJ_TLS_CURVE_SECT571R1
enumerator PJ_TLS_CURVE_SECP160K1
enumerator PJ_TLS_CURVE_SECP160R1
enumerator PJ_TLS_CURVE_SECP160R2
enumerator PJ_TLS_CURVE_SECP192K1
enumerator PJ_TLS_CURVE_SECP192R1
enumerator PJ_TLS_CURVE_SECP224K1
enumerator PJ_TLS_CURVE_SECP224R1
enumerator PJ_TLS_CURVE_SECP256K1
enumerator PJ_TLS_CURVE_SECP256R1
enumerator PJ_TLS_CURVE_SECP384R1
enumerator PJ_TLS_CURVE_SECP521R1
enumerator PJ_TLS_CURVE_BRAINPOOLP256R1
enumerator PJ_TLS_CURVE_BRAINPOOLP384R1
enumerator PJ_TLS_CURVE_BRAINPOOLP512R1
enumerator PJ_TLS_CURVE_ARBITRARY_EXPLICIT_PRIME_CURVES
enumerator PJ_TLS_CURVE_ARBITRARY_EXPLICIT_CHAR2_CURVES
enum pj_ssl_entropy_t

Entropy enumeration

Values:

enumerator PJ_SSL_ENTROPY_NONE

None

enumerator PJ_SSL_ENTROPY_EGD

EGD

enumerator PJ_SSL_ENTROPY_RANDOM

Random

enumerator PJ_SSL_ENTROPY_URANDOM

Urandom

enumerator PJ_SSL_ENTROPY_FILE

File

enumerator PJ_SSL_ENTROPY_UNKNOWN

Unknown

enum pj_ssl_sock_proto

Enumeration of secure socket protocol types. This can be combined using bitwise OR operation.

Values:

enumerator PJ_SSL_SOCK_PROTO_DEFAULT

Default protocol of backend.

enumerator PJ_SSL_SOCK_PROTO_SSL2

SSLv2.0 protocol.

enumerator PJ_SSL_SOCK_PROTO_SSL3

SSLv3.0 protocol.

enumerator PJ_SSL_SOCK_PROTO_TLS1

TLSv1.0 protocol.

enumerator PJ_SSL_SOCK_PROTO_TLS1_1

TLSv1.1 protocol.

enumerator PJ_SSL_SOCK_PROTO_TLS1_2

TLSv1.2 protocol.

enumerator PJ_SSL_SOCK_PROTO_TLS1_3

TLSv1.3 protocol.

enumerator PJ_SSL_SOCK_PROTO_SSL23

Certain backend implementation e.g:OpenSSL, has feature to enable all protocol.

enumerator PJ_SSL_SOCK_PROTO_ALL
enumerator PJ_SSL_SOCK_PROTO_DTLS1

DTLSv1.0 protocol.

Functions

pj_status_t pj_ssl_cert_load_from_files(pj_pool_t *pool, const pj_str_t *CA_file, const pj_str_t *cert_file, const pj_str_t *privkey_file, const pj_str_t *privkey_pass, pj_ssl_cert_t **p_cert)

Create credential from files. TLS server application can provide multiple certificates (RSA, ECC, and DSA) by supplying certificate name with “_rsa” suffix, e.g: “pjsip_rsa.pem”, the library will automatically check for other certificates with “_ecc” and “_dsa” suffix.

Parameters:

  • pool – The pool.

  • CA_file – The file of trusted CA list.

  • cert_file – The file of certificate.

  • privkey_file – The file of private key.

  • privkey_pass – The password of private key, if any.

  • p_cert – Pointer to credential instance to be created.

Returns:

PJ_SUCCESS when successful.

pj_status_t pj_ssl_cert_load_from_files2(pj_pool_t *pool, const pj_str_t *CA_file, const pj_str_t *CA_path, const pj_str_t *cert_file, const pj_str_t *privkey_file, const pj_str_t *privkey_pass, pj_ssl_cert_t **p_cert)

Create credential from files. TLS server application can provide multiple certificates (RSA, ECC, and DSA) by supplying certificate name with “_rsa” suffix, e.g: “pjsip_rsa.pem”, the library will automatically check for other certificates with “_ecc” and “_dsa” suffix.

This is the same as pj_ssl_cert_load_from_files() but also accepts an additional param CA_path to load CA certificates from a directory.

Parameters:

  • pool – The pool.

  • CA_file – The file of trusted CA list.

  • CA_path – The path to a directory of trusted CA list.

  • cert_file – The file of certificate.

  • privkey_file – The file of private key.

  • privkey_pass – The password of private key, if any.

  • p_cert – Pointer to credential instance to be created.

Returns:

PJ_SUCCESS when successful.

pj_status_t pj_ssl_cert_load_from_buffer(pj_pool_t *pool, const pj_ssl_cert_buffer *CA_buf, const pj_ssl_cert_buffer *cert_buf, const pj_ssl_cert_buffer *privkey_buf, const pj_str_t *privkey_pass, pj_ssl_cert_t **p_cert)

Create credential from data buffer. The certificate expected is in PEM format.

Parameters:

  • pool – The pool.

  • CA_buf – The buffer of trusted CA list.

  • cert_buf – The buffer of certificate.

  • privkey_buf – The buffer of private key.

  • privkey_pass – The password of private key, if any.

  • p_cert – Pointer to credential instance to be created.

Returns:

PJ_SUCCESS when successful.

pj_status_t pj_ssl_cert_load_from_store(pj_pool_t *pool, const pj_ssl_cert_lookup_criteria *criteria, pj_ssl_cert_t **p_cert)

Create credential from OS certificate store, this function will lookup certificate using the specified criterias.

Currently this is used by Windows Schannel backend only, it will lookup in the Current User store first, if no certificate with the specified criteria is not found, it will lookup in the Local Machine store.

Note that for manual verification (e.g: when pj_ssl_sock_param.verify_peer is disabled), the backend will provide pre-verification result against trusted CA certificates in Current User store only (will not check CA certificates in the Local Machine store).

Parameters:

  • pool – The pool.

  • criteria – The lookup criteria.

  • p_cert – Pointer to credential instance to be created.

Returns:

PJ_SUCCESS when successful.

pj_ssize_t pj_ssl_cert_info_dump(const pj_ssl_cert_info *ci, const char *indent, char *buf, pj_size_t buf_size)

Dump SSL certificate info.

Parameters:

  • ci – The certificate info.

  • indent – String for left indentation.

  • buf – The buffer where certificate info will be printed on.

  • buf_size – The buffer size.

Returns:

The length of the dump result, or -1 when buffer size is not sufficient.

pj_status_t pj_ssl_cert_get_verify_status_strings(pj_uint32_t verify_status, const char *error_strings[], unsigned *count)

Get SSL certificate verification error messages from verification status.

Parameters:

  • verify_status – The SSL certificate verification status.

  • error_strings – Array of strings to receive the verification error messages.

  • count – On input it specifies maximum error messages should be retrieved. On output it specifies the number of error messages retrieved.

Returns:

PJ_SUCCESS when successful.

void pj_ssl_cert_wipe_keys(pj_ssl_cert_t *cert)

Wipe out the keys in the SSL certificate.

Parameters:

cert – The SSL certificate.

pj_status_t pj_ssl_cipher_get_availables(pj_ssl_cipher ciphers[], unsigned *cipher_num)

Get cipher list supported by SSL/TLS backend.

Parameters:

  • ciphers – The ciphers buffer to receive cipher list.

  • cipher_num – Maximum number of ciphers to be received.

Returns:

PJ_SUCCESS when successful.

pj_bool_t pj_ssl_cipher_is_supported(pj_ssl_cipher cipher)

Check if the specified cipher is supported by SSL/TLS backend.

Parameters:

cipher – The cipher.

Returns:

PJ_TRUE when supported.

const char *pj_ssl_cipher_name(pj_ssl_cipher cipher)

Get cipher name string.

Parameters:

cipher – The cipher.

Returns:

The cipher name or NULL if cipher is not recognized/ supported.

pj_ssl_cipher pj_ssl_cipher_id(const char *cipher_name)

Get cipher ID from cipher name string. Note that on different backends (e.g. OpenSSL or Symbian implementation), cipher names may not be equivalent for the same cipher ID.

Parameters:

cipher_name – The cipher name string.

Returns:

The cipher ID or PJ_TLS_UNKNOWN_CIPHER if the cipher name string is not recognized/supported.

pj_status_t pj_ssl_curve_get_availables(pj_ssl_curve curves[], unsigned *curve_num)

Get curve list supported by SSL/TLS backend.

Parameters:

  • curves – The curves buffer to receive curve list.

  • curve_num – Maximum number of curves to be received.

Returns:

PJ_SUCCESS when successful.

pj_bool_t pj_ssl_curve_is_supported(pj_ssl_curve curve)

Check if the specified curve is supported by SSL/TLS backend.

Parameters:

curve – The curve.

Returns:

PJ_TRUE when supported.

const char *pj_ssl_curve_name(pj_ssl_curve curve)

Get curve name string.

Parameters:

curve – The curve.

Returns:

The curve name or NULL if curve is not recognized/ supported.

pj_ssl_curve pj_ssl_curve_id(const char *curve_name)

Get curve ID from curve name string. Note that on different backends (e.g. OpenSSL or Symbian implementation), curve names may not be equivalent for the same curve ID.

Parameters:

curve_name – The curve name string.

Returns:

The curve ID or PJ_TLS_UNKNOWN_CURVE if the curve name string is not recognized/supported.

void pj_ssl_sock_param_default(pj_ssl_sock_param *param)

Initialize the secure socket parameters for its creation with the default values.

Parameters:

param – The parameter to be initialized.

void pj_ssl_sock_param_copy(pj_pool_t *pool, pj_ssl_sock_param *dst, const pj_ssl_sock_param *src)

Duplicate pj_ssl_sock_param.

Parameters:

  • pool – Pool to allocate memory.

  • dst – Destination parameter.

  • src – Source parameter.

pj_status_t pj_ssl_sock_create(pj_pool_t *pool, const pj_ssl_sock_param *param, pj_ssl_sock_t **p_ssock)

Create secure socket instance.

Parameters:

  • pool – The pool for allocating secure socket instance.

  • param – The secure socket parameter, see pj_ssl_sock_param.

  • p_ssock – Pointer to secure socket instance to be created.

Returns:

PJ_SUCCESS when successful.

pj_status_t pj_ssl_sock_set_certificate(pj_ssl_sock_t *ssock, pj_pool_t *pool, const pj_ssl_cert_t *cert)

Set secure socket certificate or credentials. Credentials may include certificate, private key and trusted Certification Authorities list. Normally, server socket must provide certificate (and private key). Socket client may also need to provide certificate in case requested by the server.

Parameters:

  • ssock – The secure socket instance.

  • pool – The pool.

  • cert – The endpoint certificate/credentials, see pj_ssl_cert_t.

Returns:

PJ_SUCCESS if the operation has been successful, or the appropriate error code on failure.

pj_status_t pj_ssl_sock_close(pj_ssl_sock_t *ssock)

Close and destroy the secure socket.

Parameters:

ssock – The secure socket.

Returns:

PJ_SUCCESS if the operation has been successful, or the appropriate error code on failure.

pj_status_t pj_ssl_sock_set_user_data(pj_ssl_sock_t *ssock, void *user_data)

Associate arbitrary data with the secure socket. Application may inspect this data in the callbacks and associate it with higher level processing.

Parameters:

  • ssock – The secure socket.

  • user_data – The user data to be associated with the secure socket.

Returns:

PJ_SUCCESS if the operation has been successful, or the appropriate error code on failure.

void *pj_ssl_sock_get_user_data(pj_ssl_sock_t *ssock)

Retrieve the user data previously associated with this secure socket.

Parameters:

ssock – The secure socket.

Returns:

The user data.

pj_status_t pj_ssl_sock_get_info(pj_ssl_sock_t *ssock, pj_ssl_sock_info *info)

Retrieve the local address and port used by specified secure socket.

Parameters:

  • ssock – The secure socket.

  • info – The info buffer to be set, see pj_ssl_sock_info.

Returns:

PJ_SUCCESS on successful.

pj_status_t pj_ssl_sock_start_read(pj_ssl_sock_t *ssock, pj_pool_t *pool, unsigned buff_size, pj_uint32_t flags)

Starts read operation on this secure socket. This function will create async_cnt number of buffers (the async_cnt parameter was given in pj_ssl_sock_create() function) where each buffer is buff_size long. The buffers are allocated from the specified pool. Once the buffers are created, it then issues async_cnt number of asynchronous recv() operations to the socket and returns back to caller. Incoming data on the socket will be reported back to application via the on_data_read() callback.

Application only needs to call this function once to initiate read operations. Further read operations will be done automatically by the secure socket when on_data_read() callback returns non-zero.

Parameters:

  • ssock – The secure socket.

  • pool – Pool used to allocate buffers for incoming data.

  • buff_size – The size of each buffer, in bytes.

  • flags – Flags to be given to pj_ioqueue_recv().

Returns:

PJ_SUCCESS if the operation has been successful, or the appropriate error code on failure.

pj_status_t pj_ssl_sock_start_read2(pj_ssl_sock_t *ssock, pj_pool_t *pool, unsigned buff_size, void *readbuf[], pj_uint32_t flags)

Same as pj_ssl_sock_start_read(), except that the application supplies the buffers for the read operation so that the acive socket does not have to allocate the buffers.

Parameters:

  • ssock – The secure socket.

  • pool – Pool used to allocate buffers for incoming data.

  • buff_size – The size of each buffer, in bytes.

  • readbuf – Array of packet buffers, each has buff_size size.

  • flags – Flags to be given to pj_ioqueue_recv().

Returns:

PJ_SUCCESS if the operation has been successful, or the appropriate error code on failure.

pj_status_t pj_ssl_sock_start_recvfrom(pj_ssl_sock_t *ssock, pj_pool_t *pool, unsigned buff_size, pj_uint32_t flags)

Same as pj_ssl_sock_start_read(), except that this function is used only for datagram sockets, and it will trigger on_data_recvfrom() callback instead.

Parameters:

  • ssock – The secure socket.

  • pool – Pool used to allocate buffers for incoming data.

  • buff_size – The size of each buffer, in bytes.

  • flags – Flags to be given to pj_ioqueue_recvfrom().

Returns:

PJ_SUCCESS if the operation has been successful, or the appropriate error code on failure.

pj_status_t pj_ssl_sock_start_recvfrom2(pj_ssl_sock_t *ssock, pj_pool_t *pool, unsigned buff_size, void *readbuf[], pj_uint32_t flags)

Same as pj_ssl_sock_start_recvfrom() except that the recvfrom() operation takes the buffer from the argument rather than creating new ones.

Parameters:

  • ssock – The secure socket.

  • pool – Pool used to allocate buffers for incoming data.

  • buff_size – The size of each buffer, in bytes.

  • readbuf – Array of packet buffers, each has buff_size size.

  • flags – Flags to be given to pj_ioqueue_recvfrom().

Returns:

PJ_SUCCESS if the operation has been successful, or the appropriate error code on failure.

pj_status_t pj_ssl_sock_send(pj_ssl_sock_t *ssock, pj_ioqueue_op_key_t *send_key, const void *data, pj_ssize_t *size, unsigned flags)

Send data using the socket.

Parameters:

  • ssock – The secure socket.

  • send_key – The operation key to send the data, which is useful if application wants to submit multiple pending send operations and want to track which exact data has been sent in the on_data_sent() callback.

  • data – The data to be sent. This data must remain valid until the data has been sent.

  • size – The size of the data.

  • flags – Flags to be given to pj_ioqueue_send().

Returns:

PJ_SUCCESS if data has been sent immediately, or PJ_EPENDING if data cannot be sent immediately or PJ_ENOMEM when sending buffer could not handle all queued data, see send_buffer_size. The callback on_data_sent() will be called when data is actually sent. Any other return value indicates error condition.

pj_status_t pj_ssl_sock_sendto(pj_ssl_sock_t *ssock, pj_ioqueue_op_key_t *send_key, const void *data, pj_ssize_t *size, unsigned flags, const pj_sockaddr_t *addr, int addr_len)

Send datagram using the socket.

Parameters:

  • ssock – The secure socket.

  • send_key – The operation key to send the data, which is useful if application wants to submit multiple pending send operations and want to track which exact data has been sent in the on_data_sent() callback.

  • data – The data to be sent. This data must remain valid until the data has been sent.

  • size – The size of the data.

  • flags – Flags to be given to pj_ioqueue_send().

  • addr – The destination address.

  • addr_len – Length of buffer containing destination address.

Returns:

PJ_SUCCESS if data has been sent immediately, or PJ_EPENDING if data cannot be sent immediately. In this case the on_data_sent() callback will be called when data is actually sent. Any other return value indicates error condition.

pj_status_t pj_ssl_sock_start_accept(pj_ssl_sock_t *ssock, pj_pool_t *pool, const pj_sockaddr_t *local_addr, int addr_len)

Starts asynchronous socket accept() operations on this secure socket. This function will issue async_cnt number of asynchronous accept() operations to the socket and returns back to caller. Incoming connection on the socket will be reported back to application via the on_accept_complete() callback.

Application only needs to call this function once to initiate accept() operations. Further accept() operations will be done automatically by the secure socket when on_accept_complete() callback returns non-zero.

Parameters:

  • ssock – The secure socket.

  • pool – Pool used to allocate some internal data for the operation.

  • local_addr – Local address to bind on.

  • addr_len – Length of buffer containing local address.

Returns:

PJ_SUCCESS if the operation has been successful, or the appropriate error code on failure.

pj_status_t pj_ssl_sock_start_accept2(pj_ssl_sock_t *ssock, pj_pool_t *pool, const pj_sockaddr_t *local_addr, int addr_len, const pj_ssl_sock_param *newsock_param)

Same as pj_ssl_sock_start_accept(), but application can provide a secure socket parameter, which will be used to create a new secure socket reported in on_accept_complete() callback when there is an incoming connection.

Parameters:

  • ssock – The secure socket.

  • pool – Pool used to allocate some internal data for the operation.

  • local_addr – Local address to bind on.

  • addr_len – Length of buffer containing local address.

  • newsock_param – Secure socket parameter for new accepted sockets.

Returns:

PJ_SUCCESS if the operation has been successful, or the appropriate error code on failure.

pj_status_t pj_ssl_sock_start_connect(pj_ssl_sock_t *ssock, pj_pool_t *pool, const pj_sockaddr_t *localaddr, const pj_sockaddr_t *remaddr, int addr_len)

Starts asynchronous socket connect() operation and SSL/TLS handshaking for this socket. Once the connection is done (either successfully or not), the on_connect_complete() callback will be called.

Parameters:

  • ssock – The secure socket.

  • pool – The pool to allocate some internal data for the operation.

  • localaddr – Local address.

  • remaddr – Remote address.

  • addr_len – Length of buffer containing above addresses.

Returns:

PJ_SUCCESS if connection can be established immediately or PJ_EPENDING if connection cannot be established immediately. In this case the on_connect_complete() callback will be called when connection is complete. Any other return value indicates error condition.

pj_status_t pj_ssl_sock_start_connect2(pj_ssl_sock_t *ssock, pj_ssl_start_connect_param *connect_param)

Same as pj_ssl_sock_start_connect(), but application can provide a port_range parameter, which will be used to bind the socket to random port.

Parameters:
Returns:

PJ_SUCCESS if connection can be established immediately or PJ_EPENDING if connection cannot be established immediately. In this case the on_connect_complete() callback will be called when connection is complete. Any other return value indicates error condition.

pj_status_t pj_ssl_sock_renegotiate(pj_ssl_sock_t *ssock)

Starts SSL/TLS renegotiation over an already established SSL connection for this socket. This operation is performed transparently, no callback will be called once the renegotiation completed successfully. However, when the renegotiation fails, the connection will be closed and callback on_data_read() will be invoked with non-PJ_SUCCESS status code.

Parameters:

ssock – The secure socket.

Returns:

PJ_SUCCESS if renegotiation is completed immediately, or PJ_EPENDING if renegotiation has been started and waiting for completion, or the appropriate error code on failure.

struct pj_ssl_cert_lookup_criteria
#include <ssl_sock.h>

Describe structure of certificate lookup criteria.

Public Members

pj_ssl_cert_lookup_type type

Certificate field type to look.

struct pj_ssl_cert_info
#include <ssl_sock.h>

Describe structure of certificate info.

Public Members

unsigned version

Certificate version

pj_uint8_t serial_no[20]

Serial number, array of octets, first index is MSB

pj_str_t cn

Common name

pj_str_t info

One line subject, fields are separated by slash, e.g: “CN=sample.org/OU=HRD”

One line subject, fields are separated by slash.

struct pj_ssl_cert_info::[anonymous] subject

Subject

struct pj_ssl_cert_info::[anonymous] issuer

Issuer

pj_time_val start

Validity start

pj_time_val end

Validity end

pj_bool_t gmt

Flag if validity date/time use GMT

struct pj_ssl_cert_info::[anonymous] validity

Validity

unsigned cnt

of entry

of entry

pj_ssl_cert_name_type type

Name type

pj_str_t name

The name

struct pj_ssl_cert_info::[anonymous]::[anonymous] *entry

Subject alt name entry

struct pj_ssl_cert_info::[anonymous] subj_alt_name

Subject alternative name extension

pj_str_t raw

Raw certificate in PEM format, only available for remote certificate.

struct pj_ssl_sock_cb
#include <ssl_sock.h>

This structure contains the callbacks to be called by the secure socket.

Public Members

pj_bool_t (*on_data_read)(pj_ssl_sock_t *ssock, void *data, pj_size_t size, pj_status_t status, pj_size_t *remainder)

This callback is called when a data arrives as the result of pj_ssl_sock_start_read().

Param ssock:

The secure socket.

Param data:

The buffer containing the new data, if any. If the status argument is non-PJ_SUCCESS, this argument may be NULL.

Param size:

The length of data in the buffer.

Param status:

The status of the read operation. This may contain non-PJ_SUCCESS for example when the TCP connection has been closed. In this case, the buffer may contain left over data from previous callback which the application may want to process.

Param remainder:

If application wishes to leave some data in the buffer (common for TCP applications), it should move the remainder data to the front part of the buffer and set the remainder length here. The value of this parameter will be ignored for datagram sockets.

Return:

PJ_TRUE if further read is desired, and PJ_FALSE when application no longer wants to receive data. Application may destroy the secure socket in the callback and return PJ_FALSE here.

pj_bool_t (*on_data_recvfrom)(pj_ssl_sock_t *ssock, void *data, pj_size_t size, const pj_sockaddr_t *src_addr, int addr_len, pj_status_t status)

This callback is called when a packet arrives as the result of pj_ssl_sock_start_recvfrom().

Param ssock:

The secure socket.

Param data:

The buffer containing the packet, if any. If the status argument is non-PJ_SUCCESS, this argument will be set to NULL.

Param size:

The length of packet in the buffer. If the status argument is non-PJ_SUCCESS, this argument will be set to zero.

Param src_addr:

Source address of the packet.

Param addr_len:

Length of the source address.

Param status:

This contains

Return:

PJ_TRUE if further read is desired, and PJ_FALSE when application no longer wants to receive data. Application may destroy the secure socket in the callback and return PJ_FALSE here.

pj_bool_t (*on_data_sent)(pj_ssl_sock_t *ssock, pj_ioqueue_op_key_t *send_key, pj_ssize_t sent)

This callback is called when data has been sent.

Param ssock:

The secure socket.

Param send_key:

Key associated with the send operation.

Param sent:

If value is positive non-zero it indicates the number of data sent. When the value is negative, it contains the error code which can be retrieved by negating the value (i.e. status=-sent).

Return:

Application may destroy the secure socket in the callback and return PJ_FALSE here.

pj_bool_t (*on_accept_complete)(pj_ssl_sock_t *ssock, pj_ssl_sock_t *newsock, const pj_sockaddr_t *src_addr, int src_addr_len)

This callback is called when new connection arrives as the result of pj_ssl_sock_start_accept(). If the status of accept operation is needed use on_accept_complete2 instead of this callback.

Param ssock:

The secure socket.

Param newsock:

The new incoming secure socket.

Param src_addr:

The source address of the connection.

Param addr_len:

Length of the source address.

Return:

PJ_TRUE if further accept() is desired, and PJ_FALSE when application no longer wants to accept incoming connection. Application may destroy the secure socket in the callback and return PJ_FALSE here.

pj_bool_t (*on_accept_complete2)(pj_ssl_sock_t *ssock, pj_ssl_sock_t *newsock, const pj_sockaddr_t *src_addr, int src_addr_len, pj_status_t status)

This callback is called when new connection arrives as the result of pj_ssl_sock_start_accept().

Param asock:

The active socket.

Param newsock:

The new incoming socket.

Param src_addr:

The source address of the connection.

Param addr_len:

Length of the source address.

Param status:

The status of the accept operation. This may contain non-PJ_SUCCESS for example when the TCP listener is in bad state for example on iOS platform after the application waking up from background.

Return:

PJ_TRUE if further accept() is desired, and PJ_FALSE when application no longer wants to accept incoming connection. Application may destroy the active socket in the callback and return PJ_FALSE here.

pj_bool_t (*on_connect_complete)(pj_ssl_sock_t *ssock, pj_status_t status)

This callback is called when pending connect operation has been completed.

Param ssock:

The secure socket.

Param status:

The connection result. If connection has been successfully established, the status will contain PJ_SUCCESS.

Return:

Application may destroy the secure socket in the callback and return PJ_FALSE here.

pj_bool_t (*on_verify_cb)(pj_ssl_sock_t *ssock, pj_bool_t is_server)

This callback is called when certificate verification is being done. Certification info can be obtained from pj_ssl_sock_info. Currently it’s only implemented for OpenSSL backend.

If this is set, the callback will always be invoked, even when peer verification is disabled (pj_ssl_sock_param.verify_peer set to PJ_FALSE).

Param ssock:

The secure socket.

Param is_server:

PJ_TRUE to indicate an incoming connection.

Return:

Return PJ_TRUE if verification is successful. If verification failed, then the connection will be dropped immediately.

struct pj_ssl_sock_info
#include <ssl_sock.h>

Definition of secure socket info structure.

Public Members

pj_bool_t established

Describes whether secure socket connection is established, i.e: TLS/SSL handshaking has been done successfully.

pj_uint32_t proto

Describes secure socket protocol being used, see pj_ssl_sock_proto. Use bitwise OR operation to combine the protocol type.

pj_ssl_cipher cipher

Describes cipher suite being used, this will only be set when connection is established.

pj_sockaddr local_addr

Describes local address.

pj_sockaddr remote_addr

Describes remote address.

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_uint32_t verify_status

Status of peer certificate verification.

unsigned long last_native_err

Last native error returned by the backend.

pj_grp_lock_t *grp_lock

Group lock assigned to the ioqueue key.

void *native_ssl

Native TLS/SSL instance of the backend. Currently only available for OpenSSL backend (this will contain the OpenSSL “SSL” instance).

struct pj_ssl_sock_param
#include <ssl_sock.h>

Definition of secure socket creation parameters.

Public Members

pj_grp_lock_t *grp_lock

Optional group lock to be assigned to the ioqueue key.

Note that when a secure socket listener is configured with a group lock, any new secure socket of an accepted incoming connection will have its own group lock created automatically by the library, this group lock can be queried via pj_ssl_sock_get_info() in the info field pj_ssl_sock_info::grp_lock.

int sock_af

Specifies socket address family, either pj_AF_INET() and pj_AF_INET6().

Default is pj_AF_INET().

int sock_type

Specify socket type, either pj_SOCK_DGRAM() or pj_SOCK_STREAM().

Default is pj_SOCK_STREAM().

pj_ioqueue_t *ioqueue

Specify the ioqueue to use. Secure socket uses the ioqueue to perform active socket operations, see Active socket I/O for more detail.

pj_timer_heap_t *timer_heap

Specify the timer heap to use. Secure socket uses the timer to provide auto cancelation on asynchronous operation when it takes longer time than specified timeout period, e.g: security negotiation timeout.

pj_ssl_sock_cb cb

Specify secure socket callbacks, see pj_ssl_sock_cb.

void *user_data

Specify secure socket user data.

pj_uint32_t proto

Specify security protocol to use, see pj_ssl_sock_proto. Use bitwise OR operation to combine the protocol type.

Default is PJ_SSL_SOCK_PROTO_DEFAULT.

unsigned async_cnt

Number of concurrent asynchronous operations that is to be supported by the secure socket. This value only affects socket receive and accept operations &#8212; the secure socket will issue one or more asynchronous read and accept operations based on the value of this field. Setting this field to more than one will allow more than one incoming data or incoming connections to be processed simultaneously on multiprocessor systems, when the ioqueue is polled by more than one threads.

The default value is 1.

int concurrency

The ioqueue concurrency to be forced on the socket when it is registered to the ioqueue. See pj_ioqueue_set_concurrency() for more info about ioqueue concurrency.

When this value is -1, the concurrency setting will not be forced for this socket, and the socket will inherit the concurrency setting of the ioqueue. When this value is zero, the secure socket will disable concurrency for the socket. When this value is +1, the secure socket will enable concurrency for the socket.

The default value is -1.

pj_bool_t whole_data

If this option is specified, the secure socket will make sure that asynchronous send operation with stream oriented socket will only call the callback after all data has been sent. This means that the secure socket will automatically resend the remaining data until all data has been sent.

Please note that when this option is specified, it is possible that error is reported after partial data has been sent. Also setting this will disable the ioqueue concurrency for the socket.

Default value is 1.

pj_size_t send_buffer_size

Specify buffer size for sending operation. Buffering sending data is used for allowing application to perform multiple outstanding send operations. Whenever application specifies this setting too small, sending operation may return PJ_ENOMEM.

Default value is 8192 bytes.

pj_size_t read_buffer_size

Specify buffer size for receiving encrypted (and perhaps compressed) data on underlying socket. This setting is unused on Symbian, since SSL/TLS Symbian backend, CSecureSocket, can use application buffer directly.

Default value is 1500.

unsigned ciphers_num

Number of ciphers contained in the specified cipher preference. If this is set to zero, then the cipher list used will be determined by the backend default (for OpenSSL backend, setting PJ_SSL_SOCK_OSSL_CIPHERS will be used).

pj_ssl_cipher *ciphers

Ciphers and order preference. If empty, then default cipher list and its default order of the backend will be used.

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_time_val timeout

Security negotiation timeout. If this is set to zero (both sec and msec), the negotiation doesn’t have a timeout.

Default value is zero.

pj_bool_t verify_peer

Specify whether endpoint should verify peer certificate.

Default value is PJ_FALSE.

pj_bool_t require_client_cert

When secure socket is acting as server (handles incoming connection), it will require the client to provide certificate.

Default value is PJ_FALSE.

pj_str_t server_name

Server name indication. When secure socket is acting as client (perform outgoing connection) and the server may host multiple ‘virtual’ servers at a single underlying network address, setting this will allow client to tell the server a name of the server it is contacting. This must be set to hostname and literal IP addresses are not allowed.

Default value is zero/not-set.

pj_bool_t reuse_addr

Specify if SO_REUSEADDR should be used for listening socket. This option will only be used with accept() operation.

Default is PJ_FALSE.

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.

For GnuTLS backend, by default TCP_NODELAY will be set. For other SSL backends, the default is no options.

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 sock_cloexec

Specify if should set close-on-exec flag for socket.

Default: PJ_TRUE

pj_bool_t enable_renegotiation

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

Default: PJ_TRUE

struct pj_ssl_start_connect_param
#include <ssl_sock.h>

The parameter for pj_ssl_sock_start_connect2().

Public Members

pj_pool_t *pool

The pool to allocate some internal data for the operation.

const pj_sockaddr_t *localaddr

Local address.

pj_uint16_t local_port_range

Port range for socket binding, relative to the start port number specified in localaddr. This is only applicable when the start port number is non zero.

const pj_sockaddr_t *remaddr

Remote address.

int addr_len

Length of buffer containing above addresses.