← Back to branch summary

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

« back to all changes in this revision

Viewing changes to daemon/libs/pjproject-2.1.0/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.1.0/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__ */