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