/src/botan/build/include/botan/pwdhash.h
Line | Count | Source (jump to first uncovered line) |
1 | | /* |
2 | | * (C) 2018 Ribose Inc |
3 | | * |
4 | | * Botan is released under the Simplified BSD License (see license.txt) |
5 | | */ |
6 | | |
7 | | #ifndef BOTAN_PWDHASH_H_ |
8 | | #define BOTAN_PWDHASH_H_ |
9 | | |
10 | | #include <botan/types.h> |
11 | | #include <string> |
12 | | #include <memory> |
13 | | #include <vector> |
14 | | #include <chrono> |
15 | | |
16 | | namespace Botan { |
17 | | |
18 | | /** |
19 | | * Base class for password based key derivation functions. |
20 | | * |
21 | | * Converts a password into a key using a salt and iterated hashing to |
22 | | * make brute force attacks harder. |
23 | | */ |
24 | | class BOTAN_PUBLIC_API(2,8) PasswordHash |
25 | | { |
26 | | public: |
27 | 0 | virtual ~PasswordHash() = default; |
28 | | |
29 | | virtual std::string to_string() const = 0; |
30 | | |
31 | | /** |
32 | | * Most password hashes have some notion of iterations. |
33 | | */ |
34 | | virtual size_t iterations() const = 0; |
35 | | |
36 | | /** |
37 | | * Some password hashing algorithms have a parameter which controls how |
38 | | * much memory is used. If not supported by some algorithm, returns 0. |
39 | | */ |
40 | 0 | virtual size_t memory_param() const { return 0; } |
41 | | |
42 | | /** |
43 | | * Some password hashing algorithms have a parallelism parameter. |
44 | | * If the algorithm does not support this notion, then the |
45 | | * function returns zero. This allows distinguishing between a |
46 | | * password hash which just does not support parallel operation, |
47 | | * vs one that does support parallel operation but which has been |
48 | | * configured to use a single lane. |
49 | | */ |
50 | 0 | virtual size_t parallelism() const { return 0; } |
51 | | |
52 | | /** |
53 | | * Returns an estimate of the total memory usage required to perform this |
54 | | * key derivation. |
55 | | * |
56 | | * If this algorithm uses a small and constant amount of memory, with no |
57 | | * effort made towards being memory hard, this function returns 0. |
58 | | */ |
59 | 0 | virtual size_t total_memory_usage() const { return 0; } |
60 | | |
61 | | /** |
62 | | * Derive a key from a password |
63 | | * |
64 | | * @param out buffer to store the derived key, must be of out_len bytes |
65 | | * @param out_len the desired length of the key to produce |
66 | | * @param password the password to derive the key from |
67 | | * @param password_len the length of password in bytes |
68 | | * @param salt a randomly chosen salt |
69 | | * @param salt_len length of salt in bytes |
70 | | * |
71 | | * This function is const, but is not thread safe. Different threads should |
72 | | * either use unique objects, or serialize all access. |
73 | | */ |
74 | | virtual void derive_key(uint8_t out[], size_t out_len, |
75 | | const char* password, size_t password_len, |
76 | | const uint8_t salt[], size_t salt_len) const = 0; |
77 | | }; |
78 | | |
79 | | class BOTAN_PUBLIC_API(2,8) PasswordHashFamily |
80 | | { |
81 | | public: |
82 | | /** |
83 | | * Create an instance based on a name |
84 | | * If provider is empty then best available is chosen. |
85 | | * @param algo_spec algorithm name |
86 | | * @param provider provider implementation to choose |
87 | | * @return a null pointer if the algo/provider combination cannot be found |
88 | | */ |
89 | | static std::unique_ptr<PasswordHashFamily> create(const std::string& algo_spec, |
90 | | const std::string& provider = ""); |
91 | | |
92 | | /** |
93 | | * Create an instance based on a name, or throw if the |
94 | | * algo/provider combination cannot be found. If provider is |
95 | | * empty then best available is chosen. |
96 | | */ |
97 | | static std::unique_ptr<PasswordHashFamily> |
98 | | create_or_throw(const std::string& algo_spec, |
99 | | const std::string& provider = ""); |
100 | | |
101 | | /** |
102 | | * @return list of available providers for this algorithm, empty if not available |
103 | | */ |
104 | | static std::vector<std::string> providers(const std::string& algo_spec); |
105 | | |
106 | 0 | virtual ~PasswordHashFamily() = default; |
107 | | |
108 | | /** |
109 | | * @return name of this PasswordHash |
110 | | */ |
111 | | virtual std::string name() const = 0; |
112 | | |
113 | | /** |
114 | | * Return a new parameter set tuned for this machine |
115 | | * @param output_length how long the output length will be |
116 | | * @param msec the desired execution time in milliseconds |
117 | | * |
118 | | * @param max_memory_usage_mb some password hash functions can use a tunable |
119 | | * amount of memory, in this case max_memory_usage limits the amount of RAM |
120 | | * the returned parameters will require, in mebibytes (2**20 bytes). It may |
121 | | * require some small amount above the request. Set to zero to place no |
122 | | * limit at all. |
123 | | */ |
124 | | virtual std::unique_ptr<PasswordHash> tune(size_t output_length, |
125 | | std::chrono::milliseconds msec, |
126 | | size_t max_memory_usage_mb = 0) const = 0; |
127 | | |
128 | | /** |
129 | | * Return some default parameter set for this PBKDF that should be good |
130 | | * enough for most users. The value returned may change over time as |
131 | | * processing power and attacks improve. |
132 | | */ |
133 | | virtual std::unique_ptr<PasswordHash> default_params() const = 0; |
134 | | |
135 | | /** |
136 | | * Return a parameter chosen based on a rough approximation with the |
137 | | * specified iteration count. The exact value this returns for a particular |
138 | | * algorithm may change from over time. Think of it as an alternative to |
139 | | * tune, where time is expressed in terms of PBKDF2 iterations rather than |
140 | | * milliseconds. |
141 | | */ |
142 | | virtual std::unique_ptr<PasswordHash> from_iterations(size_t iterations) const = 0; |
143 | | |
144 | | /** |
145 | | * Create a password hash using some scheme specific format. |
146 | | * Eg PBKDF2 and PGP-S2K set iterations in i1 |
147 | | * Scrypt uses N,r,p in i{1-3} |
148 | | * Bcrypt-PBKDF just has iterations |
149 | | * Argon2{i,d,id} would use iterations, memory, parallelism for i{1-3}, |
150 | | * and Argon2 type is part of the family. |
151 | | * |
152 | | * Values not needed should be set to 0 |
153 | | */ |
154 | | virtual std::unique_ptr<PasswordHash> from_params( |
155 | | size_t i1, |
156 | | size_t i2 = 0, |
157 | | size_t i3 = 0) const = 0; |
158 | | }; |
159 | | |
160 | | } |
161 | | |
162 | | #endif |