net/cert/nss_cert_database.h

   1 // Copyright (c) 2012 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 #ifndef NET_CERT_NSS_CERT_DATABASE_H_
   6 #define NET_CERT_NSS_CERT_DATABASE_H_
   7
   8 #include <string>
   9 #include <vector>
  10
  11 #include "base/basictypes.h"
  12 #include "base/callback_forward.h"
  13 #include "base/memory/ref_counted.h"
  14 #include "base/strings/string16.h"
  15 #include "crypto/scoped_nss_types.h"
  16 #include "net/base/net_export.h"
  17 #include "net/cert/cert_type.h"
  18 #include "net/cert/x509_certificate.h"
  19
  20 namespace base {
  21 template <typename T> struct DefaultLazyInstanceTraits;
  22 class TaskRunner;
  23 }
  24 template <class ObserverType> class ObserverListThreadSafe;
  25
  26 namespace net {
  27
  28 class CryptoModule;
  29 typedef std::vector<scoped_refptr<CryptoModule> > CryptoModuleList;
  30
  31 // Provides functions to manipulate the NSS certificate stores.
  32 class NET_EXPORT NSSCertDatabase {
  33  public:
  34
  35   class NET_EXPORT Observer {
  36    public:
  37     virtual ~Observer() {}
  38
  39     // Will be called when a new certificate is added.
  40     // Called with |cert| == NULL after importing a list of certificates
  41     // in ImportFromPKCS12().
  42     virtual void OnCertAdded(const X509Certificate* cert) {}
  43
  44     // Will be called when a certificate is removed.
  45     virtual void OnCertRemoved(const X509Certificate* cert) {}
  46
  47     // Will be called when a CA certificate is changed.
  48     // Called with |cert| == NULL after importing a list of certificates
  49     // in ImportCACerts().
  50     virtual void OnCACertChanged(const X509Certificate* cert) {}
  51
  52    protected:
  53     Observer() {}
  54
  55    private:
  56     DISALLOW_COPY_AND_ASSIGN(Observer);
  57   };
  58
  59   // Stores per-certificate error codes for import failures.
  60   struct NET_EXPORT ImportCertFailure {
  61    public:
  62     ImportCertFailure(const scoped_refptr<X509Certificate>& cert, int err);
  63     ~ImportCertFailure();
  64
  65     scoped_refptr<X509Certificate> certificate;
  66     int net_error;
  67   };
  68   typedef std::vector<ImportCertFailure> ImportCertFailureList;
  69
  70   // Constants that define which usages a certificate is trusted for.
  71   // They are used in combination with CertType to specify trust for each type
  72   // of certificate.
  73   // For a CA_CERT, they specify that the CA is trusted for issuing server and
  74   // client certs of each type.
  75   // For SERVER_CERT, only TRUSTED_SSL makes sense, and specifies the cert is
  76   // trusted as a server.
  77   // For EMAIL_CERT, only TRUSTED_EMAIL makes sense, and specifies the cert is
  78   // trusted for email.
  79   // DISTRUSTED_* specifies that the cert should not be trusted for the given
  80   // usage, regardless of whether it would otherwise inherit trust from the
  81   // issuer chain.
  82   // Use TRUST_DEFAULT to inherit trust as normal.
  83   // NOTE: The actual constants are defined using an enum instead of static
  84   // consts due to compilation/linkage constraints with template functions.
  85   typedef uint32 TrustBits;
  86   enum {
  87     TRUST_DEFAULT         =      0,
  88     TRUSTED_SSL           = 1 << 0,
  89     TRUSTED_EMAIL         = 1 << 1,
  90     TRUSTED_OBJ_SIGN      = 1 << 2,
  91     DISTRUSTED_SSL        = 1 << 3,
  92     DISTRUSTED_EMAIL      = 1 << 4,
  93     DISTRUSTED_OBJ_SIGN   = 1 << 5,
  94   };
  95
  96   typedef base::Callback<void(scoped_ptr<CertificateList> certs)>
  97       ListCertsCallback;
  98
  99   // DEPRECATED: See http://crbug.com/329735.
 100   static NSSCertDatabase* GetInstance();
 101
 102   // Get a list of unique certificates in the certificate database (one
 103   // instance of all certificates).
 104   // DEPRECATED by |ListCerts|. See http://crbug.com/340460.
 105   virtual void ListCertsSync(CertificateList* certs);
 106
 107   // Asynchronously get a list of unique certificates in the certificate
 108   // database (one instance of all certificates). Note that the callback may be
 109   // run even after the database is deleted.
 110   virtual void ListCerts(const ListCertsCallback& callback);
 111
 112   // Get the default slot for public key data.
 113   virtual crypto::ScopedPK11Slot GetPublicSlot() const;
 114
 115   // Get the default slot for private key or mixed private/public key data.
 116   virtual crypto::ScopedPK11Slot GetPrivateSlot() const;
 117
 118   // Get the default module for public key data.
 119   // The returned pointer must be stored in a scoped_refptr<CryptoModule>.
 120   // DEPRECATED: use GetPublicSlot instead.
 121   // TODO(mattm): remove usage of this method and remove it.
 122   CryptoModule* GetPublicModule() const;
 123
 124   // Get the default module for private key or mixed private/public key data.
 125   // The returned pointer must be stored in a scoped_refptr<CryptoModule>.
 126   // DEPRECATED: use GetPrivateSlot instead.
 127   // TODO(mattm): remove usage of this method and remove it.
 128   CryptoModule* GetPrivateModule() const;
 129
 130   // Get all modules.
 131   // If |need_rw| is true, only writable modules will be returned.
 132   // TODO(mattm): come up with better alternative to CryptoModuleList.
 133   virtual void ListModules(CryptoModuleList* modules, bool need_rw) const;
 134
 135   // Import certificates and private keys from PKCS #12 blob into the module.
 136   // If |is_extractable| is false, mark the private key as being unextractable
 137   // from the module.
 138   // Returns OK or a network error code such as ERR_PKCS12_IMPORT_BAD_PASSWORD
 139   // or ERR_PKCS12_IMPORT_ERROR. |imported_certs|, if non-NULL, returns a list
 140   // of certs that were imported.
 141   int ImportFromPKCS12(CryptoModule* module,
 142                        const std::string& data,
 143                        const base::string16& password,
 144                        bool is_extractable,
 145                        CertificateList* imported_certs);
 146
 147   // Export the given certificates and private keys into a PKCS #12 blob,
 148   // storing into |output|.
 149   // Returns the number of certificates successfully exported.
 150   int ExportToPKCS12(const CertificateList& certs,
 151                      const base::string16& password,
 152                      std::string* output) const;
 153
 154   // Uses similar logic to nsNSSCertificateDB::handleCACertDownload to find the
 155   // root.  Assumes the list is an ordered hierarchy with the root being either
 156   // the first or last element.
 157   // TODO(mattm): improve this to handle any order.
 158   X509Certificate* FindRootInList(const CertificateList& certificates) const;
 159
 160   // Import CA certificates.
 161   // Tries to import all the certificates given.  The root will be trusted
 162   // according to |trust_bits|.  Any certificates that could not be imported
 163   // will be listed in |not_imported|.
 164   // Returns false if there is an internal error, otherwise true is returned and
 165   // |not_imported| should be checked for any certificates that were not
 166   // imported.
 167   bool ImportCACerts(const CertificateList& certificates,
 168                      TrustBits trust_bits,
 169                      ImportCertFailureList* not_imported);
 170
 171   // Import server certificate.  The first cert should be the server cert.  Any
 172   // additional certs should be intermediate/CA certs and will be imported but
 173   // not given any trust.
 174   // Any certificates that could not be imported will be listed in
 175   // |not_imported|.
 176   // |trust_bits| can be set to explicitly trust or distrust the certificate, or
 177   // use TRUST_DEFAULT to inherit trust as normal.
 178   // Returns false if there is an internal error, otherwise true is returned and
 179   // |not_imported| should be checked for any certificates that were not
 180   // imported.
 181   bool ImportServerCert(const CertificateList& certificates,
 182                         TrustBits trust_bits,
 183                         ImportCertFailureList* not_imported);
 184
 185   // Get trust bits for certificate.
 186   TrustBits GetCertTrust(const X509Certificate* cert, CertType type) const;
 187
 188   // IsUntrusted returns true if |cert| is specifically untrusted. These
 189   // certificates are stored in the database for the specific purpose of
 190   // rejecting them.
 191   bool IsUntrusted(const X509Certificate* cert) const;
 192
 193   // Set trust values for certificate.
 194   // Returns true on success or false on failure.
 195   bool SetCertTrust(const X509Certificate* cert,
 196                     CertType type,
 197                     TrustBits trust_bits);
 198
 199   // Delete certificate and associated private key (if one exists).
 200   // |cert| is still valid when this function returns. Returns true on
 201   // success.
 202   bool DeleteCertAndKey(const X509Certificate* cert);
 203
 204   // Check whether cert is stored in a readonly slot.
 205   bool IsReadOnly(const X509Certificate* cert) const;
 206
 207   // Check whether cert is stored in a hardware slot.
 208   bool IsHardwareBacked(const X509Certificate* cert) const;
 209
 210   // Registers |observer| to receive notifications of certificate changes.  The
 211   // thread on which this is called is the thread on which |observer| will be
 212   // called back with notifications.
 213   // NOTE: CertDatabase::AddObserver should be preferred. Observers registered
 214   // here will only recieve notifications generated directly through the
 215   // NSSCertDatabase, but not those from the CertDatabase. The CertDatabase
 216   // observers will recieve both.
 217   void AddObserver(Observer* observer);
 218
 219   // Unregisters |observer| from receiving notifications.  This must be called
 220   // on the same thread on which AddObserver() was called.
 221   void RemoveObserver(Observer* observer);
 222
 223   // Overrides task runner that's used for running slow tasks.
 224   void SetSlowTaskRunnerForTest(
 225       const scoped_refptr<base::TaskRunner>& task_runner);
 226
 227  protected:
 228   NSSCertDatabase();
 229   virtual ~NSSCertDatabase();
 230
 231   // Certificate listing implementation used by |ListCerts| and |ListCertsSync|.
 232   // Static so it may safely be used on the worker thread.
 233   static void ListCertsImpl(CertificateList* certs);
 234
 235   // Gets task runner that should be used for slow tasks like certificate
 236   // listing. Defaults to a base::WorkerPool runner, but may be overriden
 237   // in tests (see SetSlowTaskRunnerForTest).
 238   scoped_refptr<base::TaskRunner> GetSlowTaskRunner() const;
 239
 240  private:
 241   friend struct base::DefaultLazyInstanceTraits<NSSCertDatabase>;
 242
 243   // Broadcasts notifications to all registered observers.
 244   void NotifyObserversOfCertAdded(const X509Certificate* cert);
 245   void NotifyObserversOfCertRemoved(const X509Certificate* cert);
 246   void NotifyObserversOfCACertChanged(const X509Certificate* cert);
 247
 248   // Task runner that should be used in tests if set.
 249   scoped_refptr<base::TaskRunner> slow_task_runner_for_test_;
 250
 251   const scoped_refptr<ObserverListThreadSafe<Observer> > observer_list_;
 252
 253   DISALLOW_COPY_AND_ASSIGN(NSSCertDatabase);
 254 };
 255
 256 }  // namespace net
 257
 258 #endif  // NET_CERT_NSS_CERT_DATABASE_H_