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 "crypto/crypto_export.h" 11 12 namespace base { 13 class FilePath; 14 class Lock; 15 class Time; 16 } // namespace base 17 18 // This file specifically doesn't depend on any NSS or NSPR headers because it 19 // is included by various (non-crypto) parts of chrome to call the 20 // initialization functions. 21 namespace crypto { 22 23 // The TPMToken name used for the NSS slot opened by ScopedTestNSSDB. 24 CRYPTO_EXPORT extern const char kTestTPMTokenName[]; 25 26 #if defined(USE_NSS) 27 // EarlySetupForNSSInit performs lightweight setup which must occur before the 28 // process goes multithreaded. This does not initialise NSS. For test, see 29 // EnsureNSSInit. 30 CRYPTO_EXPORT void EarlySetupForNSSInit(); 31 #endif 32 33 // Initialize NRPR if it isn't already initialized. This function is 34 // thread-safe, and NSPR will only ever be initialized once. 35 CRYPTO_EXPORT void EnsureNSPRInit(); 36 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 48 // Initialize NSS if it isn't already initialized. This must be called before 49 // any other NSS functions. This function is thread-safe, and NSS will only 50 // ever be initialized once. 51 CRYPTO_EXPORT void EnsureNSSInit(); 52 53 // Call this before calling EnsureNSSInit() will force NSS to initialize 54 // without a persistent DB. This is used for the special case where access of 55 // persistent DB is prohibited. 56 // 57 // TODO(hclam): Isolate loading default root certs. 58 // 59 // NSS will be initialized without loading any user security modules, including 60 // the built-in root certificates module. User security modules need to be 61 // loaded manually after NSS initialization. 62 // 63 // If EnsureNSSInit() is called before then this function has no effect. 64 // 65 // Calling this method only has effect on Linux. 66 // 67 // WARNING: Use this with caution. 68 CRYPTO_EXPORT void ForceNSSNoDBInit(); 69 70 // This method is used to disable checks in NSS when used in a forked process. 71 // NSS checks whether it is running a forked process to avoid problems when 72 // using user security modules in a forked process. However if we are sure 73 // there are no modules loaded before the process is forked then there is no 74 // harm disabling the check. 75 // 76 // This method must be called before EnsureNSSInit() to take effect. 77 // 78 // WARNING: Use this with caution. 79 CRYPTO_EXPORT void DisableNSSForkCheck(); 80 81 // Load NSS library files. This function has no effect on Mac and Windows. 82 // This loads the necessary NSS library files so that NSS can be initialized 83 // after loading additional library files is disallowed, for example when the 84 // sandbox is active. 85 // 86 // Note that this does not load libnssckbi.so which contains the root 87 // certificates. 88 CRYPTO_EXPORT void LoadNSSLibraries(); 89 90 // Check if the current NSS version is greater than or equals to |version|. 91 // A sample version string is "3.12.3". 92 bool CheckNSSVersion(const char* version); 93 94 #if defined(OS_CHROMEOS) 95 // Open the r/w nssdb that's stored inside the user's encrypted home 96 // directory. This is the default slot returned by 97 // GetPublicNSSKeySlot(). 98 CRYPTO_EXPORT void OpenPersistentNSSDB(); 99 100 // Indicates that NSS should load the Chaps library so that we 101 // can access the TPM through NSS. Once this is called, 102 // GetPrivateNSSKeySlot() will return the TPM slot if one was found. 103 CRYPTO_EXPORT void EnableTPMTokenForNSS(); 104 105 // Get name and user PIN for the built-in TPM token on ChromeOS. 106 // Either one can safely be NULL. Should only be called after 107 // EnableTPMTokenForNSS has been called with a non-null delegate. 108 CRYPTO_EXPORT void GetTPMTokenInfo(std::string* token_name, 109 std::string* user_pin); 110 111 // Returns true if the TPM is owned and PKCS#11 initialized with the 112 // user and security officer PINs, and has been enabled in NSS by 113 // calling EnableTPMForNSS, and Chaps has been successfully 114 // loaded into NSS. 115 CRYPTO_EXPORT bool IsTPMTokenReady(); 116 117 // Initialize the TPM token. Does nothing if it is already initialized. 118 CRYPTO_EXPORT bool InitializeTPMToken(const std::string& token_name, 119 const std::string& user_pin); 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 // Exposed for unittests only. 132 // TODO(mattm): When NSS 3.14 is the minimum version required, 133 // switch back to using a separate user DB for each test. 134 // Because of https://bugzilla.mozilla.org/show_bug.cgi?id=588269 , the 135 // opened user DB is not automatically closed. 136 class CRYPTO_EXPORT_PRIVATE ScopedTestNSSDB { 137 public: 138 ScopedTestNSSDB(); 139 ~ScopedTestNSSDB(); 140 141 bool is_open() { return is_open_; } 142 143 private: 144 bool is_open_; 145 DISALLOW_COPY_AND_ASSIGN(ScopedTestNSSDB); 146 }; 147 148 // NSS has a bug which can cause a deadlock or stall in some cases when writing 149 // to the certDB and keyDB. It also has a bug which causes concurrent key pair 150 // generations to scribble over each other. To work around this, we synchronize 151 // writes to the NSS databases with a global lock. The lock is hidden beneath a 152 // function for easy disabling when the bug is fixed. Callers should allow for 153 // it to return NULL in the future. 154 // 155 // See https://bugzilla.mozilla.org/show_bug.cgi?id=564011 156 base::Lock* GetNSSWriteLock(); 157 158 // A helper class that acquires the NSS write Lock while the AutoNSSWriteLock 159 // is in scope. 160 class CRYPTO_EXPORT AutoNSSWriteLock { 161 public: 162 AutoNSSWriteLock(); 163 ~AutoNSSWriteLock(); 164 private: 165 base::Lock *lock_; 166 DISALLOW_COPY_AND_ASSIGN(AutoNSSWriteLock); 167 }; 168 169 #endif // defined(USE_NSS) 170 171 } // namespace crypto 172 173 #endif // CRYPTO_NSS_UTIL_H_ 174