← Back to branch summary

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

« back to all changes in this revision

Viewing changes to doc/manual/credentials_manager.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/credentials_manager.rst
 
1
 
 
2
Credentials Manager
 
3
==================================================
 
4
 
 
5
A ``Credentials_Manager`` is a way to abstract how the application
 
6
stores credentials in a way that is usable by protocol
 
7
implementations. Currently the main user is the :doc:`tls`
 
8
implementation.
 
9
 
 
10
.. cpp:class:: Credentials_Manager
 
11
 
 
12
   .. cpp:function:: std::vector<X509_Certificate> \
 
13
         trusted_certificate_authorities( \
 
14
         const std::string& type, \
 
15
         const std::string& context)
 
16
 
 
17
      Return the list of trusted certificate authorities.
 
18
 
 
19
      When *type* is "tls-client", *context* will be the hostname of
 
20
      the server, or empty if the hostname is not known.
 
21
 
 
22
      When *type* is "tls-server", the *context* will again be the
 
23
      hostname of the server, or empty if the client did not send a
 
24
      server name indicator. For TLS servers, these CAs are the ones
 
25
      trusted for signing of client certificates. If you do not want
 
26
      the TLS server to ask for a client cert,
 
27
      ``trusted_certificate_authorities`` should return an empty list
 
28
      for *type* "tls-server".
 
29
 
 
30
      The default implementation returns an empty list.
 
31
 
 
32
   .. cpp:function:: std::vector<X509_Certificate> cert_chain( \
 
33
         const std::vector<std::string>& cert_key_types, \
 
34
         const std::string& type, \
 
35
         const std::string& context)
 
36
 
 
37
      Return the certificate chain to use to identify ourselves
 
38
 
 
39
   .. cpp:function:: std::vector<X509_Certificate> cert_chain_single_type( \
 
40
         const std::string& cert_key_type, \
 
41
         const std::string& type, \
 
42
         const std::string& context)
 
43
 
 
44
      Return the certificate chain to use to identifier ourselves, if
 
45
      we have one of type *cert_key_tye* and we would like to use a
 
46
      certificate in this *type*/*context*.
 
47
 
 
48
   .. cpp:function:: Private_Key* private_key_for(const X509_Certificate& cert, \
 
49
                                                  const std::string& type, \
 
50
                                                  const std::string& context)
 
51
 
 
52
      Return the private key for this certificate. The *cert* will be
 
53
      the leaf cert of a chain returned previously by ``cert_chain``
 
54
      or ``cert_chain_single_type``.
 
55
 
 
56
In versions before 1.11.34, there was an additional function on `Credentials_Manager`
 
57
 
 
58
   .. cpp::function:: void verify_certificate_chain( \
 
59
         const std::string& type, \
 
60
         const std::string& hostname, \
 
61
         const std::vector<X509_Certificate>& cert_chain)
 
62
 
 
63
This function has been replaced by `TLS::Callbacks::tls_verify_cert_chain`.
 
64
 
 
65
SRP Authentication
 
66
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
67
 
 
68
``Credentials_Manager`` contains the hooks used by TLS clients and
 
69
servers for SRP authentication.
 
70
 
 
71
.. cpp:function:: bool attempt_srp(const std::string& type, \
 
72
                                   const std::string& context)
 
73
 
 
74
   Returns if we should consider using SRP for authentication
 
75
 
 
76
.. cpp:function:: std::string srp_identifier(const std::string& type, \
 
77
                                             const std::string& context)
 
78
 
 
79
   Returns the SRP identifier we'd like to use (used by client)
 
80
 
 
81
.. cpp:function:: std::string srp_password(const std::string& type, \
 
82
                                           const std::string& context, \
 
83
                                           const std::string& identifier)
 
84
 
 
85
   Returns the password for *identifier* (used by client)
 
86
 
 
87
.. cpp:function:: bool srp_verifier(const std::string& type, \
 
88
                                    const std::string& context, \
 
89
                                    const std::string& identifier, \
 
90
                                    std::string& group_name, \
 
91
                                    BigInt& verifier, \
 
92
                                    std::vector<uint8_t>& salt, \
 
93
                                    bool generate_fake_on_unknown)
 
94
 
 
95
    Returns the SRP verifier information for *identifier* (used by server)
 
96
 
 
97
Preshared Keys
 
98
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
99
 
 
100
TLS and some other protocols support the use of pre shared keys for
 
101
authentication.
 
102
 
 
103
.. cpp:function:: SymmetricKey psk(const std::string& type, \
 
104
                                   const std::string& context, \
 
105
                                   const std::string& identity)
 
106
 
 
107
    Return a symmetric key for use with *identity*
 
108
 
 
109
    One important special case for ``psk`` is where *type* is
 
110
    "tls-server", *context* is "session-ticket" and *identity* is an
 
111
    empty string. If a key is returned for this case, a TLS server
 
112
    will offer session tickets to clients who can use them, and the
 
113
    returned key will be used to encrypt the ticket. The server is
 
114
    allowed to change the key at any time (though changing the key
 
115
    means old session tickets can no longer be used for resumption,
 
116
    forcing a full re-handshake when the client next connects). One
 
117
    simple approach to add support for session tickets in your server
 
118
    is to generate a random key the first time ``psk`` is called to
 
119
    retrieve the session ticket key, cache it for later use in the
 
120
    ``Credentials_Manager``, and simply let it be thrown away when the
 
121
    process terminates.
 
122
 
 
123
    See :rfc:`4507` for more information about TLS session tickets.
 
124
 
 
125
.. cpp:function:: std::string psk_identity_hint(const std::string& type, \
 
126
                                                const std::string& context)
 
127
 
 
128
    Returns an identity hint which may be provided to the client. This
 
129
    can help a client understand what PSK to use.
 
130
 
 
131
.. cpp:function:: std::string psk_identity(const std::string& type, \
 
132
                                           const std::string& context, \
 
133
                                           const std::string& identity_hint)
 
134
 
 
135
    Returns the identity we would like to use given this *type* and
 
136
    *context* and the optional *identity_hint*. Not all servers or
 
137
    protocols will provide a hint.