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.
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"
14namespace base {
15class FilePath;
16class Lock;
17class Time;
18}  // namespace base
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.
23namespace crypto {
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.
29CRYPTO_EXPORT void EarlySetupForNSSInit();
32// Initialize NRPR if it isn't already initialized.  This function is
33// thread-safe, and NSPR will only ever be initialized once.
34CRYPTO_EXPORT void EnsureNSPRInit();
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.
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.
44// Make sure to get an LGTM from the Chrome Security Team if you use this.
45CRYPTO_EXPORT void InitNSSSafely();
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.
50CRYPTO_EXPORT void EnsureNSSInit();
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.
56// TODO(hclam): Isolate loading default root certs.
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.
62// If EnsureNSSInit() is called before then this function has no effect.
64// Calling this method only has effect on Linux.
66// WARNING: Use this with caution.
67CRYPTO_EXPORT void ForceNSSNoDBInit();
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.
75// This method must be called before EnsureNSSInit() to take effect.
77// WARNING: Use this with caution.
78CRYPTO_EXPORT void DisableNSSForkCheck();
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.
85// Note that this does not load libnssckbi.so which contains the root
86// certificates.
87CRYPTO_EXPORT void LoadNSSLibraries();
89// Check if the current NSS version is greater than or equals to |version|.
90// A sample version string is "3.12.3".
91bool CheckNSSVersion(const char* version);
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.
97CRYPTO_EXPORT void EnableTPMTokenForNSS();
99// Returns true if EnableTPMTokenForNSS has been called.
100CRYPTO_EXPORT bool IsTPMTokenEnabledForNSS();
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.
109CRYPTO_EXPORT bool IsTPMTokenReady(const base::Closure& callback)
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.
117CRYPTO_EXPORT void InitializeTPMTokenAndSystemSlot(
118    int system_slot_id,
119    const base::Callback<void(bool)>& callback);
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.
124CRYPTO_EXPORT base::Time PRTimeToBaseTime(int64 prtime);
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.
128CRYPTO_EXPORT int64 BaseTimeToPRTime(base::Time time);
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.
138// See https://bugzilla.mozilla.org/show_bug.cgi?id=564011
139base::Lock* GetNSSWriteLock();
141// A helper class that acquires the NSS write Lock while the AutoNSSWriteLock
142// is in scope.
143class CRYPTO_EXPORT AutoNSSWriteLock {
144 public:
145  AutoNSSWriteLock();
146  ~AutoNSSWriteLock();
147 private:
148  base::Lock *lock_;
151#endif  // defined(USE_NSS)
153}  // namespace crypto
155#endif  // CRYPTO_NSS_UTIL_H_