crypto/nss_util.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 CRYPTO_NSS_UTIL_H_
   6 #define CRYPTO_NSS_UTIL_H_
   7
   8 #include <string>
   9 #include "base/basictypes.h"
  10 #include "base/callback.h"
  11 #include "base/compiler_specific.h"
  12 #include "crypto/crypto_export.h"
  13
  14 namespace base {
  15 class FilePath;
  16 class Lock;
  17 class Time;
  18 }  // namespace base
  19
  20 // This file specifically doesn't depend on any NSS or NSPR headers because it
  21 // is included by various (non-crypto) parts of chrome to call the
  22 // initialization functions.
  23 namespace crypto {
  24
  25 #if defined(USE_NSS_CERTS)
  26 // EarlySetupForNSSInit performs lightweight setup which must occur before the
  27 // process goes multithreaded. This does not initialise NSS. For test, see
  28 // EnsureNSSInit.
  29 CRYPTO_EXPORT void EarlySetupForNSSInit();
  30 #endif
  31
  32 // Initialize NRPR if it isn't already initialized.  This function is
  33 // thread-safe, and NSPR will only ever be initialized once.
  34 CRYPTO_EXPORT void EnsureNSPRInit();
  35
  36 #if !defined(USE_OPENSSL)
  37 // Initialize NSS safely for strict sandboxing.  This function tells NSS to not
  38 // load user security modules, and makes sure NSS will have proper entropy in a
  39 // restricted, sandboxed environment.
  40 //
  41 // As a defense in depth measure, this function should be called in a sandboxed
  42 // environment.  That way, in the event of a bug, NSS will still not be able to
  43 // load security modules that could expose private data and keys.
  44 //
  45 // Make sure to get an LGTM from the Chrome Security Team if you use this.
  46 CRYPTO_EXPORT void InitNSSSafely();
  47 #endif  // !defined(USE_OPENSSL)
  48
  49 // Initialize NSS if it isn't already initialized.  This must be called before
  50 // any other NSS functions.  This function is thread-safe, and NSS will only
  51 // ever be initialized once.
  52 CRYPTO_EXPORT void EnsureNSSInit();
  53
  54 #if !defined(USE_OPENSSL)
  55
  56 // Call this before calling EnsureNSSInit() will force NSS to initialize
  57 // without a persistent DB.  This is used for the special case where access of
  58 // persistent DB is prohibited.
  59 //
  60 // TODO(hclam): Isolate loading default root certs.
  61 //
  62 // NSS will be initialized without loading any user security modules, including
  63 // the built-in root certificates module. User security modules need to be
  64 // loaded manually after NSS initialization.
  65 //
  66 // If EnsureNSSInit() is called before then this function has no effect.
  67 //
  68 // Calling this method only has effect on Linux.
  69 //
  70 // WARNING: Use this with caution.
  71 CRYPTO_EXPORT void ForceNSSNoDBInit();
  72
  73 // This method is used to disable checks in NSS when used in a forked process.
  74 // NSS checks whether it is running a forked process to avoid problems when
  75 // using user security modules in a forked process.  However if we are sure
  76 // there are no modules loaded before the process is forked then there is no
  77 // harm disabling the check.
  78 //
  79 // This method must be called before EnsureNSSInit() to take effect.
  80 //
  81 // WARNING: Use this with caution.
  82 CRYPTO_EXPORT void DisableNSSForkCheck();
  83
  84 // Load NSS library files. This function has no effect on Mac and Windows.
  85 // This loads the necessary NSS library files so that NSS can be initialized
  86 // after loading additional library files is disallowed, for example when the
  87 // sandbox is active.
  88 //
  89 // Note that this does not load libnssckbi.so which contains the root
  90 // certificates.
  91 CRYPTO_EXPORT void LoadNSSLibraries();
  92
  93 #endif  // !USE_OPENSSL
  94
  95 // Check if the current NSS version is greater than or equals to |version|.
  96 // A sample version string is "3.12.3".
  97 bool CheckNSSVersion(const char* version);
  98
  99 #if defined(OS_CHROMEOS)
 100 // Indicates that NSS should use the Chaps library so that we
 101 // can access the TPM through NSS.  InitializeTPMTokenAndSystemSlot and
 102 // InitializeTPMForChromeOSUser must still be called to load the slots.
 103 CRYPTO_EXPORT void EnableTPMTokenForNSS();
 104
 105 // Returns true if EnableTPMTokenForNSS has been called.
 106 CRYPTO_EXPORT bool IsTPMTokenEnabledForNSS();
 107
 108 // Returns true if the TPM is owned and PKCS#11 initialized with the
 109 // user and security officer PINs, and has been enabled in NSS by
 110 // calling EnableTPMForNSS, and Chaps has been successfully
 111 // loaded into NSS.
 112 // If |callback| is non-null and the function returns false, the |callback| will
 113 // be run once the TPM is ready. |callback| will never be run if the function
 114 // returns true.
 115 CRYPTO_EXPORT bool IsTPMTokenReady(const base::Closure& callback)
 116     WARN_UNUSED_RESULT;
 117
 118 // Initialize the TPM token and system slot. The |callback| will run on the same
 119 // thread with true if the token and slot were successfully loaded or were
 120 // already initialized. |callback| will be passed false if loading failed.  Once
 121 // called, InitializeTPMTokenAndSystemSlot must not be called again until the
 122 // |callback| has been run.
 123 CRYPTO_EXPORT void InitializeTPMTokenAndSystemSlot(
 124     int system_slot_id,
 125     const base::Callback<void(bool)>& callback);
 126 #endif
 127
 128 // Convert a NSS PRTime value into a base::Time object.
 129 // We use a int64 instead of PRTime here to avoid depending on NSPR headers.
 130 CRYPTO_EXPORT base::Time PRTimeToBaseTime(int64 prtime);
 131
 132 // Convert a base::Time object into a PRTime value.
 133 // We use a int64 instead of PRTime here to avoid depending on NSPR headers.
 134 CRYPTO_EXPORT int64 BaseTimeToPRTime(base::Time time);
 135
 136 #if defined(USE_NSS_CERTS)
 137 // NSS has a bug which can cause a deadlock or stall in some cases when writing
 138 // to the certDB and keyDB. It also has a bug which causes concurrent key pair
 139 // generations to scribble over each other. To work around this, we synchronize
 140 // writes to the NSS databases with a global lock. The lock is hidden beneath a
 141 // function for easy disabling when the bug is fixed. Callers should allow for
 142 // it to return NULL in the future.
 143 //
 144 // See https://bugzilla.mozilla.org/show_bug.cgi?id=564011
 145 base::Lock* GetNSSWriteLock();
 146
 147 // A helper class that acquires the NSS write Lock while the AutoNSSWriteLock
 148 // is in scope.
 149 class CRYPTO_EXPORT AutoNSSWriteLock {
 150  public:
 151   AutoNSSWriteLock();
 152   ~AutoNSSWriteLock();
 153  private:
 154   base::Lock *lock_;
 155   DISALLOW_COPY_AND_ASSIGN(AutoNSSWriteLock);
 156 };
 157 #endif  // defined(USE_NSS_CERTS)
 158
 159 }  // namespace crypto
 160
 161 #endif  // CRYPTO_NSS_UTIL_H_