Mercurial > projects > hoofbaby

comparison deps/Platinum/ThirdParty/Neptune/ThirdParty/axTLS/ssl/ssl.h @ 0:3425707ddbf6

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Initial import (hopefully this mercurial stuff works...)
author fraserofthenight
date Mon, 06 Jul 2009 08:06:28 -0700
parents
children
comparison
equal deleted inserted replaced
-1:000000000000 0:3425707ddbf6
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 /*#include "crypto.h"*/
72
73 /* need to predefine before ssl_lib.h gets to it */
74 #define SSL_SESSION_ID_SIZE 32
75
76 #include "tls1.h"
77
78 /* The optional parameters that can be given to the client/server SSL engine */
79 #define SSL_CLIENT_AUTHENTICATION 0x00010000
80 #define SSL_SERVER_VERIFY_LATER 0x00020000
81 #define SSL_NO_DEFAULT_KEY 0x00040000
82 #define SSL_DISPLAY_STATES 0x00080000
83 #define SSL_DISPLAY_BYTES 0x00100000
84 #define SSL_DISPLAY_CERTS 0x00200000
85 #define SSL_DISPLAY_RSA 0x00400000
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_ERROR_CONN_LOST -256
92 #define SSL_ERROR_SOCK_SETUP_FAILURE -258
93 #define SSL_ERROR_INVALID_HANDSHAKE -260
94 #define SSL_ERROR_INVALID_PROT_MSG -261
95 #define SSL_ERROR_INVALID_HMAC -262
96 #define SSL_ERROR_INVALID_VERSION -263
97 #define SSL_ERROR_INVALID_SESSION -265
98 #define SSL_ERROR_NO_CIPHER -266
99 #define SSL_ERROR_BAD_CERTIFICATE -268
100 #define SSL_ERROR_INVALID_KEY -269
101 #define SSL_ERROR_FINISHED_INVALID -271
102 #define SSL_ERROR_NO_CERT_DEFINED -272
103 #define SSL_ERROR_NOT_SUPPORTED -274
104 #define SSL_ERROR_TIMEOUT -275 /* GBG */
105 #define SSL_ERROR_EOS -276 /* GBG */
106 #define SSL_X509_OFFSET -512
107 #define SSL_X509_ERROR(A) (SSL_X509_OFFSET+A)
108
109 /* these are all the alerts that are recognized */
110 #define SSL_ALERT_CLOSE_NOTIFY 0
111 #define SSL_ALERT_UNEXPECTED_MESSAGE 10
112 #define SSL_ALERT_BAD_RECORD_MAC 20
113 #define SSL_ALERT_HANDSHAKE_FAILURE 40
114 #define SSL_ALERT_BAD_CERTIFICATE 42
115 #define SSL_ALERT_ILLEGAL_PARAMETER 47
116 #define SSL_ALERT_DECODE_ERROR 50
117 #define SSL_ALERT_DECRYPT_ERROR 51
118 #define SSL_ALERT_INVALID_VERSION 70
119
120 /* The ciphers that are supported */
121 #define SSL_AES128_SHA 0x2f
122 #define SSL_AES256_SHA 0x35
123 #define SSL_RC4_128_SHA 0x05
124 #define SSL_RC4_128_MD5 0x04
125
126 /* build mode ids' */
127 #define SSL_BUILD_SKELETON_MODE 0x01
128 #define SSL_BUILD_SERVER_ONLY 0x02
129 #define SSL_BUILD_ENABLE_VERIFICATION 0x03
130 #define SSL_BUILD_ENABLE_CLIENT 0x04
131 #define SSL_BUILD_FULL_MODE 0x05
132
133 /* offsets to retrieve configuration information */
134 #define SSL_BUILD_MODE 0
135 #define SSL_MAX_CERT_CFG_OFFSET 1
136 #define SSL_MAX_CA_CERT_CFG_OFFSET 2
137 #define SSL_HAS_PEM 3
138
139 /* default session sizes */
140 #define SSL_DEFAULT_SVR_SESS 5
141 #define SSL_DEFAULT_CLNT_SESS 1
142
143 /* X.509/X.520 distinguished name types */
144 #define SSL_X509_CERT_COMMON_NAME 0
145 #define SSL_X509_CERT_ORGANIZATION 1
146 #define SSL_X509_CERT_ORGANIZATIONAL_NAME 2
147 #define SSL_X509_CA_CERT_COMMON_NAME 3
148 #define SSL_X509_CA_CERT_ORGANIZATION 4
149 #define SSL_X509_CA_CERT_ORGANIZATIONAL_NAME 5
150
151 /* SSL object loader types */
152 #define SSL_OBJ_X509_CERT 1
153 #define SSL_OBJ_X509_CACERT 2
154 #define SSL_OBJ_RSA_KEY 3
155 #define SSL_OBJ_PKCS8 4
156 #define SSL_OBJ_PKCS12 5
157
158 /**
159 * @defgroup c_api Standard C API
160 * @brief The standard interface in C.
161 * @{
162 */
163
164 /**
165 * @brief Establish a new client/server context.
166 *
167 * This function is called before any client/server SSL connections are made.
168 *
169 * Each new connection will use the this context's private key and
170 * certificate chain. If a different certificate chain is required, then a
171 * different context needs to be be used.
172 *
173 * There are two threading models supported - a single thread with one
174 * SSL_CTX can support any number of SSL connections - and multiple threads can
175 * support one SSL_CTX object each (the default). But if a single SSL_CTX
176 * object uses many SSL objects in individual threads, then the
177 * CONFIG_SSL_CTX_MUTEXING option needs to be configured.
178 *
179 * @param options [in] Any particular options. At present the options
180 * supported are:
181 * - SSL_SERVER_VERIFY_LATER (client only): Don't stop a handshake if the server
182 * authentication fails. The certificate can be authenticated later with a
183 * call to ssl_verify_cert().
184 * - SSL_CLIENT_AUTHENTICATION (server only): Enforce client authentication
185 * i.e. each handshake will include a "certificate request" message from the
186 * server. Only available if verification has been enabled.
187 * - SSL_DISPLAY_BYTES (full mode build only): Display the byte sequences
188 * during the handshake.
189 * - SSL_DISPLAY_STATES (full mode build only): Display the state changes
190 * during the handshake.
191 * - SSL_DISPLAY_CERTS (full mode build only): Display the certificates that
192 * are passed during a handshake.
193 * - SSL_DISPLAY_RSA (full mode build only): Display the RSA key details that
194 * are passed during a handshake.
195 *
196 * @param num_sessions [in] The number of sessions to be used for session
197 * caching. If this value is 0, then there is no session caching. This option
198 * is not used in skeleton mode.
199 * @return A client/server context.
200 */
201 EXP_FUNC SSL_CTX * STDCALL ssl_ctx_new(uint32_t options, int num_sessions);
202
203 /**
204 * @brief Remove a client/server context.
205 *
206 * Frees any used resources used by this context. Each connection will be
207 * sent a "Close Notify" alert (if possible).
208 * @param ssl_ctx [in] The client/server context.
209 */
210 EXP_FUNC void STDCALL ssl_ctx_free(SSL_CTX *ssl_ctx);
211
212 /**
213 * @brief (server only) Establish a new SSL connection to an SSL client.
214 *
215 * It is up to the application to establish the logical connection (whether it
216 * is a socket, serial connection etc).
217 * @param ssl_ctx [in] The server context.
218 * @param client_fd [in] The client's file descriptor.
219 * @return An SSL object reference.
220 */
221 EXP_FUNC SSL * STDCALL ssl_server_new(SSL_CTX *ssl_ctx, SSL_SOCKET* client_fd);
222
223 /**
224 * @brief (client only) Establish a new SSL connection to an SSL server.
225 *
226 * It is up to the application to establish the initial logical connection
227 * (whether it is a socket, serial connection etc).
228 *
229 * This is a blocking call - it will finish when the handshake is complete (or
230 * has failed).
231 * @param ssl_ctx [in] The client context.
232 * @param client_fd [in] The client's file descriptor.
233 * @param session_id [in] A 32 byte session id for session resumption. This
234 * can be null if no session resumption is being used or required. This option
235 * is not used in skeleton mode.
236 * @param sess_id_size The size of the session id (max 32)
237 * @return An SSL object reference. Use ssl_handshake_status() to check
238 * if a handshake succeeded.
239 */
240 EXP_FUNC SSL * STDCALL ssl_client_new(SSL_CTX *ssl_ctx, SSL_SOCKET* client_fd, const uint8_t *session_id, uint8_t sess_id_size);
241
242 /**
243 * @brief Free any used resources on this connection.
244
245 * A "Close Notify" message is sent on this connection (if possible). It is up
246 * to the application to close the socket or file descriptor.
247 * @param ssl [in] The ssl object reference.
248 */
249 EXP_FUNC void STDCALL ssl_free(SSL *ssl);
250
251 /**
252 * @brief Read the SSL data stream.
253 * The socket must be in blocking mode.
254 * @param ssl [in] An SSL object reference.
255 * @param in_data [out] If the read was successful, a pointer to the read
256 * buffer will be here. Do NOT ever free this memory as this buffer is used in
257 * sucessive calls. If the call was unsuccessful, this value will be null.
258 * @return The number of decrypted bytes:
259 * - if > 0, then the handshaking is complete and we are returning the number
260 * of decrypted bytes.
261 * - SSL_OK if the handshaking stage is successful (but not yet complete).
262 * - < 0 if an error.
263 * @see ssl.h for the error code list.
264 * @note Use in_data before doing any successive ssl calls.
265 */
266 EXP_FUNC int STDCALL ssl_read(SSL *ssl, uint8_t **in_data);
267
268 /**
269 * @brief Write to the SSL data stream.
270 * The socket must be in blocking mode.
271 * @param ssl [in] An SSL obect reference.
272 * @param out_data [in] The data to be written
273 * @param out_len [in] The number of bytes to be written.
274 * @return The number of bytes sent, or if < 0 if an error.
275 * @see ssl.h for the error code list.
276 */
277 EXP_FUNC int STDCALL ssl_write(SSL *ssl, const uint8_t *out_data, int out_len);
278
279 /**
280 * @brief Find an ssl object based on a file descriptor.
281 *
282 * Goes through the list of SSL objects maintained in a client/server context
283 * to look for a file descriptor match.
284 * @param ssl_ctx [in] The client/server context.
285 * @param client_fd [in] The file descriptor.
286 * @return A reference to the SSL object. Returns null if the object could not
287 * be found.
288 */
289 EXP_FUNC SSL * STDCALL ssl_find(SSL_CTX *ssl_ctx, SSL_SOCKET* client_fd);
290
291 /**
292 * @brief Get the session id for a handshake.
293 *
294 * This will be a 32 byte sequence and is available after the first
295 * handshaking messages are sent.
296 * @param ssl [in] An SSL object reference.
297 * @return The session id as a 32 byte sequence.
298 * @note A SSLv23 handshake may have only 16 valid bytes.
299 */
300 EXP_FUNC const uint8_t * STDCALL ssl_get_session_id(const SSL *ssl);
301
302 /**
303 * @brief Get the session id size for a handshake.
304 *
305 * This will normally be 32 but could be 0 (no session id) or something else.
306 * @param ssl [in] An SSL object reference.
307 * @return The size of the session id.
308 */
309 EXP_FUNC uint8_t STDCALL ssl_get_session_id_size(const SSL *ssl);
310
311 /**
312 * @brief Return the cipher id (in the SSL form).
313 * @param ssl [in] An SSL object reference.
314 * @return The cipher id. This will be one of the following:
315 * - SSL_AES128_SHA (0x2f)
316 * - SSL_AES256_SHA (0x35)
317 * - SSL_RC4_128_SHA (0x05)
318 * - SSL_RC4_128_MD5 (0x04)
319 */
320 EXP_FUNC uint8_t STDCALL ssl_get_cipher_id(const SSL *ssl);
321
322 /**
323 * @brief Return the status of the handshake.
324 * @param ssl [in] An SSL object reference.
325 * @return SSL_OK if the handshake is complete and ok.
326 * @see ssl.h for the error code list.
327 */
328 EXP_FUNC int STDCALL ssl_handshake_status(const SSL *ssl);
329
330 /**
331 * @brief Retrieve various parameters about the axTLS engine.
332 * @param offset [in] The configuration offset. It will be one of the following:
333 * - SSL_BUILD_MODE The build mode. This will be one of the following:
334 * - SSL_BUILD_SERVER_ONLY (basic server mode)
335 * - SSL_BUILD_ENABLE_VERIFICATION (server can do client authentication)
336 * - SSL_BUILD_ENABLE_CLIENT (client/server capabilties)
337 * - SSL_BUILD_FULL_MODE (client/server with diagnostics)
338 * - SSL_BUILD_SKELETON_MODE (skeleton mode)
339 * - SSL_MAX_CERT_CFG_OFFSET The maximum number of certificates allowed.
340 * - SSL_MAX_CA_CERT_CFG_OFFSET The maximum number of CA certificates allowed.
341 * - SSL_HAS_PEM 1 if supported
342 * @return The value of the requested parameter.
343 */
344 EXP_FUNC int STDCALL ssl_get_config(int offset);
345
346 /**
347 * @brief Display why the handshake failed.
348 *
349 * This call is only useful in a 'full mode' build. The output is to stdout.
350 * @param error_code [in] An error code.
351 * @see ssl.h for the error code list.
352 */
353 EXP_FUNC void STDCALL ssl_display_error(int error_code);
354
355 /**
356 * @brief Authenticate a received certificate.
357 *
358 * This call is usually made by a client after a handshake is complete and the
359 * context is in SSL_SERVER_VERIFY_LATER mode.
360 * @param ssl [in] An SSL object reference.
361 * @return SSL_OK if the certificate is verified.
362 */
363 EXP_FUNC int STDCALL ssl_verify_cert(const SSL *ssl);
364
365 /**
366 * @brief Retrieve an X.509 distinguished name component.
367 *
368 * When a handshake is complete and a certificate has been exchanged, then the
369 * details of the remote certificate can be retrieved.
370 *
371 * This will usually be used by a client to check that the server's common
372 * name matches the URL.
373 *
374 * A full handshake needs to occur for this call to work properly.
375 *
376 * @param ssl [in] An SSL object reference.
377 * @param component [in] one of:
378 * - SSL_X509_CERT_COMMON_NAME
379 * - SSL_X509_CERT_ORGANIZATION
380 * - SSL_X509_CERT_ORGANIZATIONAL_NAME
381 * - SSL_X509_CA_CERT_COMMON_NAME
382 * - SSL_X509_CA_CERT_ORGANIZATION
383 * - SSL_X509_CA_CERT_ORGANIZATIONAL_NAME
384 * @return The appropriate string (or null if not defined)
385 * @note Verification build mode must be enabled.
386 */
387 EXP_FUNC const char * STDCALL ssl_get_cert_dn(const SSL *ssl, int component);
388
389 /* GBG added */
390 EXP_FUNC void ssl_get_cert_fingerprints(const SSL* ssl, unsigned char* md5, unsigned char* sha1);
391
392 /**
393 * @brief Force the client to perform its handshake again.
394 *
395 * For a client this involves sending another "client hello" message.
396 * For the server is means sending a "hello request" message.
397 *
398 * This is a blocking call on the client (until the handshake completes).
399 *
400 * @param ssl [in] An SSL object reference.
401 * @return SSL_OK if renegotiation instantiation was ok
402 */
403 EXP_FUNC int STDCALL ssl_renegotiate(SSL *ssl);
404
405 /**
406 * @brief Process a file that is in binary DER or ASCII PEM format.
407 *
408 * These are temporary objects that are used to load private keys,
409 * certificates etc into memory.
410 * @param ssl_ctx [in] The client/server context.
411 * @param obj_type [in] The format of the file. Can be one of:
412 * - SSL_OBJ_X509_CERT (no password required)
413 * - SSL_OBJ_X509_CACERT (no password required)
414 * - SSL_OBJ_RSA_KEY (AES128/AES256 PEM encryption supported)
415 * - SSL_OBJ_PKCS8 (RC4-128 encrypted data supported)
416 * - SSL_OBJ_PKCS12 (RC4-128 encrypted data supported)
417 *
418 * PEM files are automatically detected (if supported). The object type is
419 * also detected, and so is not relevant for these types of files.
420 * @param filename [in] The location of a file in DER/PEM format.
421 * @param password [in] The password used. Can be null if not required.
422 * @return SSL_OK if all ok
423 * @note Not available in skeleton build mode.
424 */
425 EXP_FUNC int STDCALL ssl_obj_load(SSL_CTX *ssl_ctx, int obj_type, const char *filename, const char *password);
426
427 /**
428 * @brief Process binary data.
429 *
430 * These are temporary objects that are used to load private keys,
431 * certificates etc into memory.
432 * @param ssl_ctx [in] The client/server context.
433 * @param obj_type [in] The format of the memory data.
434 * @param data [in] The binary data to be loaded.
435 * @param len [in] The amount of data to be loaded.
436 * @param password [in] The password used. Can be null if not required.
437 * @return SSL_OK if all ok
438 * @see ssl_obj_load for more details on obj_type.
439 */
440 EXP_FUNC int STDCALL ssl_obj_memory_load(SSL_CTX *ssl_ctx, int obj_type, const uint8_t *data, int len, const char *password);
441
442 #ifdef CONFIG_SSL_GENERATE_X509_CERT
443 /**
444 * @brief Create an X.509 certificate.
445 *
446 * This certificate is a self-signed v1 cert with a fixed start/stop validity
447 * times. It is signed with an internal private key in ssl_ctx.
448 *
449 * @param ssl_ctx [in] The client/server context.
450 * @param options [in] Not used yet.
451 * @param dn [in] An array of distinguished name strings. The array is defined
452 * by:
453 * - SSL_X509_CERT_COMMON_NAME (0)
454 * - If SSL_X509_CERT_COMMON_NAME is empty or not defined, then the
455 * hostname will be used.
456 * - SSL_X509_CERT_ORGANIZATION (1)
457 * - If SSL_X509_CERT_ORGANIZATION is empty or not defined, then $USERNAME
458 * will be used.
459 * - SSL_X509_CERT_ORGANIZATIONAL_NAME (2)
460 * - SSL_X509_CERT_ORGANIZATIONAL_NAME is optional.
461 * @param cert_data [out] The certificate as a sequence of bytes.
462 * @return < 0 if an error, or the size of the certificate in bytes.
463 * @note cert_data must be freed when there is no more need for it.
464 */
465 EXP_FUNC int STDCALL ssl_x509_create(SSL_CTX *ssl_ctx, uint32_t options, const char * dn[], uint8_t **cert_data);
466 #endif
467
468 /**
469 * @brief Return the axTLS library version as a string.
470 */
471 EXP_FUNC const char * STDCALL ssl_version(void);
472
473 /** @} */
474
475 #ifdef __cplusplus
476 }
477 #endif
478
479 #endif