PolarSSL v1.3.8
ssl.h
Go to the documentation of this file.
1 
27 #ifndef POLARSSL_SSL_H
28 #define POLARSSL_SSL_H
29 
30 #if !defined(POLARSSL_CONFIG_FILE)
31 #include "config.h"
32 #else
33 #include POLARSSL_CONFIG_FILE
34 #endif
35 #include "net.h"
36 #include "bignum.h"
37 #include "ecp.h"
38 
39 #include "ssl_ciphersuites.h"
40 
41 #if defined(POLARSSL_MD5_C)
42 #include "md5.h"
43 #endif
44 
45 #if defined(POLARSSL_SHA1_C)
46 #include "sha1.h"
47 #endif
48 
49 #if defined(POLARSSL_SHA256_C)
50 #include "sha256.h"
51 #endif
52 
53 #if defined(POLARSSL_SHA512_C)
54 #include "sha512.h"
55 #endif
56 
57 // for session tickets
58 #if defined(POLARSSL_AES_C)
59 #include "aes.h"
60 #endif
61 
62 #if defined(POLARSSL_X509_CRT_PARSE_C)
63 #include "x509_crt.h"
64 #include "x509_crl.h"
65 #endif
66 
67 #if defined(POLARSSL_DHM_C)
68 #include "dhm.h"
69 #endif
70 
71 #if defined(POLARSSL_ECDH_C)
72 #include "ecdh.h"
73 #endif
74 
75 #if defined(POLARSSL_ZLIB_SUPPORT)
76 #include "zlib.h"
77 #endif
78 
79 #if defined(POLARSSL_HAVE_TIME)
80 #include <time.h>
81 #endif
82 
83 /* For convenience below and in programs */
84 #if defined(POLARSSL_KEY_EXCHANGE_PSK_ENABLED) || \
85  defined(POLARSSL_KEY_EXCHANGE_RSA_PSK_ENABLED) || \
86  defined(POLARSSL_KEY_EXCHANGE_DHE_PSK_ENABLED) || \
87  defined(POLARSSL_KEY_EXCHANGE_ECDHE_PSK_ENABLED)
88 #define POLARSSL_KEY_EXCHANGE__SOME__PSK_ENABLED
89 #endif
90 
91 #if defined(POLARSSL_KEY_EXCHANGE_ECDHE_RSA_ENABLED) || \
92  defined(POLARSSL_KEY_EXCHANGE_ECDHE_ECDSA_ENABLED) || \
93  defined(POLARSSL_KEY_EXCHANGE_ECDHE_PSK_ENABLED)
94 #define POLARSSL_KEY_EXCHANGE__SOME__ECDHE_ENABLED
95 #endif
96 
97 #if defined(_MSC_VER) && !defined(inline)
98 #define inline _inline
99 #else
100 #if defined(__ARMCC_VERSION) && !defined(inline)
101 #define inline __inline
102 #endif /* __ARMCC_VERSION */
103 #endif /*_MSC_VER */
104 
105 /*
106  * SSL Error codes
107  */
108 #define POLARSSL_ERR_SSL_FEATURE_UNAVAILABLE -0x7080
109 #define POLARSSL_ERR_SSL_BAD_INPUT_DATA -0x7100
110 #define POLARSSL_ERR_SSL_INVALID_MAC -0x7180
111 #define POLARSSL_ERR_SSL_INVALID_RECORD -0x7200
112 #define POLARSSL_ERR_SSL_CONN_EOF -0x7280
113 #define POLARSSL_ERR_SSL_UNKNOWN_CIPHER -0x7300
114 #define POLARSSL_ERR_SSL_NO_CIPHER_CHOSEN -0x7380
115 #define POLARSSL_ERR_SSL_NO_RNG -0x7400
116 #define POLARSSL_ERR_SSL_NO_CLIENT_CERTIFICATE -0x7480
117 #define POLARSSL_ERR_SSL_CERTIFICATE_TOO_LARGE -0x7500
118 #define POLARSSL_ERR_SSL_CERTIFICATE_REQUIRED -0x7580
119 #define POLARSSL_ERR_SSL_PRIVATE_KEY_REQUIRED -0x7600
120 #define POLARSSL_ERR_SSL_CA_CHAIN_REQUIRED -0x7680
121 #define POLARSSL_ERR_SSL_UNEXPECTED_MESSAGE -0x7700
122 #define POLARSSL_ERR_SSL_FATAL_ALERT_MESSAGE -0x7780
123 #define POLARSSL_ERR_SSL_PEER_VERIFY_FAILED -0x7800
124 #define POLARSSL_ERR_SSL_PEER_CLOSE_NOTIFY -0x7880
125 #define POLARSSL_ERR_SSL_BAD_HS_CLIENT_HELLO -0x7900
126 #define POLARSSL_ERR_SSL_BAD_HS_SERVER_HELLO -0x7980
127 #define POLARSSL_ERR_SSL_BAD_HS_CERTIFICATE -0x7A00
128 #define POLARSSL_ERR_SSL_BAD_HS_CERTIFICATE_REQUEST -0x7A80
129 #define POLARSSL_ERR_SSL_BAD_HS_SERVER_KEY_EXCHANGE -0x7B00
130 #define POLARSSL_ERR_SSL_BAD_HS_SERVER_HELLO_DONE -0x7B80
131 #define POLARSSL_ERR_SSL_BAD_HS_CLIENT_KEY_EXCHANGE -0x7C00
132 #define POLARSSL_ERR_SSL_BAD_HS_CLIENT_KEY_EXCHANGE_RP -0x7C80
133 #define POLARSSL_ERR_SSL_BAD_HS_CLIENT_KEY_EXCHANGE_CS -0x7D00
134 #define POLARSSL_ERR_SSL_BAD_HS_CERTIFICATE_VERIFY -0x7D80
135 #define POLARSSL_ERR_SSL_BAD_HS_CHANGE_CIPHER_SPEC -0x7E00
136 #define POLARSSL_ERR_SSL_BAD_HS_FINISHED -0x7E80
137 #define POLARSSL_ERR_SSL_MALLOC_FAILED -0x7F00
138 #define POLARSSL_ERR_SSL_HW_ACCEL_FAILED -0x7F80
139 #define POLARSSL_ERR_SSL_HW_ACCEL_FALLTHROUGH -0x6F80
140 #define POLARSSL_ERR_SSL_COMPRESSION_FAILED -0x6F00
141 #define POLARSSL_ERR_SSL_BAD_HS_PROTOCOL_VERSION -0x6E80
142 #define POLARSSL_ERR_SSL_BAD_HS_NEW_SESSION_TICKET -0x6E00
143 #define POLARSSL_ERR_SSL_SESSION_TICKET_EXPIRED -0x6D80
144 #define POLARSSL_ERR_SSL_PK_TYPE_MISMATCH -0x6D00
145 #define POLARSSL_ERR_SSL_UNKNOWN_IDENTITY -0x6C80
146 #define POLARSSL_ERR_SSL_INTERNAL_ERROR -0x6C00
147 #define POLARSSL_ERR_SSL_COUNTER_WRAPPING -0x6B80
149 /*
150  * Various constants
151  */
152 #define SSL_MAJOR_VERSION_3 3
153 #define SSL_MINOR_VERSION_0 0
154 #define SSL_MINOR_VERSION_1 1
155 #define SSL_MINOR_VERSION_2 2
156 #define SSL_MINOR_VERSION_3 3
158 /* Determine minimum supported version */
159 #define SSL_MIN_MAJOR_VERSION SSL_MAJOR_VERSION_3
160 
161 #if defined(POLARSSL_SSL_PROTO_SSL3)
162 #define SSL_MIN_MINOR_VERSION SSL_MINOR_VERSION_0
163 #else
164 #if defined(POLARSSL_SSL_PROTO_TLS1)
165 #define SSL_MIN_MINOR_VERSION SSL_MINOR_VERSION_1
166 #else
167 #if defined(POLARSSL_SSL_PROTO_TLS1_1)
168 #define SSL_MIN_MINOR_VERSION SSL_MINOR_VERSION_2
169 #else
170 #if defined(POLARSSL_SSL_PROTO_TLS1_2)
171 #define SSL_MIN_MINOR_VERSION SSL_MINOR_VERSION_3
172 #endif /* POLARSSL_SSL_PROTO_TLS1_2 */
173 #endif /* POLARSSL_SSL_PROTO_TLS1_1 */
174 #endif /* POLARSSL_SSL_PROTO_TLS1 */
175 #endif /* POLARSSL_SSL_PROTO_SSL3 */
176 
177 /* Determine maximum supported version */
178 #define SSL_MAX_MAJOR_VERSION SSL_MAJOR_VERSION_3
179 
180 #if defined(POLARSSL_SSL_PROTO_TLS1_2)
181 #define SSL_MAX_MINOR_VERSION SSL_MINOR_VERSION_3
182 #else
183 #if defined(POLARSSL_SSL_PROTO_TLS1_1)
184 #define SSL_MAX_MINOR_VERSION SSL_MINOR_VERSION_2
185 #else
186 #if defined(POLARSSL_SSL_PROTO_TLS1)
187 #define SSL_MAX_MINOR_VERSION SSL_MINOR_VERSION_1
188 #else
189 #if defined(POLARSSL_SSL_PROTO_SSL3)
190 #define SSL_MAX_MINOR_VERSION SSL_MINOR_VERSION_0
191 #endif /* POLARSSL_SSL_PROTO_SSL3 */
192 #endif /* POLARSSL_SSL_PROTO_TLS1 */
193 #endif /* POLARSSL_SSL_PROTO_TLS1_1 */
194 #endif /* POLARSSL_SSL_PROTO_TLS1_2 */
195 
196 /* RFC 6066 section 4, see also mfl_code_to_length in ssl_tls.c
197  * NONE must be zero so that memset()ing structure to zero works */
198 #define SSL_MAX_FRAG_LEN_NONE 0
199 #define SSL_MAX_FRAG_LEN_512 1
200 #define SSL_MAX_FRAG_LEN_1024 2
201 #define SSL_MAX_FRAG_LEN_2048 3
202 #define SSL_MAX_FRAG_LEN_4096 4
203 #define SSL_MAX_FRAG_LEN_INVALID 5
205 #define SSL_IS_CLIENT 0
206 #define SSL_IS_SERVER 1
207 #define SSL_COMPRESS_NULL 0
208 #define SSL_COMPRESS_DEFLATE 1
209 
210 #define SSL_VERIFY_NONE 0
211 #define SSL_VERIFY_OPTIONAL 1
212 #define SSL_VERIFY_REQUIRED 2
213 
214 #define SSL_INITIAL_HANDSHAKE 0
215 #define SSL_RENEGOTIATION 1 /* In progress */
216 #define SSL_RENEGOTIATION_DONE 2 /* Done */
217 #define SSL_RENEGOTIATION_PENDING 3 /* Requested (server only) */
218 
219 #define SSL_LEGACY_RENEGOTIATION 0
220 #define SSL_SECURE_RENEGOTIATION 1
221 
222 #define SSL_RENEGOTIATION_DISABLED 0
223 #define SSL_RENEGOTIATION_ENABLED 1
224 
225 #define SSL_RENEGOTIATION_NOT_ENFORCED -1
226 #define SSL_RENEGO_MAX_RECORDS_DEFAULT 16
227 
228 #define SSL_LEGACY_NO_RENEGOTIATION 0
229 #define SSL_LEGACY_ALLOW_RENEGOTIATION 1
230 #define SSL_LEGACY_BREAK_HANDSHAKE 2
231 
232 #define SSL_TRUNC_HMAC_DISABLED 0
233 #define SSL_TRUNC_HMAC_ENABLED 1
234 #define SSL_TRUNCATED_HMAC_LEN 10 /* 80 bits, rfc 6066 section 7 */
235 
236 #define SSL_SESSION_TICKETS_DISABLED 0
237 #define SSL_SESSION_TICKETS_ENABLED 1
238 
247 #if !defined(SSL_DEFAULT_TICKET_LIFETIME)
248 #define SSL_DEFAULT_TICKET_LIFETIME 86400
249 #endif
250 
251 /*
252  * Size of the input / output buffer.
253  * Note: the RFC defines the default size of SSL / TLS messages. If you
254  * change the value here, other clients / servers may not be able to
255  * communicate with you anymore. Only change this value if you control
256  * both sides of the connection and have it reduced at both sides, or
257  * if you're using the Max Fragment Length extension and you know all your
258  * peers are using it too!
259  */
260 #if !defined(SSL_MAX_CONTENT_LEN)
261 #define SSL_MAX_CONTENT_LEN 16384
262 #endif
263 
264 /* \} name SECTION: Module settings */
265 
266 /*
267  * Allow extra bytes for record, authentication and encryption overhead:
268  * counter (8) + header (5) + IV(16) + MAC (16-48) + padding (0-256)
269  * and allow for a maximum of 1024 of compression expansion if
270  * enabled.
271  */
272 #if defined(POLARSSL_ZLIB_SUPPORT)
273 #define SSL_COMPRESSION_ADD 1024
274 #else
275 #define SSL_COMPRESSION_ADD 0
276 #endif
277 
278 #if defined(POLARSSL_RC4_C) || defined(POLARSSL_CIPHER_MODE_CBC)
279 /* Ciphersuites using HMAC */
280 #if defined(POLARSSL_SHA512_C)
281 #define SSL_MAC_ADD 48 /* SHA-384 used for HMAC */
282 #elif defined(POLARSSL_SHA256_C)
283 #define SSL_MAC_ADD 32 /* SHA-256 used for HMAC */
284 #else
285 #define SSL_MAC_ADD 20 /* SHA-1 used for HMAC */
286 #endif
287 #else
288 /* AEAD ciphersuites: GCM and CCM use a 128 bits tag */
289 #define SSL_MAC_ADD 16
290 #endif
291 
292 #if defined(POLARSSL_CIPHER_MODE_CBC)
293 #define SSL_PADDING_ADD 256
294 #else
295 #define SSL_PADDING_ADD 0
296 #endif
297 
298 #define SSL_BUFFER_LEN ( SSL_MAX_CONTENT_LEN \
299  + SSL_COMPRESSION_ADD \
300  + 29 /* counter + header + IV */ \
301  + SSL_MAC_ADD \
302  + SSL_PADDING_ADD \
303  )
304 
305 /*
306  * Signaling ciphersuite values (SCSV)
307  */
308 #define SSL_EMPTY_RENEGOTIATION_INFO 0xFF
310 /*
311  * Supported Signature and Hash algorithms (For TLS 1.2)
312  * RFC 5246 section 7.4.1.4.1
313  */
314 #define SSL_HASH_NONE 0
315 #define SSL_HASH_MD5 1
316 #define SSL_HASH_SHA1 2
317 #define SSL_HASH_SHA224 3
318 #define SSL_HASH_SHA256 4
319 #define SSL_HASH_SHA384 5
320 #define SSL_HASH_SHA512 6
321 
322 #define SSL_SIG_ANON 0
323 #define SSL_SIG_RSA 1
324 #define SSL_SIG_ECDSA 3
325 
326 /*
327  * Client Certificate Types
328  * RFC 5246 section 7.4.4 plus RFC 4492 section 5.5
329  */
330 #define SSL_CERT_TYPE_RSA_SIGN 1
331 #define SSL_CERT_TYPE_ECDSA_SIGN 64
332 
333 /*
334  * Message, alert and handshake types
335  */
336 #define SSL_MSG_CHANGE_CIPHER_SPEC 20
337 #define SSL_MSG_ALERT 21
338 #define SSL_MSG_HANDSHAKE 22
339 #define SSL_MSG_APPLICATION_DATA 23
340 
341 #define SSL_ALERT_LEVEL_WARNING 1
342 #define SSL_ALERT_LEVEL_FATAL 2
343 
344 #define SSL_ALERT_MSG_CLOSE_NOTIFY 0 /* 0x00 */
345 #define SSL_ALERT_MSG_UNEXPECTED_MESSAGE 10 /* 0x0A */
346 #define SSL_ALERT_MSG_BAD_RECORD_MAC 20 /* 0x14 */
347 #define SSL_ALERT_MSG_DECRYPTION_FAILED 21 /* 0x15 */
348 #define SSL_ALERT_MSG_RECORD_OVERFLOW 22 /* 0x16 */
349 #define SSL_ALERT_MSG_DECOMPRESSION_FAILURE 30 /* 0x1E */
350 #define SSL_ALERT_MSG_HANDSHAKE_FAILURE 40 /* 0x28 */
351 #define SSL_ALERT_MSG_NO_CERT 41 /* 0x29 */
352 #define SSL_ALERT_MSG_BAD_CERT 42 /* 0x2A */
353 #define SSL_ALERT_MSG_UNSUPPORTED_CERT 43 /* 0x2B */
354 #define SSL_ALERT_MSG_CERT_REVOKED 44 /* 0x2C */
355 #define SSL_ALERT_MSG_CERT_EXPIRED 45 /* 0x2D */
356 #define SSL_ALERT_MSG_CERT_UNKNOWN 46 /* 0x2E */
357 #define SSL_ALERT_MSG_ILLEGAL_PARAMETER 47 /* 0x2F */
358 #define SSL_ALERT_MSG_UNKNOWN_CA 48 /* 0x30 */
359 #define SSL_ALERT_MSG_ACCESS_DENIED 49 /* 0x31 */
360 #define SSL_ALERT_MSG_DECODE_ERROR 50 /* 0x32 */
361 #define SSL_ALERT_MSG_DECRYPT_ERROR 51 /* 0x33 */
362 #define SSL_ALERT_MSG_EXPORT_RESTRICTION 60 /* 0x3C */
363 #define SSL_ALERT_MSG_PROTOCOL_VERSION 70 /* 0x46 */
364 #define SSL_ALERT_MSG_INSUFFICIENT_SECURITY 71 /* 0x47 */
365 #define SSL_ALERT_MSG_INTERNAL_ERROR 80 /* 0x50 */
366 #define SSL_ALERT_MSG_USER_CANCELED 90 /* 0x5A */
367 #define SSL_ALERT_MSG_NO_RENEGOTIATION 100 /* 0x64 */
368 #define SSL_ALERT_MSG_UNSUPPORTED_EXT 110 /* 0x6E */
369 #define SSL_ALERT_MSG_UNRECOGNIZED_NAME 112 /* 0x70 */
370 #define SSL_ALERT_MSG_UNKNOWN_PSK_IDENTITY 115 /* 0x73 */
371 #define SSL_ALERT_MSG_NO_APPLICATION_PROTOCOL 120 /* 0x78 */
372 
373 #define SSL_HS_HELLO_REQUEST 0
374 #define SSL_HS_CLIENT_HELLO 1
375 #define SSL_HS_SERVER_HELLO 2
376 #define SSL_HS_NEW_SESSION_TICKET 4
377 #define SSL_HS_CERTIFICATE 11
378 #define SSL_HS_SERVER_KEY_EXCHANGE 12
379 #define SSL_HS_CERTIFICATE_REQUEST 13
380 #define SSL_HS_SERVER_HELLO_DONE 14
381 #define SSL_HS_CERTIFICATE_VERIFY 15
382 #define SSL_HS_CLIENT_KEY_EXCHANGE 16
383 #define SSL_HS_FINISHED 20
384 
385 /*
386  * TLS extensions
387  */
388 #define TLS_EXT_SERVERNAME 0
389 #define TLS_EXT_SERVERNAME_HOSTNAME 0
390 
391 #define TLS_EXT_MAX_FRAGMENT_LENGTH 1
392 
393 #define TLS_EXT_TRUNCATED_HMAC 4
394 
395 #define TLS_EXT_SUPPORTED_ELLIPTIC_CURVES 10
396 #define TLS_EXT_SUPPORTED_POINT_FORMATS 11
397 
398 #define TLS_EXT_SIG_ALG 13
399 
400 #define TLS_EXT_ALPN 16
401 
402 #define TLS_EXT_SESSION_TICKET 35
403 
404 #define TLS_EXT_RENEGOTIATION_INFO 0xFF01
405 
406 /*
407  * TLS extension flags (for extensions with outgoing ServerHello content
408  * that need it (e.g. for RENEGOTIATION_INFO the server already knows because
409  * of state of the renegotiation flag, so no indicator is required)
410  */
411 #define TLS_EXT_SUPPORTED_POINT_FORMATS_PRESENT (1 << 0)
412 
413 /*
414  * Size defines
415  */
416 #if !defined(POLARSSL_PSK_MAX_LEN)
417 #define POLARSSL_PSK_MAX_LEN 32 /* 256 bits */
418 #endif
419 
420 /* Dummy type used only for its size */
422 {
423 #if defined(POLARSSL_KEY_EXCHANGE_RSA_ENABLED)
424  unsigned char _pms_rsa[48]; /* RFC 5246 8.1.1 */
425 #endif
426 #if defined(POLARSSL_KEY_EXCHANGE_DHE_RSA_ENABLED)
427  unsigned char _pms_dhm[POLARSSL_MPI_MAX_SIZE]; /* RFC 5246 8.1.2 */
428 #endif
429 #if defined(POLARSSL_KEY_EXCHANGE_ECDHE_RSA_ENABLED) || \
430  defined(POLARSSL_KEY_EXCHANGE_ECDHE_ECDSA_ENABLED) || \
431  defined(POLARSSL_KEY_EXCHANGE_ECDH_RSA_ENABLED) || \
432  defined(POLARSSL_KEY_EXCHANGE_ECDH_ECDSA_ENABLED)
433  unsigned char _pms_ecdh[POLARSSL_ECP_MAX_BYTES]; /* RFC 4492 5.10 */
434 #endif
435 #if defined(POLARSSL_KEY_EXCHANGE_PSK_ENABLED)
436  unsigned char _pms_psk[4 + 2 * POLARSSL_PSK_MAX_LEN]; /* RFC 4279 2 */
437 #endif
438 #if defined(POLARSSL_KEY_EXCHANGE_DHE_PSK_ENABLED)
439  unsigned char _pms_dhe_psk[4 + POLARSSL_MPI_MAX_SIZE
440  + POLARSSL_PSK_MAX_LEN]; /* RFC 4279 3 */
441 #endif
442 #if defined(POLARSSL_KEY_EXCHANGE_RSA_PSK_ENABLED)
443  unsigned char _pms_rsa_psk[52 + POLARSSL_PSK_MAX_LEN]; /* RFC 4279 4 */
444 #endif
445 #if defined(POLARSSL_KEY_EXCHANGE_DHE_PSK_ENABLED)
446  unsigned char _pms_ecdhe_psk[4 + POLARSSL_ECP_MAX_BYTES
447  + POLARSSL_PSK_MAX_LEN]; /* RFC 5489 2 */
448 #endif
449 };
450 
451 #define POLARSSL_PREMASTER_SIZE sizeof( union _ssl_premaster_secret )
452 
453 #ifdef __cplusplus
454 extern "C" {
455 #endif
456 
457 /*
458  * Generic function pointers for allowing external RSA private key
459  * implementations.
460  */
461 typedef int (*rsa_decrypt_func)( void *ctx, int mode, size_t *olen,
462  const unsigned char *input, unsigned char *output,
463  size_t output_max_len );
464 typedef int (*rsa_sign_func)( void *ctx,
465  int (*f_rng)(void *, unsigned char *, size_t), void *p_rng,
466  int mode, md_type_t md_alg, unsigned int hashlen,
467  const unsigned char *hash, unsigned char *sig );
468 typedef size_t (*rsa_key_len_func)( void *ctx );
469 
470 /*
471  * SSL state machine
472  */
473 typedef enum
474 {
493 }
494 ssl_states;
495 
496 typedef struct _ssl_session ssl_session;
497 typedef struct _ssl_context ssl_context;
500 #if defined(POLARSSL_SSL_SESSION_TICKETS)
502 #endif
503 #if defined(POLARSSL_X509_CRT_PARSE_C)
505 #endif
506 
507 /*
508  * This structure is used for storing current session data.
509  */
511 {
512 #if defined(POLARSSL_HAVE_TIME)
513  time_t start;
514 #endif
517  size_t length;
518  unsigned char id[32];
519  unsigned char master[48];
521 #if defined(POLARSSL_X509_CRT_PARSE_C)
523 #endif /* POLARSSL_X509_CRT_PARSE_C */
526 #if defined(POLARSSL_SSL_SESSION_TICKETS)
527  unsigned char *ticket;
528  size_t ticket_len;
529  uint32_t ticket_lifetime;
530 #endif /* POLARSSL_SSL_SESSION_TICKETS */
531 
532 #if defined(POLARSSL_SSL_MAX_FRAGMENT_LENGTH)
533  unsigned char mfl_code;
534 #endif /* POLARSSL_SSL_MAX_FRAGMENT_LENGTH */
535 
536 #if defined(POLARSSL_SSL_TRUNCATED_HMAC)
538 #endif /* POLARSSL_SSL_TRUNCATED_HMAC */
539 };
540 
541 /*
542  * This structure contains a full set of runtime transform parameters
543  * either in negotiation or active.
544  */
546 {
547  /*
548  * Session specific crypto layer
549  */
552  unsigned int keylen;
553  size_t minlen;
554  size_t ivlen;
555  size_t fixed_ivlen;
556  size_t maclen;
558  unsigned char iv_enc[16];
559  unsigned char iv_dec[16];
561 #if defined(POLARSSL_SSL_PROTO_SSL3)
562  /* Needed only for SSL v3.0 secret */
563  unsigned char mac_enc[48];
564  unsigned char mac_dec[48];
565 #endif /* POLARSSL_SSL_PROTO_SSL3 */
566 
573  /*
574  * Session specific compression layer
575  */
576 #if defined(POLARSSL_ZLIB_SUPPORT)
577  z_stream ctx_deflate;
578  z_stream ctx_inflate;
579 #endif
580 };
581 
582 /*
583  * This structure contains the parameters only needed during handshake.
584  */
586 {
587  /*
588  * Handshake specific crypto variables
589  */
590  int sig_alg;
591  int cert_type;
593 #if defined(POLARSSL_DHM_C)
595 #endif
596 #if defined(POLARSSL_ECDH_C)
598 #endif
599 #if defined(POLARSSL_ECDH_C) || defined(POLARSSL_ECDSA_C)
601 #endif
602 #if defined(POLARSSL_X509_CRT_PARSE_C)
603 
610 #if defined(POLARSSL_SSL_SERVER_NAME_INDICATION)
612 #endif
613 #endif /* POLARSSL_X509_CRT_PARSE_C */
614 
615  /*
616  * Checksum contexts
617  */
618 #if defined(POLARSSL_SSL_PROTO_SSL3) || defined(POLARSSL_SSL_PROTO_TLS1) || \
619  defined(POLARSSL_SSL_PROTO_TLS1_1)
622 #endif
623 #if defined(POLARSSL_SSL_PROTO_TLS1_2)
624 #if defined(POLARSSL_SHA256_C)
626 #endif
627 #if defined(POLARSSL_SHA512_C)
629 #endif
630 #endif /* POLARSSL_SSL_PROTO_TLS1_2 */
631 
632  void (*update_checksum)(ssl_context *, const unsigned char *, size_t);
633  void (*calc_verify)(ssl_context *, unsigned char *);
634  void (*calc_finished)(ssl_context *, unsigned char *, int);
635  int (*tls_prf)(const unsigned char *, size_t, const char *,
636  const unsigned char *, size_t,
637  unsigned char *, size_t);
638 
639  size_t pmslen;
641  unsigned char randbytes[64];
642  unsigned char premaster[POLARSSL_PREMASTER_SIZE];
645  int resume;
648  int cli_exts;
650 #if defined(POLARSSL_SSL_SESSION_TICKETS)
652 #endif /* POLARSSL_SSL_SESSION_TICKETS */
653 };
654 
655 #if defined(POLARSSL_SSL_SESSION_TICKETS)
656 /*
657  * Parameters needed to secure session tickets
658  */
660 {
661  unsigned char key_name[16];
664  unsigned char mac_key[16];
665 };
666 #endif /* POLARSSL_SSL_SESSION_TICKETS */
667 
668 #if defined(POLARSSL_X509_CRT_PARSE_C)
669 /*
670  * List of certificate + private key pairs
671  */
673 {
678 };
679 #endif /* POLARSSL_X509_CRT_PARSE_C */
680 
682 {
683  /*
684  * Miscellaneous
685  */
686  int state;
690  int major_ver;
691  int minor_ver;
698  /*
699  * Callbacks (RNG, debug, I/O, verification)
700  */
701  int (*f_rng)(void *, unsigned char *, size_t);
702  void (*f_dbg)(void *, int, const char *);
703  int (*f_recv)(void *, unsigned char *, size_t);
704  int (*f_send)(void *, const unsigned char *, size_t);
705  int (*f_get_cache)(void *, ssl_session *);
706  int (*f_set_cache)(void *, const ssl_session *);
707 
708  void *p_rng;
709  void *p_dbg;
710  void *p_recv;
711  void *p_send;
712  void *p_get_cache;
713  void *p_set_cache;
714  void *p_hw_data;
716 #if defined(POLARSSL_SSL_SERVER_NAME_INDICATION)
717  int (*f_sni)(void *, ssl_context *, const unsigned char *, size_t);
718  void *p_sni;
719 #endif
720 
721 #if defined(POLARSSL_X509_CRT_PARSE_C)
722  int (*f_vrfy)(void *, x509_crt *, int, int *);
723  void *p_vrfy;
724 #endif
725 
726 #if defined(POLARSSL_KEY_EXCHANGE__SOME__PSK_ENABLED)
727  int (*f_psk)(void *, ssl_context *, const unsigned char *, size_t);
728  void *p_psk;
729 #endif
730 
731  /*
732  * Session layer
733  */
742  /*
743  * Record layer transformations
744  */
750  /*
751  * Record layer (incoming data)
752  */
753  unsigned char *in_ctr;
754  unsigned char *in_hdr;
755  unsigned char *in_iv;
756  unsigned char *in_msg;
757  unsigned char *in_offt;
760  size_t in_msglen;
761  size_t in_left;
763  size_t in_hslen;
764  int nb_zero;
767  /*
768  * Record layer (outgoing data)
769  */
770  unsigned char *out_ctr;
771  unsigned char *out_hdr;
772  unsigned char *out_iv;
773  unsigned char *out_msg;
776  size_t out_msglen;
777  size_t out_left;
779 #if defined(POLARSSL_ZLIB_SUPPORT)
780  unsigned char *compress_buf;
781 #endif
782 #if defined(POLARSSL_SSL_MAX_FRAGMENT_LENGTH)
783  unsigned char mfl_code;
784 #endif /* POLARSSL_SSL_MAX_FRAGMENT_LENGTH */
785 
786  /*
787  * PKI layer
788  */
789 #if defined(POLARSSL_X509_CRT_PARSE_C)
794  const char *peer_cn;
795 #endif /* POLARSSL_X509_CRT_PARSE_C */
796 
797  /*
798  * Support for generating and checking session tickets
799  */
800 #if defined(POLARSSL_SSL_SESSION_TICKETS)
802 #endif /* POLARSSL_SSL_SESSION_TICKETS */
803 
804  /*
805  * User settings
806  */
807  int endpoint;
808  int authmode;
814  const int *ciphersuite_list[4];
815 #if defined(POLARSSL_SSL_SET_CURVES)
816  const ecp_group_id *curve_list;
817 #endif
818 #if defined(POLARSSL_SSL_TRUNCATED_HMAC)
820 #endif
821 #if defined(POLARSSL_SSL_SESSION_TICKETS)
824 #endif
825 
826 #if defined(POLARSSL_DHM_C)
829 #endif
830 
831 #if defined(POLARSSL_KEY_EXCHANGE__SOME__PSK_ENABLED)
832  /*
833  * PSK values
834  */
835  unsigned char *psk;
836  size_t psk_len;
837  unsigned char *psk_identity;
839 #endif
840 
841 #if defined(POLARSSL_SSL_SERVER_NAME_INDICATION)
842  /*
843  * SNI extension
844  */
845  unsigned char *hostname;
846  size_t hostname_len;
847 #endif
848 
849 #if defined(POLARSSL_SSL_ALPN)
850  /*
851  * ALPN extension
852  */
853  const char **alpn_list;
854  const char *alpn_chosen;
855 #endif
856 
857  /*
858  * Secure renegotiation
859  */
863  char own_verify_data[36];
864  char peer_verify_data[36];
865 };
866 
867 #if defined(POLARSSL_SSL_HW_RECORD_ACCEL)
868 
869 #define SSL_CHANNEL_OUTBOUND 0
870 #define SSL_CHANNEL_INBOUND 1
871 
872 extern int (*ssl_hw_record_init)(ssl_context *ssl,
873  const unsigned char *key_enc, const unsigned char *key_dec,
874  size_t keylen,
875  const unsigned char *iv_enc, const unsigned char *iv_dec,
876  size_t ivlen,
877  const unsigned char *mac_enc, const unsigned char *mac_dec,
878  size_t maclen);
879 extern int (*ssl_hw_record_activate)(ssl_context *ssl, int direction);
880 extern int (*ssl_hw_record_reset)(ssl_context *ssl);
881 extern int (*ssl_hw_record_write)(ssl_context *ssl);
882 extern int (*ssl_hw_record_read)(ssl_context *ssl);
883 extern int (*ssl_hw_record_finish)(ssl_context *ssl);
884 #endif /* POLARSSL_SSL_HW_RECORD_ACCEL */
885 
892 const int *ssl_list_ciphersuites( void );
893 
902 const char *ssl_get_ciphersuite_name( const int ciphersuite_id );
903 
912 int ssl_get_ciphersuite_id( const char *ciphersuite_name );
913 
923 int ssl_init( ssl_context *ssl );
924 
935 int ssl_session_reset( ssl_context *ssl );
936 
946 void ssl_set_endpoint( ssl_context *ssl, int endpoint );
947 
971 void ssl_set_authmode( ssl_context *ssl, int authmode );
972 
973 #if defined(POLARSSL_X509_CRT_PARSE_C)
974 
985 void ssl_set_verify( ssl_context *ssl,
986  int (*f_vrfy)(void *, x509_crt *, int, int *),
987  void *p_vrfy );
988 #endif /* POLARSSL_X509_CRT_PARSE_C */
989 
997 void ssl_set_rng( ssl_context *ssl,
998  int (*f_rng)(void *, unsigned char *, size_t),
999  void *p_rng );
1000 
1008 void ssl_set_dbg( ssl_context *ssl,
1009  void (*f_dbg)(void *, int, const char *),
1010  void *p_dbg );
1011 
1021 void ssl_set_bio( ssl_context *ssl,
1022  int (*f_recv)(void *, unsigned char *, size_t), void *p_recv,
1023  int (*f_send)(void *, const unsigned char *, size_t), void *p_send );
1024 
1063  int (*f_get_cache)(void *, ssl_session *), void *p_get_cache,
1064  int (*f_set_cache)(void *, const ssl_session *), void *p_set_cache );
1065 
1080 int ssl_set_session( ssl_context *ssl, const ssl_session *session );
1081 
1094 void ssl_set_ciphersuites( ssl_context *ssl, const int *ciphersuites );
1095 
1110  const int *ciphersuites,
1111  int major, int minor );
1112 
1113 #if defined(POLARSSL_X509_CRT_PARSE_C)
1114 
1122 void ssl_set_ca_chain( ssl_context *ssl, x509_crt *ca_chain,
1123  x509_crl *ca_crl, const char *peer_cn );
1124 
1143 int ssl_set_own_cert( ssl_context *ssl, x509_crt *own_cert,
1144  pk_context *pk_key );
1145 
1146 #if defined(POLARSSL_RSA_C)
1147 
1163 int ssl_set_own_cert_rsa( ssl_context *ssl, x509_crt *own_cert,
1164  rsa_context *rsa_key );
1165 #endif /* POLARSSL_RSA_C */
1166 
1192 int ssl_set_own_cert_alt( ssl_context *ssl, x509_crt *own_cert,
1193  void *rsa_key,
1194  rsa_decrypt_func rsa_decrypt,
1195  rsa_sign_func rsa_sign,
1196  rsa_key_len_func rsa_key_len );
1197 #endif /* POLARSSL_X509_CRT_PARSE_C */
1198 
1199 #if defined(POLARSSL_KEY_EXCHANGE__SOME__PSK_ENABLED)
1200 
1212 int ssl_set_psk( ssl_context *ssl, const unsigned char *psk, size_t psk_len,
1213  const unsigned char *psk_identity, size_t psk_identity_len );
1214 
1235 void ssl_set_psk_cb( ssl_context *ssl,
1236  int (*f_psk)(void *, ssl_context *, const unsigned char *,
1237  size_t),
1238  void *p_psk );
1239 #endif /* POLARSSL_KEY_EXCHANGE__SOME__PSK_ENABLED */
1240 
1241 #if defined(POLARSSL_DHM_C)
1242 
1253 int ssl_set_dh_param( ssl_context *ssl, const char *dhm_P, const char *dhm_G );
1254 
1264 int ssl_set_dh_param_ctx( ssl_context *ssl, dhm_context *dhm_ctx );
1265 #endif /* POLARSSL_DHM_C */
1266 
1267 #if defined(POLARSSL_SSL_SET_CURVES)
1268 
1286 void ssl_set_curves( ssl_context *ssl, const ecp_group_id *curves );
1287 #endif /* POLARSSL_SSL_SET_CURVES */
1288 
1289 #if defined(POLARSSL_SSL_SERVER_NAME_INDICATION)
1290 
1300 int ssl_set_hostname( ssl_context *ssl, const char *hostname );
1301 
1321 void ssl_set_sni( ssl_context *ssl,
1322  int (*f_sni)(void *, ssl_context *, const unsigned char *,
1323  size_t),
1324  void *p_sni );
1325 #endif /* POLARSSL_SSL_SERVER_NAME_INDICATION */
1326 
1327 #if defined(POLARSSL_SSL_ALPN)
1328 
1337 int ssl_set_alpn_protocols( ssl_context *ssl, const char **protos );
1338 
1348 const char *ssl_get_alpn_protocol( const ssl_context *ssl );
1349 #endif /* POLARSSL_SSL_ALPN */
1350 
1366 void ssl_set_max_version( ssl_context *ssl, int major, int minor );
1367 
1368 
1382 void ssl_set_min_version( ssl_context *ssl, int major, int minor );
1383 
1384 #if defined(POLARSSL_SSL_MAX_FRAGMENT_LENGTH)
1385 
1400 int ssl_set_max_frag_len( ssl_context *ssl, unsigned char mfl_code );
1401 #endif /* POLARSSL_SSL_MAX_FRAGMENT_LENGTH */
1402 
1403 #if defined(POLARSSL_SSL_TRUNCATED_HMAC)
1404 
1415 int ssl_set_truncated_hmac( ssl_context *ssl, int truncate );
1416 #endif /* POLARSSL_SSL_TRUNCATED_HMAC */
1417 
1418 #if defined(POLARSSL_SSL_SESSION_TICKETS)
1419 
1435 int ssl_set_session_tickets( ssl_context *ssl, int use_tickets );
1436 
1444 void ssl_set_session_ticket_lifetime( ssl_context *ssl, int lifetime );
1445 #endif /* POLARSSL_SSL_SESSION_TICKETS */
1446 
1460 void ssl_set_renegotiation( ssl_context *ssl, int renegotiation );
1461 
1489 void ssl_legacy_renegotiation( ssl_context *ssl, int allow_legacy );
1490 
1516 void ssl_set_renegotiation_enforced( ssl_context *ssl, int max_records );
1517 
1525 size_t ssl_get_bytes_avail( const ssl_context *ssl );
1526 
1538 int ssl_get_verify_result( const ssl_context *ssl );
1539 
1547 const char *ssl_get_ciphersuite( const ssl_context *ssl );
1548 
1556 const char *ssl_get_version( const ssl_context *ssl );
1557 
1558 #if defined(POLARSSL_X509_CRT_PARSE_C)
1559 
1573 const x509_crt *ssl_get_peer_cert( const ssl_context *ssl );
1574 #endif /* POLARSSL_X509_CRT_PARSE_C */
1575 
1592 int ssl_get_session( const ssl_context *ssl, ssl_session *session );
1593 
1602 int ssl_handshake( ssl_context *ssl );
1603 
1616 int ssl_handshake_step( ssl_context *ssl );
1617 
1628 int ssl_renegotiate( ssl_context *ssl );
1629 
1640 int ssl_read( ssl_context *ssl, unsigned char *buf, size_t len );
1641 
1656 int ssl_write( ssl_context *ssl, const unsigned char *buf, size_t len );
1657 
1669  unsigned char level,
1670  unsigned char message );
1676 int ssl_close_notify( ssl_context *ssl );
1677 
1683 void ssl_free( ssl_context *ssl );
1684 
1690 void ssl_session_init( ssl_session *session );
1691 
1698 void ssl_session_free( ssl_session *session );
1699 
1706 void ssl_transform_free( ssl_transform *transform );
1707 
1714 void ssl_handshake_free( ssl_handshake_params *handshake );
1715 
1716 /*
1717  * Internal functions (do not call directly)
1718  */
1721 void ssl_handshake_wrapup( ssl_context *ssl );
1722 
1724 
1725 int ssl_derive_keys( ssl_context *ssl );
1726 
1727 int ssl_read_record( ssl_context *ssl );
1732 int ssl_fetch_input( ssl_context *ssl, size_t nb_want );
1733 
1734 int ssl_write_record( ssl_context *ssl );
1735 int ssl_flush_output( ssl_context *ssl );
1736 
1739 
1742 
1743 int ssl_parse_finished( ssl_context *ssl );
1744 int ssl_write_finished( ssl_context *ssl );
1745 
1747  const ssl_ciphersuite_t *ciphersuite_info );
1748 
1749 #if defined(POLARSSL_KEY_EXCHANGE__SOME__PSK_ENABLED)
1751 #endif
1752 
1753 #if defined(POLARSSL_PK_C)
1754 unsigned char ssl_sig_from_pk( pk_context *pk );
1755 pk_type_t ssl_pk_alg_from_sig( unsigned char sig );
1756 #endif
1757 
1758 md_type_t ssl_md_alg_from_hash( unsigned char hash );
1759 
1760 #if defined(POLARSSL_SSL_SET_CURVES)
1761 int ssl_curve_is_acceptable( const ssl_context *ssl, ecp_group_id grp_id );
1762 #endif
1763 
1764 #if defined(POLARSSL_X509_CRT_PARSE_C)
1765 static inline pk_context *ssl_own_key( ssl_context *ssl )
1766 {
1767  return( ssl->handshake->key_cert == NULL ? NULL
1768  : ssl->handshake->key_cert->key );
1769 }
1770 
1771 static inline x509_crt *ssl_own_cert( ssl_context *ssl )
1772 {
1773  return( ssl->handshake->key_cert == NULL ? NULL
1774  : ssl->handshake->key_cert->cert );
1775 }
1776 
1777 /*
1778  * Check usage of a certificate wrt extensions:
1779  * keyUsage, extendedKeyUsage (later), and nSCertType (later).
1780  *
1781  * Warning: cert_endpoint is the endpoint of the cert (ie, of our peer when we
1782  * check a cert we received from them)!
1783  *
1784  * Return 0 if everything is OK, -1 if not.
1785  */
1786 int ssl_check_cert_usage( const x509_crt *cert,
1787  const ssl_ciphersuite_t *ciphersuite,
1788  int cert_endpoint );
1789 #endif /* POLARSSL_X509_CRT_PARSE_C */
1790 
1791 /* constant-time buffer comparison */
1792 static inline int safer_memcmp( const void *a, const void *b, size_t n )
1793 {
1794  size_t i;
1795  const unsigned char *A = (const unsigned char *) a;
1796  const unsigned char *B = (const unsigned char *) b;
1797  unsigned char diff = 0;
1798 
1799  for( i = 0; i < n; i++ )
1800  diff |= A[i] ^ B[i];
1801 
1802  return( diff );
1803 }
1804 
1805 #ifdef __cplusplus
1806 }
1807 #endif
1808 
1809 #endif /* ssl.h */