pbkdf.h (5041B)
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 */