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 CHROMEOS_DBUS_CRYPTOHOME_CLIENT_H_
6 #define CHROMEOS_DBUS_CRYPTOHOME_CLIENT_H_
11 #include "base/basictypes.h"
12 #include "base/callback.h"
13 #include "chromeos/attestation/attestation_constants.h"
14 #include "chromeos/chromeos_export.h"
15 #include "chromeos/dbus/dbus_client.h"
16 #include "chromeos/dbus/dbus_client_implementation_type.h"
17 #include "chromeos/dbus/dbus_method_call_status.h"
21 // CryptohomeClient is used to communicate with the Cryptohome service.
22 // All method should be called from the origin thread (UI thread) which
23 // initializes the DBusThreadManager instance.
24 class CHROMEOS_EXPORT CryptohomeClient : public DBusClient {
26 // A callback to handle AsyncCallStatus signals.
27 typedef base::Callback<void(int async_id,
30 AsyncCallStatusHandler;
31 // A callback to handle AsyncCallStatusWithData signals.
32 typedef base::Callback<void(int async_id,
34 const std::string& data)>
35 AsyncCallStatusWithDataHandler;
36 // A callback to handle responses of AsyncXXX methods.
37 typedef base::Callback<void(int async_id)> AsyncMethodCallback;
38 // A callback for GetSystemSalt().
39 typedef base::Callback<void(
40 DBusMethodCallStatus call_status,
41 const std::vector<uint8>& system_salt)> GetSystemSaltCallback;
42 // A callback for WaitForServiceToBeAvailable().
43 typedef base::Callback<void(bool service_is_ready)>
44 WaitForServiceToBeAvailableCallback;
45 // A callback to handle responses of Pkcs11GetTpmTokenInfo method. The result
46 // of the D-Bus call is in |call_status|. On success, |label| holds the
47 // PKCS #11 token label. This is not useful in practice to identify a token
48 // but may be meaningful to a user. The |user_pin| can be used with the
49 // C_Login PKCS #11 function but is not necessary because tokens are logged in
50 // for the duration of a signed-in session. The |slot| corresponds to a
51 // CK_SLOT_ID for the PKCS #11 API and reliably identifies the token for the
52 // duration of the signed-in session.
53 typedef base::Callback<void(
54 DBusMethodCallStatus call_status,
55 const std::string& label,
56 const std::string& user_pin,
57 int slot)> Pkcs11GetTpmTokenInfoCallback;
58 // A callback for methods which return both a bool result and data.
59 typedef base::Callback<void(DBusMethodCallStatus call_status,
61 const std::string& data)> DataMethodCallback;
63 virtual ~CryptohomeClient();
65 // Factory function, creates a new instance and returns ownership.
66 // For normal usage, access the singleton via DBusThreadManager::Get().
67 static CryptohomeClient* Create(DBusClientImplementationType type);
69 // Returns the sanitized |username| that the stub implementation would return.
70 static std::string GetStubSanitizedUsername(const std::string& username);
72 // Sets AsyncCallStatus signal handlers.
73 // |handler| is called when results for AsyncXXX methods are returned.
74 // Cryptohome service will process the calls in a first-in-first-out manner
75 // when they are made in parallel.
76 virtual void SetAsyncCallStatusHandlers(
77 const AsyncCallStatusHandler& handler,
78 const AsyncCallStatusWithDataHandler& data_handler) = 0;
80 // Resets AsyncCallStatus signal handlers.
81 virtual void ResetAsyncCallStatusHandlers() = 0;
83 // Runs the callback as soon as the service becomes available.
84 virtual void WaitForServiceToBeAvailable(
85 const WaitForServiceToBeAvailableCallback& callback) = 0;
87 // Calls IsMounted method and returns true when the call succeeds.
88 virtual void IsMounted(const BoolDBusMethodCallback& callback) = 0;
90 // Calls Unmount method and returns true when the call succeeds.
91 // This method blocks until the call returns.
92 virtual bool Unmount(bool* success) = 0;
94 // Calls AsyncCheckKey method. |callback| is called after the method call
96 virtual void AsyncCheckKey(const std::string& username,
97 const std::string& key,
98 const AsyncMethodCallback& callback) = 0;
100 // Calls AsyncMigrateKey method. |callback| is called after the method call
102 virtual void AsyncMigrateKey(const std::string& username,
103 const std::string& from_key,
104 const std::string& to_key,
105 const AsyncMethodCallback& callback) = 0;
107 // Calls AsyncRemove method. |callback| is called after the method call
109 virtual void AsyncRemove(const std::string& username,
110 const AsyncMethodCallback& callback) = 0;
112 // Calls GetSystemSalt method. |callback| is called after the method call
114 virtual void GetSystemSalt(const GetSystemSaltCallback& callback) = 0;
116 // Calls GetSanitizedUsername method. |callback| is called after the method
118 virtual void GetSanitizedUsername(
119 const std::string& username,
120 const StringDBusMethodCallback& callback) = 0;
122 // Same as GetSanitizedUsername() but blocks until a reply is received, and
123 // returns the sanitized username synchronously. Returns an empty string if
124 // the method call fails.
125 // This may only be called in situations where blocking the UI thread is
126 // considered acceptable (e.g. restarting the browser after a crash or after
128 virtual std::string BlockingGetSanitizedUsername(
129 const std::string& username) = 0;
131 // Calls the AsyncMount method to asynchronously mount the cryptohome for
132 // |username|, using |key| to unlock it. For supported |flags|, see the
133 // documentation of AsyncMethodCaller::AsyncMount().
134 // |callback| is called after the method call succeeds.
135 virtual void AsyncMount(const std::string& username,
136 const std::string& key,
138 const AsyncMethodCallback& callback) = 0;
140 // Calls the AsyncAddKey method to asynchronously add another |new_key| for
141 // |username|, using |key| to unlock it first.
142 // |callback| is called after the method call succeeds.
143 virtual void AsyncAddKey(const std::string& username,
144 const std::string& key,
145 const std::string& new_key,
146 const AsyncMethodCallback& callback) = 0;
148 // Calls AsyncMountGuest method. |callback| is called after the method call
150 virtual void AsyncMountGuest(const AsyncMethodCallback& callback) = 0;
152 // Calls the AsyncMount method to asynchronously mount the cryptohome for
153 // |public_mount_id|. For supported |flags|, see the documentation of
154 // AsyncMethodCaller::AsyncMount(). |callback| is called after the method
156 virtual void AsyncMountPublic(const std::string& public_mount_id,
158 const AsyncMethodCallback& callback) = 0;
160 // Calls TpmIsReady method.
161 virtual void TpmIsReady(const BoolDBusMethodCallback& callback) = 0;
163 // Calls TpmIsEnabled method.
164 virtual void TpmIsEnabled(const BoolDBusMethodCallback& callback) = 0;
166 // Calls TpmIsEnabled method and returns true when the call succeeds.
167 // This method blocks until the call returns.
168 // TODO(hashimoto): Remove this method. crbug.com/141006
169 virtual bool CallTpmIsEnabledAndBlock(bool* enabled) = 0;
171 // Calls TpmGetPassword method.
172 virtual void TpmGetPassword(const StringDBusMethodCallback& callback) = 0;
174 // Calls TpmIsOwned method.
175 virtual void TpmIsOwned(const BoolDBusMethodCallback& callback) = 0;
177 // Calls TpmIsOwned method and returns true when the call succeeds.
178 // This method blocks until the call returns.
179 // TODO(hashimoto): Remove this method. crbug.com/141012
180 virtual bool CallTpmIsOwnedAndBlock(bool* owned) = 0;
182 // Calls TpmIsBeingOwned method.
183 virtual void TpmIsBeingOwned(const BoolDBusMethodCallback& callback) = 0;
185 // Calls TpmIsBeingOwned method and returns true when the call succeeds.
186 // This method blocks until the call returns.
187 // TODO(hashimoto): Remove this method. crbug.com/141011
188 virtual bool CallTpmIsBeingOwnedAndBlock(bool* owning) = 0;
190 // Calls TpmCanAttemptOwnership method.
191 // This method tells the service that it is OK to attempt ownership.
192 virtual void TpmCanAttemptOwnership(
193 const VoidDBusMethodCallback& callback) = 0;
195 // Calls TpmClearStoredPasswordMethod.
196 virtual void TpmClearStoredPassword(
197 const VoidDBusMethodCallback& callback) = 0;
199 // Calls TpmClearStoredPassword method and returns true when the call
200 // succeeds. This method blocks until the call returns.
201 // TODO(hashimoto): Remove this method. crbug.com/141010
202 virtual bool CallTpmClearStoredPasswordAndBlock() = 0;
204 // Calls Pkcs11IsTpmTokenReady method.
205 virtual void Pkcs11IsTpmTokenReady(
206 const BoolDBusMethodCallback& callback) = 0;
208 // Calls Pkcs11GetTpmTokenInfo method. This method is deprecated, you should
209 // use Pkcs11GetTpmTokenInfoForUser instead. On success |callback| will
210 // receive PKCS #11 token information for the token associated with the user
211 // who originally signed in (i.e. PKCS #11 slot 0).
212 virtual void Pkcs11GetTpmTokenInfo(
213 const Pkcs11GetTpmTokenInfoCallback& callback) = 0;
215 // Calls Pkcs11GetTpmTokenInfoForUser method. On success |callback| will
216 // receive PKCS #11 token information for the user identified by |user_email|.
217 // The |user_email| must be a canonical email address as returned by
218 // chromeos::User::email().
219 virtual void Pkcs11GetTpmTokenInfoForUser(
220 const std::string& user_email,
221 const Pkcs11GetTpmTokenInfoCallback& callback) = 0;
223 // Calls InstallAttributesGet method and returns true when the call succeeds.
224 // This method blocks until the call returns.
225 // The original content of |value| is lost.
226 virtual bool InstallAttributesGet(const std::string& name,
227 std::vector<uint8>* value,
228 bool* successful) = 0;
230 // Calls InstallAttributesSet method and returns true when the call succeeds.
231 // This method blocks until the call returns.
232 virtual bool InstallAttributesSet(const std::string& name,
233 const std::vector<uint8>& value,
234 bool* successful) = 0;
236 // Calls InstallAttributesFinalize method and returns true when the call
237 // succeeds. This method blocks until the call returns.
238 virtual bool InstallAttributesFinalize(bool* successful) = 0;
240 // Calls InstallAttributesIsReady method.
241 virtual void InstallAttributesIsReady(
242 const BoolDBusMethodCallback& callback) = 0;
244 // Calls InstallAttributesIsInvalid method and returns true when the call
245 // succeeds. This method blocks until the call returns.
246 virtual bool InstallAttributesIsInvalid(bool* is_invalid) = 0;
248 // Calls InstallAttributesIsFirstInstall method and returns true when the call
249 // succeeds. This method blocks until the call returns.
250 virtual bool InstallAttributesIsFirstInstall(bool* is_first_install) = 0;
252 // Calls the TpmAttestationIsPrepared dbus method. The callback is called
253 // when the operation completes.
254 virtual void TpmAttestationIsPrepared(
255 const BoolDBusMethodCallback& callback) = 0;
257 // Calls the TpmAttestationIsEnrolled dbus method. The callback is called
258 // when the operation completes.
259 virtual void TpmAttestationIsEnrolled(
260 const BoolDBusMethodCallback& callback) = 0;
262 // Asynchronously creates an attestation enrollment request. The callback
263 // will be called when the dbus call completes. When the operation completes,
264 // the AsyncCallStatusWithDataHandler signal handler is called. The data that
265 // is sent with the signal is an enrollment request to be sent to the Privacy
266 // CA. The enrollment is completed by calling AsyncTpmAttestationEnroll.
267 virtual void AsyncTpmAttestationCreateEnrollRequest(
268 const AsyncMethodCallback& callback) = 0;
270 // Asynchronously finishes an attestation enrollment operation. The callback
271 // will be called when the dbus call completes. When the operation completes,
272 // the AsyncCallStatusHandler signal handler is called. |pca_response| is the
273 // response to the enrollment request emitted by the Privacy CA.
274 virtual void AsyncTpmAttestationEnroll(
275 const std::string& pca_response,
276 const AsyncMethodCallback& callback) = 0;
278 // Asynchronously creates an attestation certificate request according to
279 // |certificate_profile|. Some profiles require that the |user_id| of the
280 // currently active user and an identifier of the |request_origin| be
281 // provided. |callback| will be called when the dbus call completes. When
282 // the operation completes, the AsyncCallStatusWithDataHandler signal handler
283 // is called. The data that is sent with the signal is a certificate request
284 // to be sent to the Privacy CA. The certificate request is completed by
285 // calling AsyncTpmAttestationFinishCertRequest. The |user_id| will not
286 // be included in the certificate request for the Privacy CA.
287 virtual void AsyncTpmAttestationCreateCertRequest(
288 attestation::AttestationCertificateProfile certificate_profile,
289 const std::string& user_id,
290 const std::string& request_origin,
291 const AsyncMethodCallback& callback) = 0;
293 // Asynchronously finishes a certificate request operation. The callback will
294 // be called when the dbus call completes. When the operation completes, the
295 // AsyncCallStatusWithDataHandler signal handler is called. The data that is
296 // sent with the signal is a certificate chain in PEM format. |pca_response|
297 // is the response to the certificate request emitted by the Privacy CA.
298 // |key_type| determines whether the certified key is to be associated with
299 // the current user. |key_name| is a name for the key. If |key_type| is
300 // KEY_USER, a |user_id| must be provided. Otherwise |user_id| is ignored.
301 // For normal GAIA users the |user_id| is a canonical email address.
302 virtual void AsyncTpmAttestationFinishCertRequest(
303 const std::string& pca_response,
304 attestation::AttestationKeyType key_type,
305 const std::string& user_id,
306 const std::string& key_name,
307 const AsyncMethodCallback& callback) = 0;
309 // Checks if an attestation key already exists. If the key specified by
310 // |key_type| and |key_name| exists, then the result sent to the callback will
311 // be true. If |key_type| is KEY_USER, a |user_id| must be provided.
312 // Otherwise |user_id| is ignored. For normal GAIA users the |user_id| is a
313 // canonical email address.
314 virtual void TpmAttestationDoesKeyExist(
315 attestation::AttestationKeyType key_type,
316 const std::string& user_id,
317 const std::string& key_name,
318 const BoolDBusMethodCallback& callback) = 0;
320 // Gets the attestation certificate for the key specified by |key_type| and
321 // |key_name|. |callback| will be called when the operation completes. If
322 // the key does not exist the callback |result| parameter will be false. If
323 // |key_type| is KEY_USER, a |user_id| must be provided. Otherwise |user_id|
324 // is ignored. For normal GAIA users the |user_id| is a canonical email
326 virtual void TpmAttestationGetCertificate(
327 attestation::AttestationKeyType key_type,
328 const std::string& user_id,
329 const std::string& key_name,
330 const DataMethodCallback& callback) = 0;
332 // Gets the public key for the key specified by |key_type| and |key_name|.
333 // |callback| will be called when the operation completes. If the key does
334 // not exist the callback |result| parameter will be false. If |key_type| is
335 // KEY_USER, a |user_id| must be provided. Otherwise |user_id| is ignored.
336 // For normal GAIA users the |user_id| is a canonical email address.
337 virtual void TpmAttestationGetPublicKey(
338 attestation::AttestationKeyType key_type,
339 const std::string& user_id,
340 const std::string& key_name,
341 const DataMethodCallback& callback) = 0;
343 // Asynchronously registers an attestation key with the current user's
344 // PKCS #11 token. The |callback| will be called when the dbus call
345 // completes. When the operation completes, the AsyncCallStatusHandler signal
346 // handler is called. |key_type| and |key_name| specify the key to register.
347 // If |key_type| is KEY_USER, a |user_id| must be provided. Otherwise
348 // |user_id| is ignored. For normal GAIA users the |user_id| is a canonical
350 virtual void TpmAttestationRegisterKey(
351 attestation::AttestationKeyType key_type,
352 const std::string& user_id,
353 const std::string& key_name,
354 const AsyncMethodCallback& callback) = 0;
356 // Asynchronously signs an enterprise challenge with the key specified by
357 // |key_type| and |key_name|. |domain| and |device_id| will be included in
358 // the challenge response. |options| control how the challenge response is
359 // generated. |challenge| must be a valid enterprise attestation challenge.
360 // The |callback| will be called when the dbus call completes. When the
361 // operation completes, the AsyncCallStatusWithDataHandler signal handler is
362 // called. If |key_type| is KEY_USER, a |user_id| must be provided.
363 // Otherwise |user_id| is ignored. For normal GAIA users the |user_id| is a
364 // canonical email address.
365 virtual void TpmAttestationSignEnterpriseChallenge(
366 attestation::AttestationKeyType key_type,
367 const std::string& user_id,
368 const std::string& key_name,
369 const std::string& domain,
370 const std::string& device_id,
371 attestation::AttestationChallengeOptions options,
372 const std::string& challenge,
373 const AsyncMethodCallback& callback) = 0;
375 // Asynchronously signs a simple challenge with the key specified by
376 // |key_type| and |key_name|. |challenge| can be any set of arbitrary bytes.
377 // A nonce will be appended to the challenge before signing; this method
378 // cannot be used to sign arbitrary data. The |callback| will be called when
379 // the dbus call completes. When the operation completes, the
380 // AsyncCallStatusWithDataHandler signal handler is called. If |key_type| is
381 // KEY_USER, a |user_id| must be provided. Otherwise |user_id| is ignored.
382 // For normal GAIA users the |user_id| is a canonical email address.
383 virtual void TpmAttestationSignSimpleChallenge(
384 attestation::AttestationKeyType key_type,
385 const std::string& user_id,
386 const std::string& key_name,
387 const std::string& challenge,
388 const AsyncMethodCallback& callback) = 0;
390 // Gets the payload associated with the key specified by |key_type| and
391 // |key_name|. The |callback| will be called when the operation completes.
392 // If the key does not exist the callback |result| parameter will be false.
393 // If no payload has been set for the key the callback |result| parameter will
394 // be true and the |data| parameter will be empty. If |key_type| is
395 // KEY_USER, a |user_id| must be provided. Otherwise |user_id| is ignored.
396 // For normal GAIA users the |user_id| is a canonical email address.
397 virtual void TpmAttestationGetKeyPayload(
398 attestation::AttestationKeyType key_type,
399 const std::string& user_id,
400 const std::string& key_name,
401 const DataMethodCallback& callback) = 0;
403 // Sets the |payload| associated with the key specified by |key_type| and
404 // |key_name|. The |callback| will be called when the operation completes.
405 // If the operation succeeds, the callback |result| parameter will be true.
406 // If |key_type| is KEY_USER, a |user_id| must be provided. Otherwise
407 // |user_id| is ignored. For normal GAIA users the |user_id| is a canonical
409 virtual void TpmAttestationSetKeyPayload(
410 attestation::AttestationKeyType key_type,
411 const std::string& user_id,
412 const std::string& key_name,
413 const std::string& payload,
414 const BoolDBusMethodCallback& callback) = 0;
416 // Deletes certified keys as specified by |key_type| and |key_prefix|. The
417 // |callback| will be called when the operation completes. If the operation
418 // succeeds, the callback |result| parameter will be true. If |key_type| is
419 // KEY_USER, a |user_id| must be provided. Otherwise |user_id| is ignored.
420 // For normal GAIA users the |user_id| is a canonical email address. All keys
421 // where the key name has a prefix matching |key_prefix| will be deleted. All
422 // meta-data associated with the key, including certificates, will also be
424 virtual void TpmAttestationDeleteKeys(
425 attestation::AttestationKeyType key_type,
426 const std::string& user_id,
427 const std::string& key_prefix,
428 const BoolDBusMethodCallback& callback) = 0;
431 // Create() should be used instead.
435 DISALLOW_COPY_AND_ASSIGN(CryptohomeClient);
438 } // namespace chromeos
440 #endif // CHROMEOS_DBUS_CRYPTOHOME_CLIENT_H_