ssl.h

00001 /*
00002  * Copyright (c) 2007, Cameron Rich
00003  * 
00004  * All rights reserved.
00005  * 
00006  * Redistribution and use in source and binary forms, with or without 
00007  * modification, are permitted provided that the following conditions are met:
00008  *
00009  * * Redistributions of source code must retain the above copyright notice, 
00010  *   this list of conditions and the following disclaimer.
00011  * * Redistributions in binary form must reproduce the above copyright notice, 
00012  *   this list of conditions and the following disclaimer in the documentation 
00013  *   and/or other materials provided with the distribution.
00014  * * Neither the name of the axTLS project nor the names of its contributors 
00015  *   may be used to endorse or promote products derived from this software 
00016  *   without specific prior written permission.
00017  *
00018  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
00019  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
00020  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
00021  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
00022  * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
00023  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
00024  * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
00025  * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
00026  * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
00027  * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
00028  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
00029  */
00030 
00031 /**
00032  * @mainpage axTLS API
00033  *
00034  * @image html axolotl.jpg
00035  *
00036  * The axTLS library has features such as:
00037  * - The TLSv1 SSL client/server protocol
00038  * - No requirement to use any openssl libraries.
00039  * - A choice between AES block (128/256 bit) and RC4 (128 bit) stream ciphers.
00040  * - RSA encryption/decryption with variable sized keys (up to 4096 bits).
00041  * - Certificate chaining and peer authentication.
00042  * - Session resumption, session renegotiation.
00043  * - ASN.1, X.509, PKCS#8, PKCS#12 keys/certificates with DER/PEM encoding.
00044  * - Highly configurable compile time options.
00045  * - Portable across many platforms (written in ANSI C), and has language
00046  * bindings in C, C#, VB.NET, Java, Perl and Lua.
00047  * - Partial openssl API compatibility (via a wrapper).
00048  * - A very small footprint (around 50-60kB for the library in 'server-only' 
00049  *   mode).
00050  * - No dependencies on sockets - can use serial connections for example.
00051  * - A very simple API - ~ 20 functions/methods.
00052  *
00053  * A list of these functions/methods are described below.
00054  *
00055  *  @ref c_api 
00056  *
00057  *  @ref bigint_api 
00058  *
00059  *  @ref csharp_api 
00060  *
00061  *  @ref java_api 
00062  */
00063 #ifndef HEADER_SSL_H
00064 #define HEADER_SSL_H
00065 
00066 #ifdef __cplusplus
00067 extern "C" {
00068 #endif
00069 
00070 #include <time.h>
00071 
00072 
00073 /* need to predefine before ssl_lib.h gets to it */
00074 #define SSL_SESSION_ID_SIZE                     32
00075 
00076 
00077 #include "tls1.h"
00078 
00079 /* The optional parameters that can be given to the client/server SSL engine */
00080 #define SSL_CLIENT_AUTHENTICATION               0x00010000
00081 #define SSL_SERVER_VERIFY_LATER                 0x00020000
00082 #define SSL_NO_DEFAULT_KEY                      0x00040000
00083 #define SSL_DISPLAY_STATES                      0x00080000
00084 #define SSL_DISPLAY_BYTES                       0x00100000
00085 #define SSL_DISPLAY_CERTS                       0x00200000
00086 #define SSL_DISPLAY_RSA                         0x00400000
00087 #define SSL_CONNECT_IN_PARTS                    0x00800000
00088 
00089 /* errors that can be generated */
00090 #define SSL_OK                                  0
00091 #define SSL_NOT_OK                              -1
00092 #define SSL_ERROR_DEAD                          -2
00093 #define SSL_CLOSE_NOTIFY                        -3
00094 #define SSL_ERROR_CONN_LOST                     -256
00095 #define SSL_ERROR_SOCK_SETUP_FAILURE            -258
00096 #define SSL_ERROR_INVALID_HANDSHAKE             -260
00097 #define SSL_ERROR_INVALID_PROT_MSG              -261
00098 #define SSL_ERROR_INVALID_HMAC                  -262
00099 #define SSL_ERROR_INVALID_VERSION               -263
00100 #define SSL_ERROR_INVALID_SESSION               -265
00101 #define SSL_ERROR_NO_CIPHER                     -266
00102 #define SSL_ERROR_BAD_CERTIFICATE               -268
00103 #define SSL_ERROR_INVALID_KEY                   -269
00104 #define SSL_ERROR_FINISHED_INVALID              -271
00105 #define SSL_ERROR_NO_CERT_DEFINED               -272
00106 #define SSL_ERROR_NO_CLIENT_RENOG               -273
00107 #define SSL_ERROR_NOT_SUPPORTED                 -274
00108 #define SSL_X509_OFFSET                         -512
00109 #define SSL_X509_ERROR(A)                       (SSL_X509_OFFSET+A)
00110 
00111 /* alert types that are recognized */
00112 #define SSL_ALERT_TYPE_WARNING                  1
00113 #define SLL_ALERT_TYPE_FATAL                    2
00114 
00115 /* these are all the alerts that are recognized */
00116 #define SSL_ALERT_CLOSE_NOTIFY                  0
00117 #define SSL_ALERT_UNEXPECTED_MESSAGE            10
00118 #define SSL_ALERT_BAD_RECORD_MAC                20
00119 #define SSL_ALERT_HANDSHAKE_FAILURE             40
00120 #define SSL_ALERT_BAD_CERTIFICATE               42
00121 #define SSL_ALERT_ILLEGAL_PARAMETER             47
00122 #define SSL_ALERT_DECODE_ERROR                  50
00123 #define SSL_ALERT_DECRYPT_ERROR                 51
00124 #define SSL_ALERT_INVALID_VERSION               70
00125 #define SSL_ALERT_NO_RENEGOTIATION              100
00126 
00127 /* The ciphers that are supported */
00128 #define SSL_AES128_SHA                          0x2f
00129 #define SSL_AES256_SHA                          0x35
00130 #define SSL_RC4_128_SHA                         0x05
00131 #define SSL_RC4_128_MD5                         0x04
00132 
00133 /* build mode ids' */
00134 #define SSL_BUILD_SKELETON_MODE                 0x01
00135 #define SSL_BUILD_SERVER_ONLY                   0x02
00136 #define SSL_BUILD_ENABLE_VERIFICATION           0x03
00137 #define SSL_BUILD_ENABLE_CLIENT                 0x04
00138 #define SSL_BUILD_FULL_MODE                     0x05
00139 
00140 /* offsets to retrieve configuration information */
00141 #define SSL_BUILD_MODE                          0
00142 #define SSL_MAX_CERT_CFG_OFFSET                 1
00143 #define SSL_MAX_CA_CERT_CFG_OFFSET              2
00144 #define SSL_HAS_PEM                             3
00145 
00146 /* default session sizes */
00147 #define SSL_DEFAULT_SVR_SESS                    5
00148 #define SSL_DEFAULT_CLNT_SESS                   1
00149 
00150 /* X.509/X.520 distinguished name types */
00151 #define SSL_X509_CERT_COMMON_NAME               0
00152 #define SSL_X509_CERT_ORGANIZATION              1
00153 #define SSL_X509_CERT_ORGANIZATIONAL_NAME       2
00154 #define SSL_X509_CA_CERT_COMMON_NAME            3
00155 #define SSL_X509_CA_CERT_ORGANIZATION           4
00156 #define SSL_X509_CA_CERT_ORGANIZATIONAL_NAME    5
00157 
00158 /* SSL object loader types */
00159 #define SSL_OBJ_X509_CERT                       1
00160 #define SSL_OBJ_X509_CACERT                     2
00161 #define SSL_OBJ_RSA_KEY                         3
00162 #define SSL_OBJ_PKCS8                           4
00163 #define SSL_OBJ_PKCS12                          5
00164 
00165 /**
00166  * @defgroup c_api Standard C API
00167  * @brief The standard interface in C.
00168  * @{
00169  */
00170 
00171 /**
00172  * @brief Establish a new client/server context.
00173  *
00174  * This function is called before any client/server SSL connections are made. 
00175  *
00176  * Each new connection will use the this context's private key and 
00177  * certificate chain. If a different certificate chain is required, then a 
00178  * different context needs to be be used.
00179  *
00180  * There are two threading models supported - a single thread with one
00181  * SSL_CTX can support any number of SSL connections - and multiple threads can 
00182  * support one SSL_CTX object each (the default). But if a single SSL_CTX 
00183  * object uses many SSL objects in individual threads, then the 
00184  * CONFIG_SSL_CTX_MUTEXING option needs to be configured.
00185  *
00186  * @param options [in]  Any particular options. At present the options
00187  * supported are:
00188  * - SSL_SERVER_VERIFY_LATER (client only): Don't stop a handshake if the server
00189  * authentication fails. The certificate can be authenticated later with a
00190  * call to ssl_verify_cert().
00191  * - SSL_CLIENT_AUTHENTICATION (server only): Enforce client authentication
00192  * i.e. each handshake will include a "certificate request" message from the
00193  * server. Only available if verification has been enabled.
00194  * - SSL_DISPLAY_BYTES (full mode build only): Display the byte sequences
00195  * during the handshake.
00196  * - SSL_DISPLAY_STATES (full mode build only): Display the state changes
00197  * during the handshake.
00198  * - SSL_DISPLAY_CERTS (full mode build only): Display the certificates that
00199  * are passed during a handshake.
00200  * - SSL_DISPLAY_RSA (full mode build only): Display the RSA key details that
00201  * are passed during a handshake.
00202  * - SSL_CONNECT_IN_PARTS (client only): To use a non-blocking version of 
00203  * ssl_client_new().
00204  * @param num_sessions [in] The number of sessions to be used for session
00205  * caching. If this value is 0, then there is no session caching. This option
00206  * is not used in skeleton mode.
00207  * @return A client/server context.
00208  */
00209 EXP_FUNC SSL_CTX * STDCALL ssl_ctx_new(SSL_CTX *ssl_ctx, uint32_t options, int num_sessions);
00210 
00211 /**
00212  * @brief Remove a client/server context.
00213  *
00214  * Frees any used resources used by this context. Each connection will be 
00215  * sent a "Close Notify" alert (if possible).
00216  * @param ssl_ctx [in] The client/server context.
00217  */
00218 EXP_FUNC void STDCALL ssl_ctx_free(SSL_CTX *ssl_ctx);
00219 
00220 /**
00221  * @brief (server only) Establish a new SSL connection to an SSL client.
00222  *
00223  * It is up to the application to establish the logical connection (whether it
00224  * is  a socket, serial connection etc).
00225  * @param ssl_ctx [in] The server context.
00226  * @param client_fd [in] The client's file descriptor. 
00227  * @return An SSL object reference.
00228  */
00229 EXP_FUNC SSL * STDCALL ssl_server_new(SSL_CTX *ssl_ctx, int client_fd);
00230 
00231 /**
00232  * @brief (client only) Establish a new SSL connection to an SSL server.
00233  *
00234  * It is up to the application to establish the initial logical connection 
00235  * (whether it is  a socket, serial connection etc).
00236  *
00237  * This is a normally a blocking call - it will finish when the handshake is 
00238  * complete (or has failed). To use in non-blocking mode, set 
00239  * SSL_CONNECT_IN_PARTS in ssl_ctx_new().
00240  * @param ssl_ctx [in] The client context.
00241  * @param client_fd [in] The client's file descriptor.
00242  * @param session_id [in] A 32 byte session id for session resumption. This 
00243  * can be null if no session resumption is being used or required. This option
00244  * is not used in skeleton mode.
00245  * @param sess_id_size The size of the session id (max 32)
00246  * @return An SSL object reference. Use ssl_handshake_status() to check 
00247  * if a handshake succeeded.
00248  */
00249 EXP_FUNC SSL * STDCALL ssl_client_new(SSL *ssl, int client_fd, const uint8_t *session_id, uint8_t sess_id_size);
00250 
00251 /**
00252  * @brief Free any used resources on this connection. 
00253  
00254  * A "Close Notify" message is sent on this connection (if possible). It is up 
00255  * to the application to close the socket or file descriptor.
00256  * @param ssl [in] The ssl object reference.
00257  */
00258 EXP_FUNC void STDCALL ssl_free(SSL *ssl);
00259 
00260 /**
00261  * @brief Read the SSL data stream.
00262  * If the socket is non-blocking and data is blocked then SSO_OK will be
00263  * returned.
00264  * @param ssl [in] An SSL object reference.
00265  * @param in_data [out] If the read was successful, a pointer to the read
00266  * buffer will be here. Do NOT ever free this memory as this buffer is used in
00267  * sucessive calls. If the call was unsuccessful, this value will be null.
00268  * @return The number of decrypted bytes:
00269  * - if > 0, then the handshaking is complete and we are returning the number 
00270  *   of decrypted bytes. 
00271  * - SSL_OK if the handshaking stage is successful (but not yet complete).  
00272  * - < 0 if an error.
00273  * @see ssl.h for the error code list.
00274  * @note Use in_data before doing any successive ssl calls.
00275  */
00276 //EXP_FUNC int STDCALL ssl_read(SSL *ssl, uint8_t **in_data);
00277 
00278 /**
00279  * @brief Write to the SSL data stream. 
00280  * if the socket is non-blocking and data is blocked then a check is made
00281  * to ensure that all data is sent (i.e. blocked mode is forced).
00282  * @param ssl [in] An SSL obect reference.
00283  * @param out_data [in] The data to be written
00284  * @param out_len [in] The number of bytes to be written.
00285  * @return The number of bytes sent, or if < 0 if an error.
00286  * @see ssl.h for the error code list.
00287  */
00288 EXP_FUNC int STDCALL ssl_write(SSL *ssl, const uint8_t *out_data, int out_len);
00289 
00290 /**
00291  * @brief Find an ssl object based on a file descriptor.
00292  *
00293  * Goes through the list of SSL objects maintained in a client/server context
00294  * to look for a file descriptor match.
00295  * @param ssl_ctx [in] The client/server context.
00296  * @param client_fd [in]  The file descriptor.
00297  * @return A reference to the SSL object. Returns null if the object could not 
00298  * be found.
00299  */
00300 EXP_FUNC SSL * STDCALL ssl_find(SSL_CTX *ssl_ctx, int client_fd);
00301 
00302 /**
00303  * @brief Get the session id for a handshake. 
00304  * 
00305  * This will be a 32 byte sequence and is available after the first
00306  * handshaking messages are sent.
00307  * @param ssl [in] An SSL object reference.
00308  * @return The session id as a 32 byte sequence.
00309  * @note A SSLv23 handshake may have only 16 valid bytes.
00310  */
00311 EXP_FUNC const uint8_t * STDCALL ssl_get_session_id(const SSL *ssl);
00312 
00313 /**
00314  * @brief Get the session id size for a handshake. 
00315  * 
00316  * This will normally be 32 but could be 0 (no session id) or something else.
00317  * @param ssl [in] An SSL object reference.
00318  * @return The size of the session id.
00319  */
00320 EXP_FUNC uint8_t STDCALL ssl_get_session_id_size(const SSL *ssl);
00321 
00322 /**
00323  * @brief Return the cipher id (in the SSL form).
00324  * @param ssl [in] An SSL object reference.
00325  * @return The cipher id. This will be one of the following:
00326  * - SSL_AES128_SHA (0x2f)
00327  * - SSL_AES256_SHA (0x35)
00328  * - SSL_RC4_128_SHA (0x05)
00329  * - SSL_RC4_128_MD5 (0x04)
00330  */
00331 EXP_FUNC uint8_t STDCALL ssl_get_cipher_id(const SSL *ssl);
00332 
00333 /**
00334  * @brief Return the status of the handshake.
00335  * @param ssl [in] An SSL object reference.
00336  * @return SSL_OK if the handshake is complete and ok. 
00337  * @see ssl.h for the error code list.
00338  */
00339 EXP_FUNC int STDCALL ssl_handshake_status(const SSL *ssl);
00340 
00341 /**
00342  * @brief Retrieve various parameters about the axTLS engine.
00343  * @param offset [in] The configuration offset. It will be one of the following:
00344  * - SSL_BUILD_MODE The build mode. This will be one of the following:
00345  *   - SSL_BUILD_SERVER_ONLY            (basic server mode)
00346  *   - SSL_BUILD_ENABLE_VERIFICATION    (server can do client authentication)
00347  *   - SSL_BUILD_ENABLE_CLIENT          (client/server capabilties)
00348  *   - SSL_BUILD_FULL_MODE              (client/server with diagnostics)
00349  *   - SSL_BUILD_SKELETON_MODE          (skeleton mode)
00350  * - SSL_MAX_CERT_CFG_OFFSET The maximum number of certificates allowed.
00351  * - SSL_MAX_CA_CERT_CFG_OFFSET The maximum number of CA certificates allowed.
00352  * - SSL_HAS_PEM                        1 if supported
00353  * @return The value of the requested parameter.
00354  */
00355 EXP_FUNC int STDCALL ssl_get_config(int offset);
00356 
00357 /**
00358  * @brief Display why the handshake failed.
00359  *
00360  * This call is only useful in a 'full mode' build. The output is to stdout.
00361  * @param error_code [in] An error code.
00362  * @see ssl.h for the error code list.
00363  */
00364 EXP_FUNC void STDCALL ssl_display_error(int error_code);
00365 
00366 /**
00367  * @brief Authenticate a received certificate.
00368  * 
00369  * This call is usually made by a client after a handshake is complete and the
00370  * context is in SSL_SERVER_VERIFY_LATER mode.
00371  * @param ssl [in] An SSL object reference.
00372  * @return SSL_OK if the certificate is verified.
00373  */
00374 EXP_FUNC int STDCALL ssl_verify_cert(const SSL *ssl, PrecomputedCertificate *cert);
00375 
00376 /**
00377  * @brief Retrieve an X.509 distinguished name component.
00378  * 
00379  * When a handshake is complete and a certificate has been exchanged, then the
00380  * details of the remote certificate can be retrieved.
00381  *
00382  * This will usually be used by a client to check that the server's common 
00383  * name matches the URL.
00384  *
00385  * @param ssl [in] An SSL object reference.
00386  * @param component [in] one of:
00387  * - SSL_X509_CERT_COMMON_NAME
00388  * - SSL_X509_CERT_ORGANIZATION
00389  * - SSL_X509_CERT_ORGANIZATIONAL_NAME
00390  * - SSL_X509_CA_CERT_COMMON_NAME
00391  * - SSL_X509_CA_CERT_ORGANIZATION
00392  * - SSL_X509_CA_CERT_ORGANIZATIONAL_NAME
00393  * @return The appropriate string (or null if not defined)
00394  * @note Verification build mode must be enabled.
00395  */
00396 EXP_FUNC const char * STDCALL ssl_get_cert_dn(const SSL *ssl, int component);
00397 
00398 /**
00399  * @brief Retrieve a Subject Alternative DNSName
00400  *
00401  * When a handshake is complete and a certificate has been exchanged, then the
00402  * details of the remote certificate can be retrieved.
00403  *
00404  * This will usually be used by a client to check that the server's DNS  
00405  * name matches the URL.
00406  *
00407  * @param ssl [in] An SSL object reference.
00408  * @param dnsindex [in] The index of the DNS name to retrieve.
00409  * @return The appropriate string (or null if not defined)
00410  * @note Verification build mode must be enabled.
00411  */
00412 EXP_FUNC const char * STDCALL ssl_get_cert_subject_alt_dnsname(const SSL *ssl, int dnsindex);
00413 
00414 /**
00415  * @brief Force the client to perform its handshake again.
00416  *
00417  * For a client this involves sending another "client hello" message.
00418  * For the server is means sending a "hello request" message.
00419  *
00420  * This is a blocking call on the client (until the handshake completes).
00421  *
00422  * @param ssl [in] An SSL object reference.
00423  * @return SSL_OK if renegotiation instantiation was ok
00424  */
00425 EXP_FUNC int STDCALL ssl_renegotiate(SSL *ssl);
00426 
00427 /**
00428  * @brief Process a file that is in binary DER or ASCII PEM format.
00429  *
00430  * These are temporary objects that are used to load private keys,
00431  * certificates etc into memory.
00432  * @param ssl_ctx [in] The client/server context.
00433  * @param obj_type [in] The format of the file. Can be one of:
00434  * - SSL_OBJ_X509_CERT (no password required)
00435  * - SSL_OBJ_X509_CACERT (no password required)
00436  * - SSL_OBJ_RSA_KEY (AES128/AES256 PEM encryption supported)
00437  * - SSL_OBJ_PKCS8 (RC4-128 encrypted data supported)
00438  * - SSL_OBJ_PKCS12 (RC4-128 encrypted data supported)
00439  *
00440  * PEM files are automatically detected (if supported). The object type is
00441  * also detected, and so is not relevant for these types of files.
00442  * @param filename [in] The location of a file in DER/PEM format.
00443  * @param password [in] The password used. Can be null if not required.
00444  * @return SSL_OK if all ok
00445  * @note Not available in skeleton build mode.
00446  */
00447 EXP_FUNC int STDCALL ssl_obj_load(SSL_CTX *ssl_ctx, int obj_type, const char *filename, const char *password);
00448 
00449 /**
00450  * @brief Process binary data.
00451  *
00452  * These are temporary objects that are used to load private keys,
00453  * certificates etc into memory.
00454  * @param ssl_ctx [in] The client/server context.
00455  * @param obj_type [in] The format of the memory data.
00456  * @param data [in] The binary data to be loaded.
00457  * @param len [in] The amount of data to be loaded.
00458  * @param password [in] The password used. Can be null if not required.
00459  * @return SSL_OK if all ok
00460  * @see ssl_obj_load for more details on obj_type.
00461  */
00462 EXP_FUNC int STDCALL ssl_obj_memory_load(SSL_CTX *ssl_ctx, int obj_type, const uint8_t *data, int len, const char *password);
00463 
00464 #ifdef CONFIG_SSL_GENERATE_X509_CERT
00465 /**
00466  * @brief Create an X.509 certificate. 
00467  * 
00468  * This certificate is a self-signed v1 cert with a fixed start/stop validity 
00469  * times. It is signed with an internal private key in ssl_ctx.
00470  *
00471  * @param ssl_ctx [in] The client/server context.
00472  * @param options [in] Not used yet.
00473  * @param dn [in] An array of distinguished name strings. The array is defined
00474  * by:
00475  * - SSL_X509_CERT_COMMON_NAME (0)
00476  *      - If SSL_X509_CERT_COMMON_NAME is empty or not defined, then the 
00477  *        hostname will be used.
00478  * - SSL_X509_CERT_ORGANIZATION (1)
00479  *      - If SSL_X509_CERT_ORGANIZATION is empty or not defined, then $USERNAME 
00480  *        will be used.
00481  * - SSL_X509_CERT_ORGANIZATIONAL_NAME (2)
00482  *      - SSL_X509_CERT_ORGANIZATIONAL_NAME is optional.
00483  * @param cert_data [out] The certificate as a sequence of bytes.
00484  * @return < 0 if an error, or the size of the certificate in bytes.
00485  * @note cert_data must be freed when there is no more need for it.
00486  */
00487 EXP_FUNC int STDCALL ssl_x509_create(SSL_CTX *ssl_ctx, uint32_t options, const char * dn[], uint8_t **cert_data);
00488 #endif
00489 
00490 /**
00491  * @brief Return the axTLS library version as a string.
00492  */
00493 EXP_FUNC const char * STDCALL ssl_version(void);
00494 
00495 /** @} */
00496 
00497 #ifdef __cplusplus
00498 }
00499 #endif
00500 
00501 #endif
00502 
00503