fuchsia / third_party / qemu / 394f0f72fd94595e656af62f079b7680cdbe8add / . / include / crypto / pbkdf.h

/* | |

* QEMU Crypto PBKDF support (Password-Based Key Derivation Function) | |

* | |

* Copyright (c) 2015-2016 Red Hat, Inc. | |

* | |

* This library is free software; you can redistribute it and/or | |

* modify it under the terms of the GNU Lesser General Public | |

* License as published by the Free Software Foundation; either | |

* version 2.1 of the License, or (at your option) any later version. | |

* | |

* This library is distributed in the hope that it will be useful, | |

* but WITHOUT ANY WARRANTY; without even the implied warranty of | |

* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | |

* Lesser General Public License for more details. | |

* | |

* You should have received a copy of the GNU Lesser General Public | |

* License along with this library; if not, see <http://www.gnu.org/licenses/>. | |

* | |

*/ | |

#ifndef QCRYPTO_PBKDF_H | |

#define QCRYPTO_PBKDF_H | |

#include "crypto/hash.h" | |

/** | |

* This module provides an interface to the PBKDF2 algorithm | |

* | |

* https://en.wikipedia.org/wiki/PBKDF2 | |

* | |

* <example> | |

* <title>Generating an AES encryption key from a user password</title> | |

* <programlisting> | |

* #include "crypto/cipher.h" | |

* #include "crypto/random.h" | |

* #include "crypto/pbkdf.h" | |

* | |

* .... | |

* | |

* char *password = "a-typical-awful-user-password"; | |

* size_t nkey = qcrypto_cipher_get_key_len(QCRYPTO_CIPHER_ALG_AES_128); | |

* uint8_t *salt = g_new0(uint8_t, nkey); | |

* uint8_t *key = g_new0(uint8_t, nkey); | |

* int iterations; | |

* QCryptoCipher *cipher; | |

* | |

* if (qcrypto_random_bytes(salt, nkey, errp) < 0) { | |

* g_free(key); | |

* g_free(salt); | |

* return -1; | |

* } | |

* | |

* iterations = qcrypto_pbkdf2_count_iters(QCRYPTO_HASH_ALG_SHA256, | |

* (const uint8_t *)password, | |

* strlen(password), | |

* salt, nkey, errp); | |

* if (iterations < 0) { | |

* g_free(key); | |

* g_free(salt); | |

* return -1; | |

* } | |

* | |

* if (qcrypto_pbkdf2(QCRYPTO_HASH_ALG_SHA256, | |

* (const uint8_t *)password, strlen(password), | |

* salt, nkey, iterations, key, nkey, errp) < 0) { | |

* g_free(key); | |

* g_free(salt); | |

* return -1; | |

* } | |

* | |

* g_free(salt); | |

* | |

* cipher = qcrypto_cipher_new(QCRYPTO_CIPHER_ALG_AES_128, | |

* QCRYPTO_CIPHER_MODE_ECB, | |

* key, nkey, errp); | |

* g_free(key); | |

* | |

* ....encrypt some data... | |

* | |

* qcrypto_cipher_free(cipher); | |

* </programlisting> | |

* </example> | |

* | |

*/ | |

/** | |

* qcrypto_pbkdf2_supports: | |

* @hash: the hash algorithm | |

* | |

* Determine if the current build supports the PBKDF2 algorithm | |

* in combination with the hash @hash. | |

* | |

* Returns true if supported, false otherwise | |

*/ | |

bool qcrypto_pbkdf2_supports(QCryptoHashAlgorithm hash); | |

/** | |

* qcrypto_pbkdf2: | |

* @hash: the hash algorithm to use | |

* @key: the user password / key | |

* @nkey: the length of @key in bytes | |

* @salt: a random salt | |

* @nsalt: length of @salt in bytes | |

* @iterations: the number of iterations to compute | |

* @out: pointer to pre-allocated buffer to hold output | |

* @nout: length of @out in bytes | |

* @errp: pointer to a NULL-initialized error object | |

* | |

* Apply the PBKDF2 algorithm to derive an encryption | |

* key from a user password provided in @key. The | |

* @salt parameter is used to perturb the algorithm. | |

* The @iterations count determines how many times | |

* the hashing process is run, which influences how | |

* hard it is to crack the key. The number of @iterations | |

* should be large enough such that the algorithm takes | |

* 1 second or longer to derive a key. The derived key | |

* will be stored in the preallocated buffer @out. | |

* | |

* Returns: 0 on success, -1 on error | |

*/ | |

int qcrypto_pbkdf2(QCryptoHashAlgorithm hash, | |

const uint8_t *key, size_t nkey, | |

const uint8_t *salt, size_t nsalt, | |

uint64_t iterations, | |

uint8_t *out, size_t nout, | |

Error **errp); | |

/** | |

* qcrypto_pbkdf2_count_iters: | |

* @hash: the hash algorithm to use | |

* @key: the user password / key | |

* @nkey: the length of @key in bytes | |

* @salt: a random salt | |

* @nsalt: length of @salt in bytes | |

* @nout: size of desired derived key | |

* @errp: pointer to a NULL-initialized error object | |

* | |

* Time the PBKDF2 algorithm to determine how many | |

* iterations are required to derive an encryption | |

* key from a user password provided in @key in 1 | |

* second of compute time. The result of this can | |

* be used as a the @iterations parameter of a later | |

* call to qcrypto_pbkdf2(). The value of @nout should | |

* match that value that will later be provided with | |

* a call to qcrypto_pbkdf2(). | |

* | |

* Returns: number of iterations in 1 second, -1 on error | |

*/ | |

uint64_t qcrypto_pbkdf2_count_iters(QCryptoHashAlgorithm hash, | |

const uint8_t *key, size_t nkey, | |

const uint8_t *salt, size_t nsalt, | |

size_t nout, | |

Error **errp); | |

#endif /* QCRYPTO_PBKDF_H */ |