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