Rename all text files that are actually reStructuredText to .rst

1 files changed, 125 insertions, 0 deletions

diff --git a/doc/credentials_manager.rst b/doc/credentials_manager.rst
new file mode 100644
index 000000000..57d262c45
--- /dev/null
+++ b/doc/credentials_manager.rst
@@ -0,0 +1,125 @@
+
+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
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. cpp:function:: std::string psk_identity_hint(const std::string& type, \
+                                                const std::string& context)
+
+.. cpp:function:: std::string psk_identity(const std::string& type, \
+                                           const std::string& context, \
+                                           const std::string& identity_hint)
+
+.. cpp:function:: SymmetricKey psk(const std::string& type, \
+                                   const std::string& context, \
+                                   const std::string& identity)