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

Values:

PJ_SSL_CERT_ESUCCESS = 0

No error in verification.

PJ_SSL_CERT_EISSUER_NOT_FOUND = (1 << 0)

The issuer certificate cannot be found.

PJ_SSL_CERT_EUNTRUSTED = (1 << 1)

The certificate is untrusted.

PJ_SSL_CERT_EVALIDITY_PERIOD = (1 << 2)

The certificate has expired or not yet valid.

PJ_SSL_CERT_EINVALID_FORMAT = (1 << 3)

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

PJ_SSL_CERT_EINVALID_PURPOSE = (1 << 4)

The certificate cannot be used for the specified purpose.

PJ_SSL_CERT_EISSUER_MISMATCH = (1 << 5)

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.

PJ_SSL_CERT_ECRL_FAILURE = (1 << 6)

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

PJ_SSL_CERT_EREVOKED = (1 << 7)

The certificate has been revoked.

PJ_SSL_CERT_ECHAIN_TOO_LONG = (1 << 8)

The certificate chain length is too long.

PJ_SSL_CERT_EIDENTITY_NOT_MATCH = (1 << 30)

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.

PJ_SSL_CERT_EUNKNOWN = (1 << 31)

Unknown verification error.

enum pj_ssl_cert_name_type

Values:

PJ_SSL_CERT_NAME_UNKNOWN = 0
PJ_SSL_CERT_NAME_RFC822
PJ_SSL_CERT_NAME_DNS
PJ_SSL_CERT_NAME_URI
PJ_SSL_CERT_NAME_IP
enum pj_ssl_cipher

Cipher suites enumeration.

Values:

PJ_TLS_UNKNOWN_CIPHER = -1
PJ_TLS_NULL_WITH_NULL_NULL = 0x00000000
PJ_TLS_RSA_WITH_NULL_MD5 = 0x00000001
PJ_TLS_RSA_WITH_NULL_SHA = 0x00000002
PJ_TLS_RSA_WITH_NULL_SHA256 = 0x0000003B
PJ_TLS_RSA_WITH_RC4_128_MD5 = 0x00000004
PJ_TLS_RSA_WITH_RC4_128_SHA = 0x00000005
PJ_TLS_RSA_WITH_3DES_EDE_CBC_SHA = 0x0000000A
PJ_TLS_RSA_WITH_AES_128_CBC_SHA = 0x0000002F
PJ_TLS_RSA_WITH_AES_256_CBC_SHA = 0x00000035
PJ_TLS_RSA_WITH_AES_128_CBC_SHA256 = 0x0000003C
PJ_TLS_RSA_WITH_AES_256_CBC_SHA256 = 0x0000003D
PJ_TLS_DH_DSS_WITH_3DES_EDE_CBC_SHA = 0x0000000D
PJ_TLS_DH_RSA_WITH_3DES_EDE_CBC_SHA = 0x00000010
PJ_TLS_DHE_DSS_WITH_3DES_EDE_CBC_SHA = 0x00000013
PJ_TLS_DHE_RSA_WITH_3DES_EDE_CBC_SHA = 0x00000016
PJ_TLS_DH_DSS_WITH_AES_128_CBC_SHA = 0x00000030
PJ_TLS_DH_RSA_WITH_AES_128_CBC_SHA = 0x00000031
PJ_TLS_DHE_DSS_WITH_AES_128_CBC_SHA = 0x00000032
PJ_TLS_DHE_RSA_WITH_AES_128_CBC_SHA = 0x00000033
PJ_TLS_DH_DSS_WITH_AES_256_CBC_SHA = 0x00000036
PJ_TLS_DH_RSA_WITH_AES_256_CBC_SHA = 0x00000037
PJ_TLS_DHE_DSS_WITH_AES_256_CBC_SHA = 0x00000038
PJ_TLS_DHE_RSA_WITH_AES_256_CBC_SHA = 0x00000039
PJ_TLS_DH_DSS_WITH_AES_128_CBC_SHA256 = 0x0000003E
PJ_TLS_DH_RSA_WITH_AES_128_CBC_SHA256 = 0x0000003F
PJ_TLS_DHE_DSS_WITH_AES_128_CBC_SHA256 = 0x00000040
PJ_TLS_DHE_RSA_WITH_AES_128_CBC_SHA256 = 0x00000067
PJ_TLS_DH_DSS_WITH_AES_256_CBC_SHA256 = 0x00000068
PJ_TLS_DH_RSA_WITH_AES_256_CBC_SHA256 = 0x00000069
PJ_TLS_DHE_DSS_WITH_AES_256_CBC_SHA256 = 0x0000006A
PJ_TLS_DHE_RSA_WITH_AES_256_CBC_SHA256 = 0x0000006B
PJ_TLS_DH_anon_WITH_RC4_128_MD5 = 0x00000018
PJ_TLS_DH_anon_WITH_3DES_EDE_CBC_SHA = 0x0000001B
PJ_TLS_DH_anon_WITH_AES_128_CBC_SHA = 0x00000034
PJ_TLS_DH_anon_WITH_AES_256_CBC_SHA = 0x0000003A
PJ_TLS_DH_anon_WITH_AES_128_CBC_SHA256 = 0x0000006C
PJ_TLS_DH_anon_WITH_AES_256_CBC_SHA256 = 0x0000006D
PJ_TLS_RSA_EXPORT_WITH_RC4_40_MD5 = 0x00000003
PJ_TLS_RSA_EXPORT_WITH_RC2_CBC_40_MD5 = 0x00000006
PJ_TLS_RSA_WITH_IDEA_CBC_SHA = 0x00000007
PJ_TLS_RSA_EXPORT_WITH_DES40_CBC_SHA = 0x00000008
PJ_TLS_RSA_WITH_DES_CBC_SHA = 0x00000009
PJ_TLS_DH_DSS_EXPORT_WITH_DES40_CBC_SHA = 0x0000000B
PJ_TLS_DH_DSS_WITH_DES_CBC_SHA = 0x0000000C
PJ_TLS_DH_RSA_EXPORT_WITH_DES40_CBC_SHA = 0x0000000E
PJ_TLS_DH_RSA_WITH_DES_CBC_SHA = 0x0000000F
PJ_TLS_DHE_DSS_EXPORT_WITH_DES40_CBC_SHA = 0x00000011
PJ_TLS_DHE_DSS_WITH_DES_CBC_SHA = 0x00000012
PJ_TLS_DHE_RSA_EXPORT_WITH_DES40_CBC_SHA = 0x00000014
PJ_TLS_DHE_RSA_WITH_DES_CBC_SHA = 0x00000015
PJ_TLS_DH_anon_EXPORT_WITH_RC4_40_MD5 = 0x00000017
PJ_TLS_DH_anon_EXPORT_WITH_DES40_CBC_SHA = 0x00000019
PJ_TLS_DH_anon_WITH_DES_CBC_SHA = 0x0000001A
PJ_SSL_FORTEZZA_KEA_WITH_NULL_SHA = 0x0000001C
PJ_SSL_FORTEZZA_KEA_WITH_FORTEZZA_CBC_SHA = 0x0000001D
PJ_SSL_FORTEZZA_KEA_WITH_RC4_128_SHA = 0x0000001E
PJ_SSL_CK_RC4_128_WITH_MD5 = 0x00010080
PJ_SSL_CK_RC4_128_EXPORT40_WITH_MD5 = 0x00020080
PJ_SSL_CK_RC2_128_CBC_WITH_MD5 = 0x00030080
PJ_SSL_CK_RC2_128_CBC_EXPORT40_WITH_MD5 = 0x00040080
PJ_SSL_CK_IDEA_128_CBC_WITH_MD5 = 0x00050080
PJ_SSL_CK_DES_64_CBC_WITH_MD5 = 0x00060040
PJ_SSL_CK_DES_192_EDE3_CBC_WITH_MD5 = 0x000700C0
enum pj_ssl_curve

Elliptic curves enumeration.

Values:

PJ_TLS_UNKNOWN_CURVE = 0
PJ_TLS_CURVE_SECT163K1 = 1
PJ_TLS_CURVE_SECT163R1 = 2
PJ_TLS_CURVE_SECT163R2 = 3
PJ_TLS_CURVE_SECT193R1 = 4
PJ_TLS_CURVE_SECT193R2 = 5
PJ_TLS_CURVE_SECT233K1 = 6
PJ_TLS_CURVE_SECT233R1 = 7
PJ_TLS_CURVE_SECT239K1 = 8
PJ_TLS_CURVE_SECT283K1 = 9
PJ_TLS_CURVE_SECT283R1 = 10
PJ_TLS_CURVE_SECT409K1 = 11
PJ_TLS_CURVE_SECT409R1 = 12
PJ_TLS_CURVE_SECT571K1 = 13
PJ_TLS_CURVE_SECT571R1 = 14
PJ_TLS_CURVE_SECP160K1 = 15
PJ_TLS_CURVE_SECP160R1 = 16
PJ_TLS_CURVE_SECP160R2 = 17
PJ_TLS_CURVE_SECP192K1 = 18
PJ_TLS_CURVE_SECP192R1 = 19
PJ_TLS_CURVE_SECP224K1 = 20
PJ_TLS_CURVE_SECP224R1 = 21
PJ_TLS_CURVE_SECP256K1 = 22
PJ_TLS_CURVE_SECP256R1 = 23
PJ_TLS_CURVE_SECP384R1 = 24
PJ_TLS_CURVE_SECP521R1 = 25
PJ_TLS_CURVE_BRAINPOOLP256R1 = 26
PJ_TLS_CURVE_BRAINPOOLP384R1 = 27
PJ_TLS_CURVE_BRAINPOOLP512R1 = 28
PJ_TLS_CURVE_ARBITRARY_EXPLICIT_PRIME_CURVES = 0XFF01
PJ_TLS_CURVE_ARBITRARY_EXPLICIT_CHAR2_CURVES = 0XFF02
enum pj_ssl_entropy_t

Values:

PJ_SSL_ENTROPY_NONE = 0
PJ_SSL_ENTROPY_EGD = 1
PJ_SSL_ENTROPY_RANDOM = 2
PJ_SSL_ENTROPY_URANDOM = 3
PJ_SSL_ENTROPY_FILE = 4
PJ_SSL_ENTROPY_UNKNOWN = 0x0F
enum pj_ssl_sock_proto

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

Values:

PJ_SSL_SOCK_PROTO_DEFAULT = 0

Default protocol of backend.

PJ_SSL_SOCK_PROTO_SSL2 = (1 << 0)

SSLv2.0 protocol.

PJ_SSL_SOCK_PROTO_SSL3 = (1 << 1)

SSLv3.0 protocol.

PJ_SSL_SOCK_PROTO_TLS1 = (1 << 2)

TLSv1.0 protocol.

PJ_SSL_SOCK_PROTO_TLS1_1 = (1 << 3)

TLSv1.1 protocol.

PJ_SSL_SOCK_PROTO_TLS1_2 = (1 << 4)

TLSv1.2 protocol.

PJ_SSL_SOCK_PROTO_SSL23 = (1 << 16) - 1

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

PJ_SSL_SOCK_PROTO_ALL = PJ_SSL_SOCK_PROTO_SSL23
PJ_SSL_SOCK_PROTO_DTLS1 = (1 << 16)

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.

Return

PJ_SUCCESS when successful.

Parameters
  • 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.

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.

Return

PJ_SUCCESS when successful.

Parameters
  • 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.

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.

Return

PJ_SUCCESS when successful.

Parameters
  • CA_file: The buffer of trusted CA list.

  • cert_file: The buffer of certificate.

  • privkey_file: The buffer of private key.

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

  • p_cert: Pointer to credential instance to be created.

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.

Return

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

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.

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.

Return

PJ_SUCCESS when successful.

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.

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.

Return

PJ_SUCCESS when successful.

Parameters
  • ciphers: The ciphers buffer to receive cipher list.

  • cipher_num: Maximum number of ciphers to be received.

pj_bool_t pj_ssl_cipher_is_supported(pj_ssl_cipher cipher)

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

Return

PJ_TRUE when supported.

Parameters
  • cipher: The cipher.

const char *pj_ssl_cipher_name(pj_ssl_cipher cipher)

Get cipher name string.

Return

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

Parameters
  • cipher: The cipher.

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.

Return

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

Parameters
  • cipher_name: The cipher name string.

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

Get curve list supported by SSL/TLS backend.

Return

PJ_SUCCESS when successful.

Parameters
  • curves: The curves buffer to receive curve list.

  • curves_num: Maximum number of curves to be received.

pj_bool_t pj_ssl_curve_is_supported(pj_ssl_curve curve)

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

Return

PJ_TRUE when supported.

Parameters
  • curve: The curve.

const char *pj_ssl_curve_name(pj_ssl_curve curve)

Get curve name string.

Return

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

Parameters
  • curve: The curve.

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.

Return

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

Parameters
  • curve_name: The curve name string.

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.

Return

PJ_SUCCESS when successful.

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.

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.

Return

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

Parameters
  • ssock: The secure socket instance.

  • pool: The pool.

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

pj_status_t pj_ssl_sock_close(pj_ssl_sock_t *ssock)

Close and destroy the secure socket.

Return

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

Parameters
  • ssock: The secure socket.

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.

Return

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

Parameters
  • ssock: The secure socket.

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

void *pj_ssl_sock_get_user_data(pj_ssl_sock_t *ssock)

Retrieve the user data previously associated with this secure socket.

Return

The user data.

Parameters
  • ssock: The secure socket.

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.

Return

PJ_SUCCESS on successful.

Parameters
  • ssock: The secure socket.

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

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.

Return

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

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().

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.

Return

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

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().

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.

Return

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

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().

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.

Return

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

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().

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.

Return

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.

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().

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.

Return

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.

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.

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.

Return

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

Parameters
  • ssock: The secure socket.

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

  • localaddr: Local address to bind on.

  • addr_len: Length of buffer containing local address.

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.

Return

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

Parameters
  • ssock: The secure socket.

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

  • localaddr: Local address to bind on.

  • addr_len: Length of buffer containing local address.

  • newsock_param: Secure socket parameter for new accepted sockets.

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.

Return

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.

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.

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.

Return

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.

Parameters

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.

Return

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.

Parameters
  • ssock: The secure socket.

struct pj_ssl_cert_info
#include <ssl_sock.h>

Describe structure of certificate info.

struct pj_ssl_sock_cb
#include <ssl_sock.h>

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

struct pj_ssl_sock_info
#include <ssl_sock.h>

Definition of secure socket info structure.

struct pj_ssl_sock_param
#include <ssl_sock.h>

Definition of secure socket creation parameters.

struct pj_ssl_start_connect_param
#include <ssl_sock.h>

The parameter for pj_ssl_sock_start_connect2().