tool/mbed/mbed-sdk/libraries/net/https/axTLS/ssl/ssl.h

   1 /*
   2  * Copyright (c) 2007, Cameron Rich
   3  *
   4  * All rights reserved.
   5  *
   6  * Redistribution and use in source and binary forms, with or without
   7  * modification, are permitted provided that the following conditions are met:
   8  *
   9  * * Redistributions of source code must retain the above copyright notice,
  10  *   this list of conditions and the following disclaimer.
  11  * * Redistributions in binary form must reproduce the above copyright notice,
  12  *   this list of conditions and the following disclaimer in the documentation
  13  *   and/or other materials provided with the distribution.
  14  * * Neither the name of the axTLS project nor the names of its contributors
  15  *   may be used to endorse or promote products derived from this software
  16  *   without specific prior written permission.
  17  *
  18  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  19  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  20  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  21  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
  22  * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
  23  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
  24  * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
  25  * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
  26  * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
  27  * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
  28  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  29  */
  30
  31 /**
  32  * @mainpage axTLS API
  33  *
  34  * @image html axolotl.jpg
  35  *
  36  * The axTLS library has features such as:
  37  * - The TLSv1 SSL client/server protocol
  38  * - No requirement to use any openssl libraries.
  39  * - A choice between AES block (128/256 bit) and RC4 (128 bit) stream ciphers.
  40  * - RSA encryption/decryption with variable sized keys (up to 4096 bits).
  41  * - Certificate chaining and peer authentication.
  42  * - Session resumption, session renegotiation.
  43  * - ASN.1, X.509, PKCS#8, PKCS#12 keys/certificates with DER/PEM encoding.
  44  * - Highly configurable compile time options.
  45  * - Portable across many platforms (written in ANSI C), and has language
  46  * bindings in C, C#, VB.NET, Java, Perl and Lua.
  47  * - Partial openssl API compatibility (via a wrapper).
  48  * - A very small footprint (around 50-60kB for the library in 'server-only'
  49  *   mode).
  50  * - No dependencies on sockets - can use serial connections for example.
  51  * - A very simple API - ~ 20 functions/methods.
  52  *
  53  * A list of these functions/methods are described below.
  54  *
  55  *  @ref c_api
  56  *
  57  *  @ref bigint_api
  58  *
  59  *  @ref csharp_api
  60  *
  61  *  @ref java_api
  62  */
  63 #ifndef HEADER_SSL_H
  64 #define HEADER_SSL_H
  65
  66 #ifdef __cplusplus
  67 extern "C" {
  68 #endif
  69
  70 #include <time.h>
  71
  72 /* need to predefine before ssl_lib.h gets to it */
  73 #define SSL_SESSION_ID_SIZE                     32
  74
  75 #include "tls1.h"
  76
  77 /* The optional parameters that can be given to the client/server SSL engine */
  78 #define SSL_CLIENT_AUTHENTICATION               0x00010000
  79 #define SSL_SERVER_VERIFY_LATER                 0x00020000
  80 #define SSL_NO_DEFAULT_KEY                      0x00040000
  81 #define SSL_DISPLAY_STATES                      0x00080000
  82 #define SSL_DISPLAY_BYTES                       0x00100000
  83 #define SSL_DISPLAY_CERTS                       0x00200000
  84 #define SSL_DISPLAY_RSA                         0x00400000
  85 #define SSL_CONNECT_IN_PARTS                    0x00800000
  86
  87 /* errors that can be generated */
  88 #define SSL_OK                                  0
  89 #define SSL_NOT_OK                              -1
  90 #define SSL_ERROR_DEAD                          -2
  91 #define SSL_CLOSE_NOTIFY                        -3
  92 #define SSL_ERROR_CONN_LOST                     -256
  93 #define SSL_ERROR_SOCK_SETUP_FAILURE            -258
  94 #define SSL_ERROR_INVALID_HANDSHAKE             -260
  95 #define SSL_ERROR_INVALID_PROT_MSG              -261
  96 #define SSL_ERROR_INVALID_HMAC                  -262
  97 #define SSL_ERROR_INVALID_VERSION               -263
  98 #define SSL_ERROR_INVALID_SESSION               -265
  99 #define SSL_ERROR_NO_CIPHER                     -266
 100 #define SSL_ERROR_BAD_CERTIFICATE               -268
 101 #define SSL_ERROR_INVALID_KEY                   -269
 102 #define SSL_ERROR_FINISHED_INVALID              -271
 103 #define SSL_ERROR_NO_CERT_DEFINED               -272
 104 #define SSL_ERROR_NO_CLIENT_RENOG               -273
 105 #define SSL_ERROR_NOT_SUPPORTED                 -274
 106 #define SSL_X509_OFFSET                         -512
 107 #define SSL_X509_ERROR(A)                       (SSL_X509_OFFSET+A)
 108
 109 /* alert types that are recognized */
 110 #define SSL_ALERT_TYPE_WARNING                  1
 111 #define SLL_ALERT_TYPE_FATAL                    2
 112
 113 /* these are all the alerts that are recognized */
 114 #define SSL_ALERT_CLOSE_NOTIFY                  0
 115 #define SSL_ALERT_UNEXPECTED_MESSAGE            10
 116 #define SSL_ALERT_BAD_RECORD_MAC                20
 117 #define SSL_ALERT_HANDSHAKE_FAILURE             40
 118 #define SSL_ALERT_BAD_CERTIFICATE               42
 119 #define SSL_ALERT_ILLEGAL_PARAMETER             47
 120 #define SSL_ALERT_DECODE_ERROR                  50
 121 #define SSL_ALERT_DECRYPT_ERROR                 51
 122 #define SSL_ALERT_INVALID_VERSION               70
 123 #define SSL_ALERT_NO_RENEGOTIATION              100
 124
 125 /* The ciphers that are supported */
 126 #define SSL_AES128_SHA                          0x2f
 127 #define SSL_AES256_SHA                          0x35
 128 #define SSL_RC4_128_SHA                         0x05
 129 #define SSL_RC4_128_MD5                         0x04
 130
 131 /* build mode ids' */
 132 #define SSL_BUILD_SKELETON_MODE                 0x01
 133 #define SSL_BUILD_SERVER_ONLY                   0x02
 134 #define SSL_BUILD_ENABLE_VERIFICATION           0x03
 135 #define SSL_BUILD_ENABLE_CLIENT                 0x04
 136 #define SSL_BUILD_FULL_MODE                     0x05
 137
 138 /* offsets to retrieve configuration information */
 139 #define SSL_BUILD_MODE                          0
 140 #define SSL_MAX_CERT_CFG_OFFSET                 1
 141 #define SSL_MAX_CA_CERT_CFG_OFFSET              2
 142 #define SSL_HAS_PEM                             3
 143
 144 /* default session sizes */
 145 #define SSL_DEFAULT_SVR_SESS                    5
 146 #define SSL_DEFAULT_CLNT_SESS                   1
 147
 148 /* X.509/X.520 distinguished name types */
 149 #define SSL_X509_CERT_COMMON_NAME               0
 150 #define SSL_X509_CERT_ORGANIZATION              1
 151 #define SSL_X509_CERT_ORGANIZATIONAL_NAME       2
 152 #define SSL_X509_CA_CERT_COMMON_NAME            3
 153 #define SSL_X509_CA_CERT_ORGANIZATION           4
 154 #define SSL_X509_CA_CERT_ORGANIZATIONAL_NAME    5
 155
 156 /* SSL object loader types */
 157 #define SSL_OBJ_X509_CERT                       1
 158 #define SSL_OBJ_X509_CACERT                     2
 159 #define SSL_OBJ_RSA_KEY                         3
 160 #define SSL_OBJ_PKCS8                           4
 161 #define SSL_OBJ_PKCS12                          5
 162
 163 /**
 164  * @defgroup c_api Standard C API
 165  * @brief The standard interface in C.
 166  * @{
 167  */
 168
 169 /**
 170  * @brief Establish a new client/server context.
 171  *
 172  * This function is called before any client/server SSL connections are made.
 173  *
 174  * Each new connection will use the this context's private key and
 175  * certificate chain. If a different certificate chain is required, then a
 176  * different context needs to be be used.
 177  *
 178  * There are two threading models supported - a single thread with one
 179  * SSL_CTX can support any number of SSL connections - and multiple threads can
 180  * support one SSL_CTX object each (the default). But if a single SSL_CTX
 181  * object uses many SSL objects in individual threads, then the
 182  * CONFIG_SSL_CTX_MUTEXING option needs to be configured.
 183  *
 184  * @param options [in]  Any particular options. At present the options
 185  * supported are:
 186  * - SSL_SERVER_VERIFY_LATER (client only): Don't stop a handshake if the server
 187  * authentication fails. The certificate can be authenticated later with a
 188  * call to ssl_verify_cert().
 189  * - SSL_CLIENT_AUTHENTICATION (server only): Enforce client authentication
 190  * i.e. each handshake will include a "certificate request" message from the
 191  * server. Only available if verification has been enabled.
 192  * - SSL_DISPLAY_BYTES (full mode build only): Display the byte sequences
 193  * during the handshake.
 194  * - SSL_DISPLAY_STATES (full mode build only): Display the state changes
 195  * during the handshake.
 196  * - SSL_DISPLAY_CERTS (full mode build only): Display the certificates that
 197  * are passed during a handshake.
 198  * - SSL_DISPLAY_RSA (full mode build only): Display the RSA key details that
 199  * are passed during a handshake.
 200  * - SSL_CONNECT_IN_PARTS (client only): To use a non-blocking version of
 201  * ssl_client_new().
 202  * @param num_sessions [in] The number of sessions to be used for session
 203  * caching. If this value is 0, then there is no session caching. This option
 204  * is not used in skeleton mode.
 205  * @return A client/server context.
 206  */
 207 EXP_FUNC SSL_CTX * STDCALL ssl_ctx_new(SSL_CTX *ssl_ctx, uint32_t options, int num_sessions);
 208
 209 /**
 210  * @brief Remove a client/server context.
 211  *
 212  * Frees any used resources used by this context. Each connection will be
 213  * sent a "Close Notify" alert (if possible).
 214  * @param ssl_ctx [in] The client/server context.
 215  */
 216 EXP_FUNC void STDCALL ssl_ctx_free(SSL_CTX *ssl_ctx);
 217
 218 /**
 219  * @brief (server only) Establish a new SSL connection to an SSL client.
 220  *
 221  * It is up to the application to establish the logical connection (whether it
 222  * is  a socket, serial connection etc).
 223  * @param ssl_ctx [in] The server context.
 224  * @param client_fd [in] The client's file descriptor.
 225  * @return An SSL object reference.
 226  */
 227 EXP_FUNC SSL * STDCALL ssl_server_new(SSL_CTX *ssl_ctx, int client_fd);
 228
 229 /**
 230  * @brief (client only) Establish a new SSL connection to an SSL server.
 231  *
 232  * It is up to the application to establish the initial logical connection
 233  * (whether it is  a socket, serial connection etc).
 234  *
 235  * This is a normally a blocking call - it will finish when the handshake is
 236  * complete (or has failed). To use in non-blocking mode, set
 237  * SSL_CONNECT_IN_PARTS in ssl_ctx_new().
 238  * @param ssl_ctx [in] The client context.
 239  * @param client_fd [in] The client's file descriptor.
 240  * @param session_id [in] A 32 byte session id for session resumption. This
 241  * can be null if no session resumption is being used or required. This option
 242  * is not used in skeleton mode.
 243  * @param sess_id_size The size of the session id (max 32)
 244  * @return An SSL object reference. Use ssl_handshake_status() to check
 245  * if a handshake succeeded.
 246  */
 247 EXP_FUNC SSL * STDCALL ssl_client_new(SSL *ssl, int client_fd, const uint8_t *session_id, uint8_t sess_id_size);
 248
 249 /**
 250  * @brief Free any used resources on this connection.
 251
 252  * A "Close Notify" message is sent on this connection (if possible). It is up
 253  * to the application to close the socket or file descriptor.
 254  * @param ssl [in] The ssl object reference.
 255  */
 256 EXP_FUNC void STDCALL ssl_free(SSL *ssl);
 257
 258 /**
 259  * @brief Read the SSL data stream.
 260  * If the socket is non-blocking and data is blocked then SSO_OK will be
 261  * returned.
 262  * @param ssl [in] An SSL object reference.
 263  * @param in_data [out] If the read was successful, a pointer to the read
 264  * buffer will be here. Do NOT ever free this memory as this buffer is used in
 265  * sucessive calls. If the call was unsuccessful, this value will be null.
 266  * @return The number of decrypted bytes:
 267  * - if > 0, then the handshaking is complete and we are returning the number
 268  *   of decrypted bytes.
 269  * - SSL_OK if the handshaking stage is successful (but not yet complete).
 270  * - < 0 if an error.
 271  * @see ssl.h for the error code list.
 272  * @note Use in_data before doing any successive ssl calls.
 273  */
 274 //EXP_FUNC int STDCALL ssl_read(SSL *ssl, uint8_t **in_data);
 275
 276 /**
 277  * @brief Write to the SSL data stream.
 278  * if the socket is non-blocking and data is blocked then a check is made
 279  * to ensure that all data is sent (i.e. blocked mode is forced).
 280  * @param ssl [in] An SSL obect reference.
 281  * @param out_data [in] The data to be written
 282  * @param out_len [in] The number of bytes to be written.
 283  * @return The number of bytes sent, or if < 0 if an error.
 284  * @see ssl.h for the error code list.
 285  */
 286 EXP_FUNC int STDCALL ssl_write(SSL *ssl, const uint8_t *out_data, int out_len);
 287
 288 /**
 289  * @brief Find an ssl object based on a file descriptor.
 290  *
 291  * Goes through the list of SSL objects maintained in a client/server context
 292  * to look for a file descriptor match.
 293  * @param ssl_ctx [in] The client/server context.
 294  * @param client_fd [in]  The file descriptor.
 295  * @return A reference to the SSL object. Returns null if the object could not
 296  * be found.
 297  */
 298 EXP_FUNC SSL * STDCALL ssl_find(SSL_CTX *ssl_ctx, int client_fd);
 299
 300 /**
 301  * @brief Get the session id for a handshake.
 302  *
 303  * This will be a 32 byte sequence and is available after the first
 304  * handshaking messages are sent.
 305  * @param ssl [in] An SSL object reference.
 306  * @return The session id as a 32 byte sequence.
 307  * @note A SSLv23 handshake may have only 16 valid bytes.
 308  */
 309 EXP_FUNC const uint8_t * STDCALL ssl_get_session_id(const SSL *ssl);
 310
 311 /**
 312  * @brief Get the session id size for a handshake.
 313  *
 314  * This will normally be 32 but could be 0 (no session id) or something else.
 315  * @param ssl [in] An SSL object reference.
 316  * @return The size of the session id.
 317  */
 318 EXP_FUNC uint8_t STDCALL ssl_get_session_id_size(const SSL *ssl);
 319
 320 /**
 321  * @brief Return the cipher id (in the SSL form).
 322  * @param ssl [in] An SSL object reference.
 323  * @return The cipher id. This will be one of the following:
 324  * - SSL_AES128_SHA (0x2f)
 325  * - SSL_AES256_SHA (0x35)
 326  * - SSL_RC4_128_SHA (0x05)
 327  * - SSL_RC4_128_MD5 (0x04)
 328  */
 329 EXP_FUNC uint8_t STDCALL ssl_get_cipher_id(const SSL *ssl);
 330
 331 /**
 332  * @brief Return the status of the handshake.
 333  * @param ssl [in] An SSL object reference.
 334  * @return SSL_OK if the handshake is complete and ok.
 335  * @see ssl.h for the error code list.
 336  */
 337 EXP_FUNC int STDCALL ssl_handshake_status(const SSL *ssl);
 338
 339 /**
 340  * @brief Retrieve various parameters about the axTLS engine.
 341  * @param offset [in] The configuration offset. It will be one of the following:
 342  * - SSL_BUILD_MODE The build mode. This will be one of the following:
 343  *   - SSL_BUILD_SERVER_ONLY            (basic server mode)
 344  *   - SSL_BUILD_ENABLE_VERIFICATION    (server can do client authentication)
 345  *   - SSL_BUILD_ENABLE_CLIENT          (client/server capabilties)
 346  *   - SSL_BUILD_FULL_MODE              (client/server with diagnostics)
 347  *   - SSL_BUILD_SKELETON_MODE          (skeleton mode)
 348  * - SSL_MAX_CERT_CFG_OFFSET The maximum number of certificates allowed.
 349  * - SSL_MAX_CA_CERT_CFG_OFFSET The maximum number of CA certificates allowed.
 350  * - SSL_HAS_PEM                        1 if supported
 351  * @return The value of the requested parameter.
 352  */
 353 EXP_FUNC int STDCALL ssl_get_config(int offset);
 354
 355 /**
 356  * @brief Display why the handshake failed.
 357  *
 358  * This call is only useful in a 'full mode' build. The output is to stdout.
 359  * @param error_code [in] An error code.
 360  * @see ssl.h for the error code list.
 361  */
 362 EXP_FUNC void STDCALL ssl_display_error(int error_code);
 363
 364 /**
 365  * @brief Authenticate a received certificate.
 366  *
 367  * This call is usually made by a client after a handshake is complete and the
 368  * context is in SSL_SERVER_VERIFY_LATER mode.
 369  * @param ssl [in] An SSL object reference.
 370  * @return SSL_OK if the certificate is verified.
 371  */
 372 EXP_FUNC int STDCALL ssl_verify_cert(const SSL *ssl);
 373
 374 /**
 375  * @brief Retrieve an X.509 distinguished name component.
 376  *
 377  * When a handshake is complete and a certificate has been exchanged, then the
 378  * details of the remote certificate can be retrieved.
 379  *
 380  * This will usually be used by a client to check that the server's common
 381  * name matches the URL.
 382  *
 383  * @param ssl [in] An SSL object reference.
 384  * @param component [in] one of:
 385  * - SSL_X509_CERT_COMMON_NAME
 386  * - SSL_X509_CERT_ORGANIZATION
 387  * - SSL_X509_CERT_ORGANIZATIONAL_NAME
 388  * - SSL_X509_CA_CERT_COMMON_NAME
 389  * - SSL_X509_CA_CERT_ORGANIZATION
 390  * - SSL_X509_CA_CERT_ORGANIZATIONAL_NAME
 391  * @return The appropriate string (or null if not defined)
 392  * @note Verification build mode must be enabled.
 393  */
 394 EXP_FUNC const char * STDCALL ssl_get_cert_dn(const SSL *ssl, int component);
 395
 396 /**
 397  * @brief Retrieve a Subject Alternative DNSName
 398  *
 399  * When a handshake is complete and a certificate has been exchanged, then the
 400  * details of the remote certificate can be retrieved.
 401  *
 402  * This will usually be used by a client to check that the server's DNS
 403  * name matches the URL.
 404  *
 405  * @param ssl [in] An SSL object reference.
 406  * @param dnsindex [in] The index of the DNS name to retrieve.
 407  * @return The appropriate string (or null if not defined)
 408  * @note Verification build mode must be enabled.
 409  */
 410 EXP_FUNC const char * STDCALL ssl_get_cert_subject_alt_dnsname(const SSL *ssl, int dnsindex);
 411
 412 /**
 413  * @brief Force the client to perform its handshake again.
 414  *
 415  * For a client this involves sending another "client hello" message.
 416  * For the server is means sending a "hello request" message.
 417  *
 418  * This is a blocking call on the client (until the handshake completes).
 419  *
 420  * @param ssl [in] An SSL object reference.
 421  * @return SSL_OK if renegotiation instantiation was ok
 422  */
 423 EXP_FUNC int STDCALL ssl_renegotiate(SSL *ssl);
 424
 425 /**
 426  * @brief Process a file that is in binary DER or ASCII PEM format.
 427  *
 428  * These are temporary objects that are used to load private keys,
 429  * certificates etc into memory.
 430  * @param ssl_ctx [in] The client/server context.
 431  * @param obj_type [in] The format of the file. Can be one of:
 432  * - SSL_OBJ_X509_CERT (no password required)
 433  * - SSL_OBJ_X509_CACERT (no password required)
 434  * - SSL_OBJ_RSA_KEY (AES128/AES256 PEM encryption supported)
 435  * - SSL_OBJ_PKCS8 (RC4-128 encrypted data supported)
 436  * - SSL_OBJ_PKCS12 (RC4-128 encrypted data supported)
 437  *
 438  * PEM files are automatically detected (if supported). The object type is
 439  * also detected, and so is not relevant for these types of files.
 440  * @param filename [in] The location of a file in DER/PEM format.
 441  * @param password [in] The password used. Can be null if not required.
 442  * @return SSL_OK if all ok
 443  * @note Not available in skeleton build mode.
 444  */
 445 EXP_FUNC int STDCALL ssl_obj_load(SSL_CTX *ssl_ctx, int obj_type, const char *filename, const char *password);
 446
 447 /**
 448  * @brief Process binary data.
 449  *
 450  * These are temporary objects that are used to load private keys,
 451  * certificates etc into memory.
 452  * @param ssl_ctx [in] The client/server context.
 453  * @param obj_type [in] The format of the memory data.
 454  * @param data [in] The binary data to be loaded.
 455  * @param len [in] The amount of data to be loaded.
 456  * @param password [in] The password used. Can be null if not required.
 457  * @return SSL_OK if all ok
 458  * @see ssl_obj_load for more details on obj_type.
 459  */
 460 EXP_FUNC int STDCALL ssl_obj_memory_load(SSL_CTX *ssl_ctx, int obj_type, const uint8_t *data, int len, const char *password);
 461
 462 #ifdef CONFIG_SSL_GENERATE_X509_CERT
 463 /**
 464  * @brief Create an X.509 certificate.
 465  *
 466  * This certificate is a self-signed v1 cert with a fixed start/stop validity
 467  * times. It is signed with an internal private key in ssl_ctx.
 468  *
 469  * @param ssl_ctx [in] The client/server context.
 470  * @param options [in] Not used yet.
 471  * @param dn [in] An array of distinguished name strings. The array is defined
 472  * by:
 473  * - SSL_X509_CERT_COMMON_NAME (0)
 474  *      - If SSL_X509_CERT_COMMON_NAME is empty or not defined, then the
 475  *        hostname will be used.
 476  * - SSL_X509_CERT_ORGANIZATION (1)
 477  *      - If SSL_X509_CERT_ORGANIZATION is empty or not defined, then $USERNAME
 478  *        will be used.
 479  * - SSL_X509_CERT_ORGANIZATIONAL_NAME (2)
 480  *      - SSL_X509_CERT_ORGANIZATIONAL_NAME is optional.
 481  * @param cert_data [out] The certificate as a sequence of bytes.
 482  * @return < 0 if an error, or the size of the certificate in bytes.
 483  * @note cert_data must be freed when there is no more need for it.
 484  */
 485 EXP_FUNC int STDCALL ssl_x509_create(SSL_CTX *ssl_ctx, uint32_t options, const char * dn[], uint8_t **cert_data);
 486 #endif
 487
 488 /**
 489  * @brief Return the axTLS library version as a string.
 490  */
 491 EXP_FUNC const char * STDCALL ssl_version(void);
 492
 493 /** @} */
 494
 495 #ifdef __cplusplus
 496 }
 497 #endif
 498
 499 #endif