← Back to branch summary

~ubuntu-branches/debian/sid/botan/sid

« back to all changes in this revision

Viewing changes to doc/manual/psk_db.rst

  • Committer: Package Import Robot
  • Author(s): Laszlo Boszormenyi (GCS)
  • Date: 2018-03-01 22:23:25 UTC
  • mfrom: (1.2.2)
  • Revision ID: package-import@ubuntu.com-20180301222325-7p7vc45gu3hta34d
Tags: 2.4.0-2
* Don't remove .doctrees from the manual if it doesn't exist.
* Don't specify parallel to debhelper.

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/manual/psk_db.rst
 
1
PSK Database
 
2
======================
 
3
 
 
4
.. versionadded:: 2.4.0
 
5
 
 
6
Many applications need to store pre-shared keys (hereafter PSKs) for
 
7
authentication purposes.
 
8
 
 
9
An abstract interface to PSK stores is provided in ``psk_db.h``
 
10
 
 
11
.. cpp:class:: PSK_Database
 
12
 
 
13
   .. cpp:function:: bool is_encrypted() const
 
14
 
 
15
      Returns true if (at least) the PSKs themselves are encrypted. Returns
 
16
      false if PSKs are stored in plaintext.
 
17
 
 
18
   .. cpp:function:: std::set<std::string> list_names() const
 
19
 
 
20
      Return the set of valid names stored in the database, ie values for which
 
21
      ``get`` will return a value.
 
22
 
 
23
   .. cpp:function:: void set(const std::string& name, const uint8_t psk[], size_t psk_len)
 
24
 
 
25
      Save a PSK. If ``name`` already exists, the current value will be
 
26
      overwritten.
 
27
 
 
28
   .. cpp:function:: secure_vector<uint8_t> get(const std::string& name) const
 
29
 
 
30
      Return a value saved with ``set``. Throws an exception if ``name`` doesn't
 
31
      exist.
 
32
 
 
33
   .. cpp:function:: void remove(const std::string& name)
 
34
 
 
35
      Remove ``name`` from the database. If ``name`` doesn't exist, ignores the request.
 
36
 
 
37
   .. cpp::function:: std::string get_str(const std::string& name) const
 
38
 
 
39
      Like ``get`` but casts the return value to a string.
 
40
 
 
41
   .. cpp:function:: void set_str(const std::string& name, const std::string& psk)
 
42
 
 
43
      Like ``set`` but accepts the psk as a string (eg for a password).
 
44
 
 
45
   .. cpp:function:: template<typename Alloc> void set_vec(const std::string& name, \
 
46
                                              const std::vector<uint8_t, Alloc>& psk)
 
47
 
 
48
      Like ``set`` but accepting a vector.
 
49
 
 
50
The same header also provides a specific instantiation of ``PSK_Database`` which
 
51
encrypts both names and PSKs. It must be subclassed to provide the storage.
 
52
 
 
53
.. cpp:class:: Encrypted_PSK_Database : public PSK_Database
 
54
 
 
55
   .. cpp:function:: Encrypted_PSK_Database(const secure_vector<uint8_t>& master_key)
 
56
 
 
57
      Initializes or opens a PSK database. The master key is used the secure the
 
58
      contents. It may be of any length. If encrypting PSKs under a passphrase,
 
59
      use a suitable key derivation scheme (such as PBKDF2) to derive the secret
 
60
      key. If the master key is lost, all PSKs stored are unrecoverable.
 
61
 
 
62
      Both names and values are encrypted using NIST key wrapping (see NIST
 
63
      SP800-38F) with AES-256. First the master key is used with HMAC(SHA-256)
 
64
      to derive two 256-bit keys, one for encrypting all names and the other to
 
65
      key an instance of HMAC(SHA-256). Values are each encrypted under an
 
66
      individual key created by hashing the encrypted name with HMAC. This
 
67
      associates the encrypted key with the name, and prevents an attacker with
 
68
      write access to the data store from taking an encrypted key associated
 
69
      with one entity and copying it to another entity.
 
70
 
 
71
      Names and PSKs are both padded to the next multiple of 8 bytes, providing
 
72
      some obfuscation of the length.
 
73
 
 
74
      One artifact of the names being encrypted is that is is possible to use
 
75
      multiple different master keys with the same underlying storage. Each
 
76
      master key will be responsible for a subset of the keys. An attacker who
 
77
      knows one of the keys will be able to tell there are other values
 
78
      encrypted under another key.
 
79
 
 
80
   .. cpp:function:: virtual void kv_set(const std::string& index, const std::string& value) = 0
 
81
 
 
82
      Save an encrypted value. Both ``index`` and ``value`` will be non-empty
 
83
      base64 encoded strings.
 
84
 
 
85
   .. cpp:function:: virtual std::string kv_get(const std::string& index) const = 0
 
86
 
 
87
      Return a value saved with ``kv_set``, or return the empty string.
 
88
 
 
89
   .. cpp:function:: virtual void kv_del(const std::string& index) = 0
 
90
 
 
91
      Remove a value saved with ``kv_set``.
 
92
 
 
93
   .. cpp:function:: virtual std::set<std::string> kv_get_all() const = 0
 
94
 
 
95
      Return all active names (ie values for which ``kv_get`` will return a
 
96
      non-empty string).
 
97
 
 
98
A subclass of ``Encrypted_PSK_Database`` which stores data in a SQL database
 
99
is also available. This class is declared in ``psk_db_sql.h``:
 
100
 
 
101
.. cpp:class:: Encrypted_PSK_Database_SQL : public Encrypted_PSK_Database
 
102
 
 
103
  .. cpp:function:: Encrypted_PSK_Database_SQL(const secure_vector<uint8_t>& master_key, \
 
104
                                 std::shared_ptr<SQL_Database> db, \
 
105
                                 const std::string& table_name)
 
106
 
 
107
     Creates or uses the named table in ``db``. The SQL schema of the table is
 
108
     ``(psk_name TEXT PRIMARY KEY, psk_value TEXT)``.