aboutsummaryrefslogtreecommitdiffstats
path: root/doc/credentials_manager.rst
diff options
context:
space:
mode:
authorlloyd <[email protected]>2014-01-10 23:07:16 +0000
committerlloyd <[email protected]>2014-01-10 23:07:16 +0000
commitad6555f522ae16f6284e8dafa02f630b88bcf289 (patch)
treebd63c51dbeab75eb0f90c72589bc922141237056 /doc/credentials_manager.rst
parent6894dca64c04936d07048c0e8cbf7e25858548c3 (diff)
Split up docs into the reference manual, the website, and everything else.
Add `website` target to makefile. Some progress towards fixing minimized builds. TLS now hard requires ECDSA and GCM since otherwise a minimized build has only insecure options. Remove boost_thread dependency in command line tool
Diffstat (limited to 'doc/credentials_manager.rst')
-rw-r--r--doc/credentials_manager.rst153
1 files changed, 0 insertions, 153 deletions
diff --git a/doc/credentials_manager.rst b/doc/credentials_manager.rst
deleted file mode 100644
index 04e9e3f2e..000000000
--- a/doc/credentials_manager.rst
+++ /dev/null
@@ -1,153 +0,0 @@
-
-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.