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