← Back to branch summary

~ubuntu-branches/ubuntu/trusty/sflphone/trusty

« back to all changes in this revision

Viewing changes to daemon/libs/pjproject-2.0.1/pjlib/include/pj/ssl_sock.h

  • Committer: Package Import Robot
  • Author(s): Mark Purcell
  • Date: 2014-01-28 18:23:36 UTC
  • mfrom: (4.3.4 sid)
  • Revision ID: package-import@ubuntu.com-20140128182336-jrsv0k9u6cawc068
Tags: 1.3.0-1
http://bugs.debian.org/735846
http://bugs.debian.org/727164
http://bugs.debian.org/718178
http://bugs.debian.org/736583
http://bugs.debian.org/722040
http://bugs.debian.org/736746
* New upstream release 
  - Fixes "New Upstream Release" (Closes: #735846)
  - Fixes "Ringtone does not stop" (Closes: #727164)
  - Fixes "[sflphone-kde] crash on startup" (Closes: #718178)
  - Fixes "sflphone GUI crashes when call is hung up" (Closes: #736583)
* Build-Depends: ensure GnuTLS 2.6
  - libucommon-dev (>= 6.0.7-1.1), libccrtp-dev (>= 2.0.6-3)
  - Fixes "FTBFS Build-Depends libgnutls{26,28}-dev" (Closes: #722040)
* Fix "boost 1.49 is going away" unversioned Build-Depends: (Closes: #736746)
* Add Build-Depends: libsndfile-dev, nepomuk-core-dev

Show diffs side-by-side

added added

removed removed

Lines of Context:
daemon/libs/pjproject-2.0.1/pjlib/include/pj/ssl_sock.h
1
 
/* $Id: ssl_sock.h 4146 2012-05-30 06:35:59Z nanang $ */
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
 
     * QoS traffic type to be set on this transport. When application wants
715
 
     * to apply QoS tagging to the transport, it's preferable to set this
716
 
     * field rather than \a qos_param fields since this is more portable.
717
 
     *
718
 
     * Default value is PJ_QOS_TYPE_BEST_EFFORT.
719
 
     */
720
 
    pj_qos_type qos_type;
721
 
 
722
 
    /**
723
 
     * Set the low level QoS parameters to the transport. This is a lower
724
 
     * level operation than setting the \a qos_type field and may not be
725
 
     * supported on all platforms.
726
 
     *
727
 
     * By default all settings in this structure are disabled.
728
 
     */
729
 
    pj_qos_params qos_params;
730
 
 
731
 
    /**
732
 
     * Specify if the transport should ignore any errors when setting the QoS
733
 
     * traffic type/parameters.
734
 
     *
735
 
     * Default: PJ_TRUE
736
 
     */
737
 
    pj_bool_t qos_ignore_error;
738
 
 
739
 
 
740
 
} pj_ssl_sock_param;
741
 
 
742
 
 
743
 
/**
744
 
 * Initialize the secure socket parameters for its creation with
745
 
 * the default values.
746
 
 *
747
 
 * @param param         The parameter to be initialized.
748
 
 */
749
 
PJ_DECL(void) pj_ssl_sock_param_default(pj_ssl_sock_param *param);
750
 
 
751
 
 
752
 
/**
753
 
 * Create secure socket instance.
754
 
 *
755
 
 * @param pool          The pool for allocating secure socket instance.
756
 
 * @param param         The secure socket parameter, see #pj_ssl_sock_param.
757
 
 * @param p_ssock       Pointer to secure socket instance to be created.
758
 
 *
759
 
 * @return              PJ_SUCCESS when successful.
760
 
 */
761
 
PJ_DECL(pj_status_t) pj_ssl_sock_create(pj_pool_t *pool,
762
 
                                        const pj_ssl_sock_param *param,
763
 
                                        pj_ssl_sock_t **p_ssock);
764
 
 
765
 
 
766
 
/**
767
 
 * Set secure socket certificate or credentials. Credentials may include
768
 
 * certificate, private key and trusted Certification Authorities list.
769
 
 * Normally, server socket must provide certificate (and private key).
770
 
 * Socket client may also need to provide certificate in case requested
771
 
 * by the server.
772
 
 *
773
 
 * @param ssock         The secure socket instance.
774
 
 * @param pool          The pool.
775
 
 * @param cert          The endpoint certificate/credentials, see
776
 
 *                      #pj_ssl_cert_t.
777
 
 *
778
 
 * @return              PJ_SUCCESS if the operation has been successful,
779
 
 *                      or the appropriate error code on failure.
780
 
 */
781
 
PJ_DECL(pj_status_t) pj_ssl_sock_set_certificate(
782
 
                                            pj_ssl_sock_t *ssock,
783
 
                                            pj_pool_t *pool,
784
 
                                            const pj_ssl_cert_t *cert);
785
 
 
786
 
 
787
 
/**
788
 
 * Close and destroy the secure socket.
789
 
 *
790
 
 * @param ssock         The secure socket.
791
 
 *
792
 
 * @return              PJ_SUCCESS if the operation has been successful,
793
 
 *                      or the appropriate error code on failure.
794
 
 */
795
 
PJ_DECL(pj_status_t) pj_ssl_sock_close(pj_ssl_sock_t *ssock);
796
 
 
797
 
 
798
 
/**
799
 
 * Associate arbitrary data with the secure socket. Application may
800
 
 * inspect this data in the callbacks and associate it with higher
801
 
 * level processing.
802
 
 *
803
 
 * @param ssock         The secure socket.
804
 
 * @param user_data     The user data to be associated with the secure
805
 
 *                      socket.
806
 
 *
807
 
 * @return              PJ_SUCCESS if the operation has been successful,
808
 
 *                      or the appropriate error code on failure.
809
 
 */
810
 
PJ_DECL(pj_status_t) pj_ssl_sock_set_user_data(pj_ssl_sock_t *ssock,
811
 
                                               void *user_data);
812
 
 
813
 
/**
814
 
 * Retrieve the user data previously associated with this secure
815
 
 * socket.
816
 
 *
817
 
 * @param ssock         The secure socket.
818
 
 *
819
 
 * @return              The user data.
820
 
 */
821
 
PJ_DECL(void*) pj_ssl_sock_get_user_data(pj_ssl_sock_t *ssock);
822
 
 
823
 
 
824
 
/**
825
 
 * Retrieve the local address and port used by specified secure socket.
826
 
 *
827
 
 * @param ssock         The secure socket.
828
 
 * @param info          The info buffer to be set, see #pj_ssl_sock_info.
829
 
 *
830
 
 * @return              PJ_SUCCESS on successful.
831
 
 */
832
 
PJ_DECL(pj_status_t) pj_ssl_sock_get_info(pj_ssl_sock_t *ssock,
833
 
                                          pj_ssl_sock_info *info);
834
 
 
835
 
 
836
 
/**
837
 
 * Starts read operation on this secure socket. This function will create
838
 
 * \a async_cnt number of buffers (the \a async_cnt parameter was given
839
 
 * in \a pj_ssl_sock_create() function) where each buffer is \a buff_size
840
 
 * long. The buffers are allocated from the specified \a pool. Once the
841
 
 * buffers are created, it then issues \a async_cnt number of asynchronous
842
 
 * \a recv() operations to the socket and returns back to caller. Incoming
843
 
 * data on the socket will be reported back to application via the
844
 
 * \a on_data_read() callback.
845
 
 *
846
 
 * Application only needs to call this function once to initiate read
847
 
 * operations. Further read operations will be done automatically by the
848
 
 * secure socket when \a on_data_read() callback returns non-zero.
849
 
 *
850
 
 * @param ssock         The secure socket.
851
 
 * @param pool          Pool used to allocate buffers for incoming data.
852
 
 * @param buff_size     The size of each buffer, in bytes.
853
 
 * @param flags         Flags to be given to pj_ioqueue_recv().
854
 
 *
855
 
 * @return              PJ_SUCCESS if the operation has been successful,
856
 
 *                      or the appropriate error code on failure.
857
 
 */
858
 
PJ_DECL(pj_status_t) pj_ssl_sock_start_read(pj_ssl_sock_t *ssock,
859
 
                                            pj_pool_t *pool,
860
 
                                            unsigned buff_size,
861
 
                                            pj_uint32_t flags);
862
 
 
863
 
/**
864
 
 * Same as #pj_ssl_sock_start_read(), except that the application
865
 
 * supplies the buffers for the read operation so that the acive socket
866
 
 * does not have to allocate the buffers.
867
 
 *
868
 
 * @param ssock         The secure socket.
869
 
 * @param pool          Pool used to allocate buffers for incoming data.
870
 
 * @param buff_size     The size of each buffer, in bytes.
871
 
 * @param readbuf       Array of packet buffers, each has buff_size size.
872
 
 * @param flags         Flags to be given to pj_ioqueue_recv().
873
 
 *
874
 
 * @return              PJ_SUCCESS if the operation has been successful,
875
 
 *                      or the appropriate error code on failure.
876
 
 */
877
 
PJ_DECL(pj_status_t) pj_ssl_sock_start_read2(pj_ssl_sock_t *ssock,
878
 
                                             pj_pool_t *pool,
879
 
                                             unsigned buff_size,
880
 
                                             void *readbuf[],
881
 
                                             pj_uint32_t flags);
882
 
 
883
 
/**
884
 
 * Same as pj_ssl_sock_start_read(), except that this function is used
885
 
 * only for datagram sockets, and it will trigger \a on_data_recvfrom()
886
 
 * callback instead.
887
 
 *
888
 
 * @param ssock         The secure socket.
889
 
 * @param pool          Pool used to allocate buffers for incoming data.
890
 
 * @param buff_size     The size of each buffer, in bytes.
891
 
 * @param flags         Flags to be given to pj_ioqueue_recvfrom().
892
 
 *
893
 
 * @return              PJ_SUCCESS if the operation has been successful,
894
 
 *                      or the appropriate error code on failure.
895
 
 */
896
 
PJ_DECL(pj_status_t) pj_ssl_sock_start_recvfrom(pj_ssl_sock_t *ssock,
897
 
                                                pj_pool_t *pool,
898
 
                                                unsigned buff_size,
899
 
                                                pj_uint32_t flags);
900
 
 
901
 
/**
902
 
 * Same as #pj_ssl_sock_start_recvfrom() except that the recvfrom()
903
 
 * operation takes the buffer from the argument rather than creating
904
 
 * new ones.
905
 
 *
906
 
 * @param ssock         The secure socket.
907
 
 * @param pool          Pool used to allocate buffers for incoming data.
908
 
 * @param buff_size     The size of each buffer, in bytes.
909
 
 * @param readbuf       Array of packet buffers, each has buff_size size.
910
 
 * @param flags         Flags to be given to pj_ioqueue_recvfrom().
911
 
 *
912
 
 * @return              PJ_SUCCESS if the operation has been successful,
913
 
 *                      or the appropriate error code on failure.
914
 
 */
915
 
PJ_DECL(pj_status_t) pj_ssl_sock_start_recvfrom2(pj_ssl_sock_t *ssock,
916
 
                                                 pj_pool_t *pool,
917
 
                                                 unsigned buff_size,
918
 
                                                 void *readbuf[],
919
 
                                                 pj_uint32_t flags);
920
 
 
921
 
/**
922
 
 * Send data using the socket.
923
 
 *
924
 
 * @param ssock         The secure socket.
925
 
 * @param send_key      The operation key to send the data, which is useful
926
 
 *                      if application wants to submit multiple pending
927
 
 *                      send operations and want to track which exact data
928
 
 *                      has been sent in the \a on_data_sent() callback.
929
 
 * @param data          The data to be sent. This data must remain valid
930
 
 *                      until the data has been sent.
931
 
 * @param size          The size of the data.
932
 
 * @param flags         Flags to be given to pj_ioqueue_send().
933
 
 *
934
 
 * @return              PJ_SUCCESS if data has been sent immediately, or
935
 
 *                      PJ_EPENDING if data cannot be sent immediately or
936
 
 *                      PJ_ENOMEM when sending buffer could not handle all
937
 
 *                      queued data, see \a send_buffer_size. The callback
938
 
 *                      \a on_data_sent() will be called when data is actually
939
 
 *                      sent. Any other return value indicates error condition.
940
 
 */
941
 
PJ_DECL(pj_status_t) pj_ssl_sock_send(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
 
 
947
 
/**
948
 
 * Send datagram using the socket.
949
 
 *
950
 
 * @param ssock         The secure socket.
951
 
 * @param send_key      The operation key to send the data, which is useful
952
 
 *                      if application wants to submit multiple pending
953
 
 *                      send operations and want to track which exact data
954
 
 *                      has been sent in the \a on_data_sent() callback.
955
 
 * @param data          The data to be sent. This data must remain valid
956
 
 *                      until the data has been sent.
957
 
 * @param size          The size of the data.
958
 
 * @param flags         Flags to be given to pj_ioqueue_send().
959
 
 * @param addr          The destination address.
960
 
 * @param addr_len      Length of buffer containing destination address.
961
 
 *
962
 
 * @return              PJ_SUCCESS if data has been sent immediately, or
963
 
 *                      PJ_EPENDING if data cannot be sent immediately. In
964
 
 *                      this case the \a on_data_sent() callback will be
965
 
 *                      called when data is actually sent. Any other return
966
 
 *                      value indicates error condition.
967
 
 */
968
 
PJ_DECL(pj_status_t) pj_ssl_sock_sendto(pj_ssl_sock_t *ssock,
969
 
                                        pj_ioqueue_op_key_t *send_key,
970
 
                                        const void *data,
971
 
                                        pj_ssize_t *size,
972
 
                                        unsigned flags,
973
 
                                        const pj_sockaddr_t *addr,
974
 
                                        int addr_len);
975
 
 
976
 
 
977
 
/**
978
 
 * Starts asynchronous socket accept() operations on this secure socket.
979
 
 * This function will issue \a async_cnt number of asynchronous \a accept()
980
 
 * operations to the socket and returns back to caller. Incoming
981
 
 * connection on the socket will be reported back to application via the
982
 
 * \a on_accept_complete() callback.
983
 
 *
984
 
 * Application only needs to call this function once to initiate accept()
985
 
 * operations. Further accept() operations will be done automatically by
986
 
 * the secure socket when \a on_accept_complete() callback returns non-zero.
987
 
 *
988
 
 * @param ssock         The secure socket.
989
 
 * @param pool          Pool used to allocate some internal data for the
990
 
 *                      operation.
991
 
 * @param localaddr     Local address to bind on.
992
 
 * @param addr_len      Length of buffer containing local address.
993
 
 *
994
 
 * @return              PJ_SUCCESS if the operation has been successful,
995
 
 *                      or the appropriate error code on failure.
996
 
 */
997
 
PJ_DECL(pj_status_t) pj_ssl_sock_start_accept(pj_ssl_sock_t *ssock,
998
 
                                              pj_pool_t *pool,
999
 
                                              const pj_sockaddr_t *local_addr,
1000
 
                                              int addr_len);
1001
 
 
1002
 
 
1003
 
/**
1004
 
 * Starts asynchronous socket connect() operation and SSL/TLS handshaking
1005
 
 * for this socket. Once the connection is done (either successfully or not),
1006
 
 * the \a on_connect_complete() callback will be called.
1007
 
 *
1008
 
 * @param ssock         The secure socket.
1009
 
 * @param pool          The pool to allocate some internal data for the
1010
 
 *                      operation.
1011
 
 * @param localaddr     Local address.
1012
 
 * @param remaddr       Remote address.
1013
 
 * @param addr_len      Length of buffer containing above addresses.
1014
 
 *
1015
 
 * @return              PJ_SUCCESS if connection can be established immediately
1016
 
 *                      or PJ_EPENDING if connection cannot be established
1017
 
 *                      immediately. In this case the \a on_connect_complete()
1018
 
 *                      callback will be called when connection is complete.
1019
 
 *                      Any other return value indicates error condition.
1020
 
 */
1021
 
PJ_DECL(pj_status_t) pj_ssl_sock_start_connect(pj_ssl_sock_t *ssock,
1022
 
                                               pj_pool_t *pool,
1023
 
                                               const pj_sockaddr_t *localaddr,
1024
 
                                               const pj_sockaddr_t *remaddr,
1025
 
                                               int addr_len);
1026
 
 
1027
 
 
1028
 
/**
1029
 
 * Starts SSL/TLS renegotiation over an already established SSL connection
1030
 
 * for this socket. This operation is performed transparently, no callback
1031
 
 * will be called once the renegotiation completed successfully. However,
1032
 
 * when the renegotiation fails, the connection will be closed and callback
1033
 
 * \a on_data_read() will be invoked with non-PJ_SUCCESS status code.
1034
 
 *
1035
 
 * @param ssock         The secure socket.
1036
 
 *
1037
 
 * @return              PJ_SUCCESS if renegotiation is completed immediately,
1038
 
 *                      or PJ_EPENDING if renegotiation has been started and
1039
 
 *                      waiting for completion, or the appropriate error code
1040
 
 *                      on failure.
1041
 
 */
1042
 
PJ_DECL(pj_status_t) pj_ssl_sock_renegotiate(pj_ssl_sock_t *ssock);
1043
 
 
1044
 
 
1045
 
/**
1046
 
 * @}
1047
 
 */
1048
 
 
1049
 
PJ_END_DECL
1050
 
 
1051
 
#endif  /* __PJ_SSL_SOCK_H__ */