Secure socket I/O [Input/Output]

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

Data Structures
struct	pj_ssl_cert_info
struct	pj_ssl_sock_cb
struct	pj_ssl_sock_info
struct	pj_ssl_sock_param
Typedefs
typedef struct pj_ssl_sock_t	pj_ssl_sock_t
typedef struct pj_ssl_cert_t	pj_ssl_cert_t
Enumerations
enum	pj_ssl_cert_verify_flag_t {   PJ_SSL_CERT_ESUCCESS = 0, PJ_SSL_CERT_EISSUER_NOT_FOUND = (1 << 0), PJ_SSL_CERT_EUNTRUSTED = (1 << 1), PJ_SSL_CERT_EVALIDITY_PERIOD = (1 << 2),   PJ_SSL_CERT_EINVALID_FORMAT = (1 << 3), PJ_SSL_CERT_EINVALID_PURPOSE = (1 << 4), PJ_SSL_CERT_EISSUER_MISMATCH = (1 << 5), PJ_SSL_CERT_ECRL_FAILURE = (1 << 6),   PJ_SSL_CERT_EREVOKED = (1 << 7), PJ_SSL_CERT_ECHAIN_TOO_LONG = (1 << 8), PJ_SSL_CERT_EIDENTITY_NOT_MATCH = (1 << 30), PJ_SSL_CERT_EUNKNOWN = (1 << 31) }
enum	pj_ssl_cert_name_type {   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 {   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_sock_proto {   PJ_SSL_SOCK_PROTO_DEFAULT, PJ_SSL_SOCK_PROTO_TLS1, PJ_SSL_SOCK_PROTO_SSL3, PJ_SSL_SOCK_PROTO_SSL23,   PJ_SSL_SOCK_PROTO_SSL2, PJ_SSL_SOCK_PROTO_DTLS1 }
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)
pj_ssize_t	pj_ssl_cert_info_dump (const pj_ssl_cert_info *ci, const char *indent, char *buf, pj_size_t buf_size)
pj_status_t	pj_ssl_cert_get_verify_status_strings (pj_uint32_t verify_status, const char *error_strings[], unsigned *count)
pj_status_t	pj_ssl_cipher_get_availables (pj_ssl_cipher ciphers[], unsigned *cipher_num)
pj_bool_t	pj_ssl_cipher_is_supported (pj_ssl_cipher cipher)
const char *	pj_ssl_cipher_name (pj_ssl_cipher cipher)
pj_ssl_cipher	pj_ssl_cipher_id (const char *cipher_name)
void	pj_ssl_sock_param_default (pj_ssl_sock_param *param)
pj_status_t	pj_ssl_sock_create (pj_pool_t *pool, const pj_ssl_sock_param *param, pj_ssl_sock_t **p_ssock)
pj_status_t	pj_ssl_sock_set_certificate (pj_ssl_sock_t *ssock, pj_pool_t *pool, const pj_ssl_cert_t *cert)
pj_status_t	pj_ssl_sock_close (pj_ssl_sock_t *ssock)
pj_status_t	pj_ssl_sock_set_user_data (pj_ssl_sock_t *ssock, void *user_data)
void *	pj_ssl_sock_get_user_data (pj_ssl_sock_t *ssock)
pj_status_t	pj_ssl_sock_get_info (pj_ssl_sock_t *ssock, pj_ssl_sock_info *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)
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)
pj_status_t	pj_ssl_sock_start_recvfrom (pj_ssl_sock_t *ssock, pj_pool_t *pool, unsigned buff_size, pj_uint32_t flags)
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)
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)
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)
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)
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)
pj_status_t	pj_ssl_sock_renegotiate (pj_ssl_sock_t *ssock)

---

Detailed Description

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.

---

Typedef Documentation

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 struct pj_ssl_sock_t pj_ssl_sock_t

This opaque structure describes the secure socket.

---

Enumeration Type Documentation

enum pj_ssl_cert_verify_flag_t

Enumerator:

PJ_SSL_CERT_ESUCCESS	No error in verification.
PJ_SSL_CERT_EISSUER_NOT_FOUND	The issuer certificate cannot be found.
PJ_SSL_CERT_EUNTRUSTED	The certificate is untrusted.
PJ_SSL_CERT_EVALIDITY_PERIOD	The certificate has expired or not yet valid.
PJ_SSL_CERT_EINVALID_FORMAT	One or more fields of the certificate cannot be decoded due to invalid format.
PJ_SSL_CERT_EINVALID_PURPOSE	The certificate cannot be used for the specified purpose.
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.
PJ_SSL_CERT_ECRL_FAILURE	The CRL certificate cannot be found or cannot be read properly.
PJ_SSL_CERT_EREVOKED	The certificate has been revoked.
PJ_SSL_CERT_ECHAIN_TOO_LONG	The certificate chain length is too long.
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.
PJ_SSL_CERT_EUNKNOWN	Unknown verification error.

enum pj_ssl_cipher

Cipher suites enumeration.

enum pj_ssl_sock_proto

Enumeration of secure socket protocol types.

Enumerator:

PJ_SSL_SOCK_PROTO_DEFAULT	Default protocol of backend.
PJ_SSL_SOCK_PROTO_TLS1	TLSv1.0 protocol.
PJ_SSL_SOCK_PROTO_SSL3	SSLv3.0 protocol.
PJ_SSL_SOCK_PROTO_SSL23	SSLv3.0 but can roll back to SSLv2.0.
PJ_SSL_SOCK_PROTO_SSL2	SSLv2.0 protocol.
PJ_SSL_SOCK_PROTO_DTLS1	DTLSv1.0 protocol.

---

Function Documentation

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.

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_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.

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.

Returns:

PJ_SUCCESS when successful.

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_ssl_cipher pj_ssl_cipher_id

(

const char *

cipher_name

)

Get cipher ID from cipher name string.

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_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_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_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_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.

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.

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.

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.

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_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_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.

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.
	localaddr	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_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_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.