10957b409SSimon J. Gerraty /* 20957b409SSimon J. Gerraty * Copyright (c) 2016 Thomas Pornin <pornin@bolet.org> 30957b409SSimon J. Gerraty * 40957b409SSimon J. Gerraty * Permission is hereby granted, free of charge, to any person obtaining 50957b409SSimon J. Gerraty * a copy of this software and associated documentation files (the 60957b409SSimon J. Gerraty * "Software"), to deal in the Software without restriction, including 70957b409SSimon J. Gerraty * without limitation the rights to use, copy, modify, merge, publish, 80957b409SSimon J. Gerraty * distribute, sublicense, and/or sell copies of the Software, and to 90957b409SSimon J. Gerraty * permit persons to whom the Software is furnished to do so, subject to 100957b409SSimon J. Gerraty * the following conditions: 110957b409SSimon J. Gerraty * 120957b409SSimon J. Gerraty * The above copyright notice and this permission notice shall be 130957b409SSimon J. Gerraty * included in all copies or substantial portions of the Software. 140957b409SSimon J. Gerraty * 150957b409SSimon J. Gerraty * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, 160957b409SSimon J. Gerraty * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 170957b409SSimon J. Gerraty * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND 180957b409SSimon J. Gerraty * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS 190957b409SSimon J. Gerraty * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN 200957b409SSimon J. Gerraty * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN 210957b409SSimon J. Gerraty * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 220957b409SSimon J. Gerraty * SOFTWARE. 230957b409SSimon J. Gerraty */ 240957b409SSimon J. Gerraty 250957b409SSimon J. Gerraty #ifndef BR_BEARSSL_H__ 260957b409SSimon J. Gerraty #define BR_BEARSSL_H__ 270957b409SSimon J. Gerraty 280957b409SSimon J. Gerraty #include <stddef.h> 290957b409SSimon J. Gerraty #include <stdint.h> 300957b409SSimon J. Gerraty 310957b409SSimon J. Gerraty /** \mainpage BearSSL API 320957b409SSimon J. Gerraty * 330957b409SSimon J. Gerraty * # API Layout 340957b409SSimon J. Gerraty * 350957b409SSimon J. Gerraty * The functions and structures defined by the BearSSL API are located 360957b409SSimon J. Gerraty * in various header files: 370957b409SSimon J. Gerraty * 380957b409SSimon J. Gerraty * | Header file | Elements | 390957b409SSimon J. Gerraty * | :-------------- | :------------------------------------------------ | 400957b409SSimon J. Gerraty * | bearssl_hash.h | Hash functions | 410957b409SSimon J. Gerraty * | bearssl_hmac.h | HMAC | 420957b409SSimon J. Gerraty * | bearssl_kdf.h | Key Derivation Functions | 430957b409SSimon J. Gerraty * | bearssl_rand.h | Pseudorandom byte generators | 440957b409SSimon J. Gerraty * | bearssl_prf.h | PRF implementations (for SSL/TLS) | 450957b409SSimon J. Gerraty * | bearssl_block.h | Symmetric encryption | 460957b409SSimon J. Gerraty * | bearssl_aead.h | AEAD algorithms (combined encryption + MAC) | 470957b409SSimon J. Gerraty * | bearssl_rsa.h | RSA encryption and signatures | 480957b409SSimon J. Gerraty * | bearssl_ec.h | Elliptic curves support (including ECDSA) | 490957b409SSimon J. Gerraty * | bearssl_ssl.h | SSL/TLS engine interface | 500957b409SSimon J. Gerraty * | bearssl_x509.h | X.509 certificate decoding and validation | 510957b409SSimon J. Gerraty * | bearssl_pem.h | Base64/PEM decoding support functions | 520957b409SSimon J. Gerraty * 530957b409SSimon J. Gerraty * Applications using BearSSL are supposed to simply include `bearssl.h` 540957b409SSimon J. Gerraty * as follows: 550957b409SSimon J. Gerraty * 560957b409SSimon J. Gerraty * #include <bearssl.h> 570957b409SSimon J. Gerraty * 580957b409SSimon J. Gerraty * The `bearssl.h` file itself includes all the other header files. It is 590957b409SSimon J. Gerraty * possible to include specific header files, but it has no practical 600957b409SSimon J. Gerraty * advantage for the application. The API is separated into separate 610957b409SSimon J. Gerraty * header files only for documentation convenience. 620957b409SSimon J. Gerraty * 630957b409SSimon J. Gerraty * 640957b409SSimon J. Gerraty * # Conventions 650957b409SSimon J. Gerraty * 660957b409SSimon J. Gerraty * ## MUST and SHALL 670957b409SSimon J. Gerraty * 680957b409SSimon J. Gerraty * In all descriptions, the usual "MUST", "SHALL", "MAY",... terminology 690957b409SSimon J. Gerraty * is used. Failure to meet requirements expressed with a "MUST" or 700957b409SSimon J. Gerraty * "SHALL" implies undefined behaviour, which means that segmentation 710957b409SSimon J. Gerraty * faults, buffer overflows, and other similar adverse events, may occur. 720957b409SSimon J. Gerraty * 730957b409SSimon J. Gerraty * In general, BearSSL is not very forgiving of programming errors, and 740957b409SSimon J. Gerraty * does not include much failsafes or error reporting when the problem 750957b409SSimon J. Gerraty * does not arise from external transient conditions, and can be fixed 760957b409SSimon J. Gerraty * only in the application code. This is done so in order to make the 770957b409SSimon J. Gerraty * total code footprint lighter. 780957b409SSimon J. Gerraty * 790957b409SSimon J. Gerraty * 800957b409SSimon J. Gerraty * ## `NULL` values 810957b409SSimon J. Gerraty * 820957b409SSimon J. Gerraty * Function parameters with a pointer type shall not be `NULL` unless 830957b409SSimon J. Gerraty * explicitly authorised by the documentation. As an exception, when 840957b409SSimon J. Gerraty * the pointer aims at a sequence of bytes and is accompanied with 850957b409SSimon J. Gerraty * a length parameter, and the length is zero (meaning that there is 860957b409SSimon J. Gerraty * no byte at all to retrieve), then the pointer may be `NULL` even if 870957b409SSimon J. Gerraty * not explicitly allowed. 880957b409SSimon J. Gerraty * 890957b409SSimon J. Gerraty * 900957b409SSimon J. Gerraty * ## Memory Allocation 910957b409SSimon J. Gerraty * 920957b409SSimon J. Gerraty * BearSSL does not perform dynamic memory allocation. This implies that 930957b409SSimon J. Gerraty * for any functionality that requires a non-transient state, the caller 940957b409SSimon J. Gerraty * is responsible for allocating the relevant context structure. Such 950957b409SSimon J. Gerraty * allocation can be done in any appropriate area, including static data 960957b409SSimon J. Gerraty * segments, the heap, and the stack, provided that proper alignment is 970957b409SSimon J. Gerraty * respected. The header files define these context structures 980957b409SSimon J. Gerraty * (including size and contents), so the C compiler should handle 990957b409SSimon J. Gerraty * alignment automatically. 1000957b409SSimon J. Gerraty * 1010957b409SSimon J. Gerraty * Since there is no dynamic resource allocation, there is also nothing to 1020957b409SSimon J. Gerraty * release. When the calling code is done with a BearSSL feature, it 1030957b409SSimon J. Gerraty * may simple release the context structures it allocated itself, with 1040957b409SSimon J. Gerraty * no "close function" to call. If the context structures were allocated 1050957b409SSimon J. Gerraty * on the stack (as local variables), then even that release operation is 1060957b409SSimon J. Gerraty * implicit. 1070957b409SSimon J. Gerraty * 1080957b409SSimon J. Gerraty * 1090957b409SSimon J. Gerraty * ## Structure Contents 1100957b409SSimon J. Gerraty * 1110957b409SSimon J. Gerraty * Except when explicitly indicated, structure contents are opaque: they 1120957b409SSimon J. Gerraty * are included in the header files so that calling code may know the 1130957b409SSimon J. Gerraty * structure sizes and alignment requirements, but callers SHALL NOT 1140957b409SSimon J. Gerraty * access individual fields directly. For fields that are supposed to 1150957b409SSimon J. Gerraty * be read from or written to, the API defines accessor functions (the 1160957b409SSimon J. Gerraty * simplest of these accessor functions are defined as `static inline` 1170957b409SSimon J. Gerraty * functions, and the C compiler will optimise them away). 1180957b409SSimon J. Gerraty * 1190957b409SSimon J. Gerraty * 1200957b409SSimon J. Gerraty * # API Usage 1210957b409SSimon J. Gerraty * 1220957b409SSimon J. Gerraty * BearSSL usage for running a SSL/TLS client or server is described 1230957b409SSimon J. Gerraty * on the [BearSSL Web site](https://www.bearssl.org/api1.html). The 1240957b409SSimon J. Gerraty * BearSSL source archive also comes with sample code. 1250957b409SSimon J. Gerraty */ 1260957b409SSimon J. Gerraty 1270957b409SSimon J. Gerraty #include "bearssl_hash.h" 1280957b409SSimon J. Gerraty #include "bearssl_hmac.h" 1290957b409SSimon J. Gerraty #include "bearssl_kdf.h" 1300957b409SSimon J. Gerraty #include "bearssl_rand.h" 1310957b409SSimon J. Gerraty #include "bearssl_prf.h" 1320957b409SSimon J. Gerraty #include "bearssl_block.h" 1330957b409SSimon J. Gerraty #include "bearssl_aead.h" 1340957b409SSimon J. Gerraty #include "bearssl_rsa.h" 1350957b409SSimon J. Gerraty #include "bearssl_ec.h" 1360957b409SSimon J. Gerraty #include "bearssl_ssl.h" 1370957b409SSimon J. Gerraty #include "bearssl_x509.h" 1380957b409SSimon J. Gerraty #include "bearssl_pem.h" 1390957b409SSimon J. Gerraty 140*9c474dc5SSimon J. Gerraty #ifdef __cplusplus 141*9c474dc5SSimon J. Gerraty extern "C" { 142*9c474dc5SSimon J. Gerraty #endif 143*9c474dc5SSimon J. Gerraty 1440957b409SSimon J. Gerraty /** \brief Type for a configuration option. 1450957b409SSimon J. Gerraty * 1460957b409SSimon J. Gerraty * A "configuration option" is a value that is selected when the BearSSL 1470957b409SSimon J. Gerraty * library itself is compiled. Most options are boolean; their value is 1480957b409SSimon J. Gerraty * then either 1 (option is enabled) or 0 (option is disabled). Some 1490957b409SSimon J. Gerraty * values have other integer values. Option names correspond to macro 1500957b409SSimon J. Gerraty * names. Some of the options can be explicitly set in the internal 1510957b409SSimon J. Gerraty * `"config.h"` file. 1520957b409SSimon J. Gerraty */ 1530957b409SSimon J. Gerraty typedef struct { 1540957b409SSimon J. Gerraty /** \brief Configurable option name. */ 1550957b409SSimon J. Gerraty const char *name; 1560957b409SSimon J. Gerraty /** \brief Configurable option value. */ 1570957b409SSimon J. Gerraty long value; 1580957b409SSimon J. Gerraty } br_config_option; 1590957b409SSimon J. Gerraty 1600957b409SSimon J. Gerraty /** \brief Get configuration report. 1610957b409SSimon J. Gerraty * 1620957b409SSimon J. Gerraty * This function returns compiled configuration options, each as a 1630957b409SSimon J. Gerraty * 'long' value. Names match internal macro names, in particular those 1640957b409SSimon J. Gerraty * that can be set in the `"config.h"` inner file. For boolean options, 1650957b409SSimon J. Gerraty * the numerical value is 1 if enabled, 0 if disabled. For maximum 1660957b409SSimon J. Gerraty * key sizes, values are expressed in bits. 1670957b409SSimon J. Gerraty * 1680957b409SSimon J. Gerraty * The returned array is terminated by an entry whose `name` is `NULL`. 1690957b409SSimon J. Gerraty * 1700957b409SSimon J. Gerraty * \return the configuration report. 1710957b409SSimon J. Gerraty */ 1720957b409SSimon J. Gerraty const br_config_option *br_get_config(void); 1730957b409SSimon J. Gerraty 174*9c474dc5SSimon J. Gerraty /* ======================================================================= */ 175*9c474dc5SSimon J. Gerraty 176*9c474dc5SSimon J. Gerraty /** \brief Version feature: support for time callback. */ 177*9c474dc5SSimon J. Gerraty #define BR_FEATURE_X509_TIME_CALLBACK 1 178*9c474dc5SSimon J. Gerraty 179*9c474dc5SSimon J. Gerraty #ifdef __cplusplus 180*9c474dc5SSimon J. Gerraty } 181*9c474dc5SSimon J. Gerraty #endif 182*9c474dc5SSimon J. Gerraty 1830957b409SSimon J. Gerraty #endif 184