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(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_CTX *ssl_ctx, 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 500