Ashley Mills / axTLS

Rough and ready port of axTLS

ssl/ssl.h@0:5a29fd060ac8, 2013-05-13 (annotated)

Committer:
ashleymills
Date:
Mon May 13 18:15:18 2013 +0000
Revision:
0:5a29fd060ac8
initial commit

Who changed what in which revision?

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