Added macro that indicates presence of the time callback feature. Also added C++...
[BearSSL] / inc / bearssl.h
1 /*
2 * Copyright (c) 2016 Thomas Pornin <pornin@bolet.org>
3 *
4 * Permission is hereby granted, free of charge, to any person obtaining
5 * a copy of this software and associated documentation files (the
6 * "Software"), to deal in the Software without restriction, including
7 * without limitation the rights to use, copy, modify, merge, publish,
8 * distribute, sublicense, and/or sell copies of the Software, and to
9 * permit persons to whom the Software is furnished to do so, subject to
10 * the following conditions:
11 *
12 * The above copyright notice and this permission notice shall be
13 * included in all copies or substantial portions of the Software.
14 *
15 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
16 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
17 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
18 * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
19 * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
20 * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
21 * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
22 * SOFTWARE.
23 */
24
25 #ifndef BR_BEARSSL_H__
26 #define BR_BEARSSL_H__
27
28 #include <stddef.h>
29 #include <stdint.h>
30
31 /** \mainpage BearSSL API
32 *
33 * # API Layout
34 *
35 * The functions and structures defined by the BearSSL API are located
36 * in various header files:
37 *
38 * | Header file | Elements |
39 * | :-------------- | :------------------------------------------------ |
40 * | bearssl_hash.h | Hash functions |
41 * | bearssl_hmac.h | HMAC |
42 * | bearssl_kdf.h | Key Derivation Functions |
43 * | bearssl_rand.h | Pseudorandom byte generators |
44 * | bearssl_prf.h | PRF implementations (for SSL/TLS) |
45 * | bearssl_block.h | Symmetric encryption |
46 * | bearssl_aead.h | AEAD algorithms (combined encryption + MAC) |
47 * | bearssl_rsa.h | RSA encryption and signatures |
48 * | bearssl_ec.h | Elliptic curves support (including ECDSA) |
49 * | bearssl_ssl.h | SSL/TLS engine interface |
50 * | bearssl_x509.h | X.509 certificate decoding and validation |
51 * | bearssl_pem.h | Base64/PEM decoding support functions |
52 *
53 * Applications using BearSSL are supposed to simply include `bearssl.h`
54 * as follows:
55 *
56 * #include <bearssl.h>
57 *
58 * The `bearssl.h` file itself includes all the other header files. It is
59 * possible to include specific header files, but it has no practical
60 * advantage for the application. The API is separated into separate
61 * header files only for documentation convenience.
62 *
63 *
64 * # Conventions
65 *
66 * ## MUST and SHALL
67 *
68 * In all descriptions, the usual "MUST", "SHALL", "MAY",... terminology
69 * is used. Failure to meet requirements expressed with a "MUST" or
70 * "SHALL" implies undefined behaviour, which means that segmentation
71 * faults, buffer overflows, and other similar adverse events, may occur.
72 *
73 * In general, BearSSL is not very forgiving of programming errors, and
74 * does not include much failsafes or error reporting when the problem
75 * does not arise from external transient conditions, and can be fixed
76 * only in the application code. This is done so in order to make the
77 * total code footprint lighter.
78 *
79 *
80 * ## `NULL` values
81 *
82 * Function parameters with a pointer type shall not be `NULL` unless
83 * explicitly authorised by the documentation. As an exception, when
84 * the pointer aims at a sequence of bytes and is accompanied with
85 * a length parameter, and the length is zero (meaning that there is
86 * no byte at all to retrieve), then the pointer may be `NULL` even if
87 * not explicitly allowed.
88 *
89 *
90 * ## Memory Allocation
91 *
92 * BearSSL does not perform dynamic memory allocation. This implies that
93 * for any functionality that requires a non-transient state, the caller
94 * is responsible for allocating the relevant context structure. Such
95 * allocation can be done in any appropriate area, including static data
96 * segments, the heap, and the stack, provided that proper alignment is
97 * respected. The header files define these context structures
98 * (including size and contents), so the C compiler should handle
99 * alignment automatically.
100 *
101 * Since there is no dynamic resource allocation, there is also nothing to
102 * release. When the calling code is done with a BearSSL feature, it
103 * may simple release the context structures it allocated itself, with
104 * no "close function" to call. If the context structures were allocated
105 * on the stack (as local variables), then even that release operation is
106 * implicit.
107 *
108 *
109 * ## Structure Contents
110 *
111 * Except when explicitly indicated, structure contents are opaque: they
112 * are included in the header files so that calling code may know the
113 * structure sizes and alignment requirements, but callers SHALL NOT
114 * access individual fields directly. For fields that are supposed to
115 * be read from or written to, the API defines accessor functions (the
116 * simplest of these accessor functions are defined as `static inline`
117 * functions, and the C compiler will optimise them away).
118 *
119 *
120 * # API Usage
121 *
122 * BearSSL usage for running a SSL/TLS client or server is described
123 * on the [BearSSL Web site](https://www.bearssl.org/api1.html). The
124 * BearSSL source archive also comes with sample code.
125 */
126
127 #include "bearssl_hash.h"
128 #include "bearssl_hmac.h"
129 #include "bearssl_kdf.h"
130 #include "bearssl_rand.h"
131 #include "bearssl_prf.h"
132 #include "bearssl_block.h"
133 #include "bearssl_aead.h"
134 #include "bearssl_rsa.h"
135 #include "bearssl_ec.h"
136 #include "bearssl_ssl.h"
137 #include "bearssl_x509.h"
138 #include "bearssl_pem.h"
139
140 /** \brief Type for a configuration option.
141 *
142 * A "configuration option" is a value that is selected when the BearSSL
143 * library itself is compiled. Most options are boolean; their value is
144 * then either 1 (option is enabled) or 0 (option is disabled). Some
145 * values have other integer values. Option names correspond to macro
146 * names. Some of the options can be explicitly set in the internal
147 * `"config.h"` file.
148 */
149 typedef struct {
150 /** \brief Configurable option name. */
151 const char *name;
152 /** \brief Configurable option value. */
153 long value;
154 } br_config_option;
155
156 /** \brief Get configuration report.
157 *
158 * This function returns compiled configuration options, each as a
159 * 'long' value. Names match internal macro names, in particular those
160 * that can be set in the `"config.h"` inner file. For boolean options,
161 * the numerical value is 1 if enabled, 0 if disabled. For maximum
162 * key sizes, values are expressed in bits.
163 *
164 * The returned array is terminated by an entry whose `name` is `NULL`.
165 *
166 * \return the configuration report.
167 */
168 const br_config_option *br_get_config(void);
169
170 #endif