Botan 2.19.1
Crypto and TLS for C&
pwdhash.h
Go to the documentation of this file.
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
16namespace 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*/
25 {
26 public:
27 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 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 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 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
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 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
virtual std::string name() const =0
virtual std::unique_ptr< PasswordHash > tune(size_t output_length, std::chrono::milliseconds msec, size_t max_memory_usage_mb=0) const =0
virtual std::unique_ptr< PasswordHash > from_iterations(size_t iterations) const =0
virtual ~PasswordHashFamily()=default
virtual std::unique_ptr< PasswordHash > default_params() const =0
virtual std::unique_ptr< PasswordHash > from_params(size_t i1, size_t i2=0, size_t i3=0) const =0
virtual size_t total_memory_usage() const
Definition: pwdhash.h:59
virtual size_t parallelism() const
Definition: pwdhash.h:50
virtual size_t iterations() const =0
virtual ~PasswordHash()=default
virtual void derive_key(uint8_t out[], size_t out_len, const char *password, size_t password_len, const uint8_t salt[], size_t salt_len) const =0
virtual size_t memory_param() const
Definition: pwdhash.h:40
virtual std::string to_string() const =0
#define BOTAN_PUBLIC_API(maj, min)
Definition: compiler.h:31
Definition: alg_id.cpp:13
size_t salt_len
Definition: x509_obj.cpp:25