/*

* Credentials Manager

* (C) 2011,2012 Jack Lloyd

*

* Botan is released under the Simplified BSD License (see license.txt)

*/

#ifndef BOTAN_CREDENTIALS_MANAGER_H_

#define BOTAN_CREDENTIALS_MANAGER_H_

#include <botan/pk_keys.h>

#include <botan/x509cert.h>

#include <botan/certstor.h>

#include <botan/symkey.h>

#include <string>

namespace Botan {

class X509_DN;

class BigInt;

/**

* Interface for a credentials manager.

*

* A type is a fairly static value that represents the general nature

* of the transaction occurring. Currently used values are "tls-client"

* and "tls-server". Context represents a hostname, email address,

* username, or other identifier.

*/

class BOTAN_PUBLIC_API(2,0) Credentials_Manager

   {

   public:

      virtual ~Credentials_Manager() = default;

      /**

      * Return a list of the certificates of CAs that we trust in this

      * type/context.

      *

      * @param type specifies the type of operation occurring

      *

      * @param context specifies a context relative to type. For instance

      *        for type "tls-client", context specifies the servers name.

      */

      virtual std::vector<Certificate_Store*> trusted_certificate_authorities(

         const std::string& type,

         const std::string& context);

      /**

      * Return a cert chain we can use, ordered from leaf to root,

      * or else an empty vector.

      *

      * It is assumed that the caller can get the private key of the

      * leaf with private_key_for

      *

      * @param cert_key_types specifies the key types desired ("RSA",

      *                       "DSA", "ECDSA", etc), or empty if there

      *                       is no preference by the caller.

      *

      * @param acceptable_CAs the CAs the requestor will accept (possibly empty)

      * @param type specifies the type of operation occurring

      * @param context specifies a context relative to type.

      */

      virtual std::vector<X509_Certificate> find_cert_chain(

         const std::vector<std::string>& cert_key_types,

         const std::vector<X509_DN>& acceptable_CAs,

         const std::string& type,

         const std::string& context);

      /**

      * Return a cert chain we can use, ordered from leaf to root,

      * or else an empty vector.

      *

      * This virtual function is deprecated, and will be removed in a

      * future release. Use (and override) find_cert_chain instead.

      *

      * It is assumed that the caller can get the private key of the

      * leaf with private_key_for

      *

      * @param cert_key_types specifies the key types desired ("RSA",

      *                       "DSA", "ECDSA", etc), or empty if there

      *                       is no preference by the caller.

      *

      * @param type specifies the type of operation occurring

      *

      * @param context specifies a context relative to type.

      */

      virtual std::vector<X509_Certificate> cert_chain(

         const std::vector<std::string>& cert_key_types,

         const std::string& type,

         const std::string& context);

      /**

      * Return a cert chain we can use, ordered from leaf to root,

      * or else an empty vector.

      *

      * It is assumed that the caller can get the private key of the

      * leaf with private_key_for

      *

      * @param cert_key_type specifies the type of key requested

      *                      ("RSA", "DSA", "ECDSA", etc)

      *

      * @param type specifies the type of operation occurring

      *

      * @param context specifies a context relative to type.

      */

      std::vector<X509_Certificate> cert_chain_single_type(

         const std::string& cert_key_type,

         const std::string& type,

         const std::string& context);

      /**

      * @return private key associated with this certificate if we should

      *         use it with this context. cert was returned by cert_chain

      * @note this object should retain ownership of the returned key;

      *       it should not be deleted by the caller.

      */

      virtual Private_Key* private_key_for(const X509_Certificate& cert,

                                           const std::string& type,

                                           const std::string& context);

      /**

      * @param type specifies the type of operation occurring

      * @param context specifies a context relative to type.

      * @return true if we should attempt SRP authentication

      */

      virtual bool attempt_srp(const std::string& type,

                               const std::string& context);

      /**

      * @param type specifies the type of operation occurring

      * @param context specifies a context relative to type.

      * @return identifier for client-side SRP auth, if available

                for this type/context. Should return empty string

                if password auth not desired/available.

      */

      virtual std::string srp_identifier(const std::string& type,

                                         const std::string& context);

      /**

      * @param type specifies the type of operation occurring

      * @param context specifies a context relative to type.

      * @param identifier specifies what identifier we want the

      *        password for. This will be a value previously returned

      *        by srp_identifier.

      * @return password for client-side SRP auth, if available

                for this identifier/type/context.

      */

      virtual std::string srp_password(const std::string& type,

                                       const std::string& context,

                                       const std::string& identifier);

      /**

      * Retrieve SRP verifier parameters

      */

      virtual bool srp_verifier(const std::string& type,

                                const std::string& context,

                                const std::string& identifier,

                                std::string& group_name,

                                BigInt& verifier,

                                std::vector<uint8_t>& salt,

                                bool generate_fake_on_unknown);

      /**

      * @param type specifies the type of operation occurring

      * @param context specifies a context relative to type.

      * @return the PSK identity hint for this type/context

      */

      virtual std::string psk_identity_hint(const std::string& type,

                                            const std::string& context);

      /**

      * @param type specifies the type of operation occurring

      * @param context specifies a context relative to type.

      * @param identity_hint was passed by the server (but may be empty)

      * @return the PSK identity we want to use

      */

      virtual std::string psk_identity(const std::string& type,

                                       const std::string& context,

                                       const std::string& identity_hint);

      /**

      * @param type specifies the type of operation occurring

      * @param context specifies a context relative to type.

      * @param identity is a PSK identity previously returned by

               psk_identity for the same type and context.

      * @return the PSK used for identity, or throw an exception if no

      * key exists

      */

      virtual SymmetricKey psk(const std::string& type,

                               const std::string& context,

                               const std::string& identity);

   };

}

#endif