|
BearSSL
|
The functions and structures defined by the BearSSL API are located in various header files:
| Header file | Elements |
|---|---|
| bearssl_hash.h | Hash functions |
| bearssl_hmac.h | HMAC |
| bearssl_kdf.h | Key Derivation Functions |
| bearssl_rand.h | Pseudorandom byte generators |
| bearssl_prf.h | PRF implementations (for SSL/TLS) |
| bearssl_block.h | Symmetric encryption |
| bearssl_aead.h | AEAD algorithms (combined encryption + MAC) |
| bearssl_rsa.h | RSA encryption and signatures |
| bearssl_ec.h | Elliptic curves support (including ECDSA) |
| bearssl_ssl.h | SSL/TLS engine interface |
| bearssl_x509.h | X.509 certificate decoding and validation |
| bearssl_pem.h | Base64/PEM decoding support functions |
Applications using BearSSL are supposed to simply include bearssl.h as follows:
#include <bearssl.h>
The bearssl.h file itself includes all the other header files. It is possible to include specific header files, but it has no practical advantage for the application. The API is separated into separate header files only for documentation convenience.
In all descriptions, the usual "MUST", "SHALL", "MAY",... terminology is used. Failure to meet requirements expressed with a "MUST" or "SHALL" implies undefined behaviour, which means that segmentation faults, buffer overflows, and other similar adverse events, may occur.
In general, BearSSL is not very forgiving of programming errors, and does not include much failsafes or error reporting when the problem does not arise from external transient conditions, and can be fixed only in the application code. This is done so in order to make the total code footprint lighter.
NULL valuesFunction parameters with a pointer type shall not be NULL unless explicitly authorised by the documentation. As an exception, when the pointer aims at a sequence of bytes and is accompanied with a length parameter, and the length is zero (meaning that there is no byte at all to retrieve), then the pointer may be NULL even if not explicitly allowed.
BearSSL does not perform dynamic memory allocation. This implies that for any functionality that requires a non-transient state, the caller is responsible for allocating the relevant context structure. Such allocation can be done in any appropriate area, including static data segments, the heap, and the stack, provided that proper alignment is respected. The header files define these context structures (including size and contents), so the C compiler should handle alignment automatically.
Since there is no dynamic resource allocation, there is also nothing to release. When the calling code is done with a BearSSL feature, it may simple release the context structures it allocated itself, with no "close function" to call. If the context structures were allocated on the stack (as local variables), then even that release operation is implicit.
Except when explicitly indicated, structure contents are opaque: they are included in the header files so that calling code may know the structure sizes and alignment requirements, but callers SHALL NOT access individual fields directly. For fields that are supposed to be read from or written to, the API defines accessor functions (the simplest of these accessor functions are defined as static inline functions, and the C compiler will optimise them away).
BearSSL usage for running a SSL/TLS client or server is described on the BearSSL Web site. The BearSSL source archive also comes with sample code.
1.8.13