Botan  1.11.15
src/lib/credentials/credentials_manager.h
Go to the documentation of this file.
00001 /*
00002 * Credentials Manager
00003 * (C) 2011,2012 Jack Lloyd
00004 *
00005 * Botan is released under the Simplified BSD License (see license.txt)
00006 */
00007 
00008 #ifndef BOTAN_CREDENTIALS_MANAGER_H__
00009 #define BOTAN_CREDENTIALS_MANAGER_H__
00010 
00011 #include <botan/x509cert.h>
00012 #include <botan/certstor.h>
00013 #include <botan/symkey.h>
00014 #include <string>
00015 
00016 namespace Botan {
00017 
00018 class BigInt;
00019 
00020 /**
00021 * Interface for a credentials manager.
00022 *
00023 * A type is a fairly static value that represents the general nature
00024 * of the transaction occuring. Currently used values are "tls-client"
00025 * and "tls-server". Context represents a hostname, email address,
00026 * username, or other identifier.
00027 */
00028 class BOTAN_DLL Credentials_Manager
00029    {
00030    public:
00031       virtual ~Credentials_Manager() {}
00032 
00033       /**
00034       * Return a list of the certificates of CAs that we trust in this
00035       * type/context.
00036       *
00037       * @param type specifies the type of operation occuring
00038       *
00039       * @param context specifies a context relative to type. For instance
00040       *        for type "tls-client", context specifies the servers name.
00041       */
00042       virtual std::vector<Certificate_Store*> trusted_certificate_authorities(
00043          const std::string& type,
00044          const std::string& context);
00045 
00046       /**
00047       * Check the certificate chain is valid up to a trusted root, and
00048       * optionally (if hostname != "") that the hostname given is
00049       * consistent with the leaf certificate.
00050       *
00051       * This function should throw an exception derived from
00052       * std::exception with an informative what() result if the
00053       * certificate chain cannot be verified.
00054 
00055       * @param type specifies the type of operation occuring
00056       * @param hostname specifies the purported hostname
00057       * @param cert_chain specifies a certificate chain leading to a
00058       *        trusted root CA certificate.
00059       */
00060       virtual void verify_certificate_chain(
00061          const std::string& type,
00062          const std::string& hostname,
00063          const std::vector<X509_Certificate>& cert_chain);
00064 
00065       /**
00066       * Return a cert chain we can use, ordered from leaf to root,
00067       * or else an empty vector.
00068       *
00069       * It is assumed that the caller can get the private key of the
00070       * leaf with private_key_for
00071       *
00072       * @param cert_key_types specifies the key types desired ("RSA",
00073       *                       "DSA", "ECDSA", etc), or empty if there
00074       *                       is no preference by the caller.
00075       *
00076       * @param type specifies the type of operation occuring
00077       *
00078       * @param context specifies a context relative to type.
00079       */
00080       virtual std::vector<X509_Certificate> cert_chain(
00081          const std::vector<std::string>& cert_key_types,
00082          const std::string& type,
00083          const std::string& context);
00084 
00085       /**
00086       * Return a cert chain we can use, ordered from leaf to root,
00087       * or else an empty vector.
00088       *
00089       * It is assumed that the caller can get the private key of the
00090       * leaf with private_key_for
00091       *
00092       * @param cert_key_type specifies the type of key requested
00093       *                      ("RSA", "DSA", "ECDSA", etc)
00094       *
00095       * @param type specifies the type of operation occuring
00096       *
00097       * @param context specifies a context relative to type.
00098       */
00099       std::vector<X509_Certificate> cert_chain_single_type(
00100          const std::string& cert_key_type,
00101          const std::string& type,
00102          const std::string& context);
00103 
00104       /**
00105       * @return private key associated with this certificate if we should
00106       *         use it with this context. cert was returned by cert_chain
00107       * @note this object should retain ownership of the returned key;
00108       *       it should not be deleted by the caller.
00109       */
00110       virtual Private_Key* private_key_for(const X509_Certificate& cert,
00111                                            const std::string& type,
00112                                            const std::string& context);
00113 
00114       /**
00115       * @param type specifies the type of operation occuring
00116       * @param context specifies a context relative to type.
00117       * @return true if we should attempt SRP authentication
00118       */
00119       virtual bool attempt_srp(const std::string& type,
00120                                const std::string& context);
00121 
00122       /**
00123       * @param type specifies the type of operation occuring
00124       * @param context specifies a context relative to type.
00125       * @return identifier for client-side SRP auth, if available
00126                 for this type/context. Should return empty string
00127                 if password auth not desired/available.
00128       */
00129       virtual std::string srp_identifier(const std::string& type,
00130                                          const std::string& context);
00131 
00132       /**
00133       * @param type specifies the type of operation occuring
00134       * @param context specifies a context relative to type.
00135       * @param identifier specifies what identifier we want the
00136       *        password for. This will be a value previously returned
00137       *        by srp_identifier.
00138       * @return password for client-side SRP auth, if available
00139                 for this identifier/type/context.
00140       */
00141       virtual std::string srp_password(const std::string& type,
00142                                        const std::string& context,
00143                                        const std::string& identifier);
00144 
00145       /**
00146       * Retrieve SRP verifier parameters
00147       */
00148       virtual bool srp_verifier(const std::string& type,
00149                                 const std::string& context,
00150                                 const std::string& identifier,
00151                                 std::string& group_name,
00152                                 BigInt& verifier,
00153                                 std::vector<byte>& salt,
00154                                 bool generate_fake_on_unknown);
00155 
00156       /**
00157       * @param type specifies the type of operation occuring
00158       * @param context specifies a context relative to type.
00159       * @return the PSK identity hint for this type/context
00160       */
00161       virtual std::string psk_identity_hint(const std::string& type,
00162                                             const std::string& context);
00163 
00164       /**
00165       * @param type specifies the type of operation occuring
00166       * @param context specifies a context relative to type.
00167       * @param identity_hint was passed by the server (but may be empty)
00168       * @return the PSK identity we want to use
00169       */
00170       virtual std::string psk_identity(const std::string& type,
00171                                        const std::string& context,
00172                                        const std::string& identity_hint);
00173 
00174       /**
00175       * @param type specifies the type of operation occuring
00176       * @param context specifies a context relative to type.
00177       * @param identity is a PSK identity previously returned by
00178                psk_identity for the same type and context.
00179       * @return the PSK used for identity, or throw an exception if no
00180       * key exists
00181       */
00182       virtual SymmetricKey psk(const std::string& type,
00183                                const std::string& context,
00184                                const std::string& identity);
00185    };
00186 
00187 }
00188 
00189 #endif