fido_authenticator.h 15 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316
  1. // Copyright 2018 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. #ifndef DEVICE_FIDO_FIDO_AUTHENTICATOR_H_
  5. #define DEVICE_FIDO_FIDO_AUTHENTICATOR_H_
  6. #include <cstdint>
  7. #include <string>
  8. #include "base/callback_forward.h"
  9. #include "base/component_export.h"
  10. #include "base/containers/span.h"
  11. #include "base/memory/weak_ptr.h"
  12. #include "build/build_config.h"
  13. #include "build/chromeos_buildflags.h"
  14. #include "device/fido/authenticator_get_assertion_response.h"
  15. #include "device/fido/authenticator_make_credential_response.h"
  16. #include "device/fido/authenticator_supported_options.h"
  17. #include "device/fido/bio/enrollment.h"
  18. #include "device/fido/credential_management.h"
  19. #include "device/fido/discoverable_credential_metadata.h"
  20. #include "device/fido/fido_constants.h"
  21. #include "device/fido/fido_request_handler_base.h"
  22. #include "device/fido/fido_transport_protocol.h"
  23. #include "device/fido/large_blob.h"
  24. #include "device/fido/make_credential_request_handler.h"
  25. #include "third_party/abseil-cpp/absl/types/optional.h"
  26. namespace device {
  27. struct CtapGetAssertionRequest;
  28. struct CtapGetAssertionOptions;
  29. struct CtapMakeCredentialRequest;
  30. struct MakeCredentialOptions;
  31. namespace pin {
  32. struct RetriesResponse;
  33. struct EmptyResponse;
  34. class TokenResponse;
  35. } // namespace pin
  36. // FidoAuthenticator is an authenticator from the WebAuthn Authenticator model
  37. // (https://www.w3.org/TR/webauthn/#sctn-authenticator-model). It may be a
  38. // physical device, or a built-in (platform) authenticator.
  39. class COMPONENT_EXPORT(DEVICE_FIDO) FidoAuthenticator {
  40. public:
  41. using MakeCredentialCallback = base::OnceCallback<void(
  42. CtapDeviceResponseCode,
  43. absl::optional<AuthenticatorMakeCredentialResponse>)>;
  44. using GetAssertionCallback = base::OnceCallback<void(
  45. CtapDeviceResponseCode,
  46. absl::optional<AuthenticatorGetAssertionResponse>)>;
  47. using GetCredentialInformationForRequestCallback = base::OnceCallback<void(
  48. std::vector<DiscoverableCredentialMetadata> credentials,
  49. bool has_credentials)>;
  50. using GetRetriesCallback =
  51. base::OnceCallback<void(CtapDeviceResponseCode,
  52. absl::optional<pin::RetriesResponse>)>;
  53. using GetTokenCallback =
  54. base::OnceCallback<void(CtapDeviceResponseCode,
  55. absl::optional<pin::TokenResponse>)>;
  56. using SetPINCallback =
  57. base::OnceCallback<void(CtapDeviceResponseCode,
  58. absl::optional<pin::EmptyResponse>)>;
  59. using ResetCallback =
  60. base::OnceCallback<void(CtapDeviceResponseCode,
  61. absl::optional<pin::EmptyResponse>)>;
  62. using GetCredentialsMetadataCallback =
  63. base::OnceCallback<void(CtapDeviceResponseCode,
  64. absl::optional<CredentialsMetadataResponse>)>;
  65. using EnumerateCredentialsCallback = base::OnceCallback<void(
  66. CtapDeviceResponseCode,
  67. absl::optional<std::vector<AggregatedEnumerateCredentialsResponse>>)>;
  68. using DeleteCredentialCallback =
  69. base::OnceCallback<void(CtapDeviceResponseCode,
  70. absl::optional<DeleteCredentialResponse>)>;
  71. using UpdateUserInformationCallback =
  72. base::OnceCallback<void(CtapDeviceResponseCode,
  73. absl::optional<UpdateUserInformationResponse>)>;
  74. using BioEnrollmentCallback =
  75. base::OnceCallback<void(CtapDeviceResponseCode,
  76. absl::optional<BioEnrollmentResponse>)>;
  77. using LargeBlobReadCallback = base::OnceCallback<void(
  78. CtapDeviceResponseCode,
  79. absl::optional<std::vector<std::pair<LargeBlobKey, LargeBlob>>>
  80. callback)>;
  81. FidoAuthenticator() = default;
  82. FidoAuthenticator(const FidoAuthenticator&) = delete;
  83. FidoAuthenticator& operator=(const FidoAuthenticator&) = delete;
  84. virtual ~FidoAuthenticator() = default;
  85. // Sends GetInfo request to connected authenticator. Once response to GetInfo
  86. // call is received, |callback| is invoked. Below MakeCredential() and
  87. // GetAssertion() must only called after |callback| is invoked.
  88. virtual void InitializeAuthenticator(base::OnceClosure callback) = 0;
  89. // ExcludeAppIdCredentialsBeforeMakeCredential allows a device to probe for
  90. // credential IDs from a request that used the appidExclude extension. This
  91. // assumes that |MakeCredential| will be called afterwards with the same
  92. // request. I.e. this function may do nothing if it believes that it can
  93. // better handle the exclusion during |MakeCredential|.
  94. //
  95. // The optional bool is an unused response value as all the information is
  96. // contained in the response code, which will be |kCtap2ErrCredentialExcluded|
  97. // if an excluded credential is found. (An optional<void> is an error.)
  98. virtual void ExcludeAppIdCredentialsBeforeMakeCredential(
  99. CtapMakeCredentialRequest request,
  100. MakeCredentialOptions options,
  101. base::OnceCallback<void(CtapDeviceResponseCode, absl::optional<bool>)>);
  102. virtual void MakeCredential(CtapMakeCredentialRequest request,
  103. MakeCredentialOptions options,
  104. MakeCredentialCallback callback) = 0;
  105. virtual void GetAssertion(CtapGetAssertionRequest request,
  106. CtapGetAssertionOptions options,
  107. GetAssertionCallback callback) = 0;
  108. // GetNextAssertion fetches the next assertion from a device that indicated in
  109. // the response to |GetAssertion| that multiple results were available.
  110. virtual void GetNextAssertion(GetAssertionCallback callback);
  111. // GetCredentialInformationForRequest returns a boolean indicating whether
  112. // there are credentials applicable for |request|, and if supported, a list of
  113. // the corresponding resident credential metadata for empty allow list
  114. // requests.
  115. virtual void GetCredentialInformationForRequest(
  116. const CtapGetAssertionRequest& request,
  117. GetCredentialInformationForRequestCallback callback);
  118. // GetTouch causes an (external) authenticator to flash and wait for a touch.
  119. virtual void GetTouch(base::OnceCallback<void()> callback);
  120. // GetPinRetries gets the number of PIN attempts remaining before an
  121. // authenticator locks. It is only valid to call this method if |Options|
  122. // indicates that the authenticator supports PINs.
  123. virtual void GetPinRetries(GetRetriesCallback callback);
  124. // GetUvRetries gets the number of internal user verification attempts before
  125. // internal user verification locks. It is only valid to call this method if
  126. // |Options| indicates that the authenticator supports user verification.
  127. virtual void GetUvRetries(GetRetriesCallback callback);
  128. // GetPINToken uses the given PIN to request a PinUvAuthToken from an
  129. // authenticator. It is only valid to call this method if |Options| indicates
  130. // that the authenticator supports PINs.
  131. // |permissions| are flags indicating which commands the token may be used
  132. // for.
  133. // |rp_id| binds the token to operations related to a given RP ID. |rp_id|
  134. // must be set if |permissions| includes MakeCredential or GetAssertion.
  135. virtual void GetPINToken(std::string pin,
  136. std::vector<pin::Permissions> permissions,
  137. absl::optional<std::string> rp_id,
  138. GetTokenCallback callback);
  139. // Returns |true| if the authenticator supports GetUvToken.
  140. virtual bool CanGetUvToken();
  141. // GetUvToken uses internal user verification to request a PinUvAuthToken from
  142. // an authenticator. It is only valid to call this method if CanGetUvToken()
  143. // returns true.
  144. // |rp_id| must be set if the PinUvAuthToken will be used for MakeCredential
  145. // or GetAssertion.
  146. virtual void GetUvToken(std::vector<pin::Permissions> permissions,
  147. absl::optional<std::string> rp_id,
  148. GetTokenCallback callback);
  149. // Returns the minimum PIN length for this authenticator's currently set PIN.
  150. virtual uint32_t CurrentMinPINLength();
  151. // Returns the minimum PIN length required to set a new PIN for this
  152. // authenticator.
  153. virtual uint32_t NewMinPINLength();
  154. // Returns |true| if the PIN must be changed before attempting to obtain a PIN
  155. // token.
  156. virtual bool ForcePINChange();
  157. // SetPIN sets a new PIN on a device that does not currently have one. The
  158. // length of |pin| must respect |pin::kMinLength| and |pin::kMaxLength|. It is
  159. // only valid to call this method if |Options| indicates that the
  160. // authenticator supports PINs.
  161. virtual void SetPIN(const std::string& pin, SetPINCallback callback);
  162. // ChangePIN alters the PIN on a device that already has a PIN set. The
  163. // length of |pin| must respect |pin::kMinLength| and |pin::kMaxLength|. It is
  164. // only valid to call this method if |Options| indicates that the
  165. // authenticator supports PINs.
  166. virtual void ChangePIN(const std::string& old_pin,
  167. const std::string& new_pin,
  168. SetPINCallback callback);
  169. // PINUVDisposition enumerates the possible options for obtaining user
  170. // verification when making a CTAP2 request.
  171. enum class PINUVDisposition {
  172. // No UV (neither clientPIN nor internal) is needed to make this
  173. // credential.
  174. kNoUV,
  175. // A PIN/UV Auth Token should be used to make this credential. The token
  176. // needs to be obtained via clientPIN or internal UV, depending on which
  177. // modality the device supports. The modality may need to be set up first.
  178. kGetToken,
  179. // The request should be sent with the `uv` bit set to true, in order to
  180. // perform internal user verification without a PIN/UV Auth Token.
  181. kNoTokenInternalUV,
  182. // Same as kNoTokenInternalUV, but a PIN can be used as a fallback. (A PIN
  183. // may have to be set first.)
  184. kNoTokenInternalUVPINFallback,
  185. // The request cannot be satisfied by this authenticator.
  186. kUnsatisfiable,
  187. };
  188. // PINUVDisposition returns whether and how user verification
  189. // should be obtained in order to serve the given request on this
  190. // authenticator.
  191. virtual PINUVDisposition PINUVDispositionForMakeCredential(
  192. const CtapMakeCredentialRequest& request,
  193. const FidoRequestHandlerBase::Observer* observer);
  194. // WillNeedPINToGetAssertion returns whether a PIN prompt will be needed to
  195. // serve the given request on this authenticator.
  196. virtual PINUVDisposition PINUVDispositionForGetAssertion(
  197. const CtapGetAssertionRequest& request,
  198. const FidoRequestHandlerBase::Observer* observer);
  199. virtual void GetCredentialsMetadata(const pin::TokenResponse& pin_token,
  200. GetCredentialsMetadataCallback callback);
  201. virtual void EnumerateCredentials(const pin::TokenResponse& pin_token,
  202. EnumerateCredentialsCallback callback);
  203. virtual void DeleteCredential(
  204. const pin::TokenResponse& pin_token,
  205. const PublicKeyCredentialDescriptor& credential_id,
  206. DeleteCredentialCallback callback);
  207. virtual bool SupportsUpdateUserInformation() const;
  208. virtual void UpdateUserInformation(
  209. const pin::TokenResponse& pin_token,
  210. const PublicKeyCredentialDescriptor& credential_id,
  211. const PublicKeyCredentialUserEntity& updated_user,
  212. UpdateUserInformationCallback callback);
  213. // Biometric enrollment commands.
  214. virtual void GetModality(BioEnrollmentCallback callback);
  215. virtual void GetSensorInfo(BioEnrollmentCallback callback);
  216. virtual void BioEnrollFingerprint(
  217. const pin::TokenResponse&,
  218. absl::optional<std::vector<uint8_t>> template_id,
  219. BioEnrollmentCallback);
  220. virtual void BioEnrollCancel(BioEnrollmentCallback);
  221. virtual void BioEnrollEnumerate(const pin::TokenResponse&,
  222. BioEnrollmentCallback);
  223. virtual void BioEnrollRename(const pin::TokenResponse&,
  224. std::vector<uint8_t> template_id,
  225. std::string name,
  226. BioEnrollmentCallback);
  227. virtual void BioEnrollDelete(const pin::TokenResponse&,
  228. std::vector<uint8_t> template_id,
  229. BioEnrollmentCallback);
  230. // Large blob commands.
  231. // Attempts to write a |large_blob| into the credential. If there is an
  232. // existing credential for the |large_blob_key|, it will be overwritten.
  233. virtual void WriteLargeBlob(
  234. LargeBlob large_blob,
  235. const LargeBlobKey& large_blob_key,
  236. absl::optional<pin::TokenResponse> pin_uv_auth_token,
  237. base::OnceCallback<void(CtapDeviceResponseCode)> callback);
  238. // Attempts to read large blobs from the credential encrypted with
  239. // |large_blob_keys|. Returns a map of keys to their blobs.
  240. virtual void ReadLargeBlob(
  241. const std::vector<LargeBlobKey>& large_blob_keys,
  242. absl::optional<pin::TokenResponse> pin_uv_auth_token,
  243. LargeBlobReadCallback callback);
  244. // GetAlgorithms returns the list of supported COSEAlgorithmIdentifiers, or
  245. // |nullopt| if this is unknown and thus all requests should be tried in case
  246. // they work.
  247. virtual absl::optional<base::span<const int32_t>> GetAlgorithms();
  248. // DiscoverableCredentialStorageFull returns true if creation of a
  249. // discoverable credential is likely to fail because authenticator storage is
  250. // exhausted. Even if this method returns false, credential creation may still
  251. // fail with `CTAP2_ERR_KEY_STORE_FULL` on some authenticators.
  252. virtual bool DiscoverableCredentialStorageFull() const;
  253. // Reset triggers a reset operation on the authenticator. This erases all
  254. // stored resident keys and any configured PIN.
  255. virtual void Reset(ResetCallback callback);
  256. virtual void Cancel() = 0;
  257. enum class Type {
  258. kWinNative, // i.e. webauthn.dll
  259. kTouchID, // the Chrome-native Touch ID integration on macOS
  260. kChromeOS, // the platform authenticator on Chrome OS
  261. kOther,
  262. };
  263. // GetType returns the type of the authenticator.
  264. virtual Type GetType() const;
  265. // GetId returns a unique string representing this device. This string should
  266. // be distinct from all other devices concurrently discovered.
  267. virtual std::string GetId() const = 0;
  268. // GetDisplayName returns a string identifying a device to a human, which
  269. // might not be unique. For example, |GetDisplayName| could return the VID:PID
  270. // of a HID device, but |GetId| could not because two devices can share the
  271. // same VID:PID. It defaults to returning the value of |GetId|.
  272. virtual std::string GetDisplayName() const;
  273. virtual ProtocolVersion SupportedProtocol() const;
  274. virtual bool SupportsCredProtectExtension() const;
  275. virtual bool SupportsHMACSecretExtension() const;
  276. virtual bool SupportsEnterpriseAttestation() const;
  277. virtual bool SupportsCredBlobOfSize(size_t num_bytes) const;
  278. virtual const absl::optional<AuthenticatorSupportedOptions>& Options()
  279. const = 0;
  280. virtual absl::optional<FidoTransportProtocol> AuthenticatorTransport()
  281. const = 0;
  282. virtual bool IsInPairingMode() const = 0;
  283. virtual bool IsPaired() const = 0;
  284. virtual bool RequiresBlePairingPin() const = 0;
  285. virtual base::WeakPtr<FidoAuthenticator> GetWeakPtr() = 0;
  286. };
  287. } // namespace device
  288. #endif // DEVICE_FIDO_FIDO_AUTHENTICATOR_H_