]>
Commit | Line | Data |
---|---|---|
bcdea3ba | 1 | /* |
a28d06f3 | 2 | * Copyright 1995-2021 The OpenSSL Project Authors. All Rights Reserved. |
bcdea3ba P |
3 | * |
4 | * Licensed under the Apache License 2.0 (the "License"). You may not use | |
5 | * this file except in compliance with the License. You can obtain a copy | |
6 | * in the file LICENSE in the source distribution or at | |
7 | * https://www.openssl.org/source/license.html | |
8 | */ | |
9 | ||
10 | #ifndef OSSL_PROVIDER_RAND_POOL_H | |
11 | # define OSSL_PROVIDER_RAND_POOL_H | |
80ce21fe | 12 | # pragma once |
bcdea3ba P |
13 | |
14 | # include <stdio.h> | |
7d615e21 | 15 | # include <openssl/rand.h> |
bcdea3ba P |
16 | |
17 | /* | |
18 | * Maximum allocation size for RANDOM_POOL buffers | |
19 | * | |
20 | * The max_len value for the buffer provided to the rand_drbg_get_entropy() | |
21 | * callback is currently 2^31 bytes (2 gigabytes), if a derivation function | |
22 | * is used. Since this is much too large to be allocated, the rand_pool_new() | |
23 | * function chooses more modest values as default pool length, bounded | |
24 | * by RAND_POOL_MIN_LENGTH and RAND_POOL_MAX_LENGTH | |
25 | * | |
26 | * The choice of the RAND_POOL_FACTOR is large enough such that the | |
27 | * RAND_POOL can store a random input which has a lousy entropy rate of | |
28 | * 8/256 (= 0.03125) bits per byte. This input will be sent through the | |
29 | * derivation function which 'compresses' the low quality input into a | |
30 | * high quality output. | |
31 | * | |
32 | * The factor 1.5 below is the pessimistic estimate for the extra amount | |
33 | * of entropy required when no get_nonce() callback is defined. | |
34 | */ | |
35 | # define RAND_POOL_FACTOR 256 | |
36 | # define RAND_POOL_MAX_LENGTH (RAND_POOL_FACTOR * \ | |
37 | 3 * (RAND_DRBG_STRENGTH / 16)) | |
38 | /* | |
39 | * = (RAND_POOL_FACTOR * \ | |
40 | * 1.5 * (RAND_DRBG_STRENGTH / 8)) | |
41 | */ | |
42 | ||
43 | /* | |
44 | * Initial allocation minimum. | |
45 | * | |
46 | * There is a distinction between the secure and normal allocation minimums. | |
47 | * Ideally, the secure allocation size should be a power of two. The normal | |
48 | * allocation size doesn't have any such restriction. | |
49 | * | |
50 | * The secure value is based on 128 bits of secure material, which is 16 bytes. | |
51 | * Typically, the DRBGs will set a minimum larger than this so optimal | |
52 | * allocation ought to take place (for full quality seed material). | |
53 | * | |
54 | * The normal value has been chosen by noticing that the rand_drbg_get_nonce | |
55 | * function is usually the largest of the built in allocation (twenty four | |
56 | * bytes and then appending another sixteen bytes). This means the buffer ends | |
57 | * with 40 bytes. The value of forty eight is comfortably above this which | |
58 | * allows some slack in the platform specific values used. | |
59 | */ | |
60 | # define RAND_POOL_MIN_ALLOCATION(secure) ((secure) ? 16 : 48) | |
61 | ||
62 | /* | |
63 | * The 'random pool' acts as a dumb container for collecting random | |
64 | * input from various entropy sources. It is the callers duty to 1) initialize | |
65 | * the random pool, 2) pass it to the polling callbacks, 3) seed the RNG, and | |
66 | * 4) cleanup the random pool again. | |
67 | * | |
68 | * The random pool contains no locking mechanism because its scope and | |
69 | * lifetime is intended to be restricted to a single stack frame. | |
70 | */ | |
71 | typedef struct rand_pool_st { | |
72 | unsigned char *buffer; /* points to the beginning of the random pool */ | |
73 | size_t len; /* current number of random bytes contained in the pool */ | |
74 | ||
75 | int attached; /* true pool was attached to existing buffer */ | |
76 | int secure; /* 1: allocated on the secure heap, 0: otherwise */ | |
77 | ||
78 | size_t min_len; /* minimum number of random bytes requested */ | |
79 | size_t max_len; /* maximum number of random bytes (allocated buffer size) */ | |
80 | size_t alloc_len; /* current number of bytes allocated */ | |
81 | size_t entropy; /* current entropy count in bits */ | |
82 | size_t entropy_requested; /* requested entropy count in bits */ | |
83 | } RAND_POOL; | |
84 | ||
85 | RAND_POOL *rand_pool_new(int entropy_requested, int secure, | |
86 | size_t min_len, size_t max_len); | |
87 | RAND_POOL *rand_pool_attach(const unsigned char *buffer, size_t len, | |
88 | size_t entropy); | |
89 | void rand_pool_free(RAND_POOL *pool); | |
90 | ||
91 | const unsigned char *rand_pool_buffer(RAND_POOL *pool); | |
92 | unsigned char *rand_pool_detach(RAND_POOL *pool); | |
93 | void rand_pool_reattach(RAND_POOL *pool, unsigned char *buffer); | |
94 | ||
95 | size_t rand_pool_entropy(RAND_POOL *pool); | |
96 | size_t rand_pool_length(RAND_POOL *pool); | |
97 | ||
98 | size_t rand_pool_entropy_available(RAND_POOL *pool); | |
99 | size_t rand_pool_entropy_needed(RAND_POOL *pool); | |
100 | /* |entropy_factor| expresses how many bits of data contain 1 bit of entropy */ | |
101 | size_t rand_pool_bytes_needed(RAND_POOL *pool, unsigned int entropy_factor); | |
102 | size_t rand_pool_bytes_remaining(RAND_POOL *pool); | |
103 | ||
104 | int rand_pool_add(RAND_POOL *pool, | |
105 | const unsigned char *buffer, size_t len, size_t entropy); | |
106 | unsigned char *rand_pool_add_begin(RAND_POOL *pool, size_t len); | |
107 | int rand_pool_add_end(RAND_POOL *pool, size_t len, size_t entropy); | |
108 | ||
109 | #endif /* OSSL_PROVIDER_RAND_POOL_H */ |