Add ENET device to i.MX6 SOC.
[qemu.git] / include / crypto / pbkdf.h
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 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 unsigned int 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 * @errp: pointer to a NULL-initialized error object
137 *
138 * Time the PBKDF2 algorithm to determine how many
139 * iterations are required to derive an encryption
140 * key from a user password provided in @key in 1
141 * second of compute time. The result of this can
142 * be used as a the @iterations parameter of a later
143 * call to qcrypto_pbkdf2().
144 *
145 * Returns: number of iterations in 1 second, -1 on error
146 */
147 int qcrypto_pbkdf2_count_iters(QCryptoHashAlgorithm hash,
148 const uint8_t *key, size_t nkey,
149 const uint8_t *salt, size_t nsalt,
150 Error **errp);
151
152 #endif /* QCRYPTO_PBKDF_H__ */