diff options
Diffstat (limited to 'doc/credentials_manager.rst')
| -rw-r--r-- | doc/credentials_manager.rst | 125 |
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) |