xref: /openbmc/qemu/include/crypto/pbkdf.h (revision 4a10982c)
1 /*
2  * QEMU Crypto PBKDF support (Password-Based Key Derivation Function)
3  *
4  * Copyright (c) 2015-2016 Red Hat, Inc.
5  *
6  * This library is free software; you can redistribute it and/or
7  * modify it under the terms of the GNU Lesser General Public
8  * License as published by the Free Software Foundation; either
9  * version 2.1 of the License, or (at your option) any later version.
10  *
11  * This library is distributed in the hope that it will be useful,
12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
14  * Lesser General Public License for more details.
15  *
16  * You should have received a copy of the GNU Lesser General Public
17  * License along with this library; if not, see <http://www.gnu.org/licenses/>.
18  *
19  */
20 
21 #ifndef QCRYPTO_PBKDF_H
22 #define QCRYPTO_PBKDF_H
23 
24 #include "crypto/hash.h"
25 
26 /**
27  * This module provides an interface to the PBKDF2 algorithm
28  *
29  *   https://en.wikipedia.org/wiki/PBKDF2
30  *
31  * <example>
32  *   <title>Generating an AES encryption key from a user password</title>
33  *   <programlisting>
34  * #include "crypto/cipher.h"
35  * #include "crypto/random.h"
36  * #include "crypto/pbkdf.h"
37  *
38  * ....
39  *
40  * char *password = "a-typical-awful-user-password";
41  * size_t nkey = qcrypto_cipher_get_key_len(QCRYPTO_CIPHER_ALG_AES_128);
42  * uint8_t *salt = g_new0(uint8_t, nkey);
43  * uint8_t *key = g_new0(uint8_t, nkey);
44  * int iterations;
45  * QCryptoCipher *cipher;
46  *
47  * if (qcrypto_random_bytes(salt, nkey, errp) < 0) {
48  *     g_free(key);
49  *     g_free(salt);
50  *     return -1;
51  * }
52  *
53  * iterations = qcrypto_pbkdf2_count_iters(QCRYPTO_HASH_ALG_SHA256,
54  *                                         (const uint8_t *)password,
55  *                                         strlen(password),
56  *                                         salt, nkey, errp);
57  * if (iterations < 0) {
58  *     g_free(key);
59  *     g_free(salt);
60  *     return -1;
61  * }
62  *
63  * if (qcrypto_pbkdf2(QCRYPTO_HASH_ALG_SHA256,
64  *                    (const uint8_t *)password, strlen(password),
65  *                    salt, nkey, iterations, key, nkey, errp) < 0) {
66  *     g_free(key);
67  *     g_free(salt);
68  *     return -1;
69  * }
70  *
71  * g_free(salt);
72  *
73  * cipher = qcrypto_cipher_new(QCRYPTO_CIPHER_ALG_AES_128,
74  *                             QCRYPTO_CIPHER_MODE_ECB,
75  *                             key, nkey, errp);
76  * g_free(key);
77  *
78  * ....encrypt some data...
79  *
80  * qcrypto_cipher_free(cipher);
81  *   </programlisting>
82  * </example>
83  *
84  */
85 
86 /**
87  * qcrypto_pbkdf2_supports:
88  * @hash: the hash algorithm
89  *
90  * Determine if the current build supports the PBKDF2 algorithm
91  * in combination with the hash @hash.
92  *
93  * Returns true if supported, false otherwise
94  */
95 bool qcrypto_pbkdf2_supports(QCryptoHashAlgorithm hash);
96 
97 
98 /**
99  * qcrypto_pbkdf2:
100  * @hash: the hash algorithm to use
101  * @key: the user password / key
102  * @nkey: the length of @key in bytes
103  * @salt: a random salt
104  * @nsalt: length of @salt in bytes
105  * @iterations: the number of iterations to compute
106  * @out: pointer to pre-allocated buffer to hold output
107  * @nout: length of @out in bytes
108  * @errp: pointer to a NULL-initialized error object
109  *
110  * Apply the PBKDF2 algorithm to derive an encryption
111  * key from a user password provided in @key. The
112  * @salt parameter is used to perturb the algorithm.
113  * The @iterations count determines how many times
114  * the hashing process is run, which influences how
115  * hard it is to crack the key. The number of @iterations
116  * should be large enough such that the algorithm takes
117  * 1 second or longer to derive a key. The derived key
118  * will be stored in the preallocated buffer @out.
119  *
120  * Returns: 0 on success, -1 on error
121  */
122 int qcrypto_pbkdf2(QCryptoHashAlgorithm hash,
123                    const uint8_t *key, size_t nkey,
124                    const uint8_t *salt, size_t nsalt,
125                    uint64_t iterations,
126                    uint8_t *out, size_t nout,
127                    Error **errp);
128 
129 /**
130  * qcrypto_pbkdf2_count_iters:
131  * @hash: the hash algorithm to use
132  * @key: the user password / key
133  * @nkey: the length of @key in bytes
134  * @salt: a random salt
135  * @nsalt: length of @salt in bytes
136  * @nout: size of desired derived key
137  * @errp: pointer to a NULL-initialized error object
138  *
139  * Time the PBKDF2 algorithm to determine how many
140  * iterations are required to derive an encryption
141  * key from a user password provided in @key in 1
142  * second of compute time. The result of this can
143  * be used as a the @iterations parameter of a later
144  * call to qcrypto_pbkdf2(). The value of @nout should
145  * match that value that will later be provided with
146  * a call to qcrypto_pbkdf2().
147  *
148  * Returns: number of iterations in 1 second, -1 on error
149  */
150 uint64_t qcrypto_pbkdf2_count_iters(QCryptoHashAlgorithm hash,
151                                     const uint8_t *key, size_t nkey,
152                                     const uint8_t *salt, size_t nsalt,
153                                     size_t nout,
154                                     Error **errp);
155 
156 #endif /* QCRYPTO_PBKDF_H */
157