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