j3d1/bearssl
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

More Doxygen-compatible documentation. Also unified two identical structures.

Browse source
This commit is contained in:
Thomas Pornin 2016-11-19 19:05:08 +01:00
parent 60126cafc8
commit e683ebfe19
8 changed files with 568 additions and 320 deletions
Download patch file Download diff file Expand all files Collapse all files

6
Doxyfile
View file

@ -771,7 +771,7 @@ WARN_LOGFILE =
# spaces. See also FILE_PATTERNS and EXTENSION_MAPPING # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING
# Note: If this tag is empty the current directory is searched. # Note: If this tag is empty the current directory is searched.
INPUT = inc/bearssl_hash.h INPUT = inc/bearssl.h inc/bearssl_hash.h inc/bearssl_hmac.h inc/bearssl_prf.h inc/bearssl_rand.h
# This tag can be used to specify the character encoding of the source files # This tag can be used to specify the character encoding of the source files
# that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses
@ -946,7 +946,7 @@ INLINE_SOURCES = NO
# Fortran comments will always remain visible. # Fortran comments will always remain visible.
# The default value is: YES. # The default value is: YES.
STRIP_CODE_COMMENTS = YES STRIP_CODE_COMMENTS = NO
# If the REFERENCED_BY_RELATION tag is set to YES then for each documented # If the REFERENCED_BY_RELATION tag is set to YES then for each documented
# function all documented functions referencing it will be listed. # function all documented functions referencing it will be listed.
@ -1840,7 +1840,7 @@ RTF_SOURCE_CODE = NO
# classes and files. # classes and files.
# The default value is: NO. # The default value is: NO.
GENERATE_MAN = YES GENERATE_MAN = NO
# The MAN_OUTPUT tag is used to specify where the man pages will be put. If a # The MAN_OUTPUT tag is used to specify where the man pages will be put. If a
# relative path is entered the value of OUTPUT_DIRECTORY will be put in front of # relative path is entered the value of OUTPUT_DIRECTORY will be put in front of

84
inc/bearssl.h
View file

@ -28,6 +28,90 @@
#include <stddef.h> #include <stddef.h>
#include <stdint.h> #include <stdint.h>
/** \mainpage BearSSL API
*
* # API Layout
*
* 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_rand.h | Pseudorandom byte generators |
* | bearssl_prf.h | PRF implementations (for SSL/TLS) |
* | bearssl_block.h | Symmetric encryption |
* | 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.
*
*
* # Conventions
*
* ## MUST and SHALL
*
* 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 ligther.
*
*
* ## Memory Allocation
*
* 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.
*
*
* ## Structure Contents
*
* 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).
*
*
* # API Usage
*
* BearSSL usage for running a SSL/TLS client or server is described
* on the [BearSSL Web site](https://www.bearssl.org/api1.html). The
* BearSSL source archive also comes with sample code.
*/
#include "bearssl_hash.h" #include "bearssl_hash.h"
#include "bearssl_hmac.h" #include "bearssl_hmac.h"
#include "bearssl_rand.h" #include "bearssl_rand.h"

320
inc/bearssl_hash.h
View file

@ -35,99 +35,132 @@
* *
* This file documents the API for hash functions. * This file documents the API for hash functions.
* *
* Implemented hash functions are MD5, SHA-1, SHA-224, SHA-256, SHA-384
* and SHA-512; these are the _standard hash functions_ (as specified in
* TLS). Also provided are MD5+SHA-1 (an aggregate hash function that
* computes both MD5 and SHA-1 on its input, and provides a 36-byte
* output), a multi-hasher system that computes some or all of the
* standard hash functions on the same input, and some GHASH
* implementations (GHASH is the sort-of keyed hash function used in GCM
* encryption mode).
* *
* For each standard hash function (and also MD5+SHA-1), two similar API * ## Procedural API
* are provided: one consists in direct, named function calls, while the
* other uses function pointers through a vtable. The vtable incarnates
* object-oriented programming. An introduction on the OOP concept used
* here can be read on the BearSSL Web site:<br />
* &nbsp;&nbsp;&nbsp;[https://www.bearssl.org/oop.html](https://www.bearssl.org/oop.html)
*/
/*
* Hash Functions
* --------------
* *
* For hash function 'xxx', the following elements are defined: * For each implemented hash function, of name "`xxx`", the following
* elements are defined:
* *
* br_xxx_vtable * - `br_xxx_vtable`
* An externally defined instance of br_hash_class.
* *
* br_xxx_SIZE * An externally defined instance of `br_hash_class`.
* A macro that evaluates to the output size (in bytes) of the
* hash function.
* *
* br_xxx_ID * - `br_xxx_SIZE`
* A macro that evaluates to a symbolic identifier for the hash
* function. Such identifiers are used with HMAC and signature
* algorithm implementations.
* NOTE: the numerical value of these identifiers MUST match the
* constants for hash function identification in TLS 1.2 (see RFC
* 5246, section 7.4.1.4.1). These are values 1 to 6, for MD5,
* SHA-1, SHA-224, SHA-256, SHA-384 and SHA-512, respectively.
* *
* br_xxx_context * A macro that evaluates to the output size (in bytes) of the
* Context for an ongoing computation. It is allocated by the * hash function.
* caller, and a pointer to it is passed to all functions. A
* context contains no interior pointer, so it can be moved around
* and cloned (with a simple memcpy() or equivalent) in order to
* capture the function state at some point. Computations that use
* distinct context structures are independent of each other. The
* first field of br_xxx_context is always a pointer to the
* br_xxx_vtable structure; br_xxx_init() sets that pointer.
* *
* br_xxx_init(br_xxx_context *ctx) * - `br_xxx_ID`
* Initialize the provided context. Previous contents of the structure
* are ignored. This calls resets the context to the start of a new
* hash computation.
* *
* br_xxx_update(br_xxx_context *ctx, const void *data, size_t len) * A macro that evaluates to a symbolic identifier for the hash
* Add some more bytes to the hash computation represented by the * function. Such identifiers are used with HMAC and signature
* provided context. * algorithm implementations.
* *
* br_xxx_out(const br_xxx_context *ctx, void *out) * NOTE: for the "standard" hash functions defined in [the TLS
* Complete the hash computation and write the result in the provided * standard](https://tools.ietf.org/html/rfc5246#section-7.4.1.4.1),
* buffer. The output buffer MUST be large enough to accomodate the * the symbolic identifiers match the constants used in TLS, i.e.
* result. The context is NOT modified by this operation, so this * 1 to 6 for MD5, SHA-1, SHA-224, SHA-256, SHA-384 and SHA-512,
* function can be used to get a "partial hash" while still keeping * respectively.
* the possibility of adding more bytes to the input.
* *
* br_xxx_state(const br_xxx_context *ctx, void *out) * - `br_xxx_context`
* Get a copy of the "current state" for the computation so far. For
* MD functions (MD5, SHA-1, SHA-2 family), this is the running state
* resulting from the processing of the last complete input block.
* Returned value is the current input length (in bytes).
* *
* br_xxx_set_state(br_xxx_context *ctx, const void *stb, uint64_t count) * Context for an ongoing computation. It is allocated by the
* Set the internal state to the provided values. The 'stb' and 'count' * caller, and a pointer to it is passed to all functions. A
* values shall match that which was obtained from br_xxx_state(). This * context contains no interior pointer, so it can be moved around
* restores the hash state only if the state values were at an * and cloned (with a simple `memcpy()` or equivalent) in order to
* appropriate block boundary. This does NOT set the 'vtable' pointer * capture the function state at some point. Computations that use
* in the context. * distinct context structures are independent of each other. The
* first field of `br_xxx_context` is always a pointer to the
* `br_xxx_vtable` structure; `br_xxx_init()` sets that pointer.
*
* - `br_xxx_init(br_xxx_context *ctx)`
*
* Initialise the provided context. Previous contents of the structure
* are ignored. This calls resets the context to the start of a new
* hash computation; it also sets the first field of the context
* structure (called `vtable`) to a pointer to the statically
* allocated constant `br_xxx_vtable` structure.
*
* - `br_xxx_update(br_xxx_context *ctx, const void *data, size_t len)`
*
* Add some more bytes to the hash computation represented by the
* provided context.
*
* - `br_xxx_out(const br_xxx_context *ctx, void *out)`
*
* Complete the hash computation and write the result in the provided
* buffer. The output buffer MUST be large enough to accomodate the
* result. The context is NOT modified by this operation, so this
* function can be used to get a "partial hash" while still keeping
* the possibility of adding more bytes to the input.
*
* - `br_xxx_state(const br_xxx_context *ctx, void *out)`
*
* Get a copy of the "current state" for the computation so far. For
* MD functions (MD5, SHA-1, SHA-2 family), this is the running state
* resulting from the processing of the last complete input block.
* Returned value is the current input length (in bytes).
*
* - `br_xxx_set_state(br_xxx_context *ctx, const void *stb, uint64_t count)`
*
* Set the internal state to the provided values. The 'stb' and
* 'count' values shall match that which was obtained from
* `br_xxx_state()`. This restores the hash state only if the state
* values were at an appropriate block boundary. This does NOT set
* the `vtable` pointer in the context.
* *
* Context structures can be discarded without any explicit deallocation. * Context structures can be discarded without any explicit deallocation.
* Hash function implementations are purely software and don't reserve * Hash function implementations are purely software and don't reserve
* any resources outside of the context structure itself. * any resources outside of the context structure itself.
* *
*
* ## Object-Oriented API
*
* For each hash function that follows the procedural API described
* above, an object-oriented API is also provided. In that API, function
* pointers from the vtable (`br_xxx_vtable`) are used. The vtable
* incarnates object-oriented programming. An introduction on the OOP
* concept used here can be read on the BearSSL Web site:<br />
* &nbsp;&nbsp;&nbsp;[https://www.bearssl.org/oop.html](https://www.bearssl.org/oop.html)
*
* The vtable offers functions called `init()`, `update()`, `out()`,
* `set()` and `set_state()`, which are in fact the functions from
* the procedural API. That vtable also contains two informative fields:
*
* - `context_size`
*
* The size of the context structure (`br_xxx_context`), in bytes.
* This can be used by generic implementations to perform dynamic
* context allocation.
*
* - `desc`
*
* A "descriptor" field that encodes some information on the hash
* function: symbolic identifier, output size, state size,
* internal block size, details on the padding.
*
* Users of this object-oriented API (in particular generic HMAC
* implementations) may make the following assumptions:
*
* - Hash output size is no more than 64 bytes.
* - Hash internal state size is no more than 64 bytes.
* - Internal block size is a power of two, no less than 16 and no more
* than 256.
*
*
* ## Implemented Hash Functions
*
* Implemented hash functions are: * Implemented hash functions are:
* *
* Function Name Output length State length * | Function | Name | Output length | State length |
* * | :-------- | :------ | :-----------: | :----------: |
* MD5 md5 16 16 * | MD5 | md5 | 16 | 16 |
* SHA-1 sha1 20 20 * | SHA-1 | sha1 | 20 | 20 |
* SHA-224 sha224 28 32 * | SHA-224 | sha224 | 28 | 32 |
* SHA-256 sha256 32 32 * | SHA-256 | sha256 | 32 | 32 |
* SHA-384 sha384 48 64 * | SHA-384 | sha384 | 48 | 64 |
* SHA-512 sha512 64 64 * | SHA-512 | sha512 | 64 | 64 |
* MD5+SHA-1 md5sha1 36 36 * | MD5+SHA-1 | md5sha1 | 36 | 36 |
* *
* (MD5+SHA-1 is the concatenation of MD5 and SHA-1 computed over the * (MD5+SHA-1 is the concatenation of MD5 and SHA-1 computed over the
* same input; in the implementation, the internal data buffer is * same input; in the implementation, the internal data buffer is
@ -136,38 +169,39 @@
* 1.1.) * 1.1.)
* *
* *
* An object-oriented API is also available: the first field of the * ## Multi-Hasher
* context is a pointer to a br_hash_class structure, that has the
* following contents:
* *
* context_size total size of the required context structure * An aggregate hasher is provided, that can compute several standard
* desc descriptor (see below) * hash functions in parallel. It uses `br_multihash_context` and a
* init context initialization or reset (function pointer) * procedural API. It is configured with the implementations (the vtables)
* update process some more bytes (function pointer) * that it should use; it will then compute all these hash functions in
* out get hash output so far (function pointer) * parallel, on the same input. It is meant to be used in cases when the
* state get copy of internal state (function pointer) * hash of an object will be used, but the exact hash function is not
* set_state reset the internal state (function pointer) * known yet (typically, streamed processing on X.509 certificates).
* *
* The descriptor is a combination of the following elements: * Only the standard hash functions (MD5, SHA-1, SHA-224, SHA-256, SHA-384
* bits 0 to 7 hash algorithm identifier * and SHA-512) are supported by the multi-hasher.
* bits 8 to 14 hash output size (in bytes)
* bits 15 to 22 hash internal state size (in bytes)
* bits 23 to 26 log (base 2) of hash internal block size (in bytes)
* bit 28 1 if using MD padding, 0 otherwise
* bit 29 1 if MD padding uses a 128-bit bit length, 0 otherwise
* bit 30 1 if MD padding is big-endian, 0 otherwise
* *
* For function 'xxx', the br_xxx_init() function sets the first field
* to a pointer to the relevant br_hash_class instance (i.e.
* br_xxx_vtable).
* *
* Users of this object-oriented API may make the following assumptions: * ## GHASH
* Hash output size is no more than 64 bytes. *
* Hash internal state size is no more than 64 bytes. * GHASH is not a generic hash function; it is a _universal_ hash function,
* Internal block size is a power of two, no less than 2^4 and no more * which, as the name does not say, means that it CANNOT be used in most
* than 2^8. * places where a hash function is needed. GHASH is used within the GCM
* For functions that do not have an internal block size that is a * encryption mode, to provide the checked integrity functionality.
* power of 2, the relevant element is 0. *
* A GHASH implementation is basically a function that uses the type defined
* in this file under the name `br_ghash`:
*
* typedef void (*br_ghash)(void *y, const void *h, const void *data, size_t len);
*
* The `y` pointer refers to a 16-byte value which is used as input, and
* receives the output of the GHASH invocation. `h` is a 16-byte secret
* value (that serves as key). `data` and `len` define the input data.
*
* Three GHASH implementations are provided, all constant-time, based on
* the use of integer multiplications with appropriate masking to cancel
* carry propagation.
*/ */
/** /**
@ -517,23 +551,6 @@ uint64_t br_sha1_state(const br_sha1_context *ctx, void *out);
*/ */
void br_sha1_set_state(br_sha1_context *ctx, const void *stb, uint64_t count); void br_sha1_set_state(br_sha1_context *ctx, const void *stb, uint64_t count);
/* obsolete
#define br_sha1_ID 2
#define br_sha1_SIZE 20
extern const br_hash_class br_sha1_vtable;
typedef struct {
const br_hash_class *vtable;
unsigned char buf[64];
uint64_t count;
uint32_t val[5];
} br_sha1_context;
void br_sha1_init(br_sha1_context *ctx);
void br_sha1_update(br_sha1_context *ctx, const void *data, size_t len);
void br_sha1_out(const br_sha1_context *ctx, void *out);
uint64_t br_sha1_state(const br_sha1_context *ctx, void *out);
void br_sha1_set_state(br_sha1_context *ctx, const void *stb, uint64_t count);
*/
/** /**
* \brief Symbolic identifier for SHA-224. * \brief Symbolic identifier for SHA-224.
*/ */
@ -630,24 +647,6 @@ uint64_t br_sha224_state(const br_sha224_context *ctx, void *out);
void br_sha224_set_state(br_sha224_context *ctx, void br_sha224_set_state(br_sha224_context *ctx,
const void *stb, uint64_t count); const void *stb, uint64_t count);
/* obsolete
#define br_sha224_ID 3
#define br_sha224_SIZE 28
extern const br_hash_class br_sha224_vtable;
typedef struct {
const br_hash_class *vtable;
unsigned char buf[64];
uint64_t count;
uint32_t val[8];
} br_sha224_context;
void br_sha224_init(br_sha224_context *ctx);
void br_sha224_update(br_sha224_context *ctx, const void *data, size_t len);
void br_sha224_out(const br_sha224_context *ctx, void *out);
uint64_t br_sha224_state(const br_sha224_context *ctx, void *out);
void br_sha224_set_state(br_sha224_context *ctx,
const void *stb, uint64_t count);
*/
/** /**
* \brief Symbolic identifier for SHA-256. * \brief Symbolic identifier for SHA-256.
*/ */
@ -755,18 +754,6 @@ void br_sha256_set_state(br_sha256_context *ctx,
#define br_sha256_set_state br_sha224_set_state #define br_sha256_set_state br_sha224_set_state
#endif #endif
/* obsolete
#define br_sha256_ID 4
#define br_sha256_SIZE 32
extern const br_hash_class br_sha256_vtable;
typedef br_sha224_context br_sha256_context;
void br_sha256_init(br_sha256_context *ctx);
#define br_sha256_update br_sha224_update
void br_sha256_out(const br_sha256_context *ctx, void *out);
#define br_sha256_state br_sha224_state
#define br_sha256_set_state br_sha224_set_state
*/
/** /**
* \brief Symbolic identifier for SHA-384. * \brief Symbolic identifier for SHA-384.
*/ */
@ -863,24 +850,6 @@ uint64_t br_sha384_state(const br_sha384_context *ctx, void *out);
void br_sha384_set_state(br_sha384_context *ctx, void br_sha384_set_state(br_sha384_context *ctx,
const void *stb, uint64_t count); const void *stb, uint64_t count);
/* obsolete
#define br_sha384_ID 5
#define br_sha384_SIZE 48
extern const br_hash_class br_sha384_vtable;
typedef struct {
const br_hash_class *vtable;
unsigned char buf[128];
uint64_t count;
uint64_t val[8];
} br_sha384_context;
void br_sha384_init(br_sha384_context *ctx);
void br_sha384_update(br_sha384_context *ctx, const void *data, size_t len);
void br_sha384_out(const br_sha384_context *ctx, void *out);
uint64_t br_sha384_state(const br_sha384_context *ctx, void *out);
void br_sha384_set_state(br_sha384_context *ctx,
const void *stb, uint64_t count);
*/
/** /**
* \brief Symbolic identifier for SHA-512. * \brief Symbolic identifier for SHA-512.
*/ */
@ -908,9 +877,6 @@ typedef struct {
* \brief Pointer to vtable for this context. * \brief Pointer to vtable for this context.
*/ */
const br_hash_class *vtable; const br_hash_class *vtable;
unsigned char buf[128];
uint64_t count;
uint64_t val[8];
} br_sha512_context; } br_sha512_context;
#else #else
typedef br_sha384_context br_sha512_context; typedef br_sha384_context br_sha512_context;
@ -991,18 +957,6 @@ void br_sha512_set_state(br_sha512_context *ctx,
#define br_sha512_set_state br_sha384_set_state #define br_sha512_set_state br_sha384_set_state
#endif #endif
/* obsolete
#define br_sha512_ID 6
#define br_sha512_SIZE 64
extern const br_hash_class br_sha512_vtable;
typedef br_sha384_context br_sha512_context;
void br_sha512_init(br_sha512_context *ctx);
#define br_sha512_update br_sha384_update
void br_sha512_out(const br_sha512_context *ctx, void *out);
#define br_sha512_state br_sha384_state
#define br_sha512_set_state br_sha384_set_state
*/
/* /*
* "md5sha1" is a special hash function that computes both MD5 and SHA-1 * "md5sha1" is a special hash function that computes both MD5 and SHA-1
* on the same input, and produces a 36-byte output (MD5 and SHA-1 * on the same input, and produces a 36-byte output (MD5 and SHA-1

159
inc/bearssl_hmac.h
View file

@ -30,9 +30,9 @@
#include "bearssl_hash.h" #include "bearssl_hash.h"
/* /** \file bearssl_hmac.h
* HMAC *
* ---- * # HMAC
* *
* HMAC is initialized with a key and an underlying hash function; it * HMAC is initialized with a key and an underlying hash function; it
* then fills a "key context". That context contains the processed * then fills a "key context". That context contains the processed
@ -44,94 +44,143 @@
* *
* IMPORTANT: HMAC shall be used only with functions that have the * IMPORTANT: HMAC shall be used only with functions that have the
* following properties: * following properties:
* hash output size does not exceed 64 bytes *
* hash internal state size does not exceed 64 bytes * - hash output size does not exceed 64 bytes;
* internal block length is a power of 2 between 16 and 256 bytes * - hash internal state size does not exceed 64 bytes;
* - internal block length is a power of 2 between 16 and 256 bytes.
*/ */
/* /**
* Key context. * \brief HMAC key context.
*
* The HMAC key context is initialised with a hash function implementation
* and a secret key. Contents are opaque (callers should not access them
* directly). The caller is responsible for allocating the context where
* appropriate. Context initialisation and usage incurs no dynamic
* allocation, so there is no release function.
*/ */
typedef struct { typedef struct {
#ifndef BR_DOXYGEN_IGNORE
const br_hash_class *dig_vtable; const br_hash_class *dig_vtable;
unsigned char ksi[64], kso[64]; unsigned char ksi[64], kso[64];
#endif
} br_hmac_key_context; } br_hmac_key_context;
/* /**
* Initialize the key context with the provided key, using the hash function * \brief HMAC key context initialisation.
* identified by digest_class. *
* Initialise the key context with the provided key, using the hash function
* identified by `digest_vtable`. This supports arbitrary key lengths.
*
* \param kc HMAC key context to initialise.
* \param digest_vtable pointer to the hash function implementation vtable.
* \param key pointer to the HMAC secret key.
* \param key_len HMAC secret key length (in bytes).
*/ */
void br_hmac_key_init(br_hmac_key_context *kc, void br_hmac_key_init(br_hmac_key_context *kc,
const br_hash_class *digest_class, const void *key, size_t key_len); const br_hash_class *digest_vtable, const void *key, size_t key_len);
/* /**
* A helper structure that is big enough to accommodate all context * \brief HMAC computation context.
* structures for all hash functions for which HMAC is supported. *
*/ * The HMAC computation context maintains the state for a single HMAC
typedef union { * computation. It is modified as input bytes are injected. The context
const br_hash_class *vtable; * is caller-allocated and has no release function since it does not
br_md5_context md5; * dynamically allocate external resources. Its contents are opaque.
br_sha1_context sha1;
br_sha224_context sha224;
br_sha256_context sha256;
br_sha384_context sha384;
br_sha512_context sha512;
} br_hmac_allhash_context;
/*
* Context for an HMAC computation.
*/ */
typedef struct { typedef struct {
br_hmac_allhash_context dig; #ifndef BR_DOXYGEN_IGNORE
br_hash_compat_context dig;
unsigned char kso[64]; unsigned char kso[64];
size_t out_len; size_t out_len;
#endif
} br_hmac_context; } br_hmac_context;
/* /**
* Initialize a HMAC context with a key context. The key context is * \brief HMAC computation initialisation.
*
* Initialise a HMAC context with a key context. The key context is
* unmodified. Relevant data from the key context is immediately copied; * unmodified. Relevant data from the key context is immediately copied;
* the key context can thus be independently reused, modified or released * the key context can thus be independently reused, modified or released
* without impacting this HMAC computation. * without impacting this HMAC computation.
* *
* An explicit output length can be specified; the actual output length * An explicit output length can be specified; the actual output length
* will be the minimum of that value and the natural HMAC output length. * will be the minimum of that value and the natural HMAC output length.
* If out_len is 0, then the natural HMAC output length is selected. * If `out_len` is 0, then the natural HMAC output length is selected. The
* "natural output length" is the output length of the underlying hash
* function.
*
* \param ctx HMAC context to initialise.
* \param kc HMAC key context (already initialised with the key).
* \param out_len HMAC output length (0 to select "natural length").
*/ */
void br_hmac_init(br_hmac_context *ctx, void br_hmac_init(br_hmac_context *ctx,
const br_hmac_key_context *kc, size_t out_len); const br_hmac_key_context *kc, size_t out_len);
/* /**
* Get the MAC output size. The context must have been initialized. * \brief Get the HMAC output size.
*
* The HMAC output size is the number of bytes that will actually be
* produced with `br_hmac_out()` with the provided context. This function
* MUST NOT be called on a non-initialised HMAC computation context.
* The returned value is the minimum of the HMAC natural length (output
* size of the underlying hash function) and the `out_len` parameter which
* was used with the last `br_hmac_init()` call on that context (if the
* initialisation `out_len` parameter was 0, then this function will
* return the HMAC natural length).
*
* \param ctx the (already initialised) HMAC computation context.
* \return the HMAC actual output size.
*/ */
#define br_hmac_size(ctx) ((ctx)->out_len) static inline size_t
br_hmac_size(br_hmac_context *ctx)
{
return ctx->out_len;
}
/* /**
* Process some more bytes. * \brief Inject some bytes in HMAC.
*
* The provided `len` bytes are injected as extra input in the HMAC
* computation incarnated by the `ctx` HMAC context. It is acceptable
* that `len` is zero, in which case `data` is ignored (and may be
* `NULL`) and this function does nothing.
*/ */
void br_hmac_update(br_hmac_context *ctx, const void *data, size_t len); void br_hmac_update(br_hmac_context *ctx, const void *data, size_t len);
/* /**
* Compute the HMAC output. The destination buffer MUST be large enough * \brief Compute the HMAC output.
* to accomodate the result. The context is NOT modified; further bytes *
* may be processed. Thus, "partial HMAC" values can be efficiently * The destination buffer MUST be large enough to accomodate the result;
* obtained. * its length is at most the "natural length" of HMAC (i.e. the output
* length of the underlying hash function). The context is NOT modified;
* further bytes may be processed. Thus, "partial HMAC" values can be
* efficiently obtained.
* *
* Returned value is the output length (in bytes). * Returned value is the output length (in bytes).
*
* \param ctx HMAC computation context.
* \param out destination buffer for the HMAC output.
* \return the produced value length (in bytes).
*/ */
size_t br_hmac_out(const br_hmac_context *ctx, void *out); size_t br_hmac_out(const br_hmac_context *ctx, void *out);
/* /**
* Compute the HMAC output in constant time. Some extra input bytes are * \brief Constant-time HMAC computation.
* processed, then the output is computed. The extra input consists in
* the 'len' bytes pointed to by 'data'. The 'len' parameter must lie
* between 'min_len' and 'max_len' (inclusive); max_len bytes are
* actually read from 'data'. Computing time (and memory access pattern)
* will not depend upon the data bytes or the value of 'len'.
* *
* The output is written in the 'out' buffer, that MUST be large enough * This function compute the HMAC output in constant time. Some extra
* input bytes are processed, then the output is computed. The extra
* input consists in the `len` bytes pointed to by `data`. The `len`
* parameter must lie between `min_len` and `max_len` (inclusive);
* `max_len` bytes are actually read from `data`. Computing time (and
* memory access pattern) will not depend upon the data byte contents or
* the value of `len`.
*
* The output is written in the `out` buffer, that MUST be large enough
* to receive it. * to receive it.
* *
* The difference max_len-min_len MUST be less than 2^30. * The difference `max_len - min_len` MUST be less than 2<sup>30</sup>
* (i.e. about one gigabyte).
* *
* This function computes the output properly only if the underlying * This function computes the output properly only if the underlying
* hash function uses MD padding (i.e. MD5, SHA-1, SHA-224, SHA-256, * hash function uses MD padding (i.e. MD5, SHA-1, SHA-224, SHA-256,
@ -139,7 +188,13 @@ size_t br_hmac_out(const br_hmac_context *ctx, void *out);
* *
* The provided context is NOT modified. * The provided context is NOT modified.
* *
* Returned value is the MAC length (in bytes). * \param ctx the (already initialised) HMAC computation context.
* \param data the extra input bytes.
* \param len the extra input length (in bytes).
* \param min_len minimum extra input length (in bytes).
* \param max_len maximum extra input length (in bytes).
* \param out destination buffer for the HMAC output.
* \return the produced value length (in bytes).
*/ */
size_t br_hmac_outCT(const br_hmac_context *ctx, size_t br_hmac_outCT(const br_hmac_context *ctx,
const void *data, size_t len, size_t min_len, size_t max_len, const void *data, size_t len, size_t min_len, size_t max_len,

68
inc/bearssl_prf.h
View file

@ -28,36 +28,88 @@
#include <stddef.h> #include <stddef.h>
#include <stdint.h> #include <stdint.h>
/* /** \file bearssl_prf.h
* The TLS PRF *
* ----------- * # The TLS PRF
*
* The "PRF" is the pseudorandom function used internally during the
* SSL/TLS handshake, notably to expand negociated shared secrets into
* the symmetric encryption keys that will be used to process the
* application data.
* *
* TLS 1.0 and 1.1 define a PRF that is based on both MD5 and SHA-1. This * TLS 1.0 and 1.1 define a PRF that is based on both MD5 and SHA-1. This
* is implemented by the br_tls10_prf() function. * is implemented by the `br_tls10_prf()` function.
* *
* TLS 1.2 redefines the PRF, using an explicit hash function. The * TLS 1.2 redefines the PRF, using an explicit hash function. The
* br_tls12_sha256_prf() and br_tls12_sha384_prf() functions apply that * `br_tls12_sha256_prf()` and `br_tls12_sha384_prf()` functions apply that
* PRF with, respectively, SHA-256 and SHA-384. * PRF with, respectively, SHA-256 and SHA-384. Most standard cipher suites
* rely on the SHA-256 based PRF, but some use SHA-384.
* *
* The PRF always uses as input three parameters: a "secret" (some * The PRF always uses as input three parameters: a "secret" (some
* bytes), a "label" (ASCII string), and a "seed" (again some bytes). * bytes), a "label" (ASCII string), and a "seed" (again some bytes).
* An arbitrary output length can be produced. * An arbitrary output length can be produced.
*/ */
/** \brief PRF implementation for TLS 1.0 and 1.1.
*
* This PRF is the one specified by TLS 1.0 and 1.1. It internally uses
* MD5 and SHA-1.
*
* \param dst destination buffer.
* \param len output length (in bytes).
* \param secret secret value (key) for this computation.
* \param secret_len length of "secret" (in bytes).
* \param label PRF label (zero-terminated ASCII string).
* \param seed seed for this computation (usually non-secret).
* \param seed_len length of "seed" (in bytes).
*/
void br_tls10_prf(void *dst, size_t len, void br_tls10_prf(void *dst, size_t len,
const void *secret, size_t secret_len, const void *secret, size_t secret_len,
const char *label, const void *seed, size_t seed_len); const char *label, const void *seed, size_t seed_len);
/** \brief PRF implementation for TLS 1.2, with SHA-256.
*
* This PRF is the one specified by TLS 1.2, when the underlying hash
* function is SHA-256.
*
* \param dst destination buffer.
* \param len output length (in bytes).
* \param secret secret value (key) for this computation.
* \param secret_len length of "secret" (in bytes).
* \param label PRF label (zero-terminated ASCII string).
* \param seed seed for this computation (usually non-secret).
* \param seed_len length of "seed" (in bytes).
*/
void br_tls12_sha256_prf(void *dst, size_t len, void br_tls12_sha256_prf(void *dst, size_t len,
const void *secret, size_t secret_len, const void *secret, size_t secret_len,
const char *label, const void *seed, size_t seed_len); const char *label, const void *seed, size_t seed_len);
/** \brief PRF implementation for TLS 1.2, with SHA-384.
*
* This PRF is the one specified by TLS 1.2, when the underlying hash
* function is SHA-384.
*
* \param dst destination buffer.
* \param len output length (in bytes).
* \param secret secret value (key) for this computation.
* \param secret_len length of "secret" (in bytes).
* \param label PRF label (zero-terminated ASCII string).
* \param seed seed for this computation (usually non-secret).
* \param seed_len length of "seed" (in bytes).
*/
void br_tls12_sha384_prf(void *dst, size_t len, void br_tls12_sha384_prf(void *dst, size_t len,
const void *secret, size_t secret_len, const void *secret, size_t secret_len,
const char *label, const void *seed, size_t seed_len); const char *label, const void *seed, size_t seed_len);
/* /** \brief A convenient type name for a PRF implementation.
* A convenient type name for a PRF implementation. *
* \param dst destination buffer.
* \param len output length (in bytes).
* \param secret secret value (key) for this computation.
* \param secret_len length of "secret" (in bytes).
* \param label PRF label (zero-terminated ASCII string).
* \param seed seed for this computation (usually non-secret).
* \param seed_len length of "seed" (in bytes).
*/ */
typedef void (*br_tls_prf_impl)(void *dst, size_t len, typedef void (*br_tls_prf_impl)(void *dst, size_t len,
const void *secret, size_t secret_len, const void *secret, size_t secret_len,

245
inc/bearssl_rand.h
View file

@ -28,117 +28,220 @@
#include <stddef.h> #include <stddef.h>
#include <stdint.h> #include <stdint.h>
/* /** \file bearssl_rand.h
* Pseudo-Random Generators *
* ------------------------ * # Pseudo-Random Generators
* *
* A PRNG is a state-based engine that outputs pseudo-random bytes on * A PRNG is a state-based engine that outputs pseudo-random bytes on
* demand. It is initialized with an initial seed, and additional seed * demand. It is initialized with an initial seed, and additional seed
* bytes can be added afterwards. Bytes produced depend on the seeds * bytes can be added afterwards. Bytes produced depend on the seeds and
* and also on the exact sequence of calls (including sizes requested * also on the exact sequence of calls (including sizes requested for
* for each call). * each call).
* *
* An object-oriented API is defined, with rules similar to that of
* hash functions. The context structure for a PRNG must start with
* a pointer to the vtable. The vtable contains the following fields:
* *
* context_size size of the context structure for this PRNG * ## Procedural and OOP API
* init initialize context with an initial seed
* generate produce some pseudo-random bytes
* update insert some additional seed
* *
* Note that the init() method may accept additional parameters, provided * For the PRNG of name "`xxx`", two API are provided. The _procedural_
* as a 'const void *' pointer at API level. These additional parameters * API defined a context structure `br_xxx_context` and three functions:
* depend on the implemented PRNG. *
* - `br_xxx_init()`
*
* Initialise the context with an initial seed.
*
* - `br_xxx_generate()`
*
* Produce some pseudo-random bytes.
*
* - `br_xxx_update()`
*
* Inject some additional seed.
*
* The initialisation function sets the first context field (`vtable`)
* to a pointer to the vtable that supports the OOP API. The OOP API
* provides access to the same functions through function pointers,
* named `init()`, `generate()` and `update()`.
*
* Note that the context initialisation method may accept additional
* parameters, provided as a 'const void *' pointer at API level. These
* additional parameters depend on the implemented PRNG.
*
*
* ## HMAC_DRBG
*
* HMAC_DRBG is defined in [NIST SP 800-90A Revision
* 1](http://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-90Ar1.pdf).
* It uses HMAC repeatedly, over some configurable underlying hash
* function. In BearSSL, it is implemented under the "`hmac_drbg`" name.
* The "extra parameters" pointer for context initialisation should be
* set to a pointer to the vtable for the underlying hash function (e.g.
* pointer to `br_sha256_vtable` to use HMAC_DRBG with SHA-256).
*
* According to the NIST standard, each request shall produce up to
* 2<sup>19</sup> bits (i.e. 64 kB of data); moreover, the context shall
* be reseeded at least once every 2<sup>48</sup> requests. This
* implementation does not maintain the reseed counter (the threshold is
* too high to be reached in practice) and does not object to producing
* more than 64 kB in a single request; thus, the code cannot fail,
* which corresponds to the fact that the API has no room for error
* codes. However, this implies that requesting more than 64 kB in one
* `generate()` request, or making more than 2<sup>48</sup> requests
* without reseeding, is formally out of NIST specification. There is
* no currently known security penalty for exceeding the NIST limits,
* and, in any case, HMAC_DRBG usage in implementing SSL/TLS always
* stays much below these thresholds.
*/ */
/**
* \brief Class type for PRNG implementations.
*
* A `br_prng_class` instance references the methods implementing a PRNG.
* Constant instances of this structure are defined for each implemented
* PRNG. Such instances are also called "vtables".
*/
typedef struct br_prng_class_ br_prng_class; typedef struct br_prng_class_ br_prng_class;
struct br_prng_class_ { struct br_prng_class_ {
/**
* \brief Size (in bytes) of the context structure appropriate for
* running this PRNG.
*/
size_t context_size; size_t context_size;
/**
* \brief Initialisation method.
*
* The context to initialise is provided as a pointer to its
* first field (the vtable pointer); this function sets that
* first field to a pointer to the vtable.
*
* The extra parameters depend on the implementation; each
* implementation defines what kind of extra parameters it
* expects (if any).
*
* Requirements on the initial seed depend on the implemented
* PRNG.
*
* \param ctx PRNG context to initialise.
* \param params extra parameters for the PRNG.
* \param seed initial seed.
* \param seed_len initial seed length (in bytes).
*/
void (*init)(const br_prng_class **ctx, const void *params, void (*init)(const br_prng_class **ctx, const void *params,
const void *seed, size_t seed_len); const void *seed, size_t seed_len);
/**
* \brief Random bytes generation.
*
* This method produces `len` pseudorandom bytes, in the `out`
* buffer. The context is updated accordingly.
*
* \param ctx PRNG context.
* \param out output buffer.
* \param len number of pseudorandom bytes to produce.
*/
void (*generate)(const br_prng_class **ctx, void *out, size_t len); void (*generate)(const br_prng_class **ctx, void *out, size_t len);
/**
* \brief Inject additional seed bytes.
*
* The provided seed bytes are added into the PRNG internal
* entropy pool.
*
* \param ctx PRNG context.
* \param seed additional seed.
* \param seed_len additional seed length (in bytes).
*/
void (*update)(const br_prng_class **ctx, void (*update)(const br_prng_class **ctx,
const void *seed, size_t seed_len); const void *seed, size_t seed_len);
}; };
/* /**
* HMAC_DRBG is a pseudo-random number generator based on HMAC (with * \brief Context for HMAC_DRBG.
* an underlying hash function). HMAC_DRBG is specified in NIST Special
* Publication 800-90A. It works as a stateful machine:
* -- It has an internal state.
* -- The state can be updated with additional "entropy" (some bytes
* provided from the outside).
* -- Each request is for some bits (up to some limit). For each request,
* an internal "reseed counter" is incremented.
* -- When the reseed counter reaches a given threshold, a reseed is
* necessary.
* *
* Standard limits are quite high: each request can produce up to 2^19 * The context contents are opaque, except the first field, which
* bits (i.e. 64 kB of data), and the threshold for the reseed counter * supports OOP.
* is 2^48. In practice, we cannot really reach that reseed counter, so
* the implementation simply omits the counter. Similarly, we consider
* that it is up to callers NOT to ask for more than 64 kB of randomness
* in one go. Under these conditions, this implementation cannot fail,
* and thus functions need not return any status code.
*
* (Asking for more than 64 kB of data in one generate() call won't make
* the implementation fail, and, as far as we know, it will not induce
* any actual weakness; this is "merely" out of the formal usage range
* defined for HMAC_DRBG.)
*
* A dedicated context structure (caller allocated, as usual) contains
* the current PRNG state.
*
* For the OOP interface, the "additional parameters" are a pointer to
* the class of the hash function to use.
*/ */
typedef struct { typedef struct {
/**
* \brief Pointer to the vtable.
*
* This field is set with the initialisation method/function.
*/
const br_prng_class *vtable; const br_prng_class *vtable;
#ifndef BR_DOXYGEN_IGNORE
unsigned char K[64]; unsigned char K[64];
unsigned char V[64]; unsigned char V[64];
const br_hash_class *digest_class; const br_hash_class *digest_class;
#endif
} br_hmac_drbg_context; } br_hmac_drbg_context;
/**
* \brief Statically allocated, constant vtable for HMAC_DRBG.
*/
extern const br_prng_class br_hmac_drbg_vtable; extern const br_prng_class br_hmac_drbg_vtable;
/* /**
* Initialize a HMAC_DRBG instance, with the provided initial seed (of * \brief HMAC_DRBG initialisation.
* 'len' bytes). The 'seed' used here is what is called, in SP 800-90A
* terminology, the concatenation of the "seed", "nonce" and
* "personalization string", in that order.
* *
* Formally, the underlying digest can only be SHA-1 or one of the SHA-2 * The context to initialise is provided as a pointer to its first field
* functions. This implementation also works with any other implemented * (the vtable pointer); this function sets that first field to a
* hash function (e.g. MD5), but such usage is non-standard and not * pointer to the vtable.
* recommended. *
* The `seed` value is what is called, in NIST terminology, the
* concatenation of the "seed", "nonce" and "personalization string", in
* that order.
*
* The `digest_class` parameter defines the underlying hash function.
* Formally, the NIST standard specifies that the hash function shall
* be only SHA-1 or one of the SHA-2 functions. This implementation also
* works with any other implemented hash function (such as MD5), but
* this is non-standard and therefore not recommended.
*
* \param ctx HMAC_DRBG context to initialise.
* \param digest_class vtable for the underlying hash function.
* \param seed initial seed.
* \param seed_len initial seed length (in bytes).
*/ */
void br_hmac_drbg_init(br_hmac_drbg_context *ctx, void br_hmac_drbg_init(br_hmac_drbg_context *ctx,
const br_hash_class *digest_class, const void *seed, size_t len); const br_hash_class *digest_class, const void *seed, size_t seed_len);
/* /**
* Obtain some pseudorandom bits from HMAC_DRBG. The provided context * \brief Random bytes generation with HMAC_DRBG.
* is updated. The output bits are written in 'out' ('len' bytes). The *
* size of the requested chunk of pseudorandom bits MUST NOT exceed * This method produces `len` pseudorandom bytes, in the `out`
* 64 kB (the function won't fail if more bytes are requested, but * buffer. The context is updated accordingly. Formally, requesting
* the usage will be outside of the HMAC_DRBG specification limits). * more than 65536 bytes in one request falls out of specification
* limits (but it won't fail).
*
* \param ctx HMAC_DRBG context.
* \param out output buffer.
* \param len number of pseudorandom bytes to produce.
*/ */
void br_hmac_drbg_generate(br_hmac_drbg_context *ctx, void *out, size_t len); void br_hmac_drbg_generate(br_hmac_drbg_context *ctx, void *out, size_t len);
/* /**
* Update an HMAC_DRBG instance with some new entropy. The extra 'seed' * \brief Inject additional seed bytes in HMAC_DRBG.
* complements the current state but does not completely replace any *
* previous seed. The process is such that pushing new entropy, even of * The provided seed bytes are added into the HMAC_DRBG internal
* questionable quality, will not make the output "less random" in any * entropy pool. The process does not _replace_ existing entropy,
* practical way. * thus pushing non-random bytes (i.e. bytes which are known to the
* attackers) does not degrade the overall quality of generated bytes.
*
* \param ctx HMAC_DRBG context.
* \param seed additional seed.
* \param seed_len additional seed length (in bytes).
*/ */
void br_hmac_drbg_update(br_hmac_drbg_context *ctx, void br_hmac_drbg_update(br_hmac_drbg_context *ctx,
const void *seed, size_t len); const void *seed, size_t seed_len);
/* /**
* Get the hash function implementation used by a given instance of * \brief Get the hash function implementation used by a given instance of
* HMAC_DRBG. * HMAC_DRBG.
*
* This calls MUST NOT be performed on a context which was not
* previously initialised.
*
* \param ctx HMAC_DRBG context.
* \return the hash function vtable.
*/ */
static inline const br_hash_class * static inline const br_hash_class *
br_hmac_drbg_get_hash(const br_hmac_drbg_context *ctx) br_hmac_drbg_get_hash(const br_hmac_drbg_context *ctx)

4
src/mac/hmac.c
View file

@ -57,7 +57,7 @@ void
br_hmac_key_init(br_hmac_key_context *kc, br_hmac_key_init(br_hmac_key_context *kc,
const br_hash_class *dig, const void *key, size_t key_len) const br_hash_class *dig, const void *key, size_t key_len)
{ {
br_hmac_allhash_context hc; br_hash_compat_context hc;
unsigned char kbuf[64]; unsigned char kbuf[64];
kc->dig_vtable = dig; kc->dig_vtable = dig;
@ -105,7 +105,7 @@ size_t
br_hmac_out(const br_hmac_context *ctx, void *out) br_hmac_out(const br_hmac_context *ctx, void *out)
{ {
const br_hash_class *dig; const br_hash_class *dig;
br_hmac_allhash_context hc; br_hash_compat_context hc;
unsigned char tmp[64]; unsigned char tmp[64];
size_t blen, hlen; size_t blen, hlen;

2
src/mac/hmac_ct.c
View file

@ -63,7 +63,7 @@ br_hmac_outCT(const br_hmac_context *ctx,
*/ */
const br_hash_class *dig; const br_hash_class *dig;
br_hmac_allhash_context hc; br_hash_compat_context hc;
int be; int be;
uint32_t po, bs; uint32_t po, bs;
uint32_t kr, km, kl, kz, u; uint32_t kr, km, kl, kz, u;