_ Git - BearSSL/blob - 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_rand.h  | Pseudorandom byte generators                      |
  43  * | bearssl_prf.h   | PRF implementations (for SSL/TLS)                 |
  44  * | bearssl_block.h | Symmetric encryption                              |
  45  * | bearssl_rsa.h   | RSA encryption and signatures                     |
  46  * | bearssl_ec.h    | Elliptic curves support (including ECDSA)         |
  47  * | bearssl_ssl.h   | SSL/TLS engine interface                          |
  48  * | bearssl_x509.h  | X.509 certificate decoding and validation         |
  49  * | bearssl_pem.h   | Base64/PEM decoding support functions             |
  50  *
  51  * Applications using BearSSL are supposed to simply include `bearssl.h`
  52  * as follows:
  53  *
  54  *     #include <bearssl.h>
  55  *
  56  * The `bearssl.h` file itself includes all the other header files. It is
  57  * possible to include specific header files, but it has no practical
  58  * advantage for the application. The API is separated into separate
  59  * header files only for documentation convenience.
  60  *
  61  *
  62  * # Conventions
  63  *
  64  * ## MUST and SHALL
  65  *
  66  * In all descriptions, the usual "MUST", "SHALL", "MAY",... terminology
  67  * is used. Failure to meet requirements expressed with a "MUST" or
  68  * "SHALL" implies undefined behaviour, which means that segmentation
  69  * faults, buffer overflows, and other similar adverse events, may occur.
  70  *
  71  * In general, BearSSL is not very forgiving of programming errors, and
  72  * does not include much failsafes or error reporting when the problem
  73  * does not arise from external transient conditions, and can be fixed
  74  * only in the application code. This is done so in order to make the
  75  * total code footprint lighter.
  76  *
  77  *
  78  * ## `NULL` values
  79  *
  80  * Function parameters with a pointer type shall not be `NULL` unless
  81  * explicitly authorised by the documentation. As an exception, when
  82  * the pointer aims at a sequence of bytes and is accompanied with
  83  * a length parameter, and the length is zero (meaning that there is
  84  * no byte at all to retrieve), then the pointer may be `NULL` even if
  85  * not explicitly allowed.
  86  *
  87  *
  88  * ## Memory Allocation
  89  *
  90  * BearSSL does not perform dynamic memory allocation. This implies that
  91  * for any functionality that requires a non-transient state, the caller
  92  * is responsible for allocating the relevant context structure. Such
  93  * allocation can be done in any appropriate area, including static data
  94  * segments, the heap, and the stack, provided that proper alignment is
  95  * respected. The header files define these context structures
  96  * (including size and contents), so the C compiler should handle
  97  * alignment automatically.
  98  *
  99  * Since there is no dynamic resource allocation, there is also nothing to
 100  * release. When the calling code is done with a BearSSL feature, it
 101  * may simple release the context structures it allocated itself, with
 102  * no "close function" to call. If the context structures were allocated
 103  * on the stack (as local variables), then even that release operation is
 104  * implicit.
 105  *
 106  *
 107  * ## Structure Contents
 108  *
 109  * Except when explicitly indicated, structure contents are opaque: they
 110  * are included in the header files so that calling code may know the
 111  * structure sizes and alignment requirements, but callers SHALL NOT
 112  * access individual fields directly. For fields that are supposed to
 113  * be read from or written to, the API defines accessor functions (the
 114  * simplest of these accessor functions are defined as `static inline`
 115  * functions, and the C compiler will optimise them away).
 116  *
 117  *
 118  * # API Usage
 119  *
 120  * BearSSL usage for running a SSL/TLS client or server is described
 121  * on the [BearSSL Web site](https://www.bearssl.org/api1.html). The
 122  * BearSSL source archive also comes with sample code.
 123  */
 124
 125 #include "bearssl_hash.h"
 126 #include "bearssl_hmac.h"
 127 #include "bearssl_rand.h"
 128 #include "bearssl_prf.h"
 129 #include "bearssl_block.h"
 130 #include "bearssl_rsa.h"
 131 #include "bearssl_ec.h"
 132 #include "bearssl_ssl.h"
 133 #include "bearssl_x509.h"
 134 #include "bearssl_pem.h"
 135
 136 #endif