add changelog and NEWS entry
[gnuk/gnuk.git] / polarssl-0.14.0 / include / polarssl / ssl.h
1 /**
2  * \file ssl.h
3  *
4  *  Copyright (C) 2006-2010, Brainspark B.V.
5  *
6  *  This file is part of PolarSSL (http://www.polarssl.org)
7  *  Lead Maintainer: Paul Bakker <polarssl_maintainer at polarssl.org>
8  *
9  *  All rights reserved.
10  *
11  *  This program is free software; you can redistribute it and/or modify
12  *  it under the terms of the GNU General Public License as published by
13  *  the Free Software Foundation; either version 2 of the License, or
14  *  (at your option) any later version.
15  *
16  *  This program is distributed in the hope that it will be useful,
17  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
18  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
19  *  GNU General Public License for more details.
20  *
21  *  You should have received a copy of the GNU General Public License along
22  *  with this program; if not, write to the Free Software Foundation, Inc.,
23  *  51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
24  */
25 #ifndef POLARSSL_SSL_H
26 #define POLARSSL_SSL_H
27
28 #include <time.h>
29
30 #include "polarssl/net.h"
31 #include "polarssl/dhm.h"
32 #include "polarssl/rsa.h"
33 #include "polarssl/md5.h"
34 #include "polarssl/sha1.h"
35 #include "polarssl/x509.h"
36
37 /*
38  * SSL Error codes
39  */
40 #define POLARSSL_ERR_SSL_FEATURE_UNAVAILABLE               -0x1000
41 #define POLARSSL_ERR_SSL_BAD_INPUT_DATA                    -0x1800
42 #define POLARSSL_ERR_SSL_INVALID_MAC                       -0x2000
43 #define POLARSSL_ERR_SSL_INVALID_RECORD                    -0x2800
44 #define POLARSSL_ERR_SSL_INVALID_MODULUS_SIZE              -0x3000
45 #define POLARSSL_ERR_SSL_UNKNOWN_CIPHER                    -0x3800
46 #define POLARSSL_ERR_SSL_NO_CIPHER_CHOSEN                  -0x4000
47 #define POLARSSL_ERR_SSL_NO_SESSION_FOUND                  -0x4800
48 #define POLARSSL_ERR_SSL_NO_CLIENT_CERTIFICATE             -0x5000
49 #define POLARSSL_ERR_SSL_CERTIFICATE_TOO_LARGE             -0x5800
50 #define POLARSSL_ERR_SSL_CERTIFICATE_REQUIRED              -0x6000
51 #define POLARSSL_ERR_SSL_PRIVATE_KEY_REQUIRED              -0x6800
52 #define POLARSSL_ERR_SSL_CA_CHAIN_REQUIRED                 -0x7000
53 #define POLARSSL_ERR_SSL_UNEXPECTED_MESSAGE                -0x7800
54 #define POLARSSL_ERR_SSL_FATAL_ALERT_MESSAGE               -0x8000
55 #define POLARSSL_ERR_SSL_PEER_VERIFY_FAILED                -0x8800
56 #define POLARSSL_ERR_SSL_PEER_CLOSE_NOTIFY                 -0x9000
57 #define POLARSSL_ERR_SSL_BAD_HS_CLIENT_HELLO               -0x9800
58 #define POLARSSL_ERR_SSL_BAD_HS_SERVER_HELLO               -0xA000
59 #define POLARSSL_ERR_SSL_BAD_HS_CERTIFICATE                -0xA800
60 #define POLARSSL_ERR_SSL_BAD_HS_CERTIFICATE_REQUEST        -0xB000
61 #define POLARSSL_ERR_SSL_BAD_HS_SERVER_KEY_EXCHANGE        -0xB800
62 #define POLARSSL_ERR_SSL_BAD_HS_SERVER_HELLO_DONE          -0xC000
63 #define POLARSSL_ERR_SSL_BAD_HS_CLIENT_KEY_EXCHANGE        -0xC800
64 #define POLARSSL_ERR_SSL_BAD_HS_CERTIFICATE_VERIFY         -0xD000
65 #define POLARSSL_ERR_SSL_BAD_HS_CHANGE_CIPHER_SPEC         -0xD800
66 #define POLARSSL_ERR_SSL_BAD_HS_FINISHED                   -0xE000
67
68 /*
69  * Various constants
70  */
71 #define SSL_MAJOR_VERSION_3             3
72 #define SSL_MINOR_VERSION_0             0   /*!< SSL v3.0 */
73 #define SSL_MINOR_VERSION_1             1   /*!< TLS v1.0 */
74 #define SSL_MINOR_VERSION_2             2   /*!< TLS v1.1 */
75
76 #define SSL_IS_CLIENT                   0
77 #define SSL_IS_SERVER                   1
78 #define SSL_COMPRESS_NULL               0
79
80 #define SSL_VERIFY_NONE                 0
81 #define SSL_VERIFY_OPTIONAL             1
82 #define SSL_VERIFY_REQUIRED             2
83
84 #define SSL_MAX_CONTENT_LEN         16384
85
86 /*
87  * Allow an extra 512 bytes for the record header
88  * and encryption overhead (counter + MAC + padding).
89  */
90 #define SSL_BUFFER_LEN (SSL_MAX_CONTENT_LEN + 512)
91
92 /*
93  * Supported ciphersuites
94  */
95 #define SSL_RSA_RC4_128_MD5          0x04
96 #define SSL_RSA_RC4_128_SHA          0x05
97 #define SSL_RSA_DES_168_SHA          0x0A
98 #define SSL_EDH_RSA_DES_168_SHA      0x16
99 #define SSL_RSA_AES_128_SHA          0x2F
100 #define SSL_EDH_RSA_AES_128_SHA      0x33
101 #define SSL_RSA_AES_256_SHA          0x35
102 #define SSL_EDH_RSA_AES_256_SHA      0x39
103
104 #define SSL_RSA_CAMELLIA_128_SHA     0x41
105 #define SSL_EDH_RSA_CAMELLIA_128_SHA 0x45
106 #define SSL_RSA_CAMELLIA_256_SHA     0x84
107 #define SSL_EDH_RSA_CAMELLIA_256_SHA 0x88
108
109 /*
110  * Message, alert and handshake types
111  */
112 #define SSL_MSG_CHANGE_CIPHER_SPEC     20
113 #define SSL_MSG_ALERT                  21
114 #define SSL_MSG_HANDSHAKE              22
115 #define SSL_MSG_APPLICATION_DATA       23
116
117 #define SSL_ALERT_LEVEL_WARNING         1
118 #define SSL_ALERT_LEVEL_FATAL           2
119
120 #define SSL_ALERT_MSG_CLOSE_NOTIFY           0
121 #define SSL_ALERT_MSG_UNEXPECTED_MESSAGE    10
122 #define SSL_ALERT_MSG_BAD_RECORD_MAD        20
123 #define SSL_ALERT_MSG_DECRYPTION_FAILED     21
124 #define SSL_ALERT_MSG_RECORD_OVERFLOW       22
125 #define SSL_ALERT_MSG_DECOMPRESSION_FAILURE 30
126 #define SSL_ALERT_MSG_HANDSHAKE_FAILURE     40
127 #define SSL_ALERT_MSG_NO_CERT               41
128 #define SSL_ALERT_MSG_BAD_CERT              42
129 #define SSL_ALERT_MSG_UNSUPPORTED_CERT      43
130 #define SSL_ALERT_MSG_CERT_REVOKED          44
131 #define SSL_ALERT_MSG_CERT_EXPIRED          45
132 #define SSL_ALERT_MSG_CERT_UNKNOWN          46
133 #define SSL_ALERT_MSG_ILLEGAL_PARAMETER     47
134 #define SSL_ALERT_MSG_UNKNOWN_CA            48
135 #define SSL_ALERT_MSG_ACCESS_DENIED         49
136 #define SSL_ALERT_MSG_DECODE_ERROR          50
137 #define SSL_ALERT_MSG_DECRYPT_ERROR         51
138 #define SSL_ALERT_MSG_EXPORT_RESTRICTION    60
139 #define SSL_ALERT_MSG_PROTOCOL_VERSION      70
140 #define SSL_ALERT_MSG_INSUFFICIENT_SECURITY 71
141 #define SSL_ALERT_MSG_INTERNAL_ERROR        80
142 #define SSL_ALERT_MSG_USER_CANCELED         90
143 #define SSL_ALERT_MSG_NO_RENEGOTIATION     100
144
145 #define SSL_HS_HELLO_REQUEST            0
146 #define SSL_HS_CLIENT_HELLO             1
147 #define SSL_HS_SERVER_HELLO             2
148 #define SSL_HS_CERTIFICATE             11
149 #define SSL_HS_SERVER_KEY_EXCHANGE     12
150 #define SSL_HS_CERTIFICATE_REQUEST     13
151 #define SSL_HS_SERVER_HELLO_DONE       14
152 #define SSL_HS_CERTIFICATE_VERIFY      15
153 #define SSL_HS_CLIENT_KEY_EXCHANGE     16
154 #define SSL_HS_FINISHED                20
155
156 /*
157  * TLS extensions
158  */
159 #define TLS_EXT_SERVERNAME              0
160 #define TLS_EXT_SERVERNAME_HOSTNAME     0
161
162 /*
163  * SSL state machine
164  */
165 typedef enum
166 {
167     SSL_HELLO_REQUEST,
168     SSL_CLIENT_HELLO,
169     SSL_SERVER_HELLO,
170     SSL_SERVER_CERTIFICATE,
171     SSL_SERVER_KEY_EXCHANGE,
172     SSL_CERTIFICATE_REQUEST,
173     SSL_SERVER_HELLO_DONE,
174     SSL_CLIENT_CERTIFICATE,
175     SSL_CLIENT_KEY_EXCHANGE,
176     SSL_CERTIFICATE_VERIFY,
177     SSL_CLIENT_CHANGE_CIPHER_SPEC,
178     SSL_CLIENT_FINISHED,
179     SSL_SERVER_CHANGE_CIPHER_SPEC,
180     SSL_SERVER_FINISHED,
181     SSL_FLUSH_BUFFERS,
182     SSL_HANDSHAKE_OVER
183 }
184 ssl_states;
185
186 typedef struct _ssl_session ssl_session;
187 typedef struct _ssl_context ssl_context;
188
189 /*
190  * This structure is used for session resuming.
191  */
192 struct _ssl_session
193 {
194     time_t start;               /*!< starting time      */
195     int cipher;                 /*!< chosen cipher      */
196     int length;                 /*!< session id length  */
197     unsigned char id[32];       /*!< session identifier */
198     unsigned char master[48];   /*!< the master secret  */
199     ssl_session *next;          /*!< next session entry */
200 };
201
202 struct _ssl_context
203 {
204     /*
205      * Miscellaneous
206      */
207     int state;                  /*!< SSL handshake: current state     */
208
209     int major_ver;              /*!< equal to  SSL_MAJOR_VERSION_3    */
210     int minor_ver;              /*!< either 0 (SSL3) or 1 (TLS1.0)    */
211
212     int max_major_ver;          /*!< max. major version from client   */
213     int max_minor_ver;          /*!< max. minor version from client   */
214
215     /*
216      * Callbacks (RNG, debug, I/O)
217      */
218     int  (*f_rng)(void *);
219     void (*f_dbg)(void *, int, const char *);
220     int (*f_recv)(void *, unsigned char *, int);
221     int (*f_send)(void *, unsigned char *, int);
222
223     void *p_rng;                /*!< context for the RNG function     */
224     void *p_dbg;                /*!< context for the debug function   */
225     void *p_recv;               /*!< context for reading operations   */
226     void *p_send;               /*!< context for writing operations   */
227
228     /*
229      * Session layer
230      */
231     int resume;                         /*!<  session resuming flag   */
232     int timeout;                        /*!<  sess. expiration time   */
233     ssl_session *session;               /*!<  current session data    */
234     int (*s_get)(ssl_context *);        /*!<  (server) get callback   */
235     int (*s_set)(ssl_context *);        /*!<  (server) set callback   */
236
237     /*
238      * Record layer (incoming data)
239      */
240     unsigned char *in_ctr;      /*!< 64-bit incoming message counter  */
241     unsigned char *in_hdr;      /*!< 5-byte record header (in_ctr+8)  */
242     unsigned char *in_msg;      /*!< the message contents (in_hdr+5)  */
243     unsigned char *in_offt;     /*!< read offset in application data  */
244
245     int in_msgtype;             /*!< record header: message type      */
246     int in_msglen;              /*!< record header: message length    */
247     int in_left;                /*!< amount of data read so far       */
248
249     int in_hslen;               /*!< current handshake message length */
250     int nb_zero;                /*!< # of 0-length encrypted messages */
251
252     /*
253      * Record layer (outgoing data)
254      */
255     unsigned char *out_ctr;     /*!< 64-bit outgoing message counter  */
256     unsigned char *out_hdr;     /*!< 5-byte record header (out_ctr+8) */
257     unsigned char *out_msg;     /*!< the message contents (out_hdr+5) */
258
259     int out_msgtype;            /*!< record header: message type      */
260     int out_msglen;             /*!< record header: message length    */
261     int out_left;               /*!< amount of data not yet written   */
262
263     /*
264      * PKI layer
265      */
266     rsa_context *rsa_key;               /*!<  own RSA private key     */
267     x509_cert *own_cert;                /*!<  own X.509 certificate   */
268     x509_cert *ca_chain;                /*!<  own trusted CA chain    */
269     x509_crl *ca_crl;                   /*!<  trusted CA CRLs         */
270     x509_cert *peer_cert;               /*!<  peer X.509 cert chain   */
271     const char *peer_cn;                /*!<  expected peer CN        */
272
273     int endpoint;                       /*!<  0: client, 1: server    */
274     int authmode;                       /*!<  verification mode       */
275     int client_auth;                    /*!<  flag for client auth.   */
276     int verify_result;                  /*!<  verification result     */
277
278     /*
279      * Crypto layer
280      */
281     dhm_context dhm_ctx;                /*!<  DHM key exchange        */
282     md5_context fin_md5;                /*!<  Finished MD5 checksum   */
283     sha1_context fin_sha1;              /*!<  Finished SHA-1 checksum */
284
285     int do_crypt;                       /*!<  en(de)cryption flag     */
286     int *ciphers;                       /*!<  allowed ciphersuites    */
287     int pmslen;                         /*!<  premaster length        */
288     int keylen;                         /*!<  symmetric key length    */
289     int minlen;                         /*!<  min. ciphertext length  */
290     int ivlen;                          /*!<  IV length               */
291     int maclen;                         /*!<  MAC length              */
292
293     unsigned char randbytes[64];        /*!<  random bytes            */
294     unsigned char premaster[256];       /*!<  premaster secret        */
295
296     unsigned char iv_enc[16];           /*!<  IV (encryption)         */
297     unsigned char iv_dec[16];           /*!<  IV (decryption)         */
298
299     unsigned char mac_enc[32];          /*!<  MAC (encryption)        */
300     unsigned char mac_dec[32];          /*!<  MAC (decryption)        */
301
302     unsigned long ctx_enc[128];         /*!<  encryption context      */
303     unsigned long ctx_dec[128];         /*!<  decryption context      */
304
305     /*
306      * TLS extensions
307      */
308     unsigned char *hostname;
309     unsigned long  hostname_len;
310 };
311
312 #ifdef __cplusplus
313 extern "C" {
314 #endif
315
316 extern int ssl_default_ciphers[];
317
318 /**
319  * \brief          Initialize an SSL context
320  *
321  * \param ssl      SSL context
322  *
323  * \return         0 if successful, or 1 if memory allocation failed
324  */
325 int ssl_init( ssl_context *ssl );
326
327 /**
328  * \brief          Set the current endpoint type
329  *
330  * \param ssl      SSL context
331  * \param endpoint must be SSL_IS_CLIENT or SSL_IS_SERVER
332  */
333 void ssl_set_endpoint( ssl_context *ssl, int endpoint );
334
335 /**
336  * \brief          Set the certificate verification mode
337  *
338  * \param ssl      SSL context
339  * \param mode     can be:
340  *
341  *  SSL_VERIFY_NONE:      peer certificate is not checked (default),
342  *                        this is insecure and SHOULD be avoided.
343  *
344  *  SSL_VERIFY_OPTIONAL:  peer certificate is checked, however the
345  *                        handshake continues even if verification failed;
346  *                        ssl_get_verify_result() can be called after the
347  *                        handshake is complete.
348  *
349  *  SSL_VERIFY_REQUIRED:  peer *must* present a valid certificate,
350  *                        handshake is aborted if verification failed.
351  */
352 void ssl_set_authmode( ssl_context *ssl, int authmode );
353
354 /**
355  * \brief          Set the random number generator callback
356  *
357  * \param ssl      SSL context
358  * \param f_rng    RNG function
359  * \param p_rng    RNG parameter
360  */
361 void ssl_set_rng( ssl_context *ssl,
362                   int (*f_rng)(void *),
363                   void *p_rng );
364
365 /**
366  * \brief          Set the debug callback
367  *
368  * \param ssl      SSL context
369  * \param f_dbg    debug function
370  * \param p_dbg    debug parameter
371  */
372 void ssl_set_dbg( ssl_context *ssl,
373                   void (*f_dbg)(void *, int, const char *),
374                   void  *p_dbg );
375
376 /**
377  * \brief          Set the underlying BIO read and write callbacks
378  *
379  * \param ssl      SSL context
380  * \param f_recv   read callback
381  * \param p_recv   read parameter
382  * \param f_send   write callback
383  * \param p_send   write parameter
384  */
385 void ssl_set_bio( ssl_context *ssl,
386         int (*f_recv)(void *, unsigned char *, int), void *p_recv,
387         int (*f_send)(void *, unsigned char *, int), void *p_send );
388
389 /**
390  * \brief          Set the session callbacks (server-side only)
391  *
392  * \param ssl      SSL context
393  * \param s_get    session get callback
394  * \param s_set    session set callback
395  */
396 void ssl_set_scb( ssl_context *ssl,
397                   int (*s_get)(ssl_context *),
398                   int (*s_set)(ssl_context *) );
399
400 /**
401  * \brief          Set the session resuming flag, timeout and data
402  *
403  * \param ssl      SSL context
404  * \param resume   if 0 (default), the session will not be resumed
405  * \param timeout  session timeout in seconds, or 0 (no timeout)
406  * \param session  session context
407  */
408 void ssl_set_session( ssl_context *ssl, int resume, int timeout,
409                       ssl_session *session );
410
411 /**
412  * \brief          Set the list of allowed ciphersuites
413  *
414  * \param ssl      SSL context
415  * \param ciphers  0-terminated list of allowed ciphers
416  */
417 void ssl_set_ciphers( ssl_context *ssl, int *ciphers );
418
419 /**
420  * \brief          Set the data required to verify peer certificate
421  *
422  * \param ssl      SSL context
423  * \param ca_chain trusted CA chain
424  * \param ca_crl   trusted CA CRLs
425  * \param peer_cn  expected peer CommonName (or NULL)
426  *
427  * \note           TODO: add two more parameters: depth and crl
428  */
429 void ssl_set_ca_chain( ssl_context *ssl, x509_cert *ca_chain,
430                        x509_crl *ca_crl, const char *peer_cn );
431
432 /**
433  * \brief          Set own certificate and private key
434  *
435  * \param ssl      SSL context
436  * \param own_cert own public certificate
437  * \param rsa_key  own private RSA key
438  */
439 void ssl_set_own_cert( ssl_context *ssl, x509_cert *own_cert,
440                        rsa_context *rsa_key );
441
442 /**
443  * \brief          Set the Diffie-Hellman public P and G values,
444  *                 read as hexadecimal strings (server-side only)
445  *
446  * \param ssl      SSL context
447  * \param dhm_P    Diffie-Hellman-Merkle modulus
448  * \param dhm_G    Diffie-Hellman-Merkle generator
449  *
450  * \return         0 if successful
451  */
452 int ssl_set_dh_param( ssl_context *ssl, const char *dhm_P, const char *dhm_G );
453
454 /**
455  * \brief          Set hostname for ServerName TLS Extension
456  *                 
457  *
458  * \param ssl      SSL context
459  * \param hostname the server hostname
460  *
461  * \return         0 if successful
462  */
463 int ssl_set_hostname( ssl_context *ssl, const char *hostname );
464
465 /**
466  * \brief          Return the number of data bytes available to read
467  *
468  * \param ssl      SSL context
469  *
470  * \return         how many bytes are available in the read buffer
471  */
472 int ssl_get_bytes_avail( const ssl_context *ssl );
473
474 /**
475  * \brief          Return the result of the certificate verification
476  *
477  * \param ssl      SSL context
478  *
479  * \return         0 if successful, or a combination of:
480  *                      BADCERT_EXPIRED
481  *                      BADCERT_REVOKED
482  *                      BADCERT_CN_MISMATCH
483  *                      BADCERT_NOT_TRUSTED
484  */
485 int ssl_get_verify_result( const ssl_context *ssl );
486
487 /**
488  * \brief          Return the name of the current cipher
489  *
490  * \param ssl      SSL context
491  *
492  * \return         a string containing the cipher name
493  */
494 const char *ssl_get_cipher( const ssl_context *ssl );
495
496 /**
497  * \brief          Perform the SSL handshake
498  *
499  * \param ssl      SSL context
500  *
501  * \return         0 if successful, POLARSSL_ERR_NET_TRY_AGAIN,
502  *                 or a specific SSL error code.
503  */
504 int ssl_handshake( ssl_context *ssl );
505
506 /**
507  * \brief          Read at most 'len' application data bytes
508  *
509  * \param ssl      SSL context
510  * \param buf      buffer that will hold the data
511  * \param len      how many bytes must be read
512  *
513  * \return         This function returns the number of bytes read,
514  *                 or a negative error code.
515  */
516 int ssl_read( ssl_context *ssl, unsigned char *buf, int len );
517
518 /**
519  * \brief          Write exactly 'len' application data bytes
520  *
521  * \param ssl      SSL context
522  * \param buf      buffer holding the data
523  * \param len      how many bytes must be written
524  *
525  * \return         This function returns the number of bytes written,
526  *                 or a negative error code.
527  *
528  * \note           When this function returns POLARSSL_ERR_NET_TRY_AGAIN,
529  *                 it must be called later with the *same* arguments,
530  *                 until it returns a positive value.
531  */
532 int ssl_write( ssl_context *ssl, const unsigned char *buf, int len );
533
534 /**
535  * \brief          Notify the peer that the connection is being closed
536  *
537  * \param ssl      SSL context
538  */
539 int ssl_close_notify( ssl_context *ssl );
540
541 /**
542  * \brief          Free an SSL context
543  *
544  * \param ssl      SSL context
545  */
546 void ssl_free( ssl_context *ssl );
547
548 /*
549  * Internal functions (do not call directly)
550  */
551 int ssl_handshake_client( ssl_context *ssl );
552 int ssl_handshake_server( ssl_context *ssl );
553
554 int ssl_derive_keys( ssl_context *ssl );
555 void ssl_calc_verify( ssl_context *ssl, unsigned char hash[36] );
556
557 int ssl_read_record( ssl_context *ssl );
558 int ssl_fetch_input( ssl_context *ssl, int nb_want );
559
560 int ssl_write_record( ssl_context *ssl );
561 int ssl_flush_output( ssl_context *ssl );
562
563 int ssl_parse_certificate( ssl_context *ssl );
564 int ssl_write_certificate( ssl_context *ssl );
565
566 int ssl_parse_change_cipher_spec( ssl_context *ssl );
567 int ssl_write_change_cipher_spec( ssl_context *ssl );
568
569 int ssl_parse_finished( ssl_context *ssl );
570 int ssl_write_finished( ssl_context *ssl );
571
572 #ifdef __cplusplus
573 }
574 #endif
575
576 #endif /* ssl.h */