ffi_kdf.cpp File Reference

#include <botan/ffi.h>
#include <botan/assert.h>
#include <botan/kdf.h>
#include <botan/pwdhash.h>
#include <botan/internal/ffi_rng.h>
#include <botan/internal/ffi_util.h>

Go to the source code of this file.

Functions
int	botan_bcrypt_generate (uint8_t *out, size_t *out_len, const char *pass, botan_rng_t rng_obj, size_t wf, uint32_t flags)
int	botan_bcrypt_is_valid (const char *pass, const char *hash)
int	botan_kdf (const char *kdf_algo, uint8_t out[], size_t out_len, const uint8_t secret[], size_t secret_len, const uint8_t salt[], size_t salt_len, const uint8_t label[], size_t label_len)
int	botan_pbkdf (const char *algo, uint8_t out[], size_t out_len, const char *pass, const uint8_t salt[], size_t salt_len, size_t iterations)
int	botan_pbkdf_timed (const char *algo, uint8_t out[], size_t out_len, const char *password, const uint8_t salt[], size_t salt_len, size_t ms_to_run, size_t *iterations_used)
int	botan_pwdhash (const char *algo, size_t param1, size_t param2, size_t param3, uint8_t out[], size_t out_len, const char *password, size_t password_len, const uint8_t salt[], size_t salt_len)
int	botan_pwdhash_timed (const char *algo, uint32_t msec, size_t *param1, size_t *param2, size_t *param3, uint8_t out[], size_t out_len, const char *password, size_t password_len, const uint8_t salt[], size_t salt_len)
int	botan_scrypt (uint8_t out[], size_t out_len, const char *password, const uint8_t salt[], size_t salt_len, size_t N, size_t r, size_t p)

Function Documentation

botan_bcrypt_generate()

int botan_bcrypt_generate	(	uint8_t *	out,
		size_t *	out_len,
		const char *	password,
		botan_rng_t	rng,
		size_t	work_factor,
		uint32_t	flags )

Create a password hash using Bcrypt

Parameters

out	buffer holding the password hash, should be of length 64 bytes
out_len	the desired output length in bytes
password	the password
Random Number Generators	a random number generator
work_factor	how much work to do to slow down guessing attacks
flags	should be 0 in current API revision, all other uses are reserved and return BOTAN_FFI_ERROR_BAD_FLAG

Returns

0 on success, a negative value on failure

Output is formatted bcrypt $2a$...

TOD(Botan4) this should use char for the type of out

Definition at line 177 of file ffi_kdf.cpp.

                                                                                                    {
#if defined(BOTAN_HAS_BCRYPT)
   return ffi_guard_thunk(__func__, [=]() -> int {
      if(any_null_pointers(out, out_len, pass)) {
         return BOTAN_FFI_ERROR_NULL_POINTER;
      }
 
      if(flags != 0) {
         return BOTAN_FFI_ERROR_BAD_FLAG;
      }
 
      if(wf < 4 || wf > 18) {
         return BOTAN_FFI_ERROR_BAD_PARAMETER;
      }
 
      if(*out_len < 61) {
         *out_len = 61;
         return BOTAN_FFI_ERROR_INSUFFICIENT_BUFFER_SPACE;
      }
 
      Botan::RandomNumberGenerator& rng = safe_get(rng_obj);
      const std::string bcrypt = Botan::generate_bcrypt(pass, rng, static_cast<uint16_t>(wf));
      // TODO(Botan4) change the type of out and remove this cast
      return write_str_output(reinterpret_cast<char*>(out), out_len, bcrypt);
   });
#else
   BOTAN_UNUSED(out, out_len, pass, rng_obj, wf, flags);
   return BOTAN_FFI_ERROR_NOT_IMPLEMENTED;
#endif
}

References Botan_FFI::any_null_pointers(), BOTAN_FFI_ERROR_BAD_FLAG, BOTAN_FFI_ERROR_BAD_PARAMETER, BOTAN_FFI_ERROR_INSUFFICIENT_BUFFER_SPACE, BOTAN_FFI_ERROR_NOT_IMPLEMENTED, BOTAN_FFI_ERROR_NULL_POINTER, BOTAN_UNUSED, Botan_FFI::ffi_guard_thunk(), Botan::generate_bcrypt(), Botan_FFI::safe_get(), and Botan_FFI::write_str_output().

botan_bcrypt_is_valid()

int botan_bcrypt_is_valid	(	const char *	pass,
		const char *	hash )

Check a previously created password hash

Parameters

pass	the password to check against
Hashes	the stored hash to check against

Returns

0 if if this password/hash combination is valid, 1 if the combination is not valid (but otherwise well formed), negative on error

Definition at line 209 of file ffi_kdf.cpp.

                                                              {
   if(any_null_pointers(pass, hash)) {
      return BOTAN_FFI_ERROR_NULL_POINTER;
   }
#if defined(BOTAN_HAS_BCRYPT)
   return ffi_guard_thunk(__func__, [=]() -> int {
      return Botan::check_bcrypt(pass, hash) ? BOTAN_FFI_SUCCESS : BOTAN_FFI_INVALID_VERIFIER;
   });
#else
   BOTAN_UNUSED(pass, hash);
   return BOTAN_FFI_ERROR_NOT_IMPLEMENTED;
#endif
}

References Botan_FFI::any_null_pointers(), BOTAN_FFI_ERROR_NOT_IMPLEMENTED, BOTAN_FFI_ERROR_NULL_POINTER, BOTAN_FFI_INVALID_VERIFIER, BOTAN_FFI_SUCCESS, BOTAN_UNUSED, Botan::check_bcrypt(), and Botan_FFI::ffi_guard_thunk().

botan_kdf()

int botan_kdf	(	const char *	kdf_algo,
		uint8_t	out[],
		size_t	out_len,
		const uint8_t	secret[],
		size_t	secret_len,
		const uint8_t	salt[],
		size_t	salt_len,
		const uint8_t	label[],
		size_t	label_len )

Derive a key

Parameters

kdf_algo	KDF algorithm, e.g., "SP800-56C"
out	buffer holding the derived key, must be of length out_len
out_len	the desired output length in bytes
secret	the secret input
secret_len	size of secret in bytes
salt	a diversifier
salt_len	size of salt in bytes
label	purpose for the derived keying material
label_len	size of label in bytes

Returns

0 on success, a negative value on failure

Definition at line 143 of file ffi_kdf.cpp.

                                {
   if(kdf_algo == nullptr) {
      return BOTAN_FFI_ERROR_NULL_POINTER;
   }
   if((out_len > 0 && out == nullptr) || (secret_len > 0 && secret == nullptr) || (salt_len > 0 && salt == nullptr) ||
      (label_len > 0 && label == nullptr)) {
      return BOTAN_FFI_ERROR_NULL_POINTER;
   }
   return ffi_guard_thunk(__func__, [=]() -> int {
      auto kdf = Botan::KDF::create_or_throw(kdf_algo);
      kdf->kdf(out, out_len, secret, secret_len, salt, salt_len, label, label_len);
      return BOTAN_FFI_SUCCESS;
   });
}

References BOTAN_FFI_ERROR_NULL_POINTER, BOTAN_FFI_SUCCESS, Botan::KDF::create_or_throw(), and Botan_FFI::ffi_guard_thunk().

botan_pbkdf()

int botan_pbkdf	(	const char *	pbkdf_algo,
		uint8_t	out[],
		size_t	out_len,
		const char *	passphrase,
		const uint8_t	salt[],
		size_t	salt_len,
		size_t	iterations )

Derive a key from a passphrase for a number of iterations

Parameters

pbkdf_algo	PBKDF algorithm, e.g., "PBKDF2(SHA-256)"
out	buffer to store the derived key, must be of out_len bytes
out_len	the desired length of the key to produce
passphrase	the password to derive the key from
salt	a randomly chosen salt
salt_len	length of salt in bytes
iterations	the number of iterations to use (use 10K or more)

Returns

0 on success, a negative value on failure

Deprecated: use botan_pwdhash(pbkdf_algo, iterations, 0, 0, out, out_len, passphrase, 0, salt, salt_len);

Definition at line 23 of file ffi_kdf.cpp.

                                   {
   return botan_pwdhash(algo, iterations, 0, 0, out, out_len, pass, 0, salt, salt_len);
}

References botan_pwdhash().

botan_pbkdf_timed()

int botan_pbkdf_timed	(	const char *	pbkdf_algo,
		uint8_t	out[],
		size_t	out_len,
		const char *	passphrase,
		const uint8_t	salt[],
		size_t	salt_len,
		size_t	milliseconds_to_run,
		size_t *	out_iterations_used )

Derive a key from a passphrase, running until msec time has elapsed.

Parameters

pbkdf_algo	PBKDF algorithm, e.g., "PBKDF2(SHA-256)"
out	buffer to store the derived key, must be of out_len bytes
out_len	the desired length of the key to produce
passphrase	the password to derive the key from
salt	a randomly chosen salt
salt_len	length of salt in bytes
milliseconds_to_run	if iterations is zero, then instead the PBKDF is run until milliseconds_to_run milliseconds has passed
out_iterations_used	set to the number iterations executed

Returns

0 on success, a negative value on failure

Deprecated: use

botan_pwdhash_timed(pbkdf_algo, static_cast<uint32_t>(ms_to_run), iterations_used, nullptr, nullptr, out, out_len, password, 0, salt, salt_len);

Definition at line 33 of file ffi_kdf.cpp.

                                               {
   return botan_pwdhash_timed(algo,
                              static_cast<uint32_t>(ms_to_run),
                              iterations_used,
                              nullptr,
                              nullptr,
                              out,
                              out_len,
                              password,
                              0,
                              salt,
                              salt_len);
}

References botan_pwdhash_timed().

botan_pwdhash()

int botan_pwdhash	(	const char *	algo,
		size_t	param1,
		size_t	param2,
		size_t	param3,
		uint8_t	out[],
		size_t	out_len,
		const char *	passphrase,
		size_t	passphrase_len,
		const uint8_t	salt[],
		size_t	salt_len )

Derive a key from a passphrase

Parameters

algo	PBKDF algorithm, e.g., "PBKDF2(SHA-256)" or "Scrypt"
param1	the first PBKDF algorithm parameter
param2	the second PBKDF algorithm parameter (may be zero if unneeded)
param3	the third PBKDF algorithm parameter (may be zero if unneeded)
out	buffer to store the derived key, must be of out_len bytes
out_len	the desired length of the key to produce
passphrase	the password to derive the key from
passphrase_len	if > 0, specifies length of password. If len == 0, then strlen will be called on passphrase to compute the length.
salt	a randomly chosen salt
salt_len	length of salt in bytes

Returns

0 on success, a negative value on failure

Definition at line 54 of file ffi_kdf.cpp.

                                   {
   if(any_null_pointers(algo, password)) {
      return BOTAN_FFI_ERROR_NULL_POINTER;
   }
   if(out_len > 0 && out == nullptr) {
      return BOTAN_FFI_ERROR_NULL_POINTER;
   }
   if(salt_len > 0 && salt == nullptr) {
      return BOTAN_FFI_ERROR_NULL_POINTER;
   }
 
   if(password_len == 0) {
      password_len = std::strlen(password);
   }
 
   return ffi_guard_thunk(__func__, [=]() -> int {
      auto pwdhash_fam = Botan::PasswordHashFamily::create(algo);
 
      if(!pwdhash_fam) {
         return BOTAN_FFI_ERROR_NOT_IMPLEMENTED;
      }
 
      auto pwdhash = pwdhash_fam->from_params(param1, param2, param3);
 
      pwdhash->derive_key(out, out_len, password, password_len, salt, salt_len);
 
      return BOTAN_FFI_SUCCESS;
   });
}

References Botan_FFI::any_null_pointers(), BOTAN_FFI_ERROR_NOT_IMPLEMENTED, BOTAN_FFI_ERROR_NULL_POINTER, BOTAN_FFI_SUCCESS, Botan::PasswordHashFamily::create(), and Botan_FFI::ffi_guard_thunk().

Referenced by botan_pbkdf(), and botan_scrypt().

botan_pwdhash_timed()

int botan_pwdhash_timed	(	const char *	algo,
		uint32_t	msec,
		size_t *	param1,
		size_t *	param2,
		size_t *	param3,
		uint8_t	out[],
		size_t	out_len,
		const char *	passphrase,
		size_t	passphrase_len,
		const uint8_t	salt[],
		size_t	salt_len )

Derive a key from a passphrase, choosing parameters to hit a target runtime

Parameters

algo	PBKDF algorithm, e.g., "Scrypt" or "PBKDF2(SHA-256)"
msec	the desired runtime in milliseconds
param1	will be set to the first password hash parameter
param2	will be set to the second password hash parameter
param3	will be set to the third password hash parameter
out	buffer to store the derived key, must be of out_len bytes
out_len	the desired length of the key to produce
passphrase	the password to derive the key from
passphrase_len	if > 0, specifies length of password. If len == 0, then strlen will be called on passphrase to compute the length.
salt	a randomly chosen salt
salt_len	length of salt in bytes

Returns

0 on success, a negative value on failure

Definition at line 93 of file ffi_kdf.cpp.

                                         {
   if(any_null_pointers(algo, password)) {
      return BOTAN_FFI_ERROR_NULL_POINTER;
   }
   if(out_len > 0 && out == nullptr) {
      return BOTAN_FFI_ERROR_NULL_POINTER;
   }
   if(salt_len > 0 && salt == nullptr) {
      return BOTAN_FFI_ERROR_NULL_POINTER;
   }
 
   if(password_len == 0) {
      password_len = std::strlen(password);
   }
 
   return ffi_guard_thunk(__func__, [=]() -> int {
      auto pwdhash_fam = Botan::PasswordHashFamily::create(algo);
 
      if(!pwdhash_fam) {
         return BOTAN_FFI_ERROR_NOT_IMPLEMENTED;
      }
 
      auto pwdhash = pwdhash_fam->tune_params(out_len, msec);
 
      if(param1 != nullptr) {
         *param1 = pwdhash->iterations();
      }
      if(param2 != nullptr) {
         *param2 = pwdhash->parallelism();
      }
      if(param3 != nullptr) {
         *param3 = pwdhash->memory_param();
      }
 
      pwdhash->derive_key(out, out_len, password, password_len, salt, salt_len);
 
      return BOTAN_FFI_SUCCESS;
   });
}

References Botan_FFI::any_null_pointers(), BOTAN_FFI_ERROR_NOT_IMPLEMENTED, BOTAN_FFI_ERROR_NULL_POINTER, BOTAN_FFI_SUCCESS, Botan::PasswordHashFamily::create(), and Botan_FFI::ffi_guard_thunk().

Referenced by botan_pbkdf_timed().

botan_scrypt()

int botan_scrypt	(	uint8_t	out[],
		size_t	out_len,
		const char *	passphrase,
		const uint8_t	salt[],
		size_t	salt_len,
		size_t	N,
		size_t	r,
		size_t	p )

Derive a key using scrypt Deprecated; use botan_pwdhash("Scrypt", N, r, p, out, out_len, password, 0, salt, salt_len);

Definition at line 166 of file ffi_kdf.cpp.

                           {
   return botan_pwdhash("Scrypt", N, r, p, out, out_len, password, 0, salt, salt_len);
}

References botan_pwdhash().