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(out == nullptr || out_len == nullptr || pass == nullptr) {
         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_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 *	algo,
		uint8_t	out[],
		size_t	out_len,
		const char *	pass,
		const uint8_t	salt[],
		size_t	salt_len,
		size_t	iterations )

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 *	password,
		size_t	password_len,
		const uint8_t	salt[],
		size_t	salt_len )

Definition at line 54 of file ffi_kdf.cpp.

                                   {
   if(algo == nullptr || password == nullptr) {
      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_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 *	password,
		size_t	password_len,
		const uint8_t	salt[],
		size_t	salt_len )

Definition at line 93 of file ffi_kdf.cpp.

                                         {
   if(algo == nullptr || password == nullptr) {
      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_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().