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.
5 #ifndef CRYPTO_NSS_UTIL_H_
6 #define CRYPTO_NSS_UTIL_H_
9 #include "base/basictypes.h"
10 #include "crypto/crypto_export.h"
14 #endif // defined(USE_NSS)
21 // This file specifically doesn't depend on any NSS or NSPR headers because it
22 // is included by various (non-crypto) parts of chrome to call the
23 // initialization functions.
29 // EarlySetupForNSSInit performs lightweight setup which must occur before the
30 // process goes multithreaded. This does not initialise NSS. For test, see
32 CRYPTO_EXPORT
void EarlySetupForNSSInit();
35 // Initialize NRPR if it isn't already initialized. This function is
36 // thread-safe, and NSPR will only ever be initialized once.
37 CRYPTO_EXPORT
void EnsureNSPRInit();
39 // Initialize NSS if it isn't already initialized. This must be called before
40 // any other NSS functions. This function is thread-safe, and NSS will only
41 // ever be initialized once.
42 CRYPTO_EXPORT
void EnsureNSSInit();
44 // Call this before calling EnsureNSSInit() will force NSS to initialize
45 // without a persistent DB. This is used for the special case where access of
46 // persistent DB is prohibited.
48 // TODO(hclam): Isolate loading default root certs.
50 // NSS will be initialized without loading any user security modules, including
51 // the built-in root certificates module. User security modules need to be
52 // loaded manually after NSS initialization.
54 // If EnsureNSSInit() is called before then this function has no effect.
56 // Calling this method only has effect on Linux.
58 // WARNING: Use this with caution.
59 CRYPTO_EXPORT
void ForceNSSNoDBInit();
61 // This methods is used to disable checks in NSS when used in a forked process.
62 // NSS checks whether it is running a forked process to avoid problems when
63 // using user security modules in a forked process. However if we are sure
64 // there are no modules loaded before the process is forked then there is no
65 // harm disabling the check.
67 // This method must be called before EnsureNSSInit() to take effect.
69 // WARNING: Use this with caution.
70 CRYPTO_EXPORT
void DisableNSSForkCheck();
72 // Load NSS library files. This function has no effect on Mac and Windows.
73 // This loads the necessary NSS library files so that NSS can be initialized
74 // after loading additional library files is disallowed, for example when the
77 // Note that this does not load libnssckbi.so which contains the root
79 CRYPTO_EXPORT
void LoadNSSLibraries();
81 // Check if the current NSS version is greater than or equals to |version|.
82 // A sample version string is "3.12.3".
83 bool CheckNSSVersion(const char* version
);
85 #if defined(OS_CHROMEOS)
86 // Open the r/w nssdb that's stored inside the user's encrypted home
87 // directory. This is the default slot returned by
88 // GetPublicNSSKeySlot().
89 CRYPTO_EXPORT
void OpenPersistentNSSDB();
91 // Indicates that NSS should load the Chaps library so that we
92 // can access the TPM through NSS. Once this is called,
93 // GetPrivateNSSKeySlot() will return the TPM slot if one was found.
94 CRYPTO_EXPORT
void EnableTPMTokenForNSS();
96 // Get name and user PIN for the built-in TPM token on ChromeOS.
97 // Either one can safely be NULL. Should only be called after
98 // EnableTPMTokenForNSS has been called with a non-null delegate.
99 CRYPTO_EXPORT
void GetTPMTokenInfo(std::string
* token_name
,
100 std::string
* user_pin
);
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
106 CRYPTO_EXPORT
bool IsTPMTokenReady();
108 // Initialize the TPM token. Does nothing if it is already initialized.
109 CRYPTO_EXPORT
bool InitializeTPMToken(const std::string
& token_name
,
110 const std::string
& user_pin
);
112 // Gets supplemental user key. Creates one in NSS database if it does not exist.
113 // The supplemental user key is used for AES encryption of user data that is
114 // stored and protected by cryptohome. This additional layer of encryption of
115 // provided to ensure that sensitive data wouldn't be exposed in plain text in
116 // case when an attacker would somehow gain access to all content within
118 CRYPTO_EXPORT SymmetricKey
* GetSupplementalUserKey();
121 // Convert a NSS PRTime value into a base::Time object.
122 // We use a int64 instead of PRTime here to avoid depending on NSPR headers.
123 CRYPTO_EXPORT
base::Time
PRTimeToBaseTime(int64 prtime
);
125 // Convert a base::Time object into a PRTime value.
126 // We use a int64 instead of PRTime here to avoid depending on NSPR headers.
127 CRYPTO_EXPORT int64
BaseTimeToPRTime(base::Time time
);
130 // Exposed for unittests only.
131 // TODO(mattm): When NSS 3.14 is the minimum version required,
132 // switch back to using a separate user DB for each test.
133 // Because of https://bugzilla.mozilla.org/show_bug.cgi?id=588269 , the
134 // opened user DB is not automatically closed.
135 class CRYPTO_EXPORT_PRIVATE ScopedTestNSSDB
{
140 bool is_open() { return is_open_
; }
144 DISALLOW_COPY_AND_ASSIGN(ScopedTestNSSDB
);
147 // NSS has a bug which can cause a deadlock or stall in some cases when writing
148 // to the certDB and keyDB. It also has a bug which causes concurrent key pair
149 // generations to scribble over each other. To work around this, we synchronize
150 // writes to the NSS databases with a global lock. The lock is hidden beneath a
151 // function for easy disabling when the bug is fixed. Callers should allow for
152 // it to return NULL in the future.
154 // See https://bugzilla.mozilla.org/show_bug.cgi?id=564011
155 base::Lock
* GetNSSWriteLock();
157 // A helper class that acquires the NSS write Lock while the AutoNSSWriteLock
159 class CRYPTO_EXPORT AutoNSSWriteLock
{
165 DISALLOW_COPY_AND_ASSIGN(AutoNSSWriteLock
);
168 #endif // defined(USE_NSS)
170 } // namespace crypto
172 #endif // CRYPTO_NSS_UTIL_H_