PolarSSL v1.1.4
ssl.h
Go to the documentation of this file.
00001 
00027 #ifndef POLARSSL_SSL_H
00028 #define POLARSSL_SSL_H
00029 
00030 #include <time.h>
00031 
00032 #include "net.h"
00033 #include "dhm.h"
00034 #include "rsa.h"
00035 #include "md5.h"
00036 #include "sha1.h"
00037 #include "x509.h"
00038 #include "config.h"
00039 
00040 #if defined(POLARSSL_PKCS11_C)
00041 #include "pkcs11.h"
00042 #endif
00043 
00044 #if defined(_MSC_VER) && !defined(inline)
00045 #define inline _inline
00046 #else
00047 #if defined(__ARMCC_VERSION) && !defined(inline)
00048 #define inline __inline
00049 #endif /* __ARMCC_VERSION */
00050 #endif /*_MSC_VER */
00051 
00052 /*
00053  * SSL Error codes
00054  */
00055 #define POLARSSL_ERR_SSL_FEATURE_UNAVAILABLE               -0x7080  
00056 #define POLARSSL_ERR_SSL_BAD_INPUT_DATA                    -0x7100  
00057 #define POLARSSL_ERR_SSL_INVALID_MAC                       -0x7180  
00058 #define POLARSSL_ERR_SSL_INVALID_RECORD                    -0x7200  
00059 #define POLARSSL_ERR_SSL_CONN_EOF                          -0x7280  
00060 #define POLARSSL_ERR_SSL_UNKNOWN_CIPHER                    -0x7300  
00061 #define POLARSSL_ERR_SSL_NO_CIPHER_CHOSEN                  -0x7380  
00062 #define POLARSSL_ERR_SSL_NO_SESSION_FOUND                  -0x7400  
00063 #define POLARSSL_ERR_SSL_NO_CLIENT_CERTIFICATE             -0x7480  
00064 #define POLARSSL_ERR_SSL_CERTIFICATE_TOO_LARGE             -0x7500  
00065 #define POLARSSL_ERR_SSL_CERTIFICATE_REQUIRED              -0x7580  
00066 #define POLARSSL_ERR_SSL_PRIVATE_KEY_REQUIRED              -0x7600  
00067 #define POLARSSL_ERR_SSL_CA_CHAIN_REQUIRED                 -0x7680  
00068 #define POLARSSL_ERR_SSL_UNEXPECTED_MESSAGE                -0x7700  
00069 #define POLARSSL_ERR_SSL_FATAL_ALERT_MESSAGE               -0x7780  
00070 #define POLARSSL_ERR_SSL_PEER_VERIFY_FAILED                -0x7800  
00071 #define POLARSSL_ERR_SSL_PEER_CLOSE_NOTIFY                 -0x7880  
00072 #define POLARSSL_ERR_SSL_BAD_HS_CLIENT_HELLO               -0x7900  
00073 #define POLARSSL_ERR_SSL_BAD_HS_SERVER_HELLO               -0x7980  
00074 #define POLARSSL_ERR_SSL_BAD_HS_CERTIFICATE                -0x7A00  
00075 #define POLARSSL_ERR_SSL_BAD_HS_CERTIFICATE_REQUEST        -0x7A80  
00076 #define POLARSSL_ERR_SSL_BAD_HS_SERVER_KEY_EXCHANGE        -0x7B00  
00077 #define POLARSSL_ERR_SSL_BAD_HS_SERVER_HELLO_DONE          -0x7B80  
00078 #define POLARSSL_ERR_SSL_BAD_HS_CLIENT_KEY_EXCHANGE        -0x7C00  
00079 #define POLARSSL_ERR_SSL_BAD_HS_CLIENT_KEY_EXCHANGE_DHM_RP -0x7C80  
00080 #define POLARSSL_ERR_SSL_BAD_HS_CLIENT_KEY_EXCHANGE_DHM_CS -0x7D00  
00081 #define POLARSSL_ERR_SSL_BAD_HS_CERTIFICATE_VERIFY         -0x7D80  
00082 #define POLARSSL_ERR_SSL_BAD_HS_CHANGE_CIPHER_SPEC         -0x7E00  
00083 #define POLARSSL_ERR_SSL_BAD_HS_FINISHED                   -0x7E80  
00084 #define POLARSSL_ERR_SSL_MALLOC_FAILED                     -0x7F00  
00086 /*
00087  * Various constants
00088  */
00089 #define SSL_MAJOR_VERSION_3             3
00090 #define SSL_MINOR_VERSION_0             0   
00091 #define SSL_MINOR_VERSION_1             1   
00092 #define SSL_MINOR_VERSION_2             2   
00094 #define SSL_IS_CLIENT                   0
00095 #define SSL_IS_SERVER                   1
00096 #define SSL_COMPRESS_NULL               0
00097 
00098 #define SSL_VERIFY_NONE                 0
00099 #define SSL_VERIFY_OPTIONAL             1
00100 #define SSL_VERIFY_REQUIRED             2
00101 
00102 #define SSL_MAX_CONTENT_LEN         16384
00103 
00104 /*
00105  * Allow an extra 512 bytes for the record header
00106  * and encryption overhead (counter + MAC + padding).
00107  */
00108 #define SSL_BUFFER_LEN (SSL_MAX_CONTENT_LEN + 512)
00109 
00110 /*
00111  * Supported ciphersuites
00112  */
00113 #define SSL_RSA_RC4_128_MD5          0x04
00114 #define SSL_RSA_RC4_128_SHA          0x05
00115 #define SSL_RSA_DES_168_SHA          0x0A
00116 #define SSL_EDH_RSA_DES_168_SHA      0x16
00117 #define SSL_RSA_AES_128_SHA          0x2F
00118 #define SSL_EDH_RSA_AES_128_SHA      0x33
00119 #define SSL_RSA_AES_256_SHA          0x35
00120 #define SSL_EDH_RSA_AES_256_SHA      0x39
00121 
00122 #define SSL_RSA_CAMELLIA_128_SHA     0x41
00123 #define SSL_EDH_RSA_CAMELLIA_128_SHA 0x45
00124 #define SSL_RSA_CAMELLIA_256_SHA     0x84
00125 #define SSL_EDH_RSA_CAMELLIA_256_SHA 0x88
00126 
00127 /*
00128  * Message, alert and handshake types
00129  */
00130 #define SSL_MSG_CHANGE_CIPHER_SPEC     20
00131 #define SSL_MSG_ALERT                  21
00132 #define SSL_MSG_HANDSHAKE              22
00133 #define SSL_MSG_APPLICATION_DATA       23
00134 
00135 #define SSL_ALERT_LEVEL_WARNING         1
00136 #define SSL_ALERT_LEVEL_FATAL           2
00137 
00138 #define SSL_ALERT_MSG_CLOSE_NOTIFY           0
00139 #define SSL_ALERT_MSG_UNEXPECTED_MESSAGE    10
00140 #define SSL_ALERT_MSG_BAD_RECORD_MAC        20
00141 #define SSL_ALERT_MSG_DECRYPTION_FAILED     21
00142 #define SSL_ALERT_MSG_RECORD_OVERFLOW       22
00143 #define SSL_ALERT_MSG_DECOMPRESSION_FAILURE 30
00144 #define SSL_ALERT_MSG_HANDSHAKE_FAILURE     40
00145 #define SSL_ALERT_MSG_NO_CERT               41
00146 #define SSL_ALERT_MSG_BAD_CERT              42
00147 #define SSL_ALERT_MSG_UNSUPPORTED_CERT      43
00148 #define SSL_ALERT_MSG_CERT_REVOKED          44
00149 #define SSL_ALERT_MSG_CERT_EXPIRED          45
00150 #define SSL_ALERT_MSG_CERT_UNKNOWN          46
00151 #define SSL_ALERT_MSG_ILLEGAL_PARAMETER     47
00152 #define SSL_ALERT_MSG_UNKNOWN_CA            48
00153 #define SSL_ALERT_MSG_ACCESS_DENIED         49
00154 #define SSL_ALERT_MSG_DECODE_ERROR          50
00155 #define SSL_ALERT_MSG_DECRYPT_ERROR         51
00156 #define SSL_ALERT_MSG_EXPORT_RESTRICTION    60
00157 #define SSL_ALERT_MSG_PROTOCOL_VERSION      70
00158 #define SSL_ALERT_MSG_INSUFFICIENT_SECURITY 71
00159 #define SSL_ALERT_MSG_INTERNAL_ERROR        80
00160 #define SSL_ALERT_MSG_USER_CANCELED         90
00161 #define SSL_ALERT_MSG_NO_RENEGOTIATION     100
00162 
00163 #define SSL_HS_HELLO_REQUEST            0
00164 #define SSL_HS_CLIENT_HELLO             1
00165 #define SSL_HS_SERVER_HELLO             2
00166 #define SSL_HS_CERTIFICATE             11
00167 #define SSL_HS_SERVER_KEY_EXCHANGE     12
00168 #define SSL_HS_CERTIFICATE_REQUEST     13
00169 #define SSL_HS_SERVER_HELLO_DONE       14
00170 #define SSL_HS_CERTIFICATE_VERIFY      15
00171 #define SSL_HS_CLIENT_KEY_EXCHANGE     16
00172 #define SSL_HS_FINISHED                20
00173 
00174 /*
00175  * TLS extensions
00176  */
00177 #define TLS_EXT_SERVERNAME              0
00178 #define TLS_EXT_SERVERNAME_HOSTNAME     0
00179 
00180 /*
00181  * SSL state machine
00182  */
00183 typedef enum
00184 {
00185     SSL_HELLO_REQUEST,
00186     SSL_CLIENT_HELLO,
00187     SSL_SERVER_HELLO,
00188     SSL_SERVER_CERTIFICATE,
00189     SSL_SERVER_KEY_EXCHANGE,
00190     SSL_CERTIFICATE_REQUEST,
00191     SSL_SERVER_HELLO_DONE,
00192     SSL_CLIENT_CERTIFICATE,
00193     SSL_CLIENT_KEY_EXCHANGE,
00194     SSL_CERTIFICATE_VERIFY,
00195     SSL_CLIENT_CHANGE_CIPHER_SPEC,
00196     SSL_CLIENT_FINISHED,
00197     SSL_SERVER_CHANGE_CIPHER_SPEC,
00198     SSL_SERVER_FINISHED,
00199     SSL_FLUSH_BUFFERS,
00200     SSL_HANDSHAKE_OVER
00201 }
00202 ssl_states;
00203 
00204 typedef struct _ssl_session ssl_session;
00205 typedef struct _ssl_context ssl_context;
00206 
00207 /*
00208  * This structure is used for session resuming.
00209  */
00210 struct _ssl_session
00211 {
00212     time_t start;               
00213     int ciphersuite;            
00214     size_t length;              
00215     unsigned char id[32];       
00216     unsigned char master[48];   
00217     ssl_session *next;          
00218 };
00219 
00220 struct _ssl_context
00221 {
00222     /*
00223      * Miscellaneous
00224      */
00225     int state;                  
00227     int major_ver;              
00228     int minor_ver;              
00230     int max_major_ver;          
00231     int max_minor_ver;          
00233     /*
00234      * Callbacks (RNG, debug, I/O, verification)
00235      */
00236     int  (*f_rng)(void *, unsigned char *, size_t);
00237     void (*f_dbg)(void *, int, const char *);
00238     int (*f_recv)(void *, unsigned char *, size_t);
00239     int (*f_send)(void *, const unsigned char *, size_t);
00240     int (*f_vrfy)(void *, x509_cert *, int, int);
00241 
00242     void *p_rng;                
00243     void *p_dbg;                
00244     void *p_recv;               
00245     void *p_send;               
00246     void *p_vrfy;               
00248     /*
00249      * Session layer
00250      */
00251     int resume;                         
00252     int timeout;                        
00253     ssl_session *session;               
00254     int (*s_get)(ssl_context *);        
00255     int (*s_set)(ssl_context *);        
00257     /*
00258      * Record layer (incoming data)
00259      */
00260     unsigned char *in_ctr;      
00261     unsigned char *in_hdr;      
00262     unsigned char *in_msg;      
00263     unsigned char *in_offt;     
00265     int in_msgtype;             
00266     size_t in_msglen;           
00267     size_t in_left;             
00269     size_t in_hslen;            
00270     int nb_zero;                
00272     /*
00273      * Record layer (outgoing data)
00274      */
00275     unsigned char *out_ctr;     
00276     unsigned char *out_hdr;     
00277     unsigned char *out_msg;     
00279     int out_msgtype;            
00280     size_t out_msglen;          
00281     size_t out_left;            
00283     /*
00284      * PKI layer
00285      */
00286     rsa_context *rsa_key;               
00287 #if defined(POLARSSL_PKCS11_C)
00288     pkcs11_context *pkcs11_key;         
00289 #endif
00290     x509_cert *own_cert;                
00291     x509_cert *ca_chain;                
00292     x509_crl *ca_crl;                   
00293     x509_cert *peer_cert;               
00294     const char *peer_cn;                
00296     int endpoint;                       
00297     int authmode;                       
00298     int client_auth;                    
00299     int verify_result;                  
00301     /*
00302      * Crypto layer
00303      */
00304     dhm_context dhm_ctx;                
00305     md5_context fin_md5;                
00306     sha1_context fin_sha1;              
00308     int do_crypt;                       
00309     int *ciphersuites;                  
00310     size_t pmslen;                      
00311     unsigned int keylen;                
00312     size_t minlen;                      
00313     size_t ivlen;                       
00314     size_t maclen;                      
00316     unsigned char randbytes[64];        
00317     unsigned char premaster[256];       
00319     unsigned char iv_enc[16];           
00320     unsigned char iv_dec[16];           
00322     unsigned char mac_enc[32];          
00323     unsigned char mac_dec[32];          
00325     unsigned long ctx_enc[128];         
00326     unsigned long ctx_dec[128];         
00328     /*
00329      * TLS extensions
00330      */
00331     unsigned char *hostname;
00332     size_t         hostname_len;
00333 };
00334 
00335 #ifdef __cplusplus
00336 extern "C" {
00337 #endif
00338 
00339 extern int ssl_default_ciphersuites[];
00340 
00347 static inline const int *ssl_list_ciphersuites( void )
00348 {
00349     return ssl_default_ciphersuites;
00350 }
00351 
00360 const char *ssl_get_ciphersuite_name( const int ciphersuite_id );
00361 
00370 int ssl_get_ciphersuite_id( const char *ciphersuite_name );
00371 
00380 int ssl_init( ssl_context *ssl );
00381 
00389 void ssl_session_reset( ssl_context *ssl );
00390 
00397 void ssl_set_endpoint( ssl_context *ssl, int endpoint );
00398 
00416 void ssl_set_authmode( ssl_context *ssl, int authmode );
00417 
00431 void ssl_set_verify( ssl_context *ssl,
00432                      int (*f_vrfy)(void *, x509_cert *, int, int),
00433                      void *p_vrfy );
00434 
00442 void ssl_set_rng( ssl_context *ssl,
00443                   int (*f_rng)(void *, unsigned char *, size_t),
00444                   void *p_rng );
00445 
00453 void ssl_set_dbg( ssl_context *ssl,
00454                   void (*f_dbg)(void *, int, const char *),
00455                   void  *p_dbg );
00456 
00466 void ssl_set_bio( ssl_context *ssl,
00467         int (*f_recv)(void *, unsigned char *, size_t), void *p_recv,
00468         int (*f_send)(void *, const unsigned char *, size_t), void *p_send );
00469 
00477 void ssl_set_scb( ssl_context *ssl,
00478                   int (*s_get)(ssl_context *),
00479                   int (*s_set)(ssl_context *) );
00480 
00489 void ssl_set_session( ssl_context *ssl, int resume, int timeout,
00490                       ssl_session *session );
00491 
00498 void ssl_set_ciphersuites( ssl_context *ssl, int *ciphersuites );
00499 
00510 void ssl_set_ca_chain( ssl_context *ssl, x509_cert *ca_chain,
00511                        x509_crl *ca_crl, const char *peer_cn );
00512 
00520 void ssl_set_own_cert( ssl_context *ssl, x509_cert *own_cert,
00521                        rsa_context *rsa_key );
00522 
00523 #if defined(POLARSSL_PKCS11_C)
00524 
00531 void ssl_set_own_cert_pkcs11( ssl_context *ssl, x509_cert *own_cert,
00532                        pkcs11_context *pkcs11_key );
00533 #endif
00534 
00545 int ssl_set_dh_param( ssl_context *ssl, const char *dhm_P, const char *dhm_G );
00546 
00556 int ssl_set_dh_param_ctx( ssl_context *ssl, dhm_context *dhm_ctx );
00557 
00567 int ssl_set_hostname( ssl_context *ssl, const char *hostname );
00568 
00577 void ssl_set_max_version( ssl_context *ssl, int major, int minor );
00578 
00586 size_t ssl_get_bytes_avail( const ssl_context *ssl );
00587 
00599 int ssl_get_verify_result( const ssl_context *ssl );
00600 
00608 const char *ssl_get_ciphersuite( const ssl_context *ssl );
00609 
00617 const char *ssl_get_version( const ssl_context *ssl );
00618 
00627 int ssl_handshake( ssl_context *ssl );
00628 
00639 int ssl_read( ssl_context *ssl, unsigned char *buf, size_t len );
00640 
00655 int ssl_write( ssl_context *ssl, const unsigned char *buf, size_t len );
00656 
00662 int ssl_close_notify( ssl_context *ssl );
00663 
00669 void ssl_free( ssl_context *ssl );
00670 
00671 /*
00672  * Internal functions (do not call directly)
00673  */
00674 int ssl_handshake_client( ssl_context *ssl );
00675 int ssl_handshake_server( ssl_context *ssl );
00676 
00677 int ssl_derive_keys( ssl_context *ssl );
00678 void ssl_calc_verify( ssl_context *ssl, unsigned char hash[36] );
00679 
00680 int ssl_read_record( ssl_context *ssl );
00685 int ssl_fetch_input( ssl_context *ssl, size_t nb_want );
00686 
00687 int ssl_write_record( ssl_context *ssl );
00688 int ssl_flush_output( ssl_context *ssl );
00689 
00690 int ssl_parse_certificate( ssl_context *ssl );
00691 int ssl_write_certificate( ssl_context *ssl );
00692 
00693 int ssl_parse_change_cipher_spec( ssl_context *ssl );
00694 int ssl_write_change_cipher_spec( ssl_context *ssl );
00695 
00696 int ssl_parse_finished( ssl_context *ssl );
00697 int ssl_write_finished( ssl_context *ssl );
00698 
00699 #ifdef __cplusplus
00700 }
00701 #endif
00702 
00703 #endif /* ssl.h */