Coverage Report

Created: 2020-05-23 13:54

/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