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/memory/ref_counted.h"
  13 #include "base/strings/string16.h"
  14 #include "net/base/net_export.h"
  15 #include "net/cert/cert_type.h"
  16 #include "net/cert/x509_certificate.h"
  17
  18 template <typename T> struct DefaultSingletonTraits;
  19 template <class ObserverType> class ObserverListThreadSafe;
  20
  21 namespace net {
  22
  23 class CryptoModule;
  24 typedef std::vector<scoped_refptr<CryptoModule> > CryptoModuleList;
  25
  26 // Provides functions to manipulate the NSS certificate stores.
  27 class NET_EXPORT NSSCertDatabase {
  28  public:
  29
  30   class NET_EXPORT Observer {
  31    public:
  32     virtual ~Observer() {}
  33
  34     // Will be called when a new certificate is added.
  35     // Called with |cert| == NULL after importing a list of certificates
  36     // in ImportFromPKCS12().
  37     virtual void OnCertAdded(const X509Certificate* cert) {}
  38
  39     // Will be called when a certificate is removed.
  40     virtual void OnCertRemoved(const X509Certificate* cert) {}
  41
  42     // Will be called when a certificate's trust is changed.
  43     // Called with |cert| == NULL after importing a list of certificates
  44     // in ImportCACerts().
  45     virtual void OnCertTrustChanged(const X509Certificate* cert) {}
  46
  47    protected:
  48     Observer() {}
  49
  50    private:
  51     DISALLOW_COPY_AND_ASSIGN(Observer);
  52   };
  53
  54   // Stores per-certificate error codes for import failures.
  55   struct NET_EXPORT ImportCertFailure {
  56    public:
  57     ImportCertFailure(const scoped_refptr<X509Certificate>& cert, int err);
  58     ~ImportCertFailure();
  59
  60     scoped_refptr<X509Certificate> certificate;
  61     int net_error;
  62   };
  63   typedef std::vector<ImportCertFailure> ImportCertFailureList;
  64
  65   // Constants that define which usages a certificate is trusted for.
  66   // They are used in combination with CertType to specify trust for each type
  67   // of certificate.
  68   // For a CA_CERT, they specify that the CA is trusted for issuing server and
  69   // client certs of each type.
  70   // For SERVER_CERT, only TRUSTED_SSL makes sense, and specifies the cert is
  71   // trusted as a server.
  72   // For EMAIL_CERT, only TRUSTED_EMAIL makes sense, and specifies the cert is
  73   // trusted for email.
  74   // DISTRUSTED_* specifies that the cert should not be trusted for the given
  75   // usage, regardless of whether it would otherwise inherit trust from the
  76   // issuer chain.
  77   // Use TRUST_DEFAULT to inherit trust as normal.
  78   // NOTE: The actual constants are defined using an enum instead of static
  79   // consts due to compilation/linkage constraints with template functions.
  80   typedef uint32 TrustBits;
  81   enum {
  82     TRUST_DEFAULT         =      0,
  83     TRUSTED_SSL           = 1 << 0,
  84     TRUSTED_EMAIL         = 1 << 1,
  85     TRUSTED_OBJ_SIGN      = 1 << 2,
  86     DISTRUSTED_SSL        = 1 << 3,
  87     DISTRUSTED_EMAIL      = 1 << 4,
  88     DISTRUSTED_OBJ_SIGN   = 1 << 5,
  89   };
  90
  91   static NSSCertDatabase* GetInstance();
  92
  93   // Get a list of unique certificates in the certificate database (one
  94   // instance of all certificates).
  95   void ListCerts(CertificateList* certs);
  96
  97   // Get the default module for public key data.
  98   // The returned pointer must be stored in a scoped_refptr<CryptoModule>.
  99   CryptoModule* GetPublicModule() const;
 100
 101   // Get the default module for private key or mixed private/public key data.
 102   // The returned pointer must be stored in a scoped_refptr<CryptoModule>.
 103   CryptoModule* GetPrivateModule() const;
 104
 105   // Get all modules.
 106   // If |need_rw| is true, only writable modules will be returned.
 107   void ListModules(CryptoModuleList* modules, bool need_rw) const;
 108
 109   // Import certificates and private keys from PKCS #12 blob into the module.
 110   // If |is_extractable| is false, mark the private key as being unextractable
 111   // from the module.
 112   // Returns OK or a network error code such as ERR_PKCS12_IMPORT_BAD_PASSWORD
 113   // or ERR_PKCS12_IMPORT_ERROR. |imported_certs|, if non-NULL, returns a list
 114   // of certs that were imported.
 115   int ImportFromPKCS12(CryptoModule* module,
 116                        const std::string& data,
 117                        const base::string16& password,
 118                        bool is_extractable,
 119                        CertificateList* imported_certs);
 120
 121   // Export the given certificates and private keys into a PKCS #12 blob,
 122   // storing into |output|.
 123   // Returns the number of certificates successfully exported.
 124   int ExportToPKCS12(const CertificateList& certs,
 125                      const base::string16& password,
 126                      std::string* output) const;
 127
 128   // Uses similar logic to nsNSSCertificateDB::handleCACertDownload to find the
 129   // root.  Assumes the list is an ordered hierarchy with the root being either
 130   // the first or last element.
 131   // TODO(mattm): improve this to handle any order.
 132   X509Certificate* FindRootInList(const CertificateList& certificates) const;
 133
 134   // Import CA certificates.
 135   // Tries to import all the certificates given.  The root will be trusted
 136   // according to |trust_bits|.  Any certificates that could not be imported
 137   // will be listed in |not_imported|.
 138   // Returns false if there is an internal error, otherwise true is returned and
 139   // |not_imported| should be checked for any certificates that were not
 140   // imported.
 141   bool ImportCACerts(const CertificateList& certificates,
 142                      TrustBits trust_bits,
 143                      ImportCertFailureList* not_imported);
 144
 145   // Import server certificate.  The first cert should be the server cert.  Any
 146   // additional certs should be intermediate/CA certs and will be imported but
 147   // not given any trust.
 148   // Any certificates that could not be imported will be listed in
 149   // |not_imported|.
 150   // |trust_bits| can be set to explicitly trust or distrust the certificate, or
 151   // use TRUST_DEFAULT to inherit trust as normal.
 152   // Returns false if there is an internal error, otherwise true is returned and
 153   // |not_imported| should be checked for any certificates that were not
 154   // imported.
 155   bool ImportServerCert(const CertificateList& certificates,
 156                         TrustBits trust_bits,
 157                         ImportCertFailureList* not_imported);
 158
 159   // Get trust bits for certificate.
 160   TrustBits GetCertTrust(const X509Certificate* cert, CertType type) const;
 161
 162   // IsUntrusted returns true if |cert| is specifically untrusted. These
 163   // certificates are stored in the database for the specific purpose of
 164   // rejecting them.
 165   bool IsUntrusted(const X509Certificate* cert) const;
 166
 167   // Set trust values for certificate.
 168   // Returns true on success or false on failure.
 169   bool SetCertTrust(const X509Certificate* cert,
 170                     CertType type,
 171                     TrustBits trust_bits);
 172
 173   // Delete certificate and associated private key (if one exists).
 174   // |cert| is still valid when this function returns. Returns true on
 175   // success.
 176   bool DeleteCertAndKey(const X509Certificate* cert);
 177
 178   // Check whether cert is stored in a readonly slot.
 179   bool IsReadOnly(const X509Certificate* cert) const;
 180
 181   // Registers |observer| to receive notifications of certificate changes.  The
 182   // thread on which this is called is the thread on which |observer| will be
 183   // called back with notifications.
 184   void AddObserver(Observer* observer);
 185
 186   // Unregisters |observer| from receiving notifications.  This must be called
 187   // on the same thread on which AddObserver() was called.
 188   void RemoveObserver(Observer* observer);
 189
 190  private:
 191   friend struct DefaultSingletonTraits<NSSCertDatabase>;
 192
 193   NSSCertDatabase();
 194   ~NSSCertDatabase();
 195
 196   // Broadcasts notifications to all registered observers.
 197   void NotifyObserversOfCertAdded(const X509Certificate* cert);
 198   void NotifyObserversOfCertRemoved(const X509Certificate* cert);
 199   void NotifyObserversOfCertTrustChanged(const X509Certificate* cert);
 200
 201   const scoped_refptr<ObserverListThreadSafe<Observer> > observer_list_;
 202
 203   DISALLOW_COPY_AND_ASSIGN(NSSCertDatabase);
 204 };
 205
 206 }  // namespace net
 207
 208 #endif  // NET_CERT_NSS_CERT_DATABASE_H_