PolarSSL v1.1.5
ssl.h
Go to the documentation of this file.
1 
27 #ifndef POLARSSL_SSL_H
28 #define POLARSSL_SSL_H
29 
30 #include <time.h>
31 
32 #include "net.h"
33 #include "dhm.h"
34 #include "rsa.h"
35 #include "md5.h"
36 #include "sha1.h"
37 #include "x509.h"
38 #include "config.h"
39 
40 #if defined(POLARSSL_PKCS11_C)
41 #include "pkcs11.h"
42 #endif
43 
44 #if defined(_MSC_VER) && !defined(inline)
45 #define inline _inline
46 #else
47 #if defined(__ARMCC_VERSION) && !defined(inline)
48 #define inline __inline
49 #endif /* __ARMCC_VERSION */
50 #endif /*_MSC_VER */
51 
52 /*
53  * SSL Error codes
54  */
55 #define POLARSSL_ERR_SSL_FEATURE_UNAVAILABLE -0x7080
56 #define POLARSSL_ERR_SSL_BAD_INPUT_DATA -0x7100
57 #define POLARSSL_ERR_SSL_INVALID_MAC -0x7180
58 #define POLARSSL_ERR_SSL_INVALID_RECORD -0x7200
59 #define POLARSSL_ERR_SSL_CONN_EOF -0x7280
60 #define POLARSSL_ERR_SSL_UNKNOWN_CIPHER -0x7300
61 #define POLARSSL_ERR_SSL_NO_CIPHER_CHOSEN -0x7380
62 #define POLARSSL_ERR_SSL_NO_SESSION_FOUND -0x7400
63 #define POLARSSL_ERR_SSL_NO_CLIENT_CERTIFICATE -0x7480
64 #define POLARSSL_ERR_SSL_CERTIFICATE_TOO_LARGE -0x7500
65 #define POLARSSL_ERR_SSL_CERTIFICATE_REQUIRED -0x7580
66 #define POLARSSL_ERR_SSL_PRIVATE_KEY_REQUIRED -0x7600
67 #define POLARSSL_ERR_SSL_CA_CHAIN_REQUIRED -0x7680
68 #define POLARSSL_ERR_SSL_UNEXPECTED_MESSAGE -0x7700
69 #define POLARSSL_ERR_SSL_FATAL_ALERT_MESSAGE -0x7780
70 #define POLARSSL_ERR_SSL_PEER_VERIFY_FAILED -0x7800
71 #define POLARSSL_ERR_SSL_PEER_CLOSE_NOTIFY -0x7880
72 #define POLARSSL_ERR_SSL_BAD_HS_CLIENT_HELLO -0x7900
73 #define POLARSSL_ERR_SSL_BAD_HS_SERVER_HELLO -0x7980
74 #define POLARSSL_ERR_SSL_BAD_HS_CERTIFICATE -0x7A00
75 #define POLARSSL_ERR_SSL_BAD_HS_CERTIFICATE_REQUEST -0x7A80
76 #define POLARSSL_ERR_SSL_BAD_HS_SERVER_KEY_EXCHANGE -0x7B00
77 #define POLARSSL_ERR_SSL_BAD_HS_SERVER_HELLO_DONE -0x7B80
78 #define POLARSSL_ERR_SSL_BAD_HS_CLIENT_KEY_EXCHANGE -0x7C00
79 #define POLARSSL_ERR_SSL_BAD_HS_CLIENT_KEY_EXCHANGE_DHM_RP -0x7C80
80 #define POLARSSL_ERR_SSL_BAD_HS_CLIENT_KEY_EXCHANGE_DHM_CS -0x7D00
81 #define POLARSSL_ERR_SSL_BAD_HS_CERTIFICATE_VERIFY -0x7D80
82 #define POLARSSL_ERR_SSL_BAD_HS_CHANGE_CIPHER_SPEC -0x7E00
83 #define POLARSSL_ERR_SSL_BAD_HS_FINISHED -0x7E80
84 #define POLARSSL_ERR_SSL_MALLOC_FAILED -0x7F00
86 /*
87  * Various constants
88  */
89 #define SSL_MAJOR_VERSION_3 3
90 #define SSL_MINOR_VERSION_0 0
91 #define SSL_MINOR_VERSION_1 1
92 #define SSL_MINOR_VERSION_2 2
94 #define SSL_IS_CLIENT 0
95 #define SSL_IS_SERVER 1
96 #define SSL_COMPRESS_NULL 0
97 
98 #define SSL_VERIFY_NONE 0
99 #define SSL_VERIFY_OPTIONAL 1
100 #define SSL_VERIFY_REQUIRED 2
101 
102 #define SSL_MAX_CONTENT_LEN 16384
103 
104 /*
105  * Allow an extra 512 bytes for the record header
106  * and encryption overhead (counter + MAC + padding).
107  */
108 #define SSL_BUFFER_LEN (SSL_MAX_CONTENT_LEN + 512)
109 
110 /*
111  * Supported ciphersuites
112  */
113 #define SSL_RSA_RC4_128_MD5 0x04
114 #define SSL_RSA_RC4_128_SHA 0x05
115 #define SSL_RSA_DES_168_SHA 0x0A
116 #define SSL_EDH_RSA_DES_168_SHA 0x16
117 #define SSL_RSA_AES_128_SHA 0x2F
118 #define SSL_EDH_RSA_AES_128_SHA 0x33
119 #define SSL_RSA_AES_256_SHA 0x35
120 #define SSL_EDH_RSA_AES_256_SHA 0x39
121 
122 #define SSL_RSA_CAMELLIA_128_SHA 0x41
123 #define SSL_EDH_RSA_CAMELLIA_128_SHA 0x45
124 #define SSL_RSA_CAMELLIA_256_SHA 0x84
125 #define SSL_EDH_RSA_CAMELLIA_256_SHA 0x88
126 
127 /*
128  * Message, alert and handshake types
129  */
130 #define SSL_MSG_CHANGE_CIPHER_SPEC 20
131 #define SSL_MSG_ALERT 21
132 #define SSL_MSG_HANDSHAKE 22
133 #define SSL_MSG_APPLICATION_DATA 23
134 
135 #define SSL_ALERT_LEVEL_WARNING 1
136 #define SSL_ALERT_LEVEL_FATAL 2
137 
138 #define SSL_ALERT_MSG_CLOSE_NOTIFY 0
139 #define SSL_ALERT_MSG_UNEXPECTED_MESSAGE 10
140 #define SSL_ALERT_MSG_BAD_RECORD_MAC 20
141 #define SSL_ALERT_MSG_DECRYPTION_FAILED 21
142 #define SSL_ALERT_MSG_RECORD_OVERFLOW 22
143 #define SSL_ALERT_MSG_DECOMPRESSION_FAILURE 30
144 #define SSL_ALERT_MSG_HANDSHAKE_FAILURE 40
145 #define SSL_ALERT_MSG_NO_CERT 41
146 #define SSL_ALERT_MSG_BAD_CERT 42
147 #define SSL_ALERT_MSG_UNSUPPORTED_CERT 43
148 #define SSL_ALERT_MSG_CERT_REVOKED 44
149 #define SSL_ALERT_MSG_CERT_EXPIRED 45
150 #define SSL_ALERT_MSG_CERT_UNKNOWN 46
151 #define SSL_ALERT_MSG_ILLEGAL_PARAMETER 47
152 #define SSL_ALERT_MSG_UNKNOWN_CA 48
153 #define SSL_ALERT_MSG_ACCESS_DENIED 49
154 #define SSL_ALERT_MSG_DECODE_ERROR 50
155 #define SSL_ALERT_MSG_DECRYPT_ERROR 51
156 #define SSL_ALERT_MSG_EXPORT_RESTRICTION 60
157 #define SSL_ALERT_MSG_PROTOCOL_VERSION 70
158 #define SSL_ALERT_MSG_INSUFFICIENT_SECURITY 71
159 #define SSL_ALERT_MSG_INTERNAL_ERROR 80
160 #define SSL_ALERT_MSG_USER_CANCELED 90
161 #define SSL_ALERT_MSG_NO_RENEGOTIATION 100
162 
163 #define SSL_HS_HELLO_REQUEST 0
164 #define SSL_HS_CLIENT_HELLO 1
165 #define SSL_HS_SERVER_HELLO 2
166 #define SSL_HS_CERTIFICATE 11
167 #define SSL_HS_SERVER_KEY_EXCHANGE 12
168 #define SSL_HS_CERTIFICATE_REQUEST 13
169 #define SSL_HS_SERVER_HELLO_DONE 14
170 #define SSL_HS_CERTIFICATE_VERIFY 15
171 #define SSL_HS_CLIENT_KEY_EXCHANGE 16
172 #define SSL_HS_FINISHED 20
173 
174 /*
175  * TLS extensions
176  */
177 #define TLS_EXT_SERVERNAME 0
178 #define TLS_EXT_SERVERNAME_HOSTNAME 0
179 
180 /*
181  * SSL state machine
182  */
183 typedef enum
184 {
201 }
202 ssl_states;
203 
204 typedef struct _ssl_session ssl_session;
205 typedef struct _ssl_context ssl_context;
206 
207 /*
208  * This structure is used for session resuming.
209  */
211 {
212  time_t start;
214  size_t length;
215  unsigned char id[32];
216  unsigned char master[48];
218 };
219 
221 {
222  /*
223  * Miscellaneous
224  */
225  int state;
227  int major_ver;
228  int minor_ver;
233  /*
234  * Callbacks (RNG, debug, I/O, verification)
235  */
236  int (*f_rng)(void *, unsigned char *, size_t);
237  void (*f_dbg)(void *, int, const char *);
238  int (*f_recv)(void *, unsigned char *, size_t);
239  int (*f_send)(void *, const unsigned char *, size_t);
240  int (*f_vrfy)(void *, x509_cert *, int, int);
241 
242  void *p_rng;
243  void *p_dbg;
244  void *p_recv;
245  void *p_send;
246  void *p_vrfy;
248  /*
249  * Session layer
250  */
251  int resume;
252  int timeout;
254  int (*s_get)(ssl_context *);
255  int (*s_set)(ssl_context *);
257  /*
258  * Record layer (incoming data)
259  */
260  unsigned char *in_ctr;
261  unsigned char *in_hdr;
262  unsigned char *in_msg;
263  unsigned char *in_offt;
266  size_t in_msglen;
267  size_t in_left;
269  size_t in_hslen;
270  int nb_zero;
272  /*
273  * Record layer (outgoing data)
274  */
275  unsigned char *out_ctr;
276  unsigned char *out_hdr;
277  unsigned char *out_msg;
280  size_t out_msglen;
281  size_t out_left;
283  /*
284  * PKI layer
285  */
287 #if defined(POLARSSL_PKCS11_C)
288  pkcs11_context *pkcs11_key;
289 #endif
294  const char *peer_cn;
296  int endpoint;
297  int authmode;
301  /*
302  * Crypto layer
303  */
308  int do_crypt;
310  size_t pmslen;
311  unsigned int keylen;
312  size_t minlen;
313  size_t ivlen;
314  size_t maclen;
316  unsigned char randbytes[64];
317  unsigned char premaster[256];
319  unsigned char iv_enc[16];
320  unsigned char iv_dec[16];
322  unsigned char mac_enc[32];
323  unsigned char mac_dec[32];
325  unsigned long ctx_enc[128];
326  unsigned long ctx_dec[128];
328  /*
329  * TLS extensions
330  */
331  unsigned char *hostname;
332  size_t hostname_len;
333 };
334 
335 #ifdef __cplusplus
336 extern "C" {
337 #endif
338 
339 extern int ssl_default_ciphersuites[];
340 
347 static inline const int *ssl_list_ciphersuites( void )
348 {
349  return ssl_default_ciphersuites;
350 }
351 
360 const char *ssl_get_ciphersuite_name( const int ciphersuite_id );
361 
370 int ssl_get_ciphersuite_id( const char *ciphersuite_name );
371 
380 int ssl_init( ssl_context *ssl );
381 
389 void ssl_session_reset( ssl_context *ssl );
390 
397 void ssl_set_endpoint( ssl_context *ssl, int endpoint );
398 
416 void ssl_set_authmode( ssl_context *ssl, int authmode );
417 
431 void ssl_set_verify( ssl_context *ssl,
432  int (*f_vrfy)(void *, x509_cert *, int, int),
433  void *p_vrfy );
434 
442 void ssl_set_rng( ssl_context *ssl,
443  int (*f_rng)(void *, unsigned char *, size_t),
444  void *p_rng );
445 
453 void ssl_set_dbg( ssl_context *ssl,
454  void (*f_dbg)(void *, int, const char *),
455  void *p_dbg );
456 
466 void ssl_set_bio( ssl_context *ssl,
467  int (*f_recv)(void *, unsigned char *, size_t), void *p_recv,
468  int (*f_send)(void *, const unsigned char *, size_t), void *p_send );
469 
477 void ssl_set_scb( ssl_context *ssl,
478  int (*s_get)(ssl_context *),
479  int (*s_set)(ssl_context *) );
480 
489 void ssl_set_session( ssl_context *ssl, int resume, int timeout,
490  ssl_session *session );
491 
498 void ssl_set_ciphersuites( ssl_context *ssl, int *ciphersuites );
499 
510 void ssl_set_ca_chain( ssl_context *ssl, x509_cert *ca_chain,
511  x509_crl *ca_crl, const char *peer_cn );
512 
520 void ssl_set_own_cert( ssl_context *ssl, x509_cert *own_cert,
521  rsa_context *rsa_key );
522 
523 #if defined(POLARSSL_PKCS11_C)
524 
531 void ssl_set_own_cert_pkcs11( ssl_context *ssl, x509_cert *own_cert,
532  pkcs11_context *pkcs11_key );
533 #endif
534 
545 int ssl_set_dh_param( ssl_context *ssl, const char *dhm_P, const char *dhm_G );
546 
556 int ssl_set_dh_param_ctx( ssl_context *ssl, dhm_context *dhm_ctx );
557 
567 int ssl_set_hostname( ssl_context *ssl, const char *hostname );
568 
577 void ssl_set_max_version( ssl_context *ssl, int major, int minor );
578 
586 size_t ssl_get_bytes_avail( const ssl_context *ssl );
587 
599 int ssl_get_verify_result( const ssl_context *ssl );
600 
608 const char *ssl_get_ciphersuite( const ssl_context *ssl );
609 
617 const char *ssl_get_version( const ssl_context *ssl );
618 
627 int ssl_handshake( ssl_context *ssl );
628 
639 int ssl_read( ssl_context *ssl, unsigned char *buf, size_t len );
640 
655 int ssl_write( ssl_context *ssl, const unsigned char *buf, size_t len );
656 
662 int ssl_close_notify( ssl_context *ssl );
663 
669 void ssl_free( ssl_context *ssl );
670 
671 /*
672  * Internal functions (do not call directly)
673  */
676 
677 int ssl_derive_keys( ssl_context *ssl );
678 void ssl_calc_verify( ssl_context *ssl, unsigned char hash[36] );
679 
680 int ssl_read_record( ssl_context *ssl );
685 int ssl_fetch_input( ssl_context *ssl, size_t nb_want );
686 
687 int ssl_write_record( ssl_context *ssl );
688 int ssl_flush_output( ssl_context *ssl );
689 
692 
695 
696 int ssl_parse_finished( ssl_context *ssl );
697 int ssl_write_finished( ssl_context *ssl );
698 
699 #ifdef __cplusplus
700 }
701 #endif
702 
703 #endif /* ssl.h */