PolarSSL

polarssl/ssl.h

Go to the documentation of this file.
00001 
00025 #ifndef POLARSSL_SSL_H
00026 #define POLARSSL_SSL_H
00027 
00028 #include <time.h>
00029 
00030 #include "polarssl/net.h"
00031 #include "polarssl/dhm.h"
00032 #include "polarssl/rsa.h"
00033 #include "polarssl/md5.h"
00034 #include "polarssl/sha1.h"
00035 #include "polarssl/x509.h"
00036 
00037 /*
00038  * SSL Error codes
00039  */
00040 #define POLARSSL_ERR_SSL_FEATURE_UNAVAILABLE               -0x1000
00041 #define POLARSSL_ERR_SSL_BAD_INPUT_DATA                    -0x1800
00042 #define POLARSSL_ERR_SSL_INVALID_MAC                       -0x2000
00043 #define POLARSSL_ERR_SSL_INVALID_RECORD                    -0x2800
00044 #define POLARSSL_ERR_SSL_INVALID_MODULUS_SIZE              -0x3000
00045 #define POLARSSL_ERR_SSL_UNKNOWN_CIPHER                    -0x3800
00046 #define POLARSSL_ERR_SSL_NO_CIPHER_CHOSEN                  -0x4000
00047 #define POLARSSL_ERR_SSL_NO_SESSION_FOUND                  -0x4800
00048 #define POLARSSL_ERR_SSL_NO_CLIENT_CERTIFICATE             -0x5000
00049 #define POLARSSL_ERR_SSL_CERTIFICATE_TOO_LARGE             -0x5800
00050 #define POLARSSL_ERR_SSL_CERTIFICATE_REQUIRED              -0x6000
00051 #define POLARSSL_ERR_SSL_PRIVATE_KEY_REQUIRED              -0x6800
00052 #define POLARSSL_ERR_SSL_CA_CHAIN_REQUIRED                 -0x7000
00053 #define POLARSSL_ERR_SSL_UNEXPECTED_MESSAGE                -0x7800
00054 #define POLARSSL_ERR_SSL_FATAL_ALERT_MESSAGE               -0x8000
00055 #define POLARSSL_ERR_SSL_PEER_VERIFY_FAILED                -0x8800
00056 #define POLARSSL_ERR_SSL_PEER_CLOSE_NOTIFY                 -0x9000
00057 #define POLARSSL_ERR_SSL_BAD_HS_CLIENT_HELLO               -0x9800
00058 #define POLARSSL_ERR_SSL_BAD_HS_SERVER_HELLO               -0xA000
00059 #define POLARSSL_ERR_SSL_BAD_HS_CERTIFICATE                -0xA800
00060 #define POLARSSL_ERR_SSL_BAD_HS_CERTIFICATE_REQUEST        -0xB000
00061 #define POLARSSL_ERR_SSL_BAD_HS_SERVER_KEY_EXCHANGE        -0xB800
00062 #define POLARSSL_ERR_SSL_BAD_HS_SERVER_HELLO_DONE          -0xC000
00063 #define POLARSSL_ERR_SSL_BAD_HS_CLIENT_KEY_EXCHANGE        -0xC800
00064 #define POLARSSL_ERR_SSL_BAD_HS_CERTIFICATE_VERIFY         -0xD000
00065 #define POLARSSL_ERR_SSL_BAD_HS_CHANGE_CIPHER_SPEC         -0xD800
00066 #define POLARSSL_ERR_SSL_BAD_HS_FINISHED                   -0xE000
00067 
00068 /*
00069  * Various constants
00070  */
00071 #define SSL_MAJOR_VERSION_3             3
00072 #define SSL_MINOR_VERSION_0             0   
00073 #define SSL_MINOR_VERSION_1             1   
00074 #define SSL_MINOR_VERSION_2             2   
00076 #define SSL_IS_CLIENT                   0
00077 #define SSL_IS_SERVER                   1
00078 #define SSL_COMPRESS_NULL               0
00079 
00080 #define SSL_VERIFY_NONE                 0
00081 #define SSL_VERIFY_OPTIONAL             1
00082 #define SSL_VERIFY_REQUIRED             2
00083 
00084 #define SSL_MAX_CONTENT_LEN         16384
00085 
00086 /*
00087  * Allow an extra 512 bytes for the record header
00088  * and encryption overhead (counter + MAC + padding).
00089  */
00090 #define SSL_BUFFER_LEN (SSL_MAX_CONTENT_LEN + 512)
00091 
00092 /*
00093  * Supported ciphersuites
00094  */
00095 #define SSL_RSA_RC4_128_MD5          0x04
00096 #define SSL_RSA_RC4_128_SHA          0x05
00097 #define SSL_RSA_DES_168_SHA          0x0A
00098 #define SSL_EDH_RSA_DES_168_SHA      0x16
00099 #define SSL_RSA_AES_128_SHA          0x2F
00100 #define SSL_EDH_RSA_AES_128_SHA      0x33
00101 #define SSL_RSA_AES_256_SHA          0x35
00102 #define SSL_EDH_RSA_AES_256_SHA      0x39
00103 
00104 #define SSL_RSA_CAMELLIA_128_SHA     0x41
00105 #define SSL_EDH_RSA_CAMELLIA_128_SHA 0x45
00106 #define SSL_RSA_CAMELLIA_256_SHA     0x84
00107 #define SSL_EDH_RSA_CAMELLIA_256_SHA 0x88
00108 
00109 /*
00110  * Message, alert and handshake types
00111  */
00112 #define SSL_MSG_CHANGE_CIPHER_SPEC     20
00113 #define SSL_MSG_ALERT                  21
00114 #define SSL_MSG_HANDSHAKE              22
00115 #define SSL_MSG_APPLICATION_DATA       23
00116 
00117 #define SSL_ALERT_LEVEL_WARNING         1
00118 #define SSL_ALERT_LEVEL_FATAL           2
00119 
00120 #define SSL_ALERT_MSG_CLOSE_NOTIFY           0
00121 #define SSL_ALERT_MSG_UNEXPECTED_MESSAGE    10
00122 #define SSL_ALERT_MSG_BAD_RECORD_MAD        20
00123 #define SSL_ALERT_MSG_DECRYPTION_FAILED     21
00124 #define SSL_ALERT_MSG_RECORD_OVERFLOW       22
00125 #define SSL_ALERT_MSG_DECOMPRESSION_FAILURE 30
00126 #define SSL_ALERT_MSG_HANDSHAKE_FAILURE     40
00127 #define SSL_ALERT_MSG_NO_CERT               41
00128 #define SSL_ALERT_MSG_BAD_CERT              42
00129 #define SSL_ALERT_MSG_UNSUPPORTED_CERT      43
00130 #define SSL_ALERT_MSG_CERT_REVOKED          44
00131 #define SSL_ALERT_MSG_CERT_EXPIRED          45
00132 #define SSL_ALERT_MSG_CERT_UNKNOWN          46
00133 #define SSL_ALERT_MSG_ILLEGAL_PARAMETER     47
00134 #define SSL_ALERT_MSG_UNKNOWN_CA            48
00135 #define SSL_ALERT_MSG_ACCESS_DENIED         49
00136 #define SSL_ALERT_MSG_DECODE_ERROR          50
00137 #define SSL_ALERT_MSG_DECRYPT_ERROR         51
00138 #define SSL_ALERT_MSG_EXPORT_RESTRICTION    60
00139 #define SSL_ALERT_MSG_PROTOCOL_VERSION      70
00140 #define SSL_ALERT_MSG_INSUFFICIENT_SECURITY 71
00141 #define SSL_ALERT_MSG_INTERNAL_ERROR        80
00142 #define SSL_ALERT_MSG_USER_CANCELED         90
00143 #define SSL_ALERT_MSG_NO_RENEGOTIATION     100
00144 
00145 #define SSL_HS_HELLO_REQUEST            0
00146 #define SSL_HS_CLIENT_HELLO             1
00147 #define SSL_HS_SERVER_HELLO             2
00148 #define SSL_HS_CERTIFICATE             11
00149 #define SSL_HS_SERVER_KEY_EXCHANGE     12
00150 #define SSL_HS_CERTIFICATE_REQUEST     13
00151 #define SSL_HS_SERVER_HELLO_DONE       14
00152 #define SSL_HS_CERTIFICATE_VERIFY      15
00153 #define SSL_HS_CLIENT_KEY_EXCHANGE     16
00154 #define SSL_HS_FINISHED                20
00155 
00156 /*
00157  * TLS extensions
00158  */
00159 #define TLS_EXT_SERVERNAME              0
00160 #define TLS_EXT_SERVERNAME_HOSTNAME     0
00161 
00162 /*
00163  * SSL state machine
00164  */
00165 typedef enum
00166 {
00167     SSL_HELLO_REQUEST,
00168     SSL_CLIENT_HELLO,
00169     SSL_SERVER_HELLO,
00170     SSL_SERVER_CERTIFICATE,
00171     SSL_SERVER_KEY_EXCHANGE,
00172     SSL_CERTIFICATE_REQUEST,
00173     SSL_SERVER_HELLO_DONE,
00174     SSL_CLIENT_CERTIFICATE,
00175     SSL_CLIENT_KEY_EXCHANGE,
00176     SSL_CERTIFICATE_VERIFY,
00177     SSL_CLIENT_CHANGE_CIPHER_SPEC,
00178     SSL_CLIENT_FINISHED,
00179     SSL_SERVER_CHANGE_CIPHER_SPEC,
00180     SSL_SERVER_FINISHED,
00181     SSL_FLUSH_BUFFERS,
00182     SSL_HANDSHAKE_OVER
00183 }
00184 ssl_states;
00185 
00186 typedef struct _ssl_session ssl_session;
00187 typedef struct _ssl_context ssl_context;
00188 
00189 /*
00190  * This structure is used for session resuming.
00191  */
00192 struct _ssl_session
00193 {
00194     time_t start;               
00195     int cipher;                 
00196     int length;                 
00197     unsigned char id[32];       
00198     unsigned char master[48];   
00199     ssl_session *next;          
00200 };
00201 
00202 struct _ssl_context
00203 {
00204     /*
00205      * Miscellaneous
00206      */
00207     int state;                  
00209     int major_ver;              
00210     int minor_ver;              
00212     int max_major_ver;          
00213     int max_minor_ver;          
00215     /*
00216      * Callbacks (RNG, debug, I/O)
00217      */
00218     int  (*f_rng)(void *);
00219     void (*f_dbg)(void *, int, const char *);
00220     int (*f_recv)(void *, unsigned char *, int);
00221     int (*f_send)(void *, unsigned char *, int);
00222 
00223     void *p_rng;                
00224     void *p_dbg;                
00225     void *p_recv;               
00226     void *p_send;               
00228     /*
00229      * Session layer
00230      */
00231     int resume;                         
00232     int timeout;                        
00233     ssl_session *session;               
00234     int (*s_get)(ssl_context *);        
00235     int (*s_set)(ssl_context *);        
00237     /*
00238      * Record layer (incoming data)
00239      */
00240     unsigned char *in_ctr;      
00241     unsigned char *in_hdr;      
00242     unsigned char *in_msg;      
00243     unsigned char *in_offt;     
00245     int in_msgtype;             
00246     int in_msglen;              
00247     int in_left;                
00249     int in_hslen;               
00250     int nb_zero;                
00252     /*
00253      * Record layer (outgoing data)
00254      */
00255     unsigned char *out_ctr;     
00256     unsigned char *out_hdr;     
00257     unsigned char *out_msg;     
00259     int out_msgtype;            
00260     int out_msglen;             
00261     int out_left;               
00263     /*
00264      * PKI layer
00265      */
00266     rsa_context *rsa_key;               
00267     x509_cert *own_cert;                
00268     x509_cert *ca_chain;                
00269     x509_crl *ca_crl;                   
00270     x509_cert *peer_cert;               
00271     const char *peer_cn;                
00273     int endpoint;                       
00274     int authmode;                       
00275     int client_auth;                    
00276     int verify_result;                  
00278     /*
00279      * Crypto layer
00280      */
00281     dhm_context dhm_ctx;                
00282     md5_context fin_md5;                
00283     sha1_context fin_sha1;              
00285     int do_crypt;                       
00286     int *ciphers;                       
00287     int pmslen;                         
00288     int keylen;                         
00289     int minlen;                         
00290     int ivlen;                          
00291     int maclen;                         
00293     unsigned char randbytes[64];        
00294     unsigned char premaster[256];       
00296     unsigned char iv_enc[16];           
00297     unsigned char iv_dec[16];           
00299     unsigned char mac_enc[32];          
00300     unsigned char mac_dec[32];          
00302     unsigned long ctx_enc[128];         
00303     unsigned long ctx_dec[128];         
00305     /*
00306      * TLS extensions
00307      */
00308     unsigned char *hostname;
00309     unsigned long  hostname_len;
00310 };
00311 
00312 #ifdef __cplusplus
00313 extern "C" {
00314 #endif
00315 
00316 extern int ssl_default_ciphers[];
00317 
00325 int ssl_init( ssl_context *ssl );
00326 
00333 void ssl_set_endpoint( ssl_context *ssl, int endpoint );
00334 
00352 void ssl_set_authmode( ssl_context *ssl, int authmode );
00353 
00361 void ssl_set_rng( ssl_context *ssl,
00362                   int (*f_rng)(void *),
00363                   void *p_rng );
00364 
00372 void ssl_set_dbg( ssl_context *ssl,
00373                   void (*f_dbg)(void *, int, const char *),
00374                   void  *p_dbg );
00375 
00385 void ssl_set_bio( ssl_context *ssl,
00386         int (*f_recv)(void *, unsigned char *, int), void *p_recv,
00387         int (*f_send)(void *, unsigned char *, int), void *p_send );
00388 
00396 void ssl_set_scb( ssl_context *ssl,
00397                   int (*s_get)(ssl_context *),
00398                   int (*s_set)(ssl_context *) );
00399 
00408 void ssl_set_session( ssl_context *ssl, int resume, int timeout,
00409                       ssl_session *session );
00410 
00417 void ssl_set_ciphers( ssl_context *ssl, int *ciphers );
00418 
00429 void ssl_set_ca_chain( ssl_context *ssl, x509_cert *ca_chain,
00430                        x509_crl *ca_crl, const char *peer_cn );
00431 
00439 void ssl_set_own_cert( ssl_context *ssl, x509_cert *own_cert,
00440                        rsa_context *rsa_key );
00441 
00452 int ssl_set_dh_param( ssl_context *ssl, const char *dhm_P, const char *dhm_G );
00453 
00463 int ssl_set_hostname( ssl_context *ssl, const char *hostname );
00464 
00472 int ssl_get_bytes_avail( const ssl_context *ssl );
00473 
00485 int ssl_get_verify_result( const ssl_context *ssl );
00486 
00494 const char *ssl_get_cipher( const ssl_context *ssl );
00495 
00504 int ssl_handshake( ssl_context *ssl );
00505 
00516 int ssl_read( ssl_context *ssl, unsigned char *buf, int len );
00517 
00532 int ssl_write( ssl_context *ssl, const unsigned char *buf, int len );
00533 
00539 int ssl_close_notify( ssl_context *ssl );
00540 
00546 void ssl_free( ssl_context *ssl );
00547 
00548 /*
00549  * Internal functions (do not call directly)
00550  */
00551 int ssl_handshake_client( ssl_context *ssl );
00552 int ssl_handshake_server( ssl_context *ssl );
00553 
00554 int ssl_derive_keys( ssl_context *ssl );
00555 void ssl_calc_verify( ssl_context *ssl, unsigned char hash[36] );
00556 
00557 int ssl_read_record( ssl_context *ssl );
00558 int ssl_fetch_input( ssl_context *ssl, int nb_want );
00559 
00560 int ssl_write_record( ssl_context *ssl );
00561 int ssl_flush_output( ssl_context *ssl );
00562 
00563 int ssl_parse_certificate( ssl_context *ssl );
00564 int ssl_write_certificate( ssl_context *ssl );
00565 
00566 int ssl_parse_change_cipher_spec( ssl_context *ssl );
00567 int ssl_write_change_cipher_spec( ssl_context *ssl );
00568 
00569 int ssl_parse_finished( ssl_context *ssl );
00570 int ssl_write_finished( ssl_context *ssl );
00571 
00572 #ifdef __cplusplus
00573 }
00574 #endif
00575 
00576 #endif /* ssl.h */
 All Classes Files Functions Variables Defines