Botan::Encrypted_PSK_Database Class Reference

#include <psk_db.h>

Inheritance diagram for Botan::Encrypted_PSK_Database:

Public Member Functions
	Encrypted_PSK_Database (const secure_vector< uint8_t > &master_key)
secure_vector< uint8_t >	get (std::string_view name) const override
std::string	get_str (std::string_view name) const
bool	is_encrypted () const override
std::set< std::string >	list_names () const override
void	remove (std::string_view name) override
void	set (std::string_view name, const uint8_t psk[], size_t psk_len) override
void	set_str (std::string_view name, std::string_view psk)
void	set_vec (std::string_view name, std::span< const uint8_t > psk)
	~Encrypted_PSK_Database () override

Protected Member Functions
virtual void	kv_del (std::string_view index)=0
virtual std::string	kv_get (std::string_view index) const =0
virtual std::set< std::string >	kv_get_all () const =0
virtual void	kv_set (std::string_view index, std::string_view value)=0

Detailed Description

A mixin for an encrypted PSK database.

Both names and values are encrypted using NIST key wrapping (see NIST SP800-38F) with AES-256. First the master key is used with HMAC(SHA-256) to derive two 256-bit keys, one for encrypting all names and the other to key an instance of HMAC(SHA-256). Values are each encrypted under an individual key created by hashing the encrypted name with HMAC. This associates the encrypted key with the name, and prevents an attacker with write access to the data store from taking an encrypted key associated with one entity and copying it to another entity.

Names and PSKs are both padded to the next multiple of 8 bytes, providing some obfuscation of the length.

Subclasses must implement the virtual calls to handle storing and getting raw (base64 encoded) values.

Definition at line 92 of file psk_db.h.

Constructor & Destructor Documentation

Encrypted_PSK_Database()

Botan::Encrypted_PSK_Database::Encrypted_PSK_Database

(

const secure_vector< uint8_t > &

master_key

)

Initializes or opens a PSK database. The master_key is used to secure the contents. It may be of any length. If encrypting PSKs under a passphrase, use a suitable key derivation scheme (such as Argon2id) to derive the secret key. If the master key is lost, all PSKs stored are unrecoverable.

One artifact of the names being encrypted is that is is possible to use multiple different master keys with the same underlying storage. Each master key will be responsible for a subset of the keys. An attacker who knows one of the keys will be able to tell there are other values encrypted under another key, but will not be able to tell how many other master keys are in use.

Parameters

master_key

specifies the master key used to encrypt all keys and value. It can be of any length, but should be at least 256 bits.

Subkeys for the cryptographic algorithms used are derived from this master key. No key stretching is performed; if encrypting a PSK database using a password, it is recommended to use Argon2id to derive the database master key.

Definition at line 27 of file psk_db.cpp.

                                                                                       {
   m_cipher = BlockCipher::create_or_throw("AES-256");
   m_hmac = MessageAuthenticationCode::create_or_throw("HMAC(SHA-256)");
   m_hmac->set_key(master_key);
 
   m_cipher->set_key(m_hmac->process("wrap"));
   m_hmac->set_key(m_hmac->process("hmac"));
}

References Botan::BlockCipher::create_or_throw(), and Botan::MessageAuthenticationCode::create_or_throw().

~Encrypted_PSK_Database()

Botan::Encrypted_PSK_Database::~Encrypted_PSK_Database ( )

overridedefault

Member Function Documentation

get()

secure_vector< uint8_t > Botan::Encrypted_PSK_Database::get ( std::string_view name ) const

overridevirtual

Returns

the value associated with the specified name or otherwise throw an exception.

Implements Botan::PSK_Database.

Definition at line 63 of file psk_db.cpp.

                                                                            {
   const std::vector<uint8_t> wrapped_name =
      nist_key_wrap_padded(cast_char_ptr_to_uint8(name.data()), name.size(), *m_cipher);
 
   const std::string val_base64 = kv_get(base64_encode(wrapped_name));
 
   if(val_base64.empty()) {
      throw Invalid_Argument("Named PSK not located");
   }
 
   const secure_vector<uint8_t> val = base64_decode(val_base64);
 
   auto wrap_cipher = m_cipher->new_object();
   wrap_cipher->set_key(m_hmac->process(wrapped_name));
 
   return nist_key_unwrap_padded(val.data(), val.size(), *wrap_cipher);
}

References Botan::base64_decode(), Botan::base64_encode(), Botan::cast_char_ptr_to_uint8(), kv_get(), name, Botan::nist_key_unwrap_padded(), and Botan::nist_key_wrap_padded().

get_str()

std::string Botan::PSK_Database::get_str ( std::string_view name ) const

inherited

Get a PSK in the form of a string (eg if the PSK is a password)

Definition at line 18 of file psk_db.cpp.

                                                         {
   secure_vector<uint8_t> psk = this->get(name);
   return std::string(cast_uint8_ptr_to_char(psk.data()), psk.size());
}

References Botan::cast_uint8_ptr_to_char(), and Botan::PSK_Database::get().

is_encrypted()

bool Botan::Encrypted_PSK_Database::is_encrypted ( ) const

inlineoverridevirtual

Returns

true if the values in the PSK database are encrypted. If false, saved values are being stored in plaintext.

Implements Botan::PSK_Database.

Definition at line 128 of file psk_db.h.

{ return true; }

kv_del()

virtual void Botan::Encrypted_PSK_Database::kv_del ( std::string_view index )

protectedpure virtual

Remove an index

Referenced by remove().

kv_get()

virtual std::string Botan::Encrypted_PSK_Database::kv_get ( std::string_view index ) const

protectedpure virtual

Get a value previously saved with kv_set(). Should return an empty string if index is not found.

Referenced by get().

kv_get_all()

virtual std::set< std::string > Botan::Encrypted_PSK_Database::kv_get_all ( ) const

protectedpure virtual

Return all indexes in the table (ie values for which kv_get will return a non-empty string)

Referenced by list_names().

kv_set()

virtual void Botan::Encrypted_PSK_Database::kv_set ( std::string_view index, std::string_view value )

protectedpure virtual

Save a encrypted (name/value) pair to the database. Both will be base64 encoded strings.

Referenced by set().

list_names()

std::set< std::string > Botan::Encrypted_PSK_Database::list_names ( ) const

overridevirtual

Returns

the set of names for which get() will return a value.

Implements Botan::PSK_Database.

Definition at line 38 of file psk_db.cpp.

                                                           {
   const std::set<std::string> encrypted_names = kv_get_all();
 
   std::set<std::string> names;
 
   for(const auto& enc_name : encrypted_names) {
      try {
         const secure_vector<uint8_t> raw_name = base64_decode(enc_name);
         const secure_vector<uint8_t> name_bits = nist_key_unwrap_padded(raw_name.data(), raw_name.size(), *m_cipher);
 
         std::string pt_name(cast_uint8_ptr_to_char(name_bits.data()), name_bits.size());
         names.insert(pt_name);
      } catch(Invalid_Authentication_Tag&) {}
   }
 
   return names;
}

References Botan::base64_decode(), Botan::cast_uint8_ptr_to_char(), kv_get_all(), and Botan::nist_key_unwrap_padded().

remove()

void Botan::Encrypted_PSK_Database::remove ( std::string_view name )

overridevirtual

Remove the PSK with the given name from the database

Implements Botan::PSK_Database.

Definition at line 56 of file psk_db.cpp.

                                                       {
   const std::vector<uint8_t> wrapped_name =
      nist_key_wrap_padded(cast_char_ptr_to_uint8(name.data()), name.size(), *m_cipher);
 
   this->kv_del(base64_encode(wrapped_name));
}

References Botan::base64_encode(), Botan::cast_char_ptr_to_uint8(), kv_del(), name, and Botan::nist_key_wrap_padded().

set()

void Botan::Encrypted_PSK_Database::set ( std::string_view name, const uint8_t psk[], size_t psk_len )

overridevirtual

Set a value that can later be accessed with get(). If name already exists in the database, the old value will be overwritten.

Implements Botan::PSK_Database.

Definition at line 81 of file psk_db.cpp.

                                                                                     {
   /*
   * Both as a basic precaution wrt key seperation, and specifically to prevent
   * cut-and-paste attacks against the database, each PSK is encrypted with a
   * distinct key which is derived by hashing the wrapped key name with HMAC.
   */
   const std::vector<uint8_t> wrapped_name =
      nist_key_wrap_padded(cast_char_ptr_to_uint8(name.data()), name.size(), *m_cipher);
 
   auto wrap_cipher = m_cipher->new_object();
   wrap_cipher->set_key(m_hmac->process(wrapped_name));
   const std::vector<uint8_t> wrapped_key = nist_key_wrap_padded(val, len, *wrap_cipher);
 
   this->kv_set(base64_encode(wrapped_name), base64_encode(wrapped_key));
}

References Botan::base64_encode(), Botan::cast_char_ptr_to_uint8(), kv_set(), name, and Botan::nist_key_wrap_padded().

set_str()

void Botan::PSK_Database::set_str ( std::string_view name, std::string_view psk )

inherited

Like set() but accepts the PSK as a string (eg for a password).

Definition at line 23 of file psk_db.cpp.

                                                                  {
   this->set(name, cast_char_ptr_to_uint8(psk.data()), psk.size());
}

References Botan::cast_char_ptr_to_uint8(), and Botan::PSK_Database::set().

set_vec()

void Botan::PSK_Database::set_vec ( std::string_view name, std::span< const uint8_t > psk )

inlineinherited

Like set() but accepting an arbitrary contiguous byte array.

Definition at line 69 of file psk_db.h.

{ set(name, psk.data(), psk.size()); }

References name.

---

The documentation for this class was generated from the following files:

• src/lib/psk_db/psk_db.h
• src/lib/psk_db/psk_db.cpp