PolarSSL v1.2.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 "rsa.h"
34 #include "md5.h"
35 #include "sha1.h"
36 #include "sha2.h"
37 #include "sha4.h"
38 #include "x509.h"
39 #include "config.h"
40 
41 #if defined(POLARSSL_DHM_C)
42 #include "dhm.h"
43 #endif
44 
45 #if defined(POLARSSL_ZLIB_SUPPORT)
46 #include "zlib.h"
47 #endif
48 
49 #if defined(_MSC_VER) && !defined(inline)
50 #define inline _inline
51 #else
52 #if defined(__ARMCC_VERSION) && !defined(inline)
53 #define inline __inline
54 #endif /* __ARMCC_VERSION */
55 #endif /*_MSC_VER */
56 
57 /*
58  * SSL Error codes
59  */
60 #define POLARSSL_ERR_SSL_FEATURE_UNAVAILABLE -0x7080
61 #define POLARSSL_ERR_SSL_BAD_INPUT_DATA -0x7100
62 #define POLARSSL_ERR_SSL_INVALID_MAC -0x7180
63 #define POLARSSL_ERR_SSL_INVALID_RECORD -0x7200
64 #define POLARSSL_ERR_SSL_CONN_EOF -0x7280
65 #define POLARSSL_ERR_SSL_UNKNOWN_CIPHER -0x7300
66 #define POLARSSL_ERR_SSL_NO_CIPHER_CHOSEN -0x7380
67 #define POLARSSL_ERR_SSL_NO_SESSION_FOUND -0x7400
68 #define POLARSSL_ERR_SSL_NO_CLIENT_CERTIFICATE -0x7480
69 #define POLARSSL_ERR_SSL_CERTIFICATE_TOO_LARGE -0x7500
70 #define POLARSSL_ERR_SSL_CERTIFICATE_REQUIRED -0x7580
71 #define POLARSSL_ERR_SSL_PRIVATE_KEY_REQUIRED -0x7600
72 #define POLARSSL_ERR_SSL_CA_CHAIN_REQUIRED -0x7680
73 #define POLARSSL_ERR_SSL_UNEXPECTED_MESSAGE -0x7700
74 #define POLARSSL_ERR_SSL_FATAL_ALERT_MESSAGE -0x7780
75 #define POLARSSL_ERR_SSL_PEER_VERIFY_FAILED -0x7800
76 #define POLARSSL_ERR_SSL_PEER_CLOSE_NOTIFY -0x7880
77 #define POLARSSL_ERR_SSL_BAD_HS_CLIENT_HELLO -0x7900
78 #define POLARSSL_ERR_SSL_BAD_HS_SERVER_HELLO -0x7980
79 #define POLARSSL_ERR_SSL_BAD_HS_CERTIFICATE -0x7A00
80 #define POLARSSL_ERR_SSL_BAD_HS_CERTIFICATE_REQUEST -0x7A80
81 #define POLARSSL_ERR_SSL_BAD_HS_SERVER_KEY_EXCHANGE -0x7B00
82 #define POLARSSL_ERR_SSL_BAD_HS_SERVER_HELLO_DONE -0x7B80
83 #define POLARSSL_ERR_SSL_BAD_HS_CLIENT_KEY_EXCHANGE -0x7C00
84 #define POLARSSL_ERR_SSL_BAD_HS_CLIENT_KEY_EXCHANGE_DHM_RP -0x7C80
85 #define POLARSSL_ERR_SSL_BAD_HS_CLIENT_KEY_EXCHANGE_DHM_CS -0x7D00
86 #define POLARSSL_ERR_SSL_BAD_HS_CERTIFICATE_VERIFY -0x7D80
87 #define POLARSSL_ERR_SSL_BAD_HS_CHANGE_CIPHER_SPEC -0x7E00
88 #define POLARSSL_ERR_SSL_BAD_HS_FINISHED -0x7E80
89 #define POLARSSL_ERR_SSL_MALLOC_FAILED -0x7F00
90 #define POLARSSL_ERR_SSL_HW_ACCEL_FAILED -0x7F80
91 #define POLARSSL_ERR_SSL_HW_ACCEL_FALLTHROUGH -0x6F80
92 #define POLARSSL_ERR_SSL_COMPRESSION_FAILED -0x6F00
93 #define POLARSSL_ERR_SSL_BAD_HS_PROTOCOL_VERSION -0x6E80
95 /*
96  * Various constants
97  */
98 #define SSL_MAJOR_VERSION_3 3
99 #define SSL_MINOR_VERSION_0 0
100 #define SSL_MINOR_VERSION_1 1
101 #define SSL_MINOR_VERSION_2 2
102 #define SSL_MINOR_VERSION_3 3
104 #define SSL_IS_CLIENT 0
105 #define SSL_IS_SERVER 1
106 #define SSL_COMPRESS_NULL 0
107 #define SSL_COMPRESS_DEFLATE 1
108 
109 #define SSL_VERIFY_NONE 0
110 #define SSL_VERIFY_OPTIONAL 1
111 #define SSL_VERIFY_REQUIRED 2
112 
113 #define SSL_INITIAL_HANDSHAKE 0
114 #define SSL_RENEGOTIATION 1
115 
116 #define SSL_LEGACY_RENEGOTIATION 0
117 #define SSL_SECURE_RENEGOTIATION 1
118 
119 #define SSL_RENEGOTIATION_DISABLED 0
120 #define SSL_RENEGOTIATION_ENABLED 1
121 
122 #define SSL_LEGACY_NO_RENEGOTIATION 0
123 #define SSL_LEGACY_ALLOW_RENEGOTIATION 1
124 #define SSL_LEGACY_BREAK_HANDSHAKE 2
125 
126 #define SSL_MAX_CONTENT_LEN 16384
127 
128 /*
129  * Allow an extra 512 bytes for the record header
130  * and encryption overhead (counter + MAC + padding)
131  * and allow for a maximum of 1024 of compression expansion if
132  * enabled.
133  */
134 #if defined(POLARSSL_ZLIB_SUPPORT)
135 #define SSL_COMPRESSION_ADD 1024
136 #else
137 #define SSL_COMPRESSION_ADD 0
138 #endif
139 
140 #define SSL_BUFFER_LEN (SSL_MAX_CONTENT_LEN + SSL_COMPRESSION_ADD + 512)
141 
142 /*
143  * Supported ciphersuites (Official IANA names)
144  */
145 #define TLS_RSA_WITH_NULL_MD5 0x01
146 #define TLS_RSA_WITH_NULL_SHA 0x02
147 #define TLS_RSA_WITH_NULL_SHA256 0x3B
148 #define TLS_RSA_WITH_DES_CBC_SHA 0x09
149 #define TLS_DHE_RSA_WITH_DES_CBC_SHA 0x15
151 #define TLS_RSA_WITH_RC4_128_MD5 0x04
152 #define TLS_RSA_WITH_RC4_128_SHA 0x05
153 
154 #define TLS_RSA_WITH_3DES_EDE_CBC_SHA 0x0A
155 #define TLS_DHE_RSA_WITH_3DES_EDE_CBC_SHA 0x16
156 
157 #define TLS_RSA_WITH_AES_128_CBC_SHA 0x2F
158 #define TLS_DHE_RSA_WITH_AES_128_CBC_SHA 0x33
159 #define TLS_RSA_WITH_AES_256_CBC_SHA 0x35
160 #define TLS_DHE_RSA_WITH_AES_256_CBC_SHA 0x39
161 #define TLS_RSA_WITH_AES_128_CBC_SHA256 0x3C
162 #define TLS_RSA_WITH_AES_256_CBC_SHA256 0x3D
163 #define TLS_DHE_RSA_WITH_AES_128_CBC_SHA256 0x67
164 #define TLS_DHE_RSA_WITH_AES_256_CBC_SHA256 0x6B
166 #define TLS_RSA_WITH_CAMELLIA_128_CBC_SHA 0x41
167 #define TLS_DHE_RSA_WITH_CAMELLIA_128_CBC_SHA 0x45
168 #define TLS_RSA_WITH_CAMELLIA_256_CBC_SHA 0x84
169 #define TLS_DHE_RSA_WITH_CAMELLIA_256_CBC_SHA 0x88
170 #define TLS_RSA_WITH_CAMELLIA_128_CBC_SHA256 0xBA
171 #define TLS_DHE_RSA_WITH_CAMELLIA_128_CBC_SHA256 0xBE
172 #define TLS_RSA_WITH_CAMELLIA_256_CBC_SHA256 0xC0
173 #define TLS_DHE_RSA_WITH_CAMELLIA_256_CBC_SHA256 0xC4
175 #define TLS_RSA_WITH_AES_128_GCM_SHA256 0x9C
176 #define TLS_RSA_WITH_AES_256_GCM_SHA384 0x9D
177 #define TLS_DHE_RSA_WITH_AES_128_GCM_SHA256 0x9E
178 #define TLS_DHE_RSA_WITH_AES_256_GCM_SHA384 0x9F
179 
180 #define SSL_EMPTY_RENEGOTIATION_INFO 0xFF
182 /*
183  * Supported Signature and Hash algorithms (For TLS 1.2)
184  */
185 #define SSL_HASH_NONE 0
186 #define SSL_HASH_MD5 1
187 #define SSL_HASH_SHA1 2
188 #define SSL_HASH_SHA224 3
189 #define SSL_HASH_SHA256 4
190 #define SSL_HASH_SHA384 5
191 #define SSL_HASH_SHA512 6
192 
193 #define SSL_SIG_RSA 1
194 
195 /*
196  * Client Certificate Types
197  */
198 #define SSL_CERT_TYPE_RSA_SIGN 1
199 
200 /*
201  * Message, alert and handshake types
202  */
203 #define SSL_MSG_CHANGE_CIPHER_SPEC 20
204 #define SSL_MSG_ALERT 21
205 #define SSL_MSG_HANDSHAKE 22
206 #define SSL_MSG_APPLICATION_DATA 23
207 
208 #define SSL_ALERT_LEVEL_WARNING 1
209 #define SSL_ALERT_LEVEL_FATAL 2
210 
211 #define SSL_ALERT_MSG_CLOSE_NOTIFY 0 /* 0x00 */
212 #define SSL_ALERT_MSG_UNEXPECTED_MESSAGE 10 /* 0x0A */
213 #define SSL_ALERT_MSG_BAD_RECORD_MAC 20 /* 0x14 */
214 #define SSL_ALERT_MSG_DECRYPTION_FAILED 21 /* 0x15 */
215 #define SSL_ALERT_MSG_RECORD_OVERFLOW 22 /* 0x16 */
216 #define SSL_ALERT_MSG_DECOMPRESSION_FAILURE 30 /* 0x1E */
217 #define SSL_ALERT_MSG_HANDSHAKE_FAILURE 40 /* 0x28 */
218 #define SSL_ALERT_MSG_NO_CERT 41 /* 0x29 */
219 #define SSL_ALERT_MSG_BAD_CERT 42 /* 0x2A */
220 #define SSL_ALERT_MSG_UNSUPPORTED_CERT 43 /* 0x2B */
221 #define SSL_ALERT_MSG_CERT_REVOKED 44 /* 0x2C */
222 #define SSL_ALERT_MSG_CERT_EXPIRED 45 /* 0x2D */
223 #define SSL_ALERT_MSG_CERT_UNKNOWN 46 /* 0x2E */
224 #define SSL_ALERT_MSG_ILLEGAL_PARAMETER 47 /* 0x2F */
225 #define SSL_ALERT_MSG_UNKNOWN_CA 48 /* 0x30 */
226 #define SSL_ALERT_MSG_ACCESS_DENIED 49 /* 0x31 */
227 #define SSL_ALERT_MSG_DECODE_ERROR 50 /* 0x32 */
228 #define SSL_ALERT_MSG_DECRYPT_ERROR 51 /* 0x33 */
229 #define SSL_ALERT_MSG_EXPORT_RESTRICTION 60 /* 0x3C */
230 #define SSL_ALERT_MSG_PROTOCOL_VERSION 70 /* 0x46 */
231 #define SSL_ALERT_MSG_INSUFFICIENT_SECURITY 71 /* 0x47 */
232 #define SSL_ALERT_MSG_INTERNAL_ERROR 80 /* 0x50 */
233 #define SSL_ALERT_MSG_USER_CANCELED 90 /* 0x5A */
234 #define SSL_ALERT_MSG_NO_RENEGOTIATION 100 /* 0x64 */
235 #define SSL_ALERT_MSG_UNSUPPORTED_EXT 110 /* 0x6E */
236 #define SSL_ALERT_MSG_UNRECOGNIZED_NAME 112 /* 0x70 */
237 
238 #define SSL_HS_HELLO_REQUEST 0
239 #define SSL_HS_CLIENT_HELLO 1
240 #define SSL_HS_SERVER_HELLO 2
241 #define SSL_HS_CERTIFICATE 11
242 #define SSL_HS_SERVER_KEY_EXCHANGE 12
243 #define SSL_HS_CERTIFICATE_REQUEST 13
244 #define SSL_HS_SERVER_HELLO_DONE 14
245 #define SSL_HS_CERTIFICATE_VERIFY 15
246 #define SSL_HS_CLIENT_KEY_EXCHANGE 16
247 #define SSL_HS_FINISHED 20
248 
249 /*
250  * TLS extensions
251  */
252 #define TLS_EXT_SERVERNAME 0
253 #define TLS_EXT_SERVERNAME_HOSTNAME 0
254 
255 #define TLS_EXT_SIG_ALG 13
256 
257 #define TLS_EXT_RENEGOTIATION_INFO 0xFF01
258 
259 
260 /*
261  * Generic function pointers for allowing external RSA private key
262  * implementations.
263  */
264 typedef int (*rsa_decrypt_func)( void *ctx, int mode, size_t *olen,
265  const unsigned char *input, unsigned char *output,
266  size_t output_max_len );
267 typedef int (*rsa_sign_func)( void *ctx,
268  int (*f_rng)(void *, unsigned char *, size_t), void *p_rng,
269  int mode, int hash_id, unsigned int hashlen,
270  const unsigned char *hash, unsigned char *sig );
271 typedef size_t (*rsa_key_len_func)( void *ctx );
272 
273 /*
274  * SSL state machine
275  */
276 typedef enum
277 {
295 }
296 ssl_states;
297 
298 typedef struct _ssl_session ssl_session;
299 typedef struct _ssl_context ssl_context;
302 
303 /*
304  * This structure is used for storing current session data.
305  */
307 {
308  time_t start;
311  size_t length;
312  unsigned char id[32];
313  unsigned char master[48];
315 };
316 
317 /*
318  * This structure contains a full set of runtime transform parameters
319  * either in negotiation or active.
320  */
322 {
323  /*
324  * Session specific crypto layer
325  */
326  unsigned int keylen;
327  size_t minlen;
328  size_t ivlen;
329  size_t fixed_ivlen;
330  size_t maclen;
332  unsigned char iv_enc[16];
333  unsigned char iv_dec[16];
335  unsigned char mac_enc[32];
336  unsigned char mac_dec[32];
338  uint32_t ctx_enc[136];
339  uint32_t ctx_dec[136];
341  /*
342  * Session specific compression layer
343  */
344 #if defined(POLARSSL_ZLIB_SUPPORT)
345  z_stream ctx_deflate;
346  z_stream ctx_inflate;
347 #endif
348 };
349 
350 /*
351  * This structure contains the parameters only needed during handshake.
352  */
354 {
355  /*
356  * Handshake specific crypto variables
357  */
358  int sig_alg;
359  int cert_type;
361 #if defined(POLARSSL_DHM_C)
363 #endif
364 
365  /*
366  * Checksum contexts
367  */
372 
373  void (*update_checksum)(ssl_context *, unsigned char *, size_t);
374  void (*calc_verify)(ssl_context *, unsigned char *);
375  void (*calc_finished)(ssl_context *, unsigned char *, int);
376  int (*tls_prf)(unsigned char *, size_t, char *,
377  unsigned char *, size_t,
378  unsigned char *, size_t);
379 
380  size_t pmslen;
382  unsigned char randbytes[64];
383  unsigned char premaster[POLARSSL_MPI_MAX_SIZE];
386  int resume;
387 };
388 
390 {
391  /*
392  * Miscellaneous
393  */
394  int state;
397  int major_ver;
398  int minor_ver;
405  /*
406  * Callbacks (RNG, debug, I/O, verification)
407  */
408  int (*f_rng)(void *, unsigned char *, size_t);
409  void (*f_dbg)(void *, int, const char *);
410  int (*f_recv)(void *, unsigned char *, size_t);
411  int (*f_send)(void *, const unsigned char *, size_t);
412  int (*f_vrfy)(void *, x509_cert *, int, int *);
413  int (*f_get_cache)(void *, ssl_session *);
414  int (*f_set_cache)(void *, const ssl_session *);
415  int (*f_sni)(void *, ssl_context *, const unsigned char *, size_t);
416 
417  void *p_rng;
418  void *p_dbg;
419  void *p_recv;
420  void *p_send;
421  void *p_vrfy;
422  void *p_get_cache;
423  void *p_set_cache;
424  void *p_sni;
425  void *p_hw_data;
427  /*
428  * Session layer
429  */
438  /*
439  * Record layer transformations
440  */
446  /*
447  * Record layer (incoming data)
448  */
449  unsigned char *in_ctr;
450  unsigned char *in_hdr;
451  unsigned char *in_msg;
452  unsigned char *in_offt;
455  size_t in_msglen;
456  size_t in_left;
458  size_t in_hslen;
459  int nb_zero;
461  /*
462  * Record layer (outgoing data)
463  */
464  unsigned char *out_ctr;
465  unsigned char *out_hdr;
466  unsigned char *out_msg;
469  size_t out_msglen;
470  size_t out_left;
472  /*
473  * PKI layer
474  */
475  void *rsa_key;
483  const char *peer_cn;
485  /*
486  * User settings
487  */
488  int endpoint;
489  int authmode;
494  const int *ciphersuites;
496 #if defined(POLARSSL_DHM_C)
499 #endif
500 
501  /*
502  * TLS extensions
503  */
504  unsigned char *hostname;
505  size_t hostname_len;
506 
507  /*
508  * Secure renegotiation
509  */
513  char own_verify_data[36];
514  char peer_verify_data[36];
515 };
516 
517 #ifdef __cplusplus
518 extern "C" {
519 #endif
520 
521 extern const int ssl_default_ciphersuites[];
522 
523 #if defined(POLARSSL_SSL_HW_RECORD_ACCEL)
524 extern int (*ssl_hw_record_init)(ssl_context *ssl,
525  const unsigned char *key_enc, const unsigned char *key_dec,
526  const unsigned char *iv_enc, const unsigned char *iv_dec,
527  const unsigned char *mac_enc, const unsigned char *mac_dec);
528 extern int (*ssl_hw_record_reset)(ssl_context *ssl);
529 extern int (*ssl_hw_record_write)(ssl_context *ssl);
530 extern int (*ssl_hw_record_read)(ssl_context *ssl);
531 extern int (*ssl_hw_record_finish)(ssl_context *ssl);
532 #endif
533 
540 static inline const int *ssl_list_ciphersuites( void )
541 {
542  return ssl_default_ciphersuites;
543 }
544 
553 const char *ssl_get_ciphersuite_name( const int ciphersuite_id );
554 
563 int ssl_get_ciphersuite_id( const char *ciphersuite_name );
564 
573 int ssl_init( ssl_context *ssl );
574 
585 int ssl_session_reset( ssl_context *ssl );
586 
593 void ssl_set_endpoint( ssl_context *ssl, int endpoint );
594 
612 void ssl_set_authmode( ssl_context *ssl, int authmode );
613 
625 void ssl_set_verify( ssl_context *ssl,
626  int (*f_vrfy)(void *, x509_cert *, int, int *),
627  void *p_vrfy );
628 
636 void ssl_set_rng( ssl_context *ssl,
637  int (*f_rng)(void *, unsigned char *, size_t),
638  void *p_rng );
639 
647 void ssl_set_dbg( ssl_context *ssl,
648  void (*f_dbg)(void *, int, const char *),
649  void *p_dbg );
650 
660 void ssl_set_bio( ssl_context *ssl,
661  int (*f_recv)(void *, unsigned char *, size_t), void *p_recv,
662  int (*f_send)(void *, const unsigned char *, size_t), void *p_send );
663 
702  int (*f_get_cache)(void *, ssl_session *), void *p_get_cache,
703  int (*f_set_cache)(void *, const ssl_session *), void *p_set_cache );
704 
717 void ssl_set_session( ssl_context *ssl, const ssl_session *session );
718 
725 void ssl_set_ciphersuites( ssl_context *ssl, const int *ciphersuites );
726 
735 void ssl_set_ca_chain( ssl_context *ssl, x509_cert *ca_chain,
736  x509_crl *ca_crl, const char *peer_cn );
737 
749 void ssl_set_own_cert( ssl_context *ssl, x509_cert *own_cert,
750  rsa_context *rsa_key );
751 
771 void ssl_set_own_cert_alt( ssl_context *ssl, x509_cert *own_cert,
772  void *rsa_key,
773  rsa_decrypt_func rsa_decrypt,
774  rsa_sign_func rsa_sign,
775  rsa_key_len_func rsa_key_len );
776 
777 #if defined(POLARSSL_DHM_C)
778 
789 int ssl_set_dh_param( ssl_context *ssl, const char *dhm_P, const char *dhm_G );
790 
800 int ssl_set_dh_param_ctx( ssl_context *ssl, dhm_context *dhm_ctx );
801 #endif
802 
813 int ssl_set_hostname( ssl_context *ssl, const char *hostname );
814 
834 void ssl_set_sni( ssl_context *ssl,
835  int (*f_sni)(void *, ssl_context *, const unsigned char *,
836  size_t),
837  void *p_sni );
838 
848 void ssl_set_max_version( ssl_context *ssl, int major, int minor );
849 
850 
861 void ssl_set_min_version( ssl_context *ssl, int major, int minor );
862 
876 void ssl_set_renegotiation( ssl_context *ssl, int renegotiation );
877 
905 void ssl_legacy_renegotiation( ssl_context *ssl, int allow_legacy );
906 
914 size_t ssl_get_bytes_avail( const ssl_context *ssl );
915 
927 int ssl_get_verify_result( const ssl_context *ssl );
928 
936 const char *ssl_get_ciphersuite( const ssl_context *ssl );
937 
945 const char *ssl_get_version( const ssl_context *ssl );
946 
961 const x509_cert *ssl_get_peer_cert( const ssl_context *ssl );
962 
971 int ssl_handshake( ssl_context *ssl );
972 
985 int ssl_handshake_step( ssl_context *ssl );
986 
994 int ssl_renegotiate( ssl_context *ssl );
995 
1006 int ssl_read( ssl_context *ssl, unsigned char *buf, size_t len );
1007 
1022 int ssl_write( ssl_context *ssl, const unsigned char *buf, size_t len );
1023 
1035  unsigned char level,
1036  unsigned char message );
1042 int ssl_close_notify( ssl_context *ssl );
1043 
1049 void ssl_free( ssl_context *ssl );
1050 
1057 void ssl_session_free( ssl_session *session );
1058 
1065 void ssl_transform_free( ssl_transform *transform );
1066 
1073 void ssl_handshake_free( ssl_handshake_params *handshake );
1074 
1075 /*
1076  * Internal functions (do not call directly)
1077  */
1080 void ssl_handshake_wrapup( ssl_context *ssl );
1081 
1083 
1084 int ssl_derive_keys( ssl_context *ssl );
1085 
1086 int ssl_read_record( ssl_context *ssl );
1091 int ssl_fetch_input( ssl_context *ssl, size_t nb_want );
1092 
1093 int ssl_write_record( ssl_context *ssl );
1094 int ssl_flush_output( ssl_context *ssl );
1095 
1098 
1101 
1102 int ssl_parse_finished( ssl_context *ssl );
1103 int ssl_write_finished( ssl_context *ssl );
1104 
1105 void ssl_optimize_checksum( ssl_context *ssl, int ciphersuite );
1106 
1107 #ifdef __cplusplus
1108 }
1109 #endif
1110 
1111 #endif /* ssl.h */