BLOG | DOCUMENTATION | TRAC

Home --> Documentations --> PJLIB Reference

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

Typedefs

typedef struct pj_ssl_sock_t pj_ssl_sock_t
 
typedef struct pj_ssl_cert_t pj_ssl_cert_t
 
typedef pj_str_t pj_ssl_cert_buffer
 

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_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 {
  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 {
  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 {
  PJ_SSL_SOCK_PROTO_DEFAULT = 0, PJ_SSL_SOCK_PROTO_SSL2 = (1 << 0), PJ_SSL_SOCK_PROTO_SSL3 = (1 << 1), PJ_SSL_SOCK_PROTO_TLS1 = (1 << 2),
  PJ_SSL_SOCK_PROTO_TLS1_1 = (1 << 3), PJ_SSL_SOCK_PROTO_TLS1_2 = (1 << 4), PJ_SSL_SOCK_PROTO_SSL23 = (1 << 16) - 1, PJ_SSL_SOCK_PROTO_ALL = PJ_SSL_SOCK_PROTO_SSL23,
  PJ_SSL_SOCK_PROTO_DTLS1 = (1 << 16)
}
 

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_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)
 
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)
 
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)
 
void pj_ssl_cert_wipe_keys (pj_ssl_cert_t *cert)
 
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)
 
pj_status_t pj_ssl_curve_get_availables (pj_ssl_curve curves[], unsigned *curve_num)
 
pj_bool_t pj_ssl_curve_is_supported (pj_ssl_curve curve)
 
const char * pj_ssl_curve_name (pj_ssl_curve curve)
 
pj_ssl_curve pj_ssl_curve_id (const char *curve_name)
 
void pj_ssl_sock_param_default (pj_ssl_sock_param *param)
 
void pj_ssl_sock_param_copy (pj_pool_t *pool, pj_ssl_sock_param *dst, const pj_ssl_sock_param *src)
 
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_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)
 
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_start_connect2 (pj_ssl_sock_t *ssock, pj_ssl_start_connect_param *connect_param)
 
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

◆ pj_ssl_cert_buffer

The SSL certificate buffer.

◆ pj_ssl_cert_t

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.

◆ pj_ssl_sock_t

typedef struct pj_ssl_sock_t pj_ssl_sock_t

This opaque structure describes the secure socket.

Enumeration Type Documentation

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

◆ pj_ssl_cipher

Cipher suites enumeration.

◆ pj_ssl_curve

Elliptic curves enumeration.

◆ pj_ssl_sock_proto

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

Enumerator
PJ_SSL_SOCK_PROTO_DEFAULT 

Default protocol of backend.

PJ_SSL_SOCK_PROTO_SSL2 

SSLv2.0 protocol.

PJ_SSL_SOCK_PROTO_SSL3 

SSLv3.0 protocol.

PJ_SSL_SOCK_PROTO_TLS1 

TLSv1.0 protocol.

PJ_SSL_SOCK_PROTO_TLS1_1 

TLSv1.1 protocol.

PJ_SSL_SOCK_PROTO_TLS1_2 

TLSv1.2 protocol.

PJ_SSL_SOCK_PROTO_SSL23 

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

PJ_SSL_SOCK_PROTO_DTLS1 

DTLSv1.0 protocol.

Function Documentation

◆ pj_ssl_cert_get_verify_status_strings()

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_statusThe SSL certificate verification status.
error_stringsArray of strings to receive the verification error messages.
countOn 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_ssl_cert_info_dump()

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
ciThe certificate info.
indentString for left indentation.
bufThe buffer where certificate info will be printed on.
buf_sizeThe buffer size.
Returns
The length of the dump result, or -1 when buffer size is not sufficient.

◆ pj_ssl_cert_load_from_buffer()

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
CA_fileThe buffer of trusted CA list.
cert_fileThe buffer of certificate.
privkey_fileThe buffer of private key.
privkey_passThe password of private key, if any.
p_certPointer to credential instance to be created.
Returns
PJ_SUCCESS when successful.

◆ pj_ssl_cert_load_from_files()

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
CA_fileThe file of trusted CA list.
cert_fileThe file of certificate.
privkey_fileThe file of private key.
privkey_passThe password of private key, if any.
p_certPointer to credential instance to be created.
Returns
PJ_SUCCESS when successful.

◆ pj_ssl_cert_load_from_files2()

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
CA_fileThe file of trusted CA list.
CA_pathThe path to a directory of trusted CA list.
cert_fileThe file of certificate.
privkey_fileThe file of private key.
privkey_passThe password of private key, if any.
p_certPointer to credential instance to be created.
Returns
PJ_SUCCESS when successful.

◆ pj_ssl_cert_wipe_keys()

void pj_ssl_cert_wipe_keys ( pj_ssl_cert_t cert)

Wipe out the keys in the SSL certificate.

Parameters
certThe SSL certificate.

◆ pj_ssl_cipher_get_availables()

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

Get cipher list supported by SSL/TLS backend.

Parameters
ciphersThe ciphers buffer to receive cipher list.
cipher_numMaximum number of ciphers to be received.
Returns
PJ_SUCCESS when successful.

◆ pj_ssl_cipher_id()

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_nameThe cipher name string.
Returns
The cipher ID or PJ_TLS_UNKNOWN_CIPHER if the cipher name string is not recognized/supported.

◆ pj_ssl_cipher_is_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
cipherThe cipher.
Returns
PJ_TRUE when supported.

◆ pj_ssl_cipher_name()

const char* pj_ssl_cipher_name ( pj_ssl_cipher  cipher)

Get cipher name string.

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

◆ pj_ssl_curve_get_availables()

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

Get curve list supported by SSL/TLS backend.

Parameters
curvesThe curves buffer to receive curve list.
curves_numMaximum number of curves to be received.
Returns
PJ_SUCCESS when successful.

◆ pj_ssl_curve_id()

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_nameThe curve name string.
Returns
The curve ID or PJ_TLS_UNKNOWN_CURVE if the curve name string is not recognized/supported.

◆ pj_ssl_curve_is_supported()

pj_bool_t pj_ssl_curve_is_supported ( pj_ssl_curve  curve)

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

Parameters
curveThe curve.
Returns
PJ_TRUE when supported.

◆ pj_ssl_curve_name()

const char* pj_ssl_curve_name ( pj_ssl_curve  curve)

Get curve name string.

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

◆ pj_ssl_sock_close()

pj_status_t pj_ssl_sock_close ( pj_ssl_sock_t ssock)

Close and destroy the secure socket.

Parameters
ssockThe secure socket.
Returns
PJ_SUCCESS if the operation has been successful, or the appropriate error code on failure.

◆ pj_ssl_sock_create()

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
poolThe pool for allocating secure socket instance.
paramThe secure socket parameter, see pj_ssl_sock_param.
p_ssockPointer to secure socket instance to be created.
Returns
PJ_SUCCESS when successful.

◆ pj_ssl_sock_get_info()

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
ssockThe secure socket.
infoThe info buffer to be set, see pj_ssl_sock_info.
Returns
PJ_SUCCESS on successful.

◆ pj_ssl_sock_get_user_data()

void* pj_ssl_sock_get_user_data ( pj_ssl_sock_t ssock)

Retrieve the user data previously associated with this secure socket.

Parameters
ssockThe secure socket.
Returns
The user data.

◆ pj_ssl_sock_param_copy()

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
poolPool to allocate memory.
dstDestination parameter.
srcSource parameter.

◆ pj_ssl_sock_param_default()

void pj_ssl_sock_param_default ( pj_ssl_sock_param param)

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

Parameters
paramThe parameter to be initialized.

◆ pj_ssl_sock_renegotiate()

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
ssockThe 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_ssl_sock_send()

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
ssockThe secure socket.
send_keyThe 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.
dataThe data to be sent. This data must remain valid until the data has been sent.
sizeThe size of the data.
flagsFlags 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_ssl_sock_sendto()

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
ssockThe secure socket.
send_keyThe 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.
dataThe data to be sent. This data must remain valid until the data has been sent.
sizeThe size of the data.
flagsFlags to be given to pj_ioqueue_send().
addrThe destination address.
addr_lenLength 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_ssl_sock_set_certificate()

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
ssockThe secure socket instance.
poolThe pool.
certThe 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_ssl_sock_set_user_data()

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
ssockThe secure socket.
user_dataThe 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_ssl_sock_start_accept()

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
ssockThe secure socket.
poolPool used to allocate some internal data for the operation.
localaddrLocal address to bind on.
addr_lenLength of buffer containing local address.
Returns
PJ_SUCCESS if the operation has been successful, or the appropriate error code on failure.

◆ pj_ssl_sock_start_accept2()

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
ssockThe secure socket.
poolPool used to allocate some internal data for the operation.
localaddrLocal address to bind on.
addr_lenLength of buffer containing local address.
newsock_paramSecure socket parameter for new accepted sockets.
Returns
PJ_SUCCESS if the operation has been successful, or the appropriate error code on failure.

◆ pj_ssl_sock_start_connect()

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
ssockThe secure socket.
poolThe pool to allocate some internal data for the operation.
localaddrLocal address.
remaddrRemote address.
addr_lenLength 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_ssl_sock_start_connect2()

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
ssockThe secure socket.
connect_paramThe parameter, refer to pj_ssl_start_connect_param.
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_ssl_sock_start_read()

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
ssockThe secure socket.
poolPool used to allocate buffers for incoming data.
buff_sizeThe size of each buffer, in bytes.
flagsFlags to be given to pj_ioqueue_recv().
Returns
PJ_SUCCESS if the operation has been successful, or the appropriate error code on failure.

◆ pj_ssl_sock_start_read2()

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
ssockThe secure socket.
poolPool used to allocate buffers for incoming data.
buff_sizeThe size of each buffer, in bytes.
readbufArray of packet buffers, each has buff_size size.
flagsFlags to be given to pj_ioqueue_recv().
Returns
PJ_SUCCESS if the operation has been successful, or the appropriate error code on failure.

◆ pj_ssl_sock_start_recvfrom()

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
ssockThe secure socket.
poolPool used to allocate buffers for incoming data.
buff_sizeThe size of each buffer, in bytes.
flagsFlags to be given to pj_ioqueue_recvfrom().
Returns
PJ_SUCCESS if the operation has been successful, or the appropriate error code on failure.

◆ pj_ssl_sock_start_recvfrom2()

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
ssockThe secure socket.
poolPool used to allocate buffers for incoming data.
buff_sizeThe size of each buffer, in bytes.
readbufArray of packet buffers, each has buff_size size.
flagsFlags to be given to pj_ioqueue_recvfrom().
Returns
PJ_SUCCESS if the operation has been successful, or the appropriate error code on failure.

 


PJLIB Open Source, high performance, small footprint, and very very portable framework
Copyright (C) 2006-2009 Teluu Inc.