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 171