Tristan Matthews | 0a329cc | 2013-07-17 13:20:14 -0400 | [diff] [blame] | 1 | /* $Id$ */ |
| 2 | /* |
| 3 | * Copyright (C) 2009-2011 Teluu Inc. (http://www.teluu.com) |
| 4 | * |
| 5 | * This program is free software; you can redistribute it and/or modify |
| 6 | * it under the terms of the GNU General Public License as published by |
| 7 | * the Free Software Foundation; either version 2 of the License, or |
| 8 | * (at your option) any later version. |
| 9 | * |
| 10 | * This program is distributed in the hope that it will be useful, |
| 11 | * but WITHOUT ANY WARRANTY; without even the implied warranty of |
| 12 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
| 13 | * GNU General Public License for more details. |
| 14 | * |
| 15 | * You should have received a copy of the GNU General Public License |
| 16 | * along with this program; if not, write to the Free Software |
| 17 | * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA |
| 18 | */ |
| 19 | #ifndef __PJ_SSL_SOCK_H__ |
| 20 | #define __PJ_SSL_SOCK_H__ |
| 21 | |
| 22 | /** |
| 23 | * @file ssl_sock.h |
| 24 | * @brief Secure socket |
| 25 | */ |
| 26 | |
| 27 | #include <pj/ioqueue.h> |
| 28 | #include <pj/sock.h> |
| 29 | #include <pj/sock_qos.h> |
| 30 | |
| 31 | |
| 32 | PJ_BEGIN_DECL |
| 33 | |
| 34 | /** |
| 35 | * @defgroup PJ_SSL_SOCK Secure socket I/O |
| 36 | * @brief Secure socket provides security on socket operation using standard |
| 37 | * security protocols such as SSL and TLS. |
| 38 | * @ingroup PJ_IO |
| 39 | * @{ |
| 40 | * |
| 41 | * Secure socket wraps normal socket and applies security features, i.e: |
| 42 | * privacy and data integrity, on the socket traffic, using standard security |
| 43 | * protocols such as SSL and TLS. |
| 44 | * |
| 45 | * Secure socket employs active socket operations, which is similar to (and |
| 46 | * described more detail) in \ref PJ_ACTIVESOCK. |
| 47 | */ |
| 48 | |
| 49 | |
| 50 | /** |
| 51 | * This opaque structure describes the secure socket. |
| 52 | */ |
| 53 | typedef struct pj_ssl_sock_t pj_ssl_sock_t; |
| 54 | |
| 55 | |
| 56 | /** |
| 57 | * Opaque declaration of endpoint certificate or credentials. This may contains |
| 58 | * certificate, private key, and trusted Certificate Authorities list. |
| 59 | */ |
| 60 | typedef struct pj_ssl_cert_t pj_ssl_cert_t; |
| 61 | |
| 62 | |
| 63 | typedef enum pj_ssl_cert_verify_flag_t |
| 64 | { |
| 65 | /** |
| 66 | * No error in verification. |
| 67 | */ |
| 68 | PJ_SSL_CERT_ESUCCESS = 0, |
| 69 | |
| 70 | /** |
| 71 | * The issuer certificate cannot be found. |
| 72 | */ |
| 73 | PJ_SSL_CERT_EISSUER_NOT_FOUND = (1 << 0), |
| 74 | |
| 75 | /** |
| 76 | * The certificate is untrusted. |
| 77 | */ |
| 78 | PJ_SSL_CERT_EUNTRUSTED = (1 << 1), |
| 79 | |
| 80 | /** |
| 81 | * The certificate has expired or not yet valid. |
| 82 | */ |
| 83 | PJ_SSL_CERT_EVALIDITY_PERIOD = (1 << 2), |
| 84 | |
| 85 | /** |
| 86 | * One or more fields of the certificate cannot be decoded due to |
| 87 | * invalid format. |
| 88 | */ |
| 89 | PJ_SSL_CERT_EINVALID_FORMAT = (1 << 3), |
| 90 | |
| 91 | /** |
| 92 | * The certificate cannot be used for the specified purpose. |
| 93 | */ |
| 94 | PJ_SSL_CERT_EINVALID_PURPOSE = (1 << 4), |
| 95 | |
| 96 | /** |
| 97 | * The issuer info in the certificate does not match to the (candidate) |
| 98 | * issuer certificate, e.g: issuer name not match to subject name |
| 99 | * of (candidate) issuer certificate. |
| 100 | */ |
| 101 | PJ_SSL_CERT_EISSUER_MISMATCH = (1 << 5), |
| 102 | |
| 103 | /** |
| 104 | * The CRL certificate cannot be found or cannot be read properly. |
| 105 | */ |
| 106 | PJ_SSL_CERT_ECRL_FAILURE = (1 << 6), |
| 107 | |
| 108 | /** |
| 109 | * The certificate has been revoked. |
| 110 | */ |
| 111 | PJ_SSL_CERT_EREVOKED = (1 << 7), |
| 112 | |
| 113 | /** |
| 114 | * The certificate chain length is too long. |
| 115 | */ |
| 116 | PJ_SSL_CERT_ECHAIN_TOO_LONG = (1 << 8), |
| 117 | |
| 118 | /** |
| 119 | * The server identity does not match to any identities specified in |
| 120 | * the certificate, e.g: subjectAltName extension, subject common name. |
| 121 | * This flag will only be set by application as SSL socket does not |
| 122 | * perform server identity verification. |
| 123 | */ |
| 124 | PJ_SSL_CERT_EIDENTITY_NOT_MATCH = (1 << 30), |
| 125 | |
| 126 | /** |
| 127 | * Unknown verification error. |
| 128 | */ |
| 129 | PJ_SSL_CERT_EUNKNOWN = (1 << 31) |
| 130 | |
| 131 | } pj_ssl_cert_verify_flag_t; |
| 132 | |
| 133 | |
| 134 | typedef enum pj_ssl_cert_name_type |
| 135 | { |
| 136 | PJ_SSL_CERT_NAME_UNKNOWN = 0, |
| 137 | PJ_SSL_CERT_NAME_RFC822, |
| 138 | PJ_SSL_CERT_NAME_DNS, |
| 139 | PJ_SSL_CERT_NAME_URI, |
| 140 | PJ_SSL_CERT_NAME_IP |
| 141 | } pj_ssl_cert_name_type; |
| 142 | |
| 143 | /** |
| 144 | * Describe structure of certificate info. |
| 145 | */ |
| 146 | typedef struct pj_ssl_cert_info { |
| 147 | |
| 148 | unsigned version; /**< Certificate version */ |
| 149 | |
| 150 | pj_uint8_t serial_no[20]; /**< Serial number, array of |
| 151 | octets, first index is |
| 152 | MSB */ |
| 153 | |
| 154 | struct { |
| 155 | pj_str_t cn; /**< Common name */ |
| 156 | pj_str_t info; /**< One line subject, fields |
| 157 | are separated by slash, e.g: |
| 158 | "CN=sample.org/OU=HRD" */ |
| 159 | } subject; /**< Subject */ |
| 160 | |
| 161 | struct { |
| 162 | pj_str_t cn; /**< Common name */ |
| 163 | pj_str_t info; /**< One line subject, fields |
| 164 | are separated by slash.*/ |
| 165 | } issuer; /**< Issuer */ |
| 166 | |
| 167 | struct { |
| 168 | pj_time_val start; /**< Validity start */ |
| 169 | pj_time_val end; /**< Validity end */ |
| 170 | pj_bool_t gmt; /**< Flag if validity date/time |
| 171 | use GMT */ |
| 172 | } validity; /**< Validity */ |
| 173 | |
| 174 | struct { |
| 175 | unsigned cnt; /**< # of entry */ |
| 176 | struct { |
| 177 | pj_ssl_cert_name_type type; |
| 178 | /**< Name type */ |
| 179 | pj_str_t name; /**< The name */ |
| 180 | } *entry; /**< Subject alt name entry */ |
| 181 | } subj_alt_name; /**< Subject alternative |
| 182 | name extension */ |
| 183 | |
| 184 | } pj_ssl_cert_info; |
| 185 | |
| 186 | |
| 187 | /** |
| 188 | * Create credential from files. |
| 189 | * |
| 190 | * @param CA_file The file of trusted CA list. |
| 191 | * @param cert_file The file of certificate. |
| 192 | * @param privkey_file The file of private key. |
| 193 | * @param privkey_pass The password of private key, if any. |
| 194 | * @param p_cert Pointer to credential instance to be created. |
| 195 | * |
| 196 | * @return PJ_SUCCESS when successful. |
| 197 | */ |
| 198 | PJ_DECL(pj_status_t) pj_ssl_cert_load_from_files(pj_pool_t *pool, |
| 199 | const pj_str_t *CA_file, |
| 200 | const pj_str_t *cert_file, |
| 201 | const pj_str_t *privkey_file, |
| 202 | const pj_str_t *privkey_pass, |
| 203 | pj_ssl_cert_t **p_cert); |
| 204 | |
| 205 | |
| 206 | /** |
| 207 | * Dump SSL certificate info. |
| 208 | * |
| 209 | * @param ci The certificate info. |
| 210 | * @param indent String for left indentation. |
| 211 | * @param buf The buffer where certificate info will be printed on. |
| 212 | * @param buf_size The buffer size. |
| 213 | * |
| 214 | * @return The length of the dump result, or -1 when buffer size |
| 215 | * is not sufficient. |
| 216 | */ |
| 217 | PJ_DECL(pj_ssize_t) pj_ssl_cert_info_dump(const pj_ssl_cert_info *ci, |
| 218 | const char *indent, |
| 219 | char *buf, |
| 220 | pj_size_t buf_size); |
| 221 | |
| 222 | |
| 223 | /** |
| 224 | * Get SSL certificate verification error messages from verification status. |
| 225 | * |
| 226 | * @param verify_status The SSL certificate verification status. |
| 227 | * @param error_strings Array of strings to receive the verification error |
| 228 | * messages. |
| 229 | * @param count On input it specifies maximum error messages should be |
| 230 | * retrieved. On output it specifies the number of error |
| 231 | * messages retrieved. |
| 232 | * |
| 233 | * @return PJ_SUCCESS when successful. |
| 234 | */ |
| 235 | PJ_DECL(pj_status_t) pj_ssl_cert_get_verify_status_strings( |
| 236 | pj_uint32_t verify_status, |
| 237 | const char *error_strings[], |
| 238 | unsigned *count); |
| 239 | |
| 240 | |
| 241 | /** |
| 242 | * Cipher suites enumeration. |
| 243 | */ |
| 244 | typedef enum pj_ssl_cipher { |
| 245 | |
| 246 | /* NULL */ |
| 247 | PJ_TLS_NULL_WITH_NULL_NULL = 0x00000000, |
| 248 | |
| 249 | /* TLS/SSLv3 */ |
| 250 | PJ_TLS_RSA_WITH_NULL_MD5 = 0x00000001, |
| 251 | PJ_TLS_RSA_WITH_NULL_SHA = 0x00000002, |
| 252 | PJ_TLS_RSA_WITH_NULL_SHA256 = 0x0000003B, |
| 253 | PJ_TLS_RSA_WITH_RC4_128_MD5 = 0x00000004, |
| 254 | PJ_TLS_RSA_WITH_RC4_128_SHA = 0x00000005, |
| 255 | PJ_TLS_RSA_WITH_3DES_EDE_CBC_SHA = 0x0000000A, |
| 256 | PJ_TLS_RSA_WITH_AES_128_CBC_SHA = 0x0000002F, |
| 257 | PJ_TLS_RSA_WITH_AES_256_CBC_SHA = 0x00000035, |
| 258 | PJ_TLS_RSA_WITH_AES_128_CBC_SHA256 = 0x0000003C, |
| 259 | PJ_TLS_RSA_WITH_AES_256_CBC_SHA256 = 0x0000003D, |
| 260 | PJ_TLS_DH_DSS_WITH_3DES_EDE_CBC_SHA = 0x0000000D, |
| 261 | PJ_TLS_DH_RSA_WITH_3DES_EDE_CBC_SHA = 0x00000010, |
| 262 | PJ_TLS_DHE_DSS_WITH_3DES_EDE_CBC_SHA = 0x00000013, |
| 263 | PJ_TLS_DHE_RSA_WITH_3DES_EDE_CBC_SHA = 0x00000016, |
| 264 | PJ_TLS_DH_DSS_WITH_AES_128_CBC_SHA = 0x00000030, |
| 265 | PJ_TLS_DH_RSA_WITH_AES_128_CBC_SHA = 0x00000031, |
| 266 | PJ_TLS_DHE_DSS_WITH_AES_128_CBC_SHA = 0x00000032, |
| 267 | PJ_TLS_DHE_RSA_WITH_AES_128_CBC_SHA = 0x00000033, |
| 268 | PJ_TLS_DH_DSS_WITH_AES_256_CBC_SHA = 0x00000036, |
| 269 | PJ_TLS_DH_RSA_WITH_AES_256_CBC_SHA = 0x00000037, |
| 270 | PJ_TLS_DHE_DSS_WITH_AES_256_CBC_SHA = 0x00000038, |
| 271 | PJ_TLS_DHE_RSA_WITH_AES_256_CBC_SHA = 0x00000039, |
| 272 | PJ_TLS_DH_DSS_WITH_AES_128_CBC_SHA256 = 0x0000003E, |
| 273 | PJ_TLS_DH_RSA_WITH_AES_128_CBC_SHA256 = 0x0000003F, |
| 274 | PJ_TLS_DHE_DSS_WITH_AES_128_CBC_SHA256 = 0x00000040, |
| 275 | PJ_TLS_DHE_RSA_WITH_AES_128_CBC_SHA256 = 0x00000067, |
| 276 | PJ_TLS_DH_DSS_WITH_AES_256_CBC_SHA256 = 0x00000068, |
| 277 | PJ_TLS_DH_RSA_WITH_AES_256_CBC_SHA256 = 0x00000069, |
| 278 | PJ_TLS_DHE_DSS_WITH_AES_256_CBC_SHA256 = 0x0000006A, |
| 279 | PJ_TLS_DHE_RSA_WITH_AES_256_CBC_SHA256 = 0x0000006B, |
| 280 | PJ_TLS_DH_anon_WITH_RC4_128_MD5 = 0x00000018, |
| 281 | PJ_TLS_DH_anon_WITH_3DES_EDE_CBC_SHA = 0x0000001B, |
| 282 | PJ_TLS_DH_anon_WITH_AES_128_CBC_SHA = 0x00000034, |
| 283 | PJ_TLS_DH_anon_WITH_AES_256_CBC_SHA = 0x0000003A, |
| 284 | PJ_TLS_DH_anon_WITH_AES_128_CBC_SHA256 = 0x0000006C, |
| 285 | PJ_TLS_DH_anon_WITH_AES_256_CBC_SHA256 = 0x0000006D, |
| 286 | |
| 287 | /* TLS (deprecated) */ |
| 288 | PJ_TLS_RSA_EXPORT_WITH_RC4_40_MD5 = 0x00000003, |
| 289 | PJ_TLS_RSA_EXPORT_WITH_RC2_CBC_40_MD5 = 0x00000006, |
| 290 | PJ_TLS_RSA_WITH_IDEA_CBC_SHA = 0x00000007, |
| 291 | PJ_TLS_RSA_EXPORT_WITH_DES40_CBC_SHA = 0x00000008, |
| 292 | PJ_TLS_RSA_WITH_DES_CBC_SHA = 0x00000009, |
| 293 | PJ_TLS_DH_DSS_EXPORT_WITH_DES40_CBC_SHA = 0x0000000B, |
| 294 | PJ_TLS_DH_DSS_WITH_DES_CBC_SHA = 0x0000000C, |
| 295 | PJ_TLS_DH_RSA_EXPORT_WITH_DES40_CBC_SHA = 0x0000000E, |
| 296 | PJ_TLS_DH_RSA_WITH_DES_CBC_SHA = 0x0000000F, |
| 297 | PJ_TLS_DHE_DSS_EXPORT_WITH_DES40_CBC_SHA = 0x00000011, |
| 298 | PJ_TLS_DHE_DSS_WITH_DES_CBC_SHA = 0x00000012, |
| 299 | PJ_TLS_DHE_RSA_EXPORT_WITH_DES40_CBC_SHA = 0x00000014, |
| 300 | PJ_TLS_DHE_RSA_WITH_DES_CBC_SHA = 0x00000015, |
| 301 | PJ_TLS_DH_anon_EXPORT_WITH_RC4_40_MD5 = 0x00000017, |
| 302 | PJ_TLS_DH_anon_EXPORT_WITH_DES40_CBC_SHA = 0x00000019, |
| 303 | PJ_TLS_DH_anon_WITH_DES_CBC_SHA = 0x0000001A, |
| 304 | |
| 305 | /* SSLv3 */ |
| 306 | PJ_SSL_FORTEZZA_KEA_WITH_NULL_SHA = 0x0000001C, |
| 307 | PJ_SSL_FORTEZZA_KEA_WITH_FORTEZZA_CBC_SHA = 0x0000001D, |
| 308 | PJ_SSL_FORTEZZA_KEA_WITH_RC4_128_SHA = 0x0000001E, |
| 309 | |
| 310 | /* SSLv2 */ |
| 311 | PJ_SSL_CK_RC4_128_WITH_MD5 = 0x00010080, |
| 312 | PJ_SSL_CK_RC4_128_EXPORT40_WITH_MD5 = 0x00020080, |
| 313 | PJ_SSL_CK_RC2_128_CBC_WITH_MD5 = 0x00030080, |
| 314 | PJ_SSL_CK_RC2_128_CBC_EXPORT40_WITH_MD5 = 0x00040080, |
| 315 | PJ_SSL_CK_IDEA_128_CBC_WITH_MD5 = 0x00050080, |
| 316 | PJ_SSL_CK_DES_64_CBC_WITH_MD5 = 0x00060040, |
| 317 | PJ_SSL_CK_DES_192_EDE3_CBC_WITH_MD5 = 0x000700C0 |
| 318 | |
| 319 | } pj_ssl_cipher; |
| 320 | |
| 321 | |
| 322 | /** |
| 323 | * Get cipher list supported by SSL/TLS backend. |
| 324 | * |
| 325 | * @param ciphers The ciphers buffer to receive cipher list. |
| 326 | * @param cipher_num Maximum number of ciphers to be received. |
| 327 | * |
| 328 | * @return PJ_SUCCESS when successful. |
| 329 | */ |
| 330 | PJ_DECL(pj_status_t) pj_ssl_cipher_get_availables(pj_ssl_cipher ciphers[], |
| 331 | unsigned *cipher_num); |
| 332 | |
| 333 | |
| 334 | /** |
| 335 | * Check if the specified cipher is supported by SSL/TLS backend. |
| 336 | * |
| 337 | * @param cipher The cipher. |
| 338 | * |
| 339 | * @return PJ_TRUE when supported. |
| 340 | */ |
| 341 | PJ_DECL(pj_bool_t) pj_ssl_cipher_is_supported(pj_ssl_cipher cipher); |
| 342 | |
| 343 | |
| 344 | /** |
| 345 | * Get cipher name string. |
| 346 | * |
| 347 | * @param cipher The cipher. |
| 348 | * |
| 349 | * @return The cipher name or NULL if cipher is not recognized/ |
| 350 | * supported. |
| 351 | */ |
| 352 | PJ_DECL(const char*) pj_ssl_cipher_name(pj_ssl_cipher cipher); |
| 353 | |
| 354 | |
| 355 | /** |
| 356 | * Get cipher ID from cipher name string. |
| 357 | * |
| 358 | * @param cipher_name The cipher name string. |
| 359 | * |
| 360 | * @return The cipher ID or PJ_TLS_UNKNOWN_CIPHER if the cipher |
| 361 | * name string is not recognized/supported. |
| 362 | */ |
| 363 | PJ_DECL(pj_ssl_cipher) pj_ssl_cipher_id(const char *cipher_name); |
| 364 | |
| 365 | |
| 366 | /** |
| 367 | * This structure contains the callbacks to be called by the secure socket. |
| 368 | */ |
| 369 | typedef struct pj_ssl_sock_cb |
| 370 | { |
| 371 | /** |
| 372 | * This callback is called when a data arrives as the result of |
| 373 | * pj_ssl_sock_start_read(). |
| 374 | * |
| 375 | * @param ssock The secure socket. |
| 376 | * @param data The buffer containing the new data, if any. If |
| 377 | * the status argument is non-PJ_SUCCESS, this |
| 378 | * argument may be NULL. |
| 379 | * @param size The length of data in the buffer. |
| 380 | * @param status The status of the read operation. This may contain |
| 381 | * non-PJ_SUCCESS for example when the TCP connection |
| 382 | * has been closed. In this case, the buffer may |
| 383 | * contain left over data from previous callback which |
| 384 | * the application may want to process. |
| 385 | * @param remainder If application wishes to leave some data in the |
| 386 | * buffer (common for TCP applications), it should |
| 387 | * move the remainder data to the front part of the |
| 388 | * buffer and set the remainder length here. The value |
| 389 | * of this parameter will be ignored for datagram |
| 390 | * sockets. |
| 391 | * |
| 392 | * @return PJ_TRUE if further read is desired, and PJ_FALSE |
| 393 | * when application no longer wants to receive data. |
| 394 | * Application may destroy the secure socket in the |
| 395 | * callback and return PJ_FALSE here. |
| 396 | */ |
| 397 | pj_bool_t (*on_data_read)(pj_ssl_sock_t *ssock, |
| 398 | void *data, |
| 399 | pj_size_t size, |
| 400 | pj_status_t status, |
| 401 | pj_size_t *remainder); |
| 402 | /** |
| 403 | * This callback is called when a packet arrives as the result of |
| 404 | * pj_ssl_sock_start_recvfrom(). |
| 405 | * |
| 406 | * @param ssock The secure socket. |
| 407 | * @param data The buffer containing the packet, if any. If |
| 408 | * the status argument is non-PJ_SUCCESS, this |
| 409 | * argument will be set to NULL. |
| 410 | * @param size The length of packet in the buffer. If |
| 411 | * the status argument is non-PJ_SUCCESS, this |
| 412 | * argument will be set to zero. |
| 413 | * @param src_addr Source address of the packet. |
| 414 | * @param addr_len Length of the source address. |
| 415 | * @param status This contains |
| 416 | * |
| 417 | * @return PJ_TRUE if further read is desired, and PJ_FALSE |
| 418 | * when application no longer wants to receive data. |
| 419 | * Application may destroy the secure socket in the |
| 420 | * callback and return PJ_FALSE here. |
| 421 | */ |
| 422 | pj_bool_t (*on_data_recvfrom)(pj_ssl_sock_t *ssock, |
| 423 | void *data, |
| 424 | pj_size_t size, |
| 425 | const pj_sockaddr_t *src_addr, |
| 426 | int addr_len, |
| 427 | pj_status_t status); |
| 428 | |
| 429 | /** |
| 430 | * This callback is called when data has been sent. |
| 431 | * |
| 432 | * @param ssock The secure socket. |
| 433 | * @param send_key Key associated with the send operation. |
| 434 | * @param sent If value is positive non-zero it indicates the |
| 435 | * number of data sent. When the value is negative, |
| 436 | * it contains the error code which can be retrieved |
| 437 | * by negating the value (i.e. status=-sent). |
| 438 | * |
| 439 | * @return Application may destroy the secure socket in the |
| 440 | * callback and return PJ_FALSE here. |
| 441 | */ |
| 442 | pj_bool_t (*on_data_sent)(pj_ssl_sock_t *ssock, |
| 443 | pj_ioqueue_op_key_t *send_key, |
| 444 | pj_ssize_t sent); |
| 445 | |
| 446 | /** |
| 447 | * This callback is called when new connection arrives as the result |
| 448 | * of pj_ssl_sock_start_accept(). |
| 449 | * |
| 450 | * @param ssock The secure socket. |
| 451 | * @param newsock The new incoming secure socket. |
| 452 | * @param src_addr The source address of the connection. |
| 453 | * @param addr_len Length of the source address. |
| 454 | * |
| 455 | * @return PJ_TRUE if further accept() is desired, and PJ_FALSE |
| 456 | * when application no longer wants to accept incoming |
| 457 | * connection. Application may destroy the secure socket |
| 458 | * in the callback and return PJ_FALSE here. |
| 459 | */ |
| 460 | pj_bool_t (*on_accept_complete)(pj_ssl_sock_t *ssock, |
| 461 | pj_ssl_sock_t *newsock, |
| 462 | const pj_sockaddr_t *src_addr, |
| 463 | int src_addr_len); |
| 464 | |
| 465 | /** |
| 466 | * This callback is called when pending connect operation has been |
| 467 | * completed. |
| 468 | * |
| 469 | * @param ssock The secure socket. |
| 470 | * @param status The connection result. If connection has been |
| 471 | * successfully established, the status will contain |
| 472 | * PJ_SUCCESS. |
| 473 | * |
| 474 | * @return Application may destroy the secure socket in the |
| 475 | * callback and return PJ_FALSE here. |
| 476 | */ |
| 477 | pj_bool_t (*on_connect_complete)(pj_ssl_sock_t *ssock, |
| 478 | pj_status_t status); |
| 479 | |
| 480 | } pj_ssl_sock_cb; |
| 481 | |
| 482 | |
| 483 | /** |
| 484 | * Enumeration of secure socket protocol types. |
| 485 | */ |
| 486 | typedef enum pj_ssl_sock_proto |
| 487 | { |
| 488 | PJ_SSL_SOCK_PROTO_DEFAULT, /**< Default protocol of backend. */ |
| 489 | PJ_SSL_SOCK_PROTO_TLS1, /**< TLSv1.0 protocol. */ |
| 490 | PJ_SSL_SOCK_PROTO_SSL3, /**< SSLv3.0 protocol. */ |
| 491 | PJ_SSL_SOCK_PROTO_SSL23, /**< SSLv3.0 but can roll back to |
| 492 | SSLv2.0. */ |
| 493 | PJ_SSL_SOCK_PROTO_SSL2, /**< SSLv2.0 protocol. */ |
| 494 | PJ_SSL_SOCK_PROTO_DTLS1 /**< DTLSv1.0 protocol. */ |
| 495 | } pj_ssl_sock_proto; |
| 496 | |
| 497 | |
| 498 | /** |
| 499 | * Definition of secure socket info structure. |
| 500 | */ |
| 501 | typedef struct pj_ssl_sock_info |
| 502 | { |
| 503 | /** |
| 504 | * Describes whether secure socket connection is established, i.e: TLS/SSL |
| 505 | * handshaking has been done successfully. |
| 506 | */ |
| 507 | pj_bool_t established; |
| 508 | |
| 509 | /** |
| 510 | * Describes secure socket protocol being used. |
| 511 | */ |
| 512 | pj_ssl_sock_proto proto; |
| 513 | |
| 514 | /** |
| 515 | * Describes cipher suite being used, this will only be set when connection |
| 516 | * is established. |
| 517 | */ |
| 518 | pj_ssl_cipher cipher; |
| 519 | |
| 520 | /** |
| 521 | * Describes local address. |
| 522 | */ |
| 523 | pj_sockaddr local_addr; |
| 524 | |
| 525 | /** |
| 526 | * Describes remote address. |
| 527 | */ |
| 528 | pj_sockaddr remote_addr; |
| 529 | |
| 530 | /** |
| 531 | * Describes active local certificate info. |
| 532 | */ |
| 533 | pj_ssl_cert_info *local_cert_info; |
| 534 | |
| 535 | /** |
| 536 | * Describes active remote certificate info. |
| 537 | */ |
| 538 | pj_ssl_cert_info *remote_cert_info; |
| 539 | |
| 540 | /** |
| 541 | * Status of peer certificate verification. |
| 542 | */ |
| 543 | pj_uint32_t verify_status; |
| 544 | |
| 545 | /** |
| 546 | * Last native error returned by the backend. |
| 547 | */ |
| 548 | unsigned long last_native_err; |
| 549 | |
| 550 | } pj_ssl_sock_info; |
| 551 | |
| 552 | |
| 553 | /** |
| 554 | * Definition of secure socket creation parameters. |
| 555 | */ |
| 556 | typedef struct pj_ssl_sock_param |
| 557 | { |
| 558 | /** |
| 559 | * Specifies socket address family, either pj_AF_INET() and pj_AF_INET6(). |
| 560 | * |
| 561 | * Default is pj_AF_INET(). |
| 562 | */ |
| 563 | int sock_af; |
| 564 | |
| 565 | /** |
| 566 | * Specify socket type, either pj_SOCK_DGRAM() or pj_SOCK_STREAM(). |
| 567 | * |
| 568 | * Default is pj_SOCK_STREAM(). |
| 569 | */ |
| 570 | int sock_type; |
| 571 | |
| 572 | /** |
| 573 | * Specify the ioqueue to use. Secure socket uses the ioqueue to perform |
| 574 | * active socket operations, see \ref PJ_ACTIVESOCK for more detail. |
| 575 | */ |
| 576 | pj_ioqueue_t *ioqueue; |
| 577 | |
| 578 | /** |
| 579 | * Specify the timer heap to use. Secure socket uses the timer to provide |
| 580 | * auto cancelation on asynchronous operation when it takes longer time |
| 581 | * than specified timeout period, e.g: security negotiation timeout. |
| 582 | */ |
| 583 | pj_timer_heap_t *timer_heap; |
| 584 | |
| 585 | /** |
| 586 | * Specify secure socket callbacks, see #pj_ssl_sock_cb. |
| 587 | */ |
| 588 | pj_ssl_sock_cb cb; |
| 589 | |
| 590 | /** |
| 591 | * Specify secure socket user data. |
| 592 | */ |
| 593 | void *user_data; |
| 594 | |
| 595 | /** |
| 596 | * Specify security protocol to use, see #pj_ssl_sock_proto. |
| 597 | * |
| 598 | * Default is PJ_SSL_SOCK_PROTO_DEFAULT. |
| 599 | */ |
| 600 | pj_ssl_sock_proto proto; |
| 601 | |
| 602 | /** |
| 603 | * Number of concurrent asynchronous operations that is to be supported |
| 604 | * by the secure socket. This value only affects socket receive and |
| 605 | * accept operations -- the secure socket will issue one or more |
| 606 | * asynchronous read and accept operations based on the value of this |
| 607 | * field. Setting this field to more than one will allow more than one |
| 608 | * incoming data or incoming connections to be processed simultaneously |
| 609 | * on multiprocessor systems, when the ioqueue is polled by more than |
| 610 | * one threads. |
| 611 | * |
| 612 | * The default value is 1. |
| 613 | */ |
| 614 | unsigned async_cnt; |
| 615 | |
| 616 | /** |
| 617 | * The ioqueue concurrency to be forced on the socket when it is |
| 618 | * registered to the ioqueue. See #pj_ioqueue_set_concurrency() for more |
| 619 | * info about ioqueue concurrency. |
| 620 | * |
| 621 | * When this value is -1, the concurrency setting will not be forced for |
| 622 | * this socket, and the socket will inherit the concurrency setting of |
| 623 | * the ioqueue. When this value is zero, the secure socket will disable |
| 624 | * concurrency for the socket. When this value is +1, the secure socket |
| 625 | * will enable concurrency for the socket. |
| 626 | * |
| 627 | * The default value is -1. |
| 628 | */ |
| 629 | int concurrency; |
| 630 | |
| 631 | /** |
| 632 | * If this option is specified, the secure socket will make sure that |
| 633 | * asynchronous send operation with stream oriented socket will only |
| 634 | * call the callback after all data has been sent. This means that the |
| 635 | * secure socket will automatically resend the remaining data until |
| 636 | * all data has been sent. |
| 637 | * |
| 638 | * Please note that when this option is specified, it is possible that |
| 639 | * error is reported after partial data has been sent. Also setting |
| 640 | * this will disable the ioqueue concurrency for the socket. |
| 641 | * |
| 642 | * Default value is 1. |
| 643 | */ |
| 644 | pj_bool_t whole_data; |
| 645 | |
| 646 | /** |
| 647 | * Specify buffer size for sending operation. Buffering sending data |
| 648 | * is used for allowing application to perform multiple outstanding |
| 649 | * send operations. Whenever application specifies this setting too |
| 650 | * small, sending operation may return PJ_ENOMEM. |
| 651 | * |
| 652 | * Default value is 8192 bytes. |
| 653 | */ |
| 654 | pj_size_t send_buffer_size; |
| 655 | |
| 656 | /** |
| 657 | * Specify buffer size for receiving encrypted (and perhaps compressed) |
| 658 | * data on underlying socket. This setting is unused on Symbian, since |
| 659 | * SSL/TLS Symbian backend, CSecureSocket, can use application buffer |
| 660 | * directly. |
| 661 | * |
| 662 | * Default value is 1500. |
| 663 | */ |
| 664 | pj_size_t read_buffer_size; |
| 665 | |
| 666 | /** |
| 667 | * Number of ciphers contained in the specified cipher preference. |
| 668 | * If this is set to zero, then default cipher list of the backend |
| 669 | * will be used. |
| 670 | */ |
| 671 | unsigned ciphers_num; |
| 672 | |
| 673 | /** |
| 674 | * Ciphers and order preference. If empty, then default cipher list and |
| 675 | * its default order of the backend will be used. |
| 676 | */ |
| 677 | pj_ssl_cipher *ciphers; |
| 678 | |
| 679 | /** |
| 680 | * Security negotiation timeout. If this is set to zero (both sec and |
| 681 | * msec), the negotiation doesn't have a timeout. |
| 682 | * |
| 683 | * Default value is zero. |
| 684 | */ |
| 685 | pj_time_val timeout; |
| 686 | |
| 687 | /** |
| 688 | * Specify whether endpoint should verify peer certificate. |
| 689 | * |
| 690 | * Default value is PJ_FALSE. |
| 691 | */ |
| 692 | pj_bool_t verify_peer; |
| 693 | |
| 694 | /** |
| 695 | * When secure socket is acting as server (handles incoming connection), |
| 696 | * it will require the client to provide certificate. |
| 697 | * |
| 698 | * Default value is PJ_FALSE. |
| 699 | */ |
| 700 | pj_bool_t require_client_cert; |
| 701 | |
| 702 | /** |
| 703 | * Server name indication. When secure socket is acting as client |
| 704 | * (perform outgoing connection) and the server may host multiple |
| 705 | * 'virtual' servers at a single underlying network address, setting |
| 706 | * this will allow client to tell the server a name of the server |
| 707 | * it is contacting. |
| 708 | * |
| 709 | * Default value is zero/not-set. |
| 710 | */ |
| 711 | pj_str_t server_name; |
| 712 | |
| 713 | /** |
| 714 | * Specify if SO_REUSEADDR should be used for listening socket. This |
| 715 | * option will only be used with accept() operation. |
| 716 | * |
| 717 | * Default is PJ_FALSE. |
| 718 | */ |
| 719 | pj_bool_t reuse_addr; |
| 720 | |
| 721 | /** |
| 722 | * QoS traffic type to be set on this transport. When application wants |
| 723 | * to apply QoS tagging to the transport, it's preferable to set this |
| 724 | * field rather than \a qos_param fields since this is more portable. |
| 725 | * |
| 726 | * Default value is PJ_QOS_TYPE_BEST_EFFORT. |
| 727 | */ |
| 728 | pj_qos_type qos_type; |
| 729 | |
| 730 | /** |
| 731 | * Set the low level QoS parameters to the transport. This is a lower |
| 732 | * level operation than setting the \a qos_type field and may not be |
| 733 | * supported on all platforms. |
| 734 | * |
| 735 | * By default all settings in this structure are disabled. |
| 736 | */ |
| 737 | pj_qos_params qos_params; |
| 738 | |
| 739 | /** |
| 740 | * Specify if the transport should ignore any errors when setting the QoS |
| 741 | * traffic type/parameters. |
| 742 | * |
| 743 | * Default: PJ_TRUE |
| 744 | */ |
| 745 | pj_bool_t qos_ignore_error; |
| 746 | |
| 747 | |
| 748 | } pj_ssl_sock_param; |
| 749 | |
| 750 | |
| 751 | /** |
| 752 | * Initialize the secure socket parameters for its creation with |
| 753 | * the default values. |
| 754 | * |
| 755 | * @param param The parameter to be initialized. |
| 756 | */ |
| 757 | PJ_DECL(void) pj_ssl_sock_param_default(pj_ssl_sock_param *param); |
| 758 | |
| 759 | |
| 760 | /** |
| 761 | * Create secure socket instance. |
| 762 | * |
| 763 | * @param pool The pool for allocating secure socket instance. |
| 764 | * @param param The secure socket parameter, see #pj_ssl_sock_param. |
| 765 | * @param p_ssock Pointer to secure socket instance to be created. |
| 766 | * |
| 767 | * @return PJ_SUCCESS when successful. |
| 768 | */ |
| 769 | PJ_DECL(pj_status_t) pj_ssl_sock_create(pj_pool_t *pool, |
| 770 | const pj_ssl_sock_param *param, |
| 771 | pj_ssl_sock_t **p_ssock); |
| 772 | |
| 773 | |
| 774 | /** |
| 775 | * Set secure socket certificate or credentials. Credentials may include |
| 776 | * certificate, private key and trusted Certification Authorities list. |
| 777 | * Normally, server socket must provide certificate (and private key). |
| 778 | * Socket client may also need to provide certificate in case requested |
| 779 | * by the server. |
| 780 | * |
| 781 | * @param ssock The secure socket instance. |
| 782 | * @param pool The pool. |
| 783 | * @param cert The endpoint certificate/credentials, see |
| 784 | * #pj_ssl_cert_t. |
| 785 | * |
| 786 | * @return PJ_SUCCESS if the operation has been successful, |
| 787 | * or the appropriate error code on failure. |
| 788 | */ |
| 789 | PJ_DECL(pj_status_t) pj_ssl_sock_set_certificate( |
| 790 | pj_ssl_sock_t *ssock, |
| 791 | pj_pool_t *pool, |
| 792 | const pj_ssl_cert_t *cert); |
| 793 | |
| 794 | |
| 795 | /** |
| 796 | * Close and destroy the secure socket. |
| 797 | * |
| 798 | * @param ssock The secure socket. |
| 799 | * |
| 800 | * @return PJ_SUCCESS if the operation has been successful, |
| 801 | * or the appropriate error code on failure. |
| 802 | */ |
| 803 | PJ_DECL(pj_status_t) pj_ssl_sock_close(pj_ssl_sock_t *ssock); |
| 804 | |
| 805 | |
| 806 | /** |
| 807 | * Associate arbitrary data with the secure socket. Application may |
| 808 | * inspect this data in the callbacks and associate it with higher |
| 809 | * level processing. |
| 810 | * |
| 811 | * @param ssock The secure socket. |
| 812 | * @param user_data The user data to be associated with the secure |
| 813 | * socket. |
| 814 | * |
| 815 | * @return PJ_SUCCESS if the operation has been successful, |
| 816 | * or the appropriate error code on failure. |
| 817 | */ |
| 818 | PJ_DECL(pj_status_t) pj_ssl_sock_set_user_data(pj_ssl_sock_t *ssock, |
| 819 | void *user_data); |
| 820 | |
| 821 | /** |
| 822 | * Retrieve the user data previously associated with this secure |
| 823 | * socket. |
| 824 | * |
| 825 | * @param ssock The secure socket. |
| 826 | * |
| 827 | * @return The user data. |
| 828 | */ |
| 829 | PJ_DECL(void*) pj_ssl_sock_get_user_data(pj_ssl_sock_t *ssock); |
| 830 | |
| 831 | |
| 832 | /** |
| 833 | * Retrieve the local address and port used by specified secure socket. |
| 834 | * |
| 835 | * @param ssock The secure socket. |
| 836 | * @param info The info buffer to be set, see #pj_ssl_sock_info. |
| 837 | * |
| 838 | * @return PJ_SUCCESS on successful. |
| 839 | */ |
| 840 | PJ_DECL(pj_status_t) pj_ssl_sock_get_info(pj_ssl_sock_t *ssock, |
| 841 | pj_ssl_sock_info *info); |
| 842 | |
| 843 | |
| 844 | /** |
| 845 | * Starts read operation on this secure socket. This function will create |
| 846 | * \a async_cnt number of buffers (the \a async_cnt parameter was given |
| 847 | * in \a pj_ssl_sock_create() function) where each buffer is \a buff_size |
| 848 | * long. The buffers are allocated from the specified \a pool. Once the |
| 849 | * buffers are created, it then issues \a async_cnt number of asynchronous |
| 850 | * \a recv() operations to the socket and returns back to caller. Incoming |
| 851 | * data on the socket will be reported back to application via the |
| 852 | * \a on_data_read() callback. |
| 853 | * |
| 854 | * Application only needs to call this function once to initiate read |
| 855 | * operations. Further read operations will be done automatically by the |
| 856 | * secure socket when \a on_data_read() callback returns non-zero. |
| 857 | * |
| 858 | * @param ssock The secure socket. |
| 859 | * @param pool Pool used to allocate buffers for incoming data. |
| 860 | * @param buff_size The size of each buffer, in bytes. |
| 861 | * @param flags Flags to be given to pj_ioqueue_recv(). |
| 862 | * |
| 863 | * @return PJ_SUCCESS if the operation has been successful, |
| 864 | * or the appropriate error code on failure. |
| 865 | */ |
| 866 | PJ_DECL(pj_status_t) pj_ssl_sock_start_read(pj_ssl_sock_t *ssock, |
| 867 | pj_pool_t *pool, |
| 868 | unsigned buff_size, |
| 869 | pj_uint32_t flags); |
| 870 | |
| 871 | /** |
| 872 | * Same as #pj_ssl_sock_start_read(), except that the application |
| 873 | * supplies the buffers for the read operation so that the acive socket |
| 874 | * does not have to allocate the buffers. |
| 875 | * |
| 876 | * @param ssock The secure socket. |
| 877 | * @param pool Pool used to allocate buffers for incoming data. |
| 878 | * @param buff_size The size of each buffer, in bytes. |
| 879 | * @param readbuf Array of packet buffers, each has buff_size size. |
| 880 | * @param flags Flags to be given to pj_ioqueue_recv(). |
| 881 | * |
| 882 | * @return PJ_SUCCESS if the operation has been successful, |
| 883 | * or the appropriate error code on failure. |
| 884 | */ |
| 885 | PJ_DECL(pj_status_t) pj_ssl_sock_start_read2(pj_ssl_sock_t *ssock, |
| 886 | pj_pool_t *pool, |
| 887 | unsigned buff_size, |
| 888 | void *readbuf[], |
| 889 | pj_uint32_t flags); |
| 890 | |
| 891 | /** |
| 892 | * Same as pj_ssl_sock_start_read(), except that this function is used |
| 893 | * only for datagram sockets, and it will trigger \a on_data_recvfrom() |
| 894 | * callback instead. |
| 895 | * |
| 896 | * @param ssock The secure socket. |
| 897 | * @param pool Pool used to allocate buffers for incoming data. |
| 898 | * @param buff_size The size of each buffer, in bytes. |
| 899 | * @param flags Flags to be given to pj_ioqueue_recvfrom(). |
| 900 | * |
| 901 | * @return PJ_SUCCESS if the operation has been successful, |
| 902 | * or the appropriate error code on failure. |
| 903 | */ |
| 904 | PJ_DECL(pj_status_t) pj_ssl_sock_start_recvfrom(pj_ssl_sock_t *ssock, |
| 905 | pj_pool_t *pool, |
| 906 | unsigned buff_size, |
| 907 | pj_uint32_t flags); |
| 908 | |
| 909 | /** |
| 910 | * Same as #pj_ssl_sock_start_recvfrom() except that the recvfrom() |
| 911 | * operation takes the buffer from the argument rather than creating |
| 912 | * new ones. |
| 913 | * |
| 914 | * @param ssock The secure socket. |
| 915 | * @param pool Pool used to allocate buffers for incoming data. |
| 916 | * @param buff_size The size of each buffer, in bytes. |
| 917 | * @param readbuf Array of packet buffers, each has buff_size size. |
| 918 | * @param flags Flags to be given to pj_ioqueue_recvfrom(). |
| 919 | * |
| 920 | * @return PJ_SUCCESS if the operation has been successful, |
| 921 | * or the appropriate error code on failure. |
| 922 | */ |
| 923 | PJ_DECL(pj_status_t) pj_ssl_sock_start_recvfrom2(pj_ssl_sock_t *ssock, |
| 924 | pj_pool_t *pool, |
| 925 | unsigned buff_size, |
| 926 | void *readbuf[], |
| 927 | pj_uint32_t flags); |
| 928 | |
| 929 | /** |
| 930 | * Send data using the socket. |
| 931 | * |
| 932 | * @param ssock The secure socket. |
| 933 | * @param send_key The operation key to send the data, which is useful |
| 934 | * if application wants to submit multiple pending |
| 935 | * send operations and want to track which exact data |
| 936 | * has been sent in the \a on_data_sent() callback. |
| 937 | * @param data The data to be sent. This data must remain valid |
| 938 | * until the data has been sent. |
| 939 | * @param size The size of the data. |
| 940 | * @param flags Flags to be given to pj_ioqueue_send(). |
| 941 | * |
| 942 | * @return PJ_SUCCESS if data has been sent immediately, or |
| 943 | * PJ_EPENDING if data cannot be sent immediately or |
| 944 | * PJ_ENOMEM when sending buffer could not handle all |
| 945 | * queued data, see \a send_buffer_size. The callback |
| 946 | * \a on_data_sent() will be called when data is actually |
| 947 | * sent. Any other return value indicates error condition. |
| 948 | */ |
| 949 | PJ_DECL(pj_status_t) pj_ssl_sock_send(pj_ssl_sock_t *ssock, |
| 950 | pj_ioqueue_op_key_t *send_key, |
| 951 | const void *data, |
| 952 | pj_ssize_t *size, |
| 953 | unsigned flags); |
| 954 | |
| 955 | /** |
| 956 | * Send datagram using the socket. |
| 957 | * |
| 958 | * @param ssock The secure socket. |
| 959 | * @param send_key The operation key to send the data, which is useful |
| 960 | * if application wants to submit multiple pending |
| 961 | * send operations and want to track which exact data |
| 962 | * has been sent in the \a on_data_sent() callback. |
| 963 | * @param data The data to be sent. This data must remain valid |
| 964 | * until the data has been sent. |
| 965 | * @param size The size of the data. |
| 966 | * @param flags Flags to be given to pj_ioqueue_send(). |
| 967 | * @param addr The destination address. |
| 968 | * @param addr_len Length of buffer containing destination address. |
| 969 | * |
| 970 | * @return PJ_SUCCESS if data has been sent immediately, or |
| 971 | * PJ_EPENDING if data cannot be sent immediately. In |
| 972 | * this case the \a on_data_sent() callback will be |
| 973 | * called when data is actually sent. Any other return |
| 974 | * value indicates error condition. |
| 975 | */ |
| 976 | PJ_DECL(pj_status_t) pj_ssl_sock_sendto(pj_ssl_sock_t *ssock, |
| 977 | pj_ioqueue_op_key_t *send_key, |
| 978 | const void *data, |
| 979 | pj_ssize_t *size, |
| 980 | unsigned flags, |
| 981 | const pj_sockaddr_t *addr, |
| 982 | int addr_len); |
| 983 | |
| 984 | |
| 985 | /** |
| 986 | * Starts asynchronous socket accept() operations on this secure socket. |
| 987 | * This function will issue \a async_cnt number of asynchronous \a accept() |
| 988 | * operations to the socket and returns back to caller. Incoming |
| 989 | * connection on the socket will be reported back to application via the |
| 990 | * \a on_accept_complete() callback. |
| 991 | * |
| 992 | * Application only needs to call this function once to initiate accept() |
| 993 | * operations. Further accept() operations will be done automatically by |
| 994 | * the secure socket when \a on_accept_complete() callback returns non-zero. |
| 995 | * |
| 996 | * @param ssock The secure socket. |
| 997 | * @param pool Pool used to allocate some internal data for the |
| 998 | * operation. |
| 999 | * @param localaddr Local address to bind on. |
| 1000 | * @param addr_len Length of buffer containing local address. |
| 1001 | * |
| 1002 | * @return PJ_SUCCESS if the operation has been successful, |
| 1003 | * or the appropriate error code on failure. |
| 1004 | */ |
| 1005 | PJ_DECL(pj_status_t) pj_ssl_sock_start_accept(pj_ssl_sock_t *ssock, |
| 1006 | pj_pool_t *pool, |
| 1007 | const pj_sockaddr_t *local_addr, |
| 1008 | int addr_len); |
| 1009 | |
| 1010 | |
| 1011 | /** |
| 1012 | * Starts asynchronous socket connect() operation and SSL/TLS handshaking |
| 1013 | * for this socket. Once the connection is done (either successfully or not), |
| 1014 | * the \a on_connect_complete() callback will be called. |
| 1015 | * |
| 1016 | * @param ssock The secure socket. |
| 1017 | * @param pool The pool to allocate some internal data for the |
| 1018 | * operation. |
| 1019 | * @param localaddr Local address. |
| 1020 | * @param remaddr Remote address. |
| 1021 | * @param addr_len Length of buffer containing above addresses. |
| 1022 | * |
| 1023 | * @return PJ_SUCCESS if connection can be established immediately |
| 1024 | * or PJ_EPENDING if connection cannot be established |
| 1025 | * immediately. In this case the \a on_connect_complete() |
| 1026 | * callback will be called when connection is complete. |
| 1027 | * Any other return value indicates error condition. |
| 1028 | */ |
| 1029 | PJ_DECL(pj_status_t) pj_ssl_sock_start_connect(pj_ssl_sock_t *ssock, |
| 1030 | pj_pool_t *pool, |
| 1031 | const pj_sockaddr_t *localaddr, |
| 1032 | const pj_sockaddr_t *remaddr, |
| 1033 | int addr_len); |
| 1034 | |
| 1035 | |
| 1036 | /** |
| 1037 | * Starts SSL/TLS renegotiation over an already established SSL connection |
| 1038 | * for this socket. This operation is performed transparently, no callback |
| 1039 | * will be called once the renegotiation completed successfully. However, |
| 1040 | * when the renegotiation fails, the connection will be closed and callback |
| 1041 | * \a on_data_read() will be invoked with non-PJ_SUCCESS status code. |
| 1042 | * |
| 1043 | * @param ssock The secure socket. |
| 1044 | * |
| 1045 | * @return PJ_SUCCESS if renegotiation is completed immediately, |
| 1046 | * or PJ_EPENDING if renegotiation has been started and |
| 1047 | * waiting for completion, or the appropriate error code |
| 1048 | * on failure. |
| 1049 | */ |
| 1050 | PJ_DECL(pj_status_t) pj_ssl_sock_renegotiate(pj_ssl_sock_t *ssock); |
| 1051 | |
| 1052 | |
| 1053 | /** |
| 1054 | * @} |
| 1055 | */ |
| 1056 | |
| 1057 | PJ_END_DECL |
| 1058 | |
| 1059 | #endif /* __PJ_SSL_SOCK_H__ */ |