Nanang Izzuddin | 6c62bf4 | 2009-08-27 19:55:13 +0000 | [diff] [blame] | 1 | /* $Id$ */ |
| 2 | /* |
| 3 | * Copyright (C) 2009 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> |
Benny Prijono | a25bc9d | 2009-11-09 08:51:34 +0000 | [diff] [blame] | 29 | #include <pj/sock_qos.h> |
Nanang Izzuddin | 6c62bf4 | 2009-08-27 19:55:13 +0000 | [diff] [blame] | 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 | |
Nanang Izzuddin | 6c62bf4 | 2009-08-27 19:55:13 +0000 | [diff] [blame] | 49 | |
Nanang Izzuddin | 006cc01 | 2009-10-16 03:06:13 +0000 | [diff] [blame] | 50 | /** |
Nanang Izzuddin | 6c62bf4 | 2009-08-27 19:55:13 +0000 | [diff] [blame] | 51 | * This opaque structure describes the secure socket. |
| 52 | */ |
| 53 | typedef struct pj_ssl_sock_t pj_ssl_sock_t; |
| 54 | |
Nanang Izzuddin | 006cc01 | 2009-10-16 03:06:13 +0000 | [diff] [blame] | 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 | |
Nanang Izzuddin | 2fb937e | 2010-02-24 05:43:34 +0000 | [diff] [blame] | 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 | |
Nanang Izzuddin | 006cc01 | 2009-10-16 03:06:13 +0000 | [diff] [blame] | 143 | /** |
Nanang Izzuddin | ea6d3c4 | 2009-10-26 15:47:52 +0000 | [diff] [blame] | 144 | * Describe structure of certificate info. |
| 145 | */ |
| 146 | typedef struct pj_ssl_cert_info { |
Nanang Izzuddin | 2fb937e | 2010-02-24 05:43:34 +0000 | [diff] [blame] | 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 |
Nanang Izzuddin | 5e69da5 | 2010-02-25 11:58:19 +0000 | [diff] [blame] | 157 | are separated by slash, e.g: |
| 158 | "CN=sample.org/OU=HRD" */ |
Nanang Izzuddin | 2fb937e | 2010-02-24 05:43:34 +0000 | [diff] [blame] | 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 | |
Nanang Izzuddin | ea6d3c4 | 2009-10-26 15:47:52 +0000 | [diff] [blame] | 184 | } pj_ssl_cert_info; |
| 185 | |
| 186 | |
| 187 | /** |
Nanang Izzuddin | 006cc01 | 2009-10-16 03:06:13 +0000 | [diff] [blame] | 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. |
Nanang Izzuddin | ea6d3c4 | 2009-10-26 15:47:52 +0000 | [diff] [blame] | 194 | * @param p_cert Pointer to credential instance to be created. |
Nanang Izzuddin | 006cc01 | 2009-10-16 03:06:13 +0000 | [diff] [blame] | 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 | |
Nanang Izzuddin | 2fb937e | 2010-02-24 05:43:34 +0000 | [diff] [blame] | 206 | /** |
| 207 | * Dump SSL certificate info. |
| 208 | * |
| 209 | * @param ci The certificate info. |
Nanang Izzuddin | 5e69da5 | 2010-02-25 11:58:19 +0000 | [diff] [blame] | 210 | * @param indent String for left indentation. |
Nanang Izzuddin | 2fb937e | 2010-02-24 05:43:34 +0000 | [diff] [blame] | 211 | * @param buf The buffer where certificate info will be printed on. |
| 212 | * @param buf_size The buffer size. |
| 213 | * |
Nanang Izzuddin | 5e69da5 | 2010-02-25 11:58:19 +0000 | [diff] [blame] | 214 | * @return The length of the dump result, or -1 when buffer size |
| 215 | * is not sufficient. |
Nanang Izzuddin | 2fb937e | 2010-02-24 05:43:34 +0000 | [diff] [blame] | 216 | */ |
Nanang Izzuddin | 5e69da5 | 2010-02-25 11:58:19 +0000 | [diff] [blame] | 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); |
Nanang Izzuddin | 2fb937e | 2010-02-24 05:43:34 +0000 | [diff] [blame] | 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 | */ |
Nanang Izzuddin | 5e69da5 | 2010-02-25 11:58:19 +0000 | [diff] [blame] | 235 | PJ_DECL(pj_status_t) pj_ssl_cert_get_verify_status_strings( |
| 236 | pj_uint32_t verify_status, |
Nanang Izzuddin | 2fb937e | 2010-02-24 05:43:34 +0000 | [diff] [blame] | 237 | const char *error_strings[], |
| 238 | unsigned *count); |
| 239 | |
| 240 | |
Nanang Izzuddin | 006cc01 | 2009-10-16 03:06:13 +0000 | [diff] [blame] | 241 | /** |
| 242 | * Cipher suites enumeration. |
| 243 | */ |
| 244 | typedef enum pj_ssl_cipher { |
| 245 | |
| 246 | /* NULL */ |
Nanang Izzuddin | 5e69da5 | 2010-02-25 11:58:19 +0000 | [diff] [blame] | 247 | PJ_TLS_NULL_WITH_NULL_NULL = 0x00000000, |
Nanang Izzuddin | 006cc01 | 2009-10-16 03:06:13 +0000 | [diff] [blame] | 248 | |
| 249 | /* TLS/SSLv3 */ |
Nanang Izzuddin | 5e69da5 | 2010-02-25 11:58:19 +0000 | [diff] [blame] | 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, |
Nanang Izzuddin | 006cc01 | 2009-10-16 03:06:13 +0000 | [diff] [blame] | 286 | |
| 287 | /* TLS (deprecated) */ |
Nanang Izzuddin | 5e69da5 | 2010-02-25 11:58:19 +0000 | [diff] [blame] | 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, |
Nanang Izzuddin | 006cc01 | 2009-10-16 03:06:13 +0000 | [diff] [blame] | 304 | |
| 305 | /* SSLv3 */ |
Nanang Izzuddin | 5e69da5 | 2010-02-25 11:58:19 +0000 | [diff] [blame] | 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, |
Nanang Izzuddin | 006cc01 | 2009-10-16 03:06:13 +0000 | [diff] [blame] | 309 | |
| 310 | /* SSLv2 */ |
Nanang Izzuddin | 5e69da5 | 2010-02-25 11:58:19 +0000 | [diff] [blame] | 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 |
Nanang Izzuddin | 006cc01 | 2009-10-16 03:06:13 +0000 | [diff] [blame] | 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 | * Get cipher name string. |
| 336 | * |
| 337 | * @param cipher The cipher. |
| 338 | * |
| 339 | * @return The cipher name or NULL if cipher is not recognized. |
| 340 | */ |
| 341 | PJ_DECL(const char*) pj_ssl_cipher_name(pj_ssl_cipher cipher); |
| 342 | |
| 343 | |
Nanang Izzuddin | 6c62bf4 | 2009-08-27 19:55:13 +0000 | [diff] [blame] | 344 | /** |
| 345 | * This structure contains the callbacks to be called by the secure socket. |
| 346 | */ |
| 347 | typedef struct pj_ssl_sock_cb |
| 348 | { |
| 349 | /** |
| 350 | * This callback is called when a data arrives as the result of |
| 351 | * pj_ssl_sock_start_read(). |
| 352 | * |
| 353 | * @param ssock The secure socket. |
| 354 | * @param data The buffer containing the new data, if any. If |
| 355 | * the status argument is non-PJ_SUCCESS, this |
| 356 | * argument may be NULL. |
| 357 | * @param size The length of data in the buffer. |
| 358 | * @param status The status of the read operation. This may contain |
| 359 | * non-PJ_SUCCESS for example when the TCP connection |
| 360 | * has been closed. In this case, the buffer may |
| 361 | * contain left over data from previous callback which |
| 362 | * the application may want to process. |
| 363 | * @param remainder If application wishes to leave some data in the |
| 364 | * buffer (common for TCP applications), it should |
| 365 | * move the remainder data to the front part of the |
| 366 | * buffer and set the remainder length here. The value |
| 367 | * of this parameter will be ignored for datagram |
| 368 | * sockets. |
| 369 | * |
| 370 | * @return PJ_TRUE if further read is desired, and PJ_FALSE |
| 371 | * when application no longer wants to receive data. |
| 372 | * Application may destroy the secure socket in the |
| 373 | * callback and return PJ_FALSE here. |
| 374 | */ |
| 375 | pj_bool_t (*on_data_read)(pj_ssl_sock_t *ssock, |
| 376 | void *data, |
| 377 | pj_size_t size, |
| 378 | pj_status_t status, |
| 379 | pj_size_t *remainder); |
| 380 | /** |
| 381 | * This callback is called when a packet arrives as the result of |
| 382 | * pj_ssl_sock_start_recvfrom(). |
| 383 | * |
| 384 | * @param ssock The secure socket. |
| 385 | * @param data The buffer containing the packet, if any. If |
| 386 | * the status argument is non-PJ_SUCCESS, this |
| 387 | * argument will be set to NULL. |
| 388 | * @param size The length of packet in the buffer. If |
| 389 | * the status argument is non-PJ_SUCCESS, this |
| 390 | * argument will be set to zero. |
| 391 | * @param src_addr Source address of the packet. |
| 392 | * @param addr_len Length of the source address. |
| 393 | * @param status This contains |
| 394 | * |
| 395 | * @return PJ_TRUE if further read is desired, and PJ_FALSE |
| 396 | * when application no longer wants to receive data. |
| 397 | * Application may destroy the secure socket in the |
| 398 | * callback and return PJ_FALSE here. |
| 399 | */ |
| 400 | pj_bool_t (*on_data_recvfrom)(pj_ssl_sock_t *ssock, |
| 401 | void *data, |
| 402 | pj_size_t size, |
| 403 | const pj_sockaddr_t *src_addr, |
| 404 | int addr_len, |
| 405 | pj_status_t status); |
| 406 | |
| 407 | /** |
| 408 | * This callback is called when data has been sent. |
| 409 | * |
| 410 | * @param ssock The secure socket. |
| 411 | * @param send_key Key associated with the send operation. |
| 412 | * @param sent If value is positive non-zero it indicates the |
| 413 | * number of data sent. When the value is negative, |
| 414 | * it contains the error code which can be retrieved |
| 415 | * by negating the value (i.e. status=-sent). |
| 416 | * |
| 417 | * @return Application may destroy the secure socket in the |
| 418 | * callback and return PJ_FALSE here. |
| 419 | */ |
| 420 | pj_bool_t (*on_data_sent)(pj_ssl_sock_t *ssock, |
| 421 | pj_ioqueue_op_key_t *send_key, |
| 422 | pj_ssize_t sent); |
| 423 | |
| 424 | /** |
| 425 | * This callback is called when new connection arrives as the result |
| 426 | * of pj_ssl_sock_start_accept(). |
| 427 | * |
| 428 | * @param ssock The secure socket. |
| 429 | * @param newsock The new incoming secure socket. |
| 430 | * @param src_addr The source address of the connection. |
| 431 | * @param addr_len Length of the source address. |
| 432 | * |
| 433 | * @return PJ_TRUE if further accept() is desired, and PJ_FALSE |
| 434 | * when application no longer wants to accept incoming |
| 435 | * connection. Application may destroy the secure socket |
| 436 | * in the callback and return PJ_FALSE here. |
| 437 | */ |
| 438 | pj_bool_t (*on_accept_complete)(pj_ssl_sock_t *ssock, |
| 439 | pj_ssl_sock_t *newsock, |
| 440 | const pj_sockaddr_t *src_addr, |
| 441 | int src_addr_len); |
| 442 | |
| 443 | /** |
| 444 | * This callback is called when pending connect operation has been |
| 445 | * completed. |
| 446 | * |
| 447 | * @param ssock The secure socket. |
| 448 | * @param status The connection result. If connection has been |
| 449 | * successfully established, the status will contain |
| 450 | * PJ_SUCCESS. |
| 451 | * |
| 452 | * @return Application may destroy the secure socket in the |
| 453 | * callback and return PJ_FALSE here. |
| 454 | */ |
| 455 | pj_bool_t (*on_connect_complete)(pj_ssl_sock_t *ssock, |
| 456 | pj_status_t status); |
| 457 | |
| 458 | } pj_ssl_sock_cb; |
| 459 | |
| 460 | |
| 461 | /** |
| 462 | * Enumeration of secure socket protocol types. |
| 463 | */ |
| 464 | typedef enum pj_ssl_sock_proto |
| 465 | { |
| 466 | PJ_SSL_SOCK_PROTO_DEFAULT, /**< Default protocol of backend. */ |
| 467 | PJ_SSL_SOCK_PROTO_TLS1, /**< TLSv1.0 protocol. */ |
Nanang Izzuddin | 6c62bf4 | 2009-08-27 19:55:13 +0000 | [diff] [blame] | 468 | PJ_SSL_SOCK_PROTO_SSL3, /**< SSLv3.0 protocol. */ |
| 469 | PJ_SSL_SOCK_PROTO_SSL23, /**< SSLv3.0 but can roll back to |
| 470 | SSLv2.0. */ |
Nanang Izzuddin | 006cc01 | 2009-10-16 03:06:13 +0000 | [diff] [blame] | 471 | PJ_SSL_SOCK_PROTO_SSL2, /**< SSLv2.0 protocol. */ |
Nanang Izzuddin | 6c62bf4 | 2009-08-27 19:55:13 +0000 | [diff] [blame] | 472 | PJ_SSL_SOCK_PROTO_DTLS1 /**< DTLSv1.0 protocol. */ |
| 473 | } pj_ssl_sock_proto; |
| 474 | |
| 475 | |
| 476 | /** |
| 477 | * Definition of secure socket info structure. |
| 478 | */ |
| 479 | typedef struct pj_ssl_sock_info |
| 480 | { |
| 481 | /** |
| 482 | * Describes whether secure socket connection is established, i.e: TLS/SSL |
| 483 | * handshaking has been done successfully. |
| 484 | */ |
| 485 | pj_bool_t established; |
Nanang Izzuddin | ea6d3c4 | 2009-10-26 15:47:52 +0000 | [diff] [blame] | 486 | |
Nanang Izzuddin | 6c62bf4 | 2009-08-27 19:55:13 +0000 | [diff] [blame] | 487 | /** |
| 488 | * Describes secure socket protocol being used. |
| 489 | */ |
| 490 | pj_ssl_sock_proto proto; |
Nanang Izzuddin | ea6d3c4 | 2009-10-26 15:47:52 +0000 | [diff] [blame] | 491 | |
Nanang Izzuddin | 6c62bf4 | 2009-08-27 19:55:13 +0000 | [diff] [blame] | 492 | /** |
Nanang Izzuddin | 006cc01 | 2009-10-16 03:06:13 +0000 | [diff] [blame] | 493 | * Describes cipher suite being used, this will only be set when connection |
| 494 | * is established. |
Nanang Izzuddin | 6c62bf4 | 2009-08-27 19:55:13 +0000 | [diff] [blame] | 495 | */ |
Nanang Izzuddin | 006cc01 | 2009-10-16 03:06:13 +0000 | [diff] [blame] | 496 | pj_ssl_cipher cipher; |
Nanang Izzuddin | ea6d3c4 | 2009-10-26 15:47:52 +0000 | [diff] [blame] | 497 | |
Nanang Izzuddin | 6c62bf4 | 2009-08-27 19:55:13 +0000 | [diff] [blame] | 498 | /** |
| 499 | * Describes local address. |
| 500 | */ |
| 501 | pj_sockaddr local_addr; |
Nanang Izzuddin | ea6d3c4 | 2009-10-26 15:47:52 +0000 | [diff] [blame] | 502 | |
Nanang Izzuddin | 6c62bf4 | 2009-08-27 19:55:13 +0000 | [diff] [blame] | 503 | /** |
| 504 | * Describes remote address. |
| 505 | */ |
| 506 | pj_sockaddr remote_addr; |
| 507 | |
Nanang Izzuddin | ea6d3c4 | 2009-10-26 15:47:52 +0000 | [diff] [blame] | 508 | /** |
| 509 | * Describes active local certificate info. |
| 510 | */ |
Nanang Izzuddin | 2fb937e | 2010-02-24 05:43:34 +0000 | [diff] [blame] | 511 | pj_ssl_cert_info *local_cert_info; |
Nanang Izzuddin | ea6d3c4 | 2009-10-26 15:47:52 +0000 | [diff] [blame] | 512 | |
| 513 | /** |
| 514 | * Describes active remote certificate info. |
| 515 | */ |
Nanang Izzuddin | 2fb937e | 2010-02-24 05:43:34 +0000 | [diff] [blame] | 516 | pj_ssl_cert_info *remote_cert_info; |
| 517 | |
| 518 | /** |
| 519 | * Status of peer certificate verification. |
| 520 | */ |
| 521 | pj_uint32_t verify_status; |
| 522 | |
Nanang Izzuddin | 6c62bf4 | 2009-08-27 19:55:13 +0000 | [diff] [blame] | 523 | } pj_ssl_sock_info; |
| 524 | |
Nanang Izzuddin | 006cc01 | 2009-10-16 03:06:13 +0000 | [diff] [blame] | 525 | |
Nanang Izzuddin | 6c62bf4 | 2009-08-27 19:55:13 +0000 | [diff] [blame] | 526 | /** |
| 527 | * Definition of secure socket creation parameters. |
| 528 | */ |
| 529 | typedef struct pj_ssl_sock_param |
| 530 | { |
| 531 | /** |
| 532 | * Specifies socket address family, either pj_AF_INET() and pj_AF_INET6(). |
| 533 | * |
| 534 | * Default is pj_AF_INET(). |
| 535 | */ |
| 536 | int sock_af; |
| 537 | |
| 538 | /** |
| 539 | * Specify socket type, either pj_SOCK_DGRAM() or pj_SOCK_STREAM(). |
| 540 | * |
| 541 | * Default is pj_SOCK_STREAM(). |
| 542 | */ |
| 543 | int sock_type; |
| 544 | |
| 545 | /** |
| 546 | * Specify the ioqueue to use. Secure socket uses the ioqueue to perform |
| 547 | * active socket operations, see \ref PJ_ACTIVESOCK for more detail. |
| 548 | */ |
| 549 | pj_ioqueue_t *ioqueue; |
| 550 | |
| 551 | /** |
Nanang Izzuddin | ea6d3c4 | 2009-10-26 15:47:52 +0000 | [diff] [blame] | 552 | * Specify the timer heap to use. Secure socket uses the timer to provide |
| 553 | * auto cancelation on asynchronous operation when it takes longer time |
| 554 | * than specified timeout period, e.g: security negotiation timeout. |
| 555 | */ |
| 556 | pj_timer_heap_t *timer_heap; |
| 557 | |
| 558 | /** |
Nanang Izzuddin | 6c62bf4 | 2009-08-27 19:55:13 +0000 | [diff] [blame] | 559 | * Specify secure socket callbacks, see #pj_ssl_sock_cb. |
| 560 | */ |
| 561 | pj_ssl_sock_cb cb; |
| 562 | |
| 563 | /** |
| 564 | * Specify secure socket user data. |
| 565 | */ |
| 566 | void *user_data; |
| 567 | |
| 568 | /** |
| 569 | * Specify security protocol to use, see #pj_ssl_sock_proto. |
| 570 | * |
| 571 | * Default is PJ_SSL_SOCK_PROTO_DEFAULT. |
| 572 | */ |
| 573 | pj_ssl_sock_proto proto; |
| 574 | |
| 575 | /** |
| 576 | * Number of concurrent asynchronous operations that is to be supported |
| 577 | * by the secure socket. This value only affects socket receive and |
| 578 | * accept operations -- the secure socket will issue one or more |
| 579 | * asynchronous read and accept operations based on the value of this |
| 580 | * field. Setting this field to more than one will allow more than one |
| 581 | * incoming data or incoming connections to be processed simultaneously |
| 582 | * on multiprocessor systems, when the ioqueue is polled by more than |
| 583 | * one threads. |
| 584 | * |
| 585 | * The default value is 1. |
| 586 | */ |
| 587 | unsigned async_cnt; |
| 588 | |
| 589 | /** |
| 590 | * The ioqueue concurrency to be forced on the socket when it is |
| 591 | * registered to the ioqueue. See #pj_ioqueue_set_concurrency() for more |
| 592 | * info about ioqueue concurrency. |
| 593 | * |
| 594 | * When this value is -1, the concurrency setting will not be forced for |
| 595 | * this socket, and the socket will inherit the concurrency setting of |
| 596 | * the ioqueue. When this value is zero, the secure socket will disable |
| 597 | * concurrency for the socket. When this value is +1, the secure socket |
| 598 | * will enable concurrency for the socket. |
| 599 | * |
| 600 | * The default value is -1. |
| 601 | */ |
| 602 | int concurrency; |
| 603 | |
| 604 | /** |
| 605 | * If this option is specified, the secure socket will make sure that |
| 606 | * asynchronous send operation with stream oriented socket will only |
| 607 | * call the callback after all data has been sent. This means that the |
| 608 | * secure socket will automatically resend the remaining data until |
| 609 | * all data has been sent. |
| 610 | * |
| 611 | * Please note that when this option is specified, it is possible that |
| 612 | * error is reported after partial data has been sent. Also setting |
| 613 | * this will disable the ioqueue concurrency for the socket. |
| 614 | * |
| 615 | * Default value is 1. |
| 616 | */ |
| 617 | pj_bool_t whole_data; |
| 618 | |
| 619 | /** |
Nanang Izzuddin | ea6d3c4 | 2009-10-26 15:47:52 +0000 | [diff] [blame] | 620 | * Specify buffer size for sending operation. Buffering sending data |
| 621 | * is used for allowing application to perform multiple outstanding |
| 622 | * send operations. Whenever application specifies this setting too |
| 623 | * small, sending operation may return PJ_ENOMEM. |
Nanang Izzuddin | 6c62bf4 | 2009-08-27 19:55:13 +0000 | [diff] [blame] | 624 | * |
Nanang Izzuddin | ea6d3c4 | 2009-10-26 15:47:52 +0000 | [diff] [blame] | 625 | * Default value is 8192 bytes. |
Nanang Izzuddin | 6c62bf4 | 2009-08-27 19:55:13 +0000 | [diff] [blame] | 626 | */ |
| 627 | pj_size_t send_buffer_size; |
| 628 | |
| 629 | /** |
Nanang Izzuddin | 006cc01 | 2009-10-16 03:06:13 +0000 | [diff] [blame] | 630 | * Specify buffer size for receiving encrypted (and perhaps compressed) |
| 631 | * data on underlying socket. This setting is unused on Symbian, since |
| 632 | * SSL/TLS Symbian backend, CSecureSocket, can use application buffer |
| 633 | * directly. |
| 634 | * |
| 635 | * Default value is 1500. |
| 636 | */ |
| 637 | pj_size_t read_buffer_size; |
| 638 | |
| 639 | /** |
| 640 | * Number of ciphers contained in the specified cipher preference. |
| 641 | * If this is set to zero, then default cipher list of the backend |
Nanang Izzuddin | 6c62bf4 | 2009-08-27 19:55:13 +0000 | [diff] [blame] | 642 | * will be used. |
| 643 | */ |
Nanang Izzuddin | 006cc01 | 2009-10-16 03:06:13 +0000 | [diff] [blame] | 644 | unsigned ciphers_num; |
| 645 | |
| 646 | /** |
| 647 | * Ciphers and order preference. If empty, then default cipher list and |
| 648 | * its default order of the backend will be used. |
| 649 | */ |
| 650 | pj_ssl_cipher *ciphers; |
Nanang Izzuddin | 6c62bf4 | 2009-08-27 19:55:13 +0000 | [diff] [blame] | 651 | |
| 652 | /** |
| 653 | * Security negotiation timeout. If this is set to zero (both sec and |
| 654 | * msec), the negotiation doesn't have a timeout. |
| 655 | * |
| 656 | * Default value is zero. |
| 657 | */ |
| 658 | pj_time_val timeout; |
| 659 | |
| 660 | /** |
| 661 | * Specify whether endpoint should verify peer certificate. |
| 662 | * |
| 663 | * Default value is PJ_FALSE. |
| 664 | */ |
| 665 | pj_bool_t verify_peer; |
| 666 | |
| 667 | /** |
| 668 | * When secure socket is acting as server (handles incoming connection), |
| 669 | * it will require the client to provide certificate. |
| 670 | * |
| 671 | * Default value is PJ_FALSE. |
| 672 | */ |
| 673 | pj_bool_t require_client_cert; |
| 674 | |
| 675 | /** |
Nanang Izzuddin | 2fb937e | 2010-02-24 05:43:34 +0000 | [diff] [blame] | 676 | * Server name indication. When secure socket is acting as client |
| 677 | * (perform outgoing connection) and the server may host multiple |
| 678 | * 'virtual' servers at a single underlying network address, setting |
| 679 | * this will allow client to tell the server a name of the server |
| 680 | * it is contacting. |
Nanang Izzuddin | 6c62bf4 | 2009-08-27 19:55:13 +0000 | [diff] [blame] | 681 | * |
| 682 | * Default value is zero/not-set. |
| 683 | */ |
Nanang Izzuddin | ea6d3c4 | 2009-10-26 15:47:52 +0000 | [diff] [blame] | 684 | pj_str_t server_name; |
Benny Prijono | a25bc9d | 2009-11-09 08:51:34 +0000 | [diff] [blame] | 685 | |
| 686 | /** |
| 687 | * QoS traffic type to be set on this transport. When application wants |
| 688 | * to apply QoS tagging to the transport, it's preferable to set this |
| 689 | * field rather than \a qos_param fields since this is more portable. |
| 690 | * |
| 691 | * Default value is PJ_QOS_TYPE_BEST_EFFORT. |
| 692 | */ |
| 693 | pj_qos_type qos_type; |
| 694 | |
| 695 | /** |
| 696 | * Set the low level QoS parameters to the transport. This is a lower |
| 697 | * level operation than setting the \a qos_type field and may not be |
| 698 | * supported on all platforms. |
| 699 | * |
| 700 | * By default all settings in this structure are disabled. |
| 701 | */ |
| 702 | pj_qos_params qos_params; |
| 703 | |
| 704 | /** |
| 705 | * Specify if the transport should ignore any errors when setting the QoS |
| 706 | * traffic type/parameters. |
| 707 | * |
| 708 | * Default: PJ_TRUE |
| 709 | */ |
| 710 | pj_bool_t qos_ignore_error; |
| 711 | |
| 712 | |
Nanang Izzuddin | 6c62bf4 | 2009-08-27 19:55:13 +0000 | [diff] [blame] | 713 | } pj_ssl_sock_param; |
| 714 | |
| 715 | |
| 716 | /** |
| 717 | * Initialize the secure socket parameters for its creation with |
| 718 | * the default values. |
| 719 | * |
| 720 | * @param param The parameter to be initialized. |
| 721 | */ |
| 722 | PJ_DECL(void) pj_ssl_sock_param_default(pj_ssl_sock_param *param); |
| 723 | |
| 724 | |
| 725 | /** |
| 726 | * Create secure socket instance. |
| 727 | * |
| 728 | * @param pool The pool for allocating secure socket instance. |
| 729 | * @param param The secure socket parameter, see #pj_ssl_sock_param. |
| 730 | * @param p_ssock Pointer to secure socket instance to be created. |
| 731 | * |
| 732 | * @return PJ_SUCCESS when successful. |
| 733 | */ |
| 734 | PJ_DECL(pj_status_t) pj_ssl_sock_create(pj_pool_t *pool, |
| 735 | const pj_ssl_sock_param *param, |
| 736 | pj_ssl_sock_t **p_ssock); |
| 737 | |
| 738 | |
| 739 | /** |
| 740 | * Set secure socket certificate or credentials. Credentials may include |
| 741 | * certificate, private key and trusted Certification Authorities list. |
| 742 | * Normally, server socket must provide certificate (and private key). |
| 743 | * Socket client may also need to provide certificate in case requested |
| 744 | * by the server. |
| 745 | * |
| 746 | * @param ssock The secure socket instance. |
| 747 | * @param pool The pool. |
| 748 | * @param cert The endpoint certificate/credentials, see |
| 749 | * #pj_ssl_cert_t. |
| 750 | * |
| 751 | * @return PJ_SUCCESS if the operation has been successful, |
| 752 | * or the appropriate error code on failure. |
| 753 | */ |
| 754 | PJ_DECL(pj_status_t) pj_ssl_sock_set_certificate( |
| 755 | pj_ssl_sock_t *ssock, |
| 756 | pj_pool_t *pool, |
| 757 | const pj_ssl_cert_t *cert); |
| 758 | |
| 759 | |
| 760 | /** |
| 761 | * Close and destroy the secure socket. |
| 762 | * |
| 763 | * @param ssock The secure socket. |
| 764 | * |
| 765 | * @return PJ_SUCCESS if the operation has been successful, |
| 766 | * or the appropriate error code on failure. |
| 767 | */ |
| 768 | PJ_DECL(pj_status_t) pj_ssl_sock_close(pj_ssl_sock_t *ssock); |
| 769 | |
| 770 | |
| 771 | /** |
| 772 | * Associate arbitrary data with the secure socket. Application may |
| 773 | * inspect this data in the callbacks and associate it with higher |
| 774 | * level processing. |
| 775 | * |
| 776 | * @param ssock The secure socket. |
| 777 | * @param user_data The user data to be associated with the secure |
| 778 | * socket. |
| 779 | * |
| 780 | * @return PJ_SUCCESS if the operation has been successful, |
| 781 | * or the appropriate error code on failure. |
| 782 | */ |
| 783 | PJ_DECL(pj_status_t) pj_ssl_sock_set_user_data(pj_ssl_sock_t *ssock, |
| 784 | void *user_data); |
| 785 | |
| 786 | /** |
| 787 | * Retrieve the user data previously associated with this secure |
| 788 | * socket. |
| 789 | * |
| 790 | * @param ssock The secure socket. |
| 791 | * |
| 792 | * @return The user data. |
| 793 | */ |
| 794 | PJ_DECL(void*) pj_ssl_sock_get_user_data(pj_ssl_sock_t *ssock); |
| 795 | |
| 796 | |
| 797 | /** |
| 798 | * Retrieve the local address and port used by specified secure socket. |
| 799 | * |
| 800 | * @param ssock The secure socket. |
| 801 | * @param info The info buffer to be set, see #pj_ssl_sock_info. |
| 802 | * |
| 803 | * @return PJ_SUCCESS on successful. |
| 804 | */ |
| 805 | PJ_DECL(pj_status_t) pj_ssl_sock_get_info(pj_ssl_sock_t *ssock, |
| 806 | pj_ssl_sock_info *info); |
| 807 | |
| 808 | |
| 809 | /** |
| 810 | * Starts read operation on this secure socket. This function will create |
| 811 | * \a async_cnt number of buffers (the \a async_cnt parameter was given |
| 812 | * in \a pj_ssl_sock_create() function) where each buffer is \a buff_size |
| 813 | * long. The buffers are allocated from the specified \a pool. Once the |
| 814 | * buffers are created, it then issues \a async_cnt number of asynchronous |
| 815 | * \a recv() operations to the socket and returns back to caller. Incoming |
| 816 | * data on the socket will be reported back to application via the |
| 817 | * \a on_data_read() callback. |
| 818 | * |
| 819 | * Application only needs to call this function once to initiate read |
| 820 | * operations. Further read operations will be done automatically by the |
| 821 | * secure socket when \a on_data_read() callback returns non-zero. |
| 822 | * |
| 823 | * @param ssock The secure socket. |
| 824 | * @param pool Pool used to allocate buffers for incoming data. |
| 825 | * @param buff_size The size of each buffer, in bytes. |
| 826 | * @param flags Flags to be given to pj_ioqueue_recv(). |
| 827 | * |
| 828 | * @return PJ_SUCCESS if the operation has been successful, |
| 829 | * or the appropriate error code on failure. |
| 830 | */ |
| 831 | PJ_DECL(pj_status_t) pj_ssl_sock_start_read(pj_ssl_sock_t *ssock, |
| 832 | pj_pool_t *pool, |
| 833 | unsigned buff_size, |
| 834 | pj_uint32_t flags); |
| 835 | |
| 836 | /** |
| 837 | * Same as #pj_ssl_sock_start_read(), except that the application |
| 838 | * supplies the buffers for the read operation so that the acive socket |
| 839 | * does not have to allocate the buffers. |
| 840 | * |
| 841 | * @param ssock The secure socket. |
| 842 | * @param pool Pool used to allocate buffers for incoming data. |
| 843 | * @param buff_size The size of each buffer, in bytes. |
| 844 | * @param readbuf Array of packet buffers, each has buff_size size. |
| 845 | * @param flags Flags to be given to pj_ioqueue_recv(). |
| 846 | * |
| 847 | * @return PJ_SUCCESS if the operation has been successful, |
| 848 | * or the appropriate error code on failure. |
| 849 | */ |
| 850 | PJ_DECL(pj_status_t) pj_ssl_sock_start_read2(pj_ssl_sock_t *ssock, |
| 851 | pj_pool_t *pool, |
| 852 | unsigned buff_size, |
| 853 | void *readbuf[], |
| 854 | pj_uint32_t flags); |
| 855 | |
| 856 | /** |
| 857 | * Same as pj_ssl_sock_start_read(), except that this function is used |
| 858 | * only for datagram sockets, and it will trigger \a on_data_recvfrom() |
| 859 | * callback instead. |
| 860 | * |
| 861 | * @param ssock The secure socket. |
| 862 | * @param pool Pool used to allocate buffers for incoming data. |
| 863 | * @param buff_size The size of each buffer, in bytes. |
| 864 | * @param flags Flags to be given to pj_ioqueue_recvfrom(). |
| 865 | * |
| 866 | * @return PJ_SUCCESS if the operation has been successful, |
| 867 | * or the appropriate error code on failure. |
| 868 | */ |
| 869 | PJ_DECL(pj_status_t) pj_ssl_sock_start_recvfrom(pj_ssl_sock_t *ssock, |
| 870 | pj_pool_t *pool, |
| 871 | unsigned buff_size, |
| 872 | pj_uint32_t flags); |
| 873 | |
| 874 | /** |
| 875 | * Same as #pj_ssl_sock_start_recvfrom() except that the recvfrom() |
| 876 | * operation takes the buffer from the argument rather than creating |
| 877 | * new ones. |
| 878 | * |
| 879 | * @param ssock The secure socket. |
| 880 | * @param pool Pool used to allocate buffers for incoming data. |
| 881 | * @param buff_size The size of each buffer, in bytes. |
| 882 | * @param readbuf Array of packet buffers, each has buff_size size. |
| 883 | * @param flags Flags to be given to pj_ioqueue_recvfrom(). |
| 884 | * |
| 885 | * @return PJ_SUCCESS if the operation has been successful, |
| 886 | * or the appropriate error code on failure. |
| 887 | */ |
| 888 | PJ_DECL(pj_status_t) pj_ssl_sock_start_recvfrom2(pj_ssl_sock_t *ssock, |
| 889 | pj_pool_t *pool, |
| 890 | unsigned buff_size, |
| 891 | void *readbuf[], |
| 892 | pj_uint32_t flags); |
| 893 | |
| 894 | /** |
| 895 | * Send data using the socket. |
| 896 | * |
| 897 | * @param ssock The secure socket. |
| 898 | * @param send_key The operation key to send the data, which is useful |
| 899 | * if application wants to submit multiple pending |
| 900 | * send operations and want to track which exact data |
| 901 | * has been sent in the \a on_data_sent() callback. |
| 902 | * @param data The data to be sent. This data must remain valid |
| 903 | * until the data has been sent. |
| 904 | * @param size The size of the data. |
| 905 | * @param flags Flags to be given to pj_ioqueue_send(). |
| 906 | * |
Nanang Izzuddin | 6c62bf4 | 2009-08-27 19:55:13 +0000 | [diff] [blame] | 907 | * @return PJ_SUCCESS if data has been sent immediately, or |
Nanang Izzuddin | ea6d3c4 | 2009-10-26 15:47:52 +0000 | [diff] [blame] | 908 | * PJ_EPENDING if data cannot be sent immediately or |
| 909 | * PJ_ENOMEM when sending buffer could not handle all |
| 910 | * queued data, see \a send_buffer_size. The callback |
| 911 | * \a on_data_sent() will be called when data is actually |
| 912 | * sent. Any other return value indicates error condition. |
Nanang Izzuddin | 6c62bf4 | 2009-08-27 19:55:13 +0000 | [diff] [blame] | 913 | */ |
| 914 | PJ_DECL(pj_status_t) pj_ssl_sock_send(pj_ssl_sock_t *ssock, |
| 915 | pj_ioqueue_op_key_t *send_key, |
| 916 | const void *data, |
| 917 | pj_ssize_t *size, |
| 918 | unsigned flags); |
| 919 | |
| 920 | /** |
| 921 | * Send datagram using the socket. |
| 922 | * |
| 923 | * @param ssock The secure socket. |
| 924 | * @param send_key The operation key to send the data, which is useful |
| 925 | * if application wants to submit multiple pending |
| 926 | * send operations and want to track which exact data |
| 927 | * has been sent in the \a on_data_sent() callback. |
| 928 | * @param data The data to be sent. This data must remain valid |
| 929 | * until the data has been sent. |
| 930 | * @param size The size of the data. |
| 931 | * @param flags Flags to be given to pj_ioqueue_send(). |
| 932 | * @param addr The destination address. |
| 933 | * @param addr_len Length of buffer containing destination address. |
| 934 | * |
| 935 | * @return PJ_SUCCESS if data has been sent immediately, or |
| 936 | * PJ_EPENDING if data cannot be sent immediately. In |
| 937 | * this case the \a on_data_sent() callback will be |
| 938 | * called when data is actually sent. Any other return |
| 939 | * value indicates error condition. |
| 940 | */ |
| 941 | PJ_DECL(pj_status_t) pj_ssl_sock_sendto(pj_ssl_sock_t *ssock, |
| 942 | pj_ioqueue_op_key_t *send_key, |
| 943 | const void *data, |
| 944 | pj_ssize_t *size, |
| 945 | unsigned flags, |
| 946 | const pj_sockaddr_t *addr, |
| 947 | int addr_len); |
| 948 | |
| 949 | |
| 950 | /** |
| 951 | * Starts asynchronous socket accept() operations on this secure socket. |
| 952 | * This function will issue \a async_cnt number of asynchronous \a accept() |
| 953 | * operations to the socket and returns back to caller. Incoming |
| 954 | * connection on the socket will be reported back to application via the |
| 955 | * \a on_accept_complete() callback. |
| 956 | * |
| 957 | * Application only needs to call this function once to initiate accept() |
| 958 | * operations. Further accept() operations will be done automatically by |
| 959 | * the secure socket when \a on_accept_complete() callback returns non-zero. |
| 960 | * |
| 961 | * @param ssock The secure socket. |
| 962 | * @param pool Pool used to allocate some internal data for the |
| 963 | * operation. |
| 964 | * @param localaddr Local address to bind on. |
| 965 | * @param addr_len Length of buffer containing local address. |
| 966 | * |
| 967 | * @return PJ_SUCCESS if the operation has been successful, |
| 968 | * or the appropriate error code on failure. |
| 969 | */ |
| 970 | PJ_DECL(pj_status_t) pj_ssl_sock_start_accept(pj_ssl_sock_t *ssock, |
| 971 | pj_pool_t *pool, |
| 972 | const pj_sockaddr_t *local_addr, |
| 973 | int addr_len); |
| 974 | |
| 975 | |
| 976 | /** |
| 977 | * Starts asynchronous socket connect() operation and SSL/TLS handshaking |
| 978 | * for this socket. Once the connection is done (either successfully or not), |
| 979 | * the \a on_connect_complete() callback will be called. |
| 980 | * |
| 981 | * @param ssock The secure socket. |
| 982 | * @param pool The pool to allocate some internal data for the |
| 983 | * operation. |
| 984 | * @param localaddr Local address. |
| 985 | * @param remaddr Remote address. |
| 986 | * @param addr_len Length of buffer containing above addresses. |
| 987 | * |
| 988 | * @return PJ_SUCCESS if connection can be established immediately |
| 989 | * or PJ_EPENDING if connection cannot be established |
| 990 | * immediately. In this case the \a on_connect_complete() |
| 991 | * callback will be called when connection is complete. |
| 992 | * Any other return value indicates error condition. |
| 993 | */ |
| 994 | PJ_DECL(pj_status_t) pj_ssl_sock_start_connect(pj_ssl_sock_t *ssock, |
| 995 | pj_pool_t *pool, |
| 996 | const pj_sockaddr_t *localaddr, |
| 997 | const pj_sockaddr_t *remaddr, |
| 998 | int addr_len); |
| 999 | |
| 1000 | |
| 1001 | /** |
Nanang Izzuddin | ea6d3c4 | 2009-10-26 15:47:52 +0000 | [diff] [blame] | 1002 | * Starts SSL/TLS renegotiation over an already established SSL connection |
| 1003 | * for this socket. This operation is performed transparently, no callback |
| 1004 | * will be called once the renegotiation completed successfully. However, |
| 1005 | * when the renegotiation fails, the connection will be closed and callback |
| 1006 | * \a on_data_read() will be invoked with non-PJ_SUCCESS status code. |
| 1007 | * |
| 1008 | * @param ssock The secure socket. |
| 1009 | * |
| 1010 | * @return PJ_SUCCESS if renegotiation is completed immediately, |
| 1011 | * or PJ_EPENDING if renegotiation has been started and |
| 1012 | * waiting for completion, or the appropriate error code |
| 1013 | * on failure. |
| 1014 | */ |
| 1015 | PJ_DECL(pj_status_t) pj_ssl_sock_renegotiate(pj_ssl_sock_t *ssock); |
| 1016 | |
| 1017 | |
| 1018 | /** |
Nanang Izzuddin | 6c62bf4 | 2009-08-27 19:55:13 +0000 | [diff] [blame] | 1019 | * @} |
| 1020 | */ |
| 1021 | |
| 1022 | PJ_END_DECL |
| 1023 | |
| 1024 | #endif /* __PJ_SSL_SOCK_H__ */ |