include/tropicssl/ssl.h

   1 /**
   2  * \file ssl.h
   3  *
   4  *  Based on XySSL: Copyright (C) 2006-2008  Christophe Devine
   5  *
   6  *  Copyright (C) 2009  Paul Bakker <polarssl_maintainer at polarssl dot org>
   7  *
   8  *  All rights reserved.
   9  *
  10  *  Redistribution and use in source and binary forms, with or without
  11  *  modification, are permitted provided that the following conditions
  12  *  are met:
  13  *
  14  *    * Redistributions of source code must retain the above copyright
  15  *      notice, this list of conditions and the following disclaimer.
  16  *    * Redistributions in binary form must reproduce the above copyright
  17  *      notice, this list of conditions and the following disclaimer in the
  18  *      documentation and/or other materials provided with the distribution.
  19  *    * Neither the names of PolarSSL or XySSL nor the names of its contributors
  20  *      may be used to endorse or promote products derived from this software
  21  *      without specific prior written permission.
  22  *
  23  *  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  24  *  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  25  *  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
  26  *  FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  27  *  OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  28  *  SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
  29  *  TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
  30  *  PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
  31  *  LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
  32  *  NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
  33  *  SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  34  */
  35 #ifndef TROPICSSL_SSL_H
  36 #define TROPICSSL_SSL_H
  37
  38 #include <time.h>
  39
  40 #include "tropicssl/net.h"
  41 #include "tropicssl/dhm.h"
  42 #include "tropicssl/rsa.h"
  43 #include "tropicssl/md5.h"
  44 #include "tropicssl/sha1.h"
  45 #include "tropicssl/x509.h"
  46
  47 #define TROPICSSL_ERR_SSL_FEATURE_UNAVAILABLE               -0x1000
  48 #define TROPICSSL_ERR_SSL_BAD_INPUT_DATA                    -0x1800
  49 #define TROPICSSL_ERR_SSL_INVALID_MAC                       -0x2000
  50 #define TROPICSSL_ERR_SSL_INVALID_RECORD                    -0x2800
  51 #define TROPICSSL_ERR_SSL_INVALID_MODULUS_SIZE              -0x3000
  52 #define TROPICSSL_ERR_SSL_UNKNOWN_CIPHER                    -0x3800
  53 #define TROPICSSL_ERR_SSL_NO_CIPHER_CHOSEN                  -0x4000
  54 #define TROPICSSL_ERR_SSL_NO_SESSION_FOUND                  -0x4800
  55 #define TROPICSSL_ERR_SSL_NO_CLIENT_CERTIFICATE             -0x5000
  56 #define TROPICSSL_ERR_SSL_CERTIFICATE_TOO_LARGE             -0x5800
  57 #define TROPICSSL_ERR_SSL_CERTIFICATE_REQUIRED              -0x6000
  58 #define TROPICSSL_ERR_SSL_PRIVATE_KEY_REQUIRED              -0x6800
  59 #define TROPICSSL_ERR_SSL_CA_CHAIN_REQUIRED                 -0x7000
  60 #define TROPICSSL_ERR_SSL_UNEXPECTED_MESSAGE                -0x7800
  61 #define TROPICSSL_ERR_SSL_FATAL_ALERT_MESSAGE               -0x8000
  62 #define TROPICSSL_ERR_SSL_PEER_VERIFY_FAILED                -0x8800
  63 #define TROPICSSL_ERR_SSL_PEER_CLOSE_NOTIFY                 -0x9000
  64 #define TROPICSSL_ERR_SSL_BAD_HS_CLIENT_HELLO               -0x9800
  65 #define TROPICSSL_ERR_SSL_BAD_HS_SERVER_HELLO               -0xA000
  66 #define TROPICSSL_ERR_SSL_BAD_HS_CERTIFICATE                -0xA800
  67 #define TROPICSSL_ERR_SSL_BAD_HS_CERTIFICATE_REQUEST        -0xB000
  68 #define TROPICSSL_ERR_SSL_BAD_HS_SERVER_KEY_EXCHANGE        -0xB800
  69 #define TROPICSSL_ERR_SSL_BAD_HS_SERVER_HELLO_DONE          -0xC000
  70 #define TROPICSSL_ERR_SSL_BAD_HS_CLIENT_KEY_EXCHANGE        -0xC800
  71 #define TROPICSSL_ERR_SSL_BAD_HS_CERTIFICATE_VERIFY         -0xD000
  72 #define TROPICSSL_ERR_SSL_BAD_HS_CHANGE_CIPHER_SPEC         -0xD800
  73 #define TROPICSSL_ERR_SSL_BAD_HS_FINISHED                   -0xE000
  74
  75 /*
  76  * Various constants
  77  */
  78 #define SSL_MAJOR_VERSION_3             3
  79 #define SSL_MINOR_VERSION_0             0       /*!< SSL v3.0 */
  80 #define SSL_MINOR_VERSION_1             1       /*!< TLS v1.0 */
  81 #define SSL_MINOR_VERSION_2             2       /*!< TLS v1.1 */
  82
  83 #define SSL_IS_CLIENT                   0
  84 #define SSL_IS_SERVER                   1
  85 #define SSL_COMPRESS_NULL               0
  86
  87 #define SSL_VERIFY_NONE                 0
  88 #define SSL_VERIFY_OPTIONAL             1
  89 #define SSL_VERIFY_REQUIRED             2
  90
  91 #define SSL_MAX_CONTENT_LEN         16384
  92
  93 /*
  94  * Allow an extra 512 bytes for the record header
  95  * and encryption overhead (counter + MAC + padding).
  96  */
  97 #define SSL_BUFFER_LEN (SSL_MAX_CONTENT_LEN + 512)
  98
  99 /*
 100  * Supported ciphersuites
 101  */
 102 #define SSL_RSA_RC4_128_MD5              4
 103 #define SSL_RSA_RC4_128_SHA              5
 104 #define SSL_RSA_DES_168_SHA             10
 105 #define SSL_EDH_RSA_DES_168_SHA         22
 106 #define SSL_RSA_AES_128_SHA             47
 107 #define SSL_RSA_AES_256_SHA             53
 108 #define SSL_EDH_RSA_AES_256_SHA         57
 109
 110 #define SSL_RSA_CAMELLIA_128_SHA        0x41
 111 #define SSL_RSA_CAMELLIA_256_SHA        0x84
 112 #define SSL_EDH_RSA_CAMELLIA_256_SHA    0x88
 113
 114 /*
 115  * Message, alert and handshake types
 116  */
 117 #define SSL_MSG_CHANGE_CIPHER_SPEC     20
 118 #define SSL_MSG_ALERT                  21
 119 #define SSL_MSG_HANDSHAKE              22
 120 #define SSL_MSG_APPLICATION_DATA       23
 121
 122 #define SSL_ALERT_CLOSE_NOTIFY          0
 123 #define SSL_ALERT_WARNING               1
 124 #define SSL_ALERT_FATAL                 2
 125 #define SSL_ALERT_NO_CERTIFICATE       41
 126
 127 #define SSL_HS_HELLO_REQUEST            0
 128 #define SSL_HS_CLIENT_HELLO             1
 129 #define SSL_HS_SERVER_HELLO             2
 130 #define SSL_HS_CERTIFICATE             11
 131 #define SSL_HS_SERVER_KEY_EXCHANGE     12
 132 #define SSL_HS_CERTIFICATE_REQUEST     13
 133 #define SSL_HS_SERVER_HELLO_DONE       14
 134 #define SSL_HS_CERTIFICATE_VERIFY      15
 135 #define SSL_HS_CLIENT_KEY_EXCHANGE     16
 136 #define SSL_HS_FINISHED                20
 137
 138 /*
 139  * TLS extensions
 140  */
 141 #define TLS_EXT_SERVERNAME              0
 142 #define TLS_EXT_SERVERNAME_HOSTNAME     0
 143
 144 /*
 145  * SSL state machine
 146  */
 147 typedef enum {
 148         SSL_HELLO_REQUEST,
 149         SSL_CLIENT_HELLO,
 150         SSL_SERVER_HELLO,
 151         SSL_SERVER_CERTIFICATE,
 152         SSL_SERVER_KEY_EXCHANGE,
 153         SSL_CERTIFICATE_REQUEST,
 154         SSL_SERVER_HELLO_DONE,
 155         SSL_CLIENT_CERTIFICATE,
 156         SSL_CLIENT_KEY_EXCHANGE,
 157         SSL_CERTIFICATE_VERIFY,
 158         SSL_CLIENT_CHANGE_CIPHER_SPEC,
 159         SSL_CLIENT_FINISHED,
 160         SSL_SERVER_CHANGE_CIPHER_SPEC,
 161         SSL_SERVER_FINISHED,
 162         SSL_FLUSH_BUFFERS,
 163         SSL_HANDSHAKE_OVER
 164 } ssl_states;
 165
 166 typedef struct _ssl_session ssl_session;
 167 typedef struct _ssl_context ssl_context;
 168
 169 /*
 170  * This structure is used for session resuming.
 171  */
 172 struct _ssl_session {
 173         time_t start;           /*!< starting time      */
 174         int cipher;             /*!< chosen cipher      */
 175         int length;             /*!< session id length  */
 176         unsigned char id[32];   /*!< session identifier */
 177         unsigned char master[48];       /*!< the master secret  */
 178         ssl_session *next;      /*!< next session entry */
 179 };
 180
 181 struct _ssl_context {
 182         /*
 183          * Miscellaneous
 184          */
 185         int state;              /*!< SSL handshake: current state     */
 186
 187         int major_ver;          /*!< equal to  SSL_MAJOR_VERSION_3    */
 188         int minor_ver;          /*!< either 0 (SSL3) or 1 (TLS1.0)    */
 189
 190         int max_major_ver;      /*!< max. major version from client   */
 191         int max_minor_ver;      /*!< max. minor version from client   */
 192
 193         /*
 194          * Callbacks (RNG, debug, I/O)
 195          */
 196         int (*f_rng) (void *);
 197         void (*f_dbg) (void *, int, const char *);
 198         int (*f_recv) (void *, unsigned char *, int);
 199         int (*f_send) (void *, const unsigned char *, int);
 200
 201         void *p_rng;            /*!< context for the RNG function     */
 202         void *p_dbg;            /*!< context for the debug function   */
 203         void *p_recv;           /*!< context for reading operations   */
 204         void *p_send;           /*!< context for writing operations   */
 205
 206         /*
 207          * Session layer
 208          */
 209         int resume;             /*!<  session resuming flag   */
 210         int timeout;            /*!<  sess. expiration time   */
 211         ssl_session *session;   /*!<  current session data    */
 212         int (*s_get) (ssl_context *);   /*!<  (server) get callback   */
 213         int (*s_set) (ssl_context *);   /*!<  (server) set callback   */
 214
 215         /*
 216          * Record layer (incoming data)
 217          */
 218         unsigned char *in_ctr;  /*!< 64-bit incoming message counter  */
 219         unsigned char *in_hdr;  /*!< 5-byte record header (in_ctr+8)  */
 220         unsigned char *in_msg;  /*!< the message contents (in_hdr+5)  */
 221         unsigned char *in_offt; /*!< read offset in application data  */
 222
 223         int in_msgtype;         /*!< record header: message type      */
 224         int in_msglen;          /*!< record header: message length    */
 225         int in_left;            /*!< amount of data read so far       */
 226
 227         int in_hslen;           /*!< current handshake message length */
 228         int nb_zero;            /*!< # of 0-length encrypted messages */
 229
 230         /*
 231          * Record layer (outgoing data)
 232          */
 233         unsigned char *out_ctr; /*!< 64-bit outgoing message counter  */
 234         unsigned char *out_hdr; /*!< 5-byte record header (out_ctr+8) */
 235         unsigned char *out_msg; /*!< the message contents (out_hdr+5) */
 236
 237         int out_msgtype;        /*!< record header: message type      */
 238         int out_msglen;         /*!< record header: message length    */
 239         int out_left;           /*!< amount of data not yet written   */
 240
 241         /*
 242          * PKI layer
 243          */
 244         rsa_context *rsa_key;   /*!<  own RSA private key     */
 245         x509_cert *own_cert;    /*!<  own X.509 certificate   */
 246         x509_cert *ca_chain;    /*!<  own trusted CA chain    */
 247         x509_cert *peer_cert;   /*!<  peer X.509 cert chain   */
 248         const char *peer_cn;    /*!<  expected peer CN        */
 249
 250         int endpoint;           /*!<  0: client, 1: server    */
 251         int authmode;           /*!<  verification mode       */
 252         int client_auth;        /*!<  flag for client auth.   */
 253         int verify_result;      /*!<  verification result     */
 254
 255         /*
 256          * Crypto layer
 257          */
 258         dhm_context dhm_ctx;    /*!<  DHM key exchange        */
 259         md5_context fin_md5;    /*!<  Finished MD5 checksum   */
 260         sha1_context fin_sha1;  /*!<  Finished SHA-1 checksum */
 261
 262         int do_crypt;           /*!<  en(de)cryption flag     */
 263         const int *ciphers;     /*!<  allowed ciphersuites    */
 264         int pmslen;             /*!<  premaster length        */
 265         int keylen;             /*!<  symmetric key length    */
 266         int minlen;             /*!<  min. ciphertext length  */
 267         int ivlen;              /*!<  IV length               */
 268         int maclen;             /*!<  MAC length              */
 269
 270         unsigned char randbytes[64];    /*!<  random bytes            */
 271         unsigned char premaster[256];   /*!<  premaster secret        */
 272
 273         unsigned char iv_enc[16];       /*!<  IV (encryption)         */
 274         unsigned char iv_dec[16];       /*!<  IV (decryption)         */
 275
 276         unsigned char mac_enc[32];      /*!<  MAC (encryption)        */
 277         unsigned char mac_dec[32];      /*!<  MAC (decryption)        */
 278
 279         unsigned long ctx_enc[128];     /*!<  encryption context      */
 280         unsigned long ctx_dec[128];     /*!<  decryption context      */
 281
 282         /*
 283          * TLS extensions
 284          */
 285         unsigned char *hostname;
 286         unsigned long hostname_len;
 287 };
 288
 289 #ifdef __cplusplus
 290 extern "C" {
 291 #endif
 292
 293         extern const int ssl_default_ciphers[];
 294
 295         /**
 296          * \brief          Initialize an SSL context
 297          *
 298          * \param ssl      SSL context
 299          *
 300          * \return         0 if successful, or 1 if memory allocation failed
 301          */
 302         int ssl_init(ssl_context * ssl);
 303
 304         /**
 305          * \brief          Set the current endpoint type
 306          *
 307          * \param ssl      SSL context
 308          * \param endpoint must be SSL_IS_CLIENT or SSL_IS_SERVER
 309          */
 310         void ssl_set_endpoint(ssl_context * ssl, int endpoint);
 311
 312         /**
 313          * \brief          Set the certificate verification mode
 314          *
 315          * \param ssl      SSL context
 316          * \param mode     can be:
 317          *
 318          *  SSL_VERIFY_NONE:      peer certificate is not checked (default),
 319          *                        this is insecure and SHOULD be avoided.
 320          *
 321          *  SSL_VERIFY_OPTIONAL:  peer certificate is checked, however the
 322          *                        handshake continues even if verification failed;
 323          *                        ssl_get_verify_result() can be called after the
 324          *                        handshake is complete.
 325          *
 326          *  SSL_VERIFY_REQUIRED:  peer *must* present a valid certificate,
 327          *                        handshake is aborted if verification failed.
 328          */
 329         void ssl_set_authmode(ssl_context * ssl, int authmode);
 330
 331         /**
 332          * \brief          Set the random number generator callback
 333          *
 334          * \param ssl      SSL context
 335          * \param f_rng    RNG function
 336          * \param p_rng    RNG parameter
 337          */
 338         void ssl_set_rng(ssl_context * ssl, int (*f_rng) (void *), void *p_rng);
 339
 340         /**
 341          * \brief          Set the debug callback
 342          *
 343          * \param ssl      SSL context
 344          * \param f_dbg    debug function
 345          * \param p_dbg    debug parameter
 346          */
 347         void ssl_set_dbg(ssl_context * ssl,
 348                          void (*f_dbg) (void *, int, const char *), void *p_dbg);
 349
 350         /**
 351          * \brief          Set the underlying BIO read and write callbacks
 352          *
 353          * \param ssl      SSL context
 354          * \param f_recv   read callback
 355          * \param p_recv   read parameter
 356          * \param f_send   write callback
 357          * \param p_send   write parameter
 358          */
 359         void ssl_set_bio(ssl_context * ssl,
 360                          int (*f_recv) (void *, unsigned char *, int),
 361                          void *p_recv, int (*f_send) (void *, const unsigned char *,
 362                                                       int), void *p_send);
 363
 364         /**
 365          * \brief          Set the session callbacks (server-side only)
 366          *
 367          * \param ssl      SSL context
 368          * \param s_get    session get callback
 369          * \param s_set    session set callback
 370          */
 371         void ssl_set_scb(ssl_context * ssl,
 372                          int (*s_get) (ssl_context *),
 373                          int (*s_set) (ssl_context *));
 374
 375         /**
 376          * \brief          Set the session resuming flag, timeout and data
 377          *
 378          * \param ssl      SSL context
 379          * \param resume   if 0 (default), the session will not be resumed
 380          * \param timeout  session timeout in seconds, or 0 (no timeout)
 381          * \param session  session context
 382          */
 383         void ssl_set_session(ssl_context * ssl, int resume, int timeout,
 384                              ssl_session * session);
 385
 386         /**
 387          * \brief          Set the list of allowed ciphersuites
 388          *
 389          * \param ssl      SSL context
 390          * \param ciphers  0-terminated list of allowed ciphers
 391          */
 392         void ssl_set_ciphers(ssl_context * ssl, const int *ciphers);
 393
 394         /**
 395          * \brief          Set the data required to verify peer certificate
 396          *
 397          * \param ssl      SSL context
 398          * \param ca_chain trusted CA chain
 399          * \param peer_cn  expected peer CommonName (or NULL)
 400          *
 401          * \note           TODO: add two more parameters: depth and crl
 402          */
 403         void ssl_set_ca_chain(ssl_context * ssl, x509_cert * ca_chain,
 404                               const char *peer_cn);
 405
 406         /**
 407          * \brief          Set own certificate and private key
 408          *
 409          * \param ssl      SSL context
 410          * \param own_cert own public certificate
 411          * \param rsa_key  own private RSA key
 412          */
 413         void ssl_set_own_cert(ssl_context * ssl, x509_cert * own_cert,
 414                               rsa_context * rsa_key);
 415
 416         /**
 417          * \brief          Set the Diffie-Hellman public P and G values,
 418          *                 read as hexadecimal strings (server-side only)
 419          *
 420          * \param ssl      SSL context
 421          * \param dhm_P    Diffie-Hellman-Merkle modulus
 422          * \param dhm_G    Diffie-Hellman-Merkle generator
 423          *
 424          * \return         0 if successful
 425          */
 426         int ssl_set_dh_param(ssl_context * ssl, const char *dhm_P, const char *dhm_G);
 427
 428         /**
 429          * \brief          Set hostname for ServerName TLS Extension
 430          *
 431          *
 432          * \param ssl      SSL context
 433          * \param hostname the server hostname
 434          *
 435          * \return         0 if successful
 436          */
 437         int ssl_set_hostname(ssl_context * ssl, const char *hostname);
 438
 439         /**
 440          * \brief          Return the number of data bytes available to read
 441          *
 442          * \param ssl      SSL context
 443          *
 444          * \return         how many bytes are available in the read buffer
 445          */
 446         int ssl_get_bytes_avail(const ssl_context * ssl);
 447
 448         /**
 449          * \brief          Return the result of the certificate verification
 450          *
 451          * \param ssl      SSL context
 452          *
 453          * \return         0 if successful, or a combination of:
 454          *                      BADCERT_EXPIRED
 455          *                      BADCERT_REVOKED
 456          *                      BADCERT_CN_MISMATCH
 457          *                      BADCERT_NOT_TRUSTED
 458          */
 459         int ssl_get_verify_result(const ssl_context * ssl);
 460
 461         /**
 462          * \brief          Return the name of the current cipher
 463          *
 464          * \param ssl      SSL context
 465          *
 466          * \return         a string containing the cipher name
 467          */
 468         const char *ssl_get_cipher(const ssl_context * ssl);
 469
 470         /**
 471          * \brief          Perform the SSL handshake
 472          *
 473          * \param ssl      SSL context
 474          *
 475          * \return         0 if successful, TROPICSSL_ERR_NET_TRY_AGAIN,
 476          *                 or a specific SSL error code.
 477          */
 478         int ssl_handshake(ssl_context * ssl);
 479
 480         /**
 481          * \brief          Read at most 'len' application data bytes
 482          *
 483          * \param ssl      SSL context
 484          * \param buf      buffer that will hold the data
 485          * \param len      how many bytes must be read
 486          *
 487          * \return         This function returns the number of bytes read,
 488          *                 or a negative error code.
 489          */
 490         int ssl_read(ssl_context * ssl, unsigned char *buf, int len);
 491
 492         /**
 493          * \brief          Write exactly 'len' application data bytes
 494          *
 495          * \param ssl      SSL context
 496          * \param buf      buffer holding the data
 497          * \param len      how many bytes must be written
 498          *
 499          * \return         This function returns the number of bytes written,
 500          *                 or a negative error code.
 501          *
 502          * \note           When this function returns TROPICSSL_ERR_NET_TRY_AGAIN,
 503          *                 it must be called later with the *same* arguments,
 504          *                 until it returns a positive value.
 505          */
 506         int ssl_write(ssl_context * ssl, const unsigned char *buf, int len);
 507
 508         /**
 509          * \brief          Notify the peer that the connection is being closed
 510          */
 511         int ssl_close_notify(ssl_context * ssl);
 512
 513         /**
 514          * \brief          Free an SSL context
 515          */
 516         void ssl_free(ssl_context * ssl);
 517
 518         /*
 519          * Internal functions (do not call directly)
 520          */
 521         int ssl_handshake_client(ssl_context * ssl);
 522         int ssl_handshake_server(ssl_context * ssl);
 523
 524         int ssl_derive_keys(ssl_context * ssl);
 525         void ssl_calc_verify(ssl_context * ssl, unsigned char hash[36]);
 526
 527         int ssl_read_record(ssl_context * ssl);
 528         int ssl_fetch_input(ssl_context * ssl, int nb_want);
 529
 530         int ssl_write_record(ssl_context * ssl);
 531         int ssl_flush_output(ssl_context * ssl);
 532
 533         int ssl_parse_certificate(ssl_context * ssl);
 534         int ssl_write_certificate(ssl_context * ssl);
 535
 536         int ssl_parse_change_cipher_spec(ssl_context * ssl);
 537         int ssl_write_change_cipher_spec(ssl_context * ssl);
 538
 539         int ssl_parse_finished(ssl_context * ssl);
 540         int ssl_write_finished(ssl_context * ssl);
 541
 542 #ifdef __cplusplus
 543 }
 544 #endif
 545 #endif                          /* ssl.h */