// Copyright 2017 The Chromium Authors
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
module blink.mojom;
import "components/payments/mojom/payment_request_data.mojom";
import "mojo/public/mojom/base/time.mojom";
import "third_party/blink/public/mojom/payments/payment_credential.mojom";
import "url/mojom/origin.mojom";
import "url/mojom/url.mojom";
// This file describes the communication between the WebAuthentication renderer
// implementation and browser-side implementations to create public key
// credentials and use already-created credentials to get assertions.
// See https://w3c.github.io/webauthn/.
// The maximum allowable list size for vectors of
// `PublicKeyCredentialDescriptor` (i.e.
// `PublicKeyCredentialCreationOptions.exclude_credentials` and
// `PublicKeyCredentialRequestOptions.allow_credentials`).
const uint32 kPublicKeyCredentialDescriptorListMaxSize = 64;
enum AuthenticatorStatus {
SUCCESS,
PENDING_REQUEST,
NOT_ALLOWED_ERROR,
INVALID_DOMAIN,
CREDENTIAL_EXCLUDED,
NOT_IMPLEMENTED,
NOT_FOCUSED,
RESIDENT_CREDENTIALS_UNSUPPORTED,
USER_VERIFICATION_UNSUPPORTED,
ALGORITHM_UNSUPPORTED,
EMPTY_ALLOW_CREDENTIALS,
ANDROID_NOT_SUPPORTED_ERROR,
PROTECTION_POLICY_INCONSISTENT,
ABORT_ERROR,
OPAQUE_DOMAIN,
INVALID_PROTOCOL,
BAD_RELYING_PARTY_ID,
BAD_RELYING_PARTY_ID_ATTEMPTED_FETCH,
BAD_RELYING_PARTY_ID_WRONG_CONTENT_TYPE,
BAD_RELYING_PARTY_ID_JSON_PARSE_ERROR,
BAD_RELYING_PARTY_ID_NO_JSON_MATCH,
BAD_RELYING_PARTY_ID_NO_JSON_MATCH_HIT_LIMITS,
CANNOT_READ_AND_WRITE_LARGE_BLOB,
INVALID_ALLOW_CREDENTIALS_FOR_LARGE_BLOB,
FAILED_TO_SAVE_CREDENTIAL_ID_FOR_PAYMENT_EXTENSION,
REMOTE_DESKTOP_CLIENT_OVERRIDE_NOT_AUTHORIZED,
DEVICE_PUBLIC_KEY_ATTESTATION_REJECTED,
CERTIFICATE_ERROR,
// ERROR_WITH_DOM_EXCEPTION_DETAILS indicates that the error will be
// described in a `WebAuthnDOMExceptionDetails` structure.
ERROR_WITH_DOM_EXCEPTION_DETAILS,
UNKNOWN_ERROR,
};
// See https://www.w3.org/TR/webauthn/#transport
enum AuthenticatorTransport {
USB,
NFC,
BLE,
HYBRID,
INTERNAL,
};
// See https://w3c.github.io/webauthn/#enum-hints
enum Hint {
SECURITY_KEY,
CLIENT_DEVICE,
HYBRID,
};
// Credential information returned by both Authenticator::MakeCredential
// and Authenticator::GetAssertion.
struct CommonCredentialInfo {
// The base64url encoding of |raw_id|.
string id;
// An identifier for the credential.
array<uint8> raw_id;
// A blob of data containing the JSON serialization of client data passed
// to the authenticator.
array<uint8> client_data_json;
// A blob of data returned by the authenticator after generating an assertion.
array<uint8> authenticator_data;
};
// Content of user verification method extension returned by
// Authenticator::GetAssertion.
// See https://w3c.github.io/webauthn/#sctn-uvm-extension
// Registry of the available values, see
// https://fidoalliance.org/specs/fido-v2.0-id-20180227/fido-registry-v2.0-id-20180227.html#user-verification-methods
[EnableIf=is_android]
struct UvmEntry {
uint32 user_verification_method;
uint16 key_protection_type;
uint16 matcher_protection_type;
};
// The output for the `supplementalPubKeys` extension.
struct SupplementalPubKeysResponse {
array<array<uint8>> signatures;
};
// The public key and attestation returned by Authenticator::MakeCredential.
struct MakeCredentialAuthenticatorResponse {
CommonCredentialInfo info;
// The attachment of the authenticator that created the credential.
AuthenticatorAttachment authenticator_attachment;
// A blob of data returned by the authenticator after creating a credential.
array<uint8> attestation_object;
// A list of transports that the authenticator supports, with the transport
// used for the registration as the first element.
array<AuthenticatorTransport> transports;
// True if getClientExtensionResults() called on the returned
// PublicKeyCredential instance should contain an `hmacCreateSecret`
// extension output. If so, |hmac_create_secret| contains the actual value.
bool echo_hmac_create_secret;
bool hmac_create_secret;
// True if getClientExtensionResults() called on the returned
// PublicKeyCredential instance should contain a `prf` extension output. If
// so, |prf| contains the value of the `enabled` member.
bool echo_prf;
bool prf;
PRFValues? prf_results;
// True if getClientExtensionResults() called on the returned
// PublicKeyCredential instance should contain a `credBlob` extension output.
// If so, |cred_blob| contains the value of the output.
bool echo_cred_blob;
bool cred_blob;
// The DER-encoded, ASN.1 public key of the newly created credential. May be
// missing if the browser does not understand the public-key type.
array<uint8>? public_key_der;
// The COSE algorithm of the newly created credential.
// See https://www.iana.org/assignments/cose/cose.xhtml#algorithms
int32 public_key_algo;
// True if getClientExtensionResults() called on the returned
// PublicKeyCredential instance should contain a `credProps` extension
// output. |has_cred_props_rk| indicates if the rk member in that extension
// output should be set to the value in |cred_props_rk|.
bool echo_cred_props;
bool has_cred_props_rk;
bool cred_props_rk;
// True if getClientExtensionResults() called on the returned
// PublicKeyCredential instance should contain a `largeBlob` extension output.
// |supports_large_blob| indicates the value the `supported` member in that
// extension output should be.
bool echo_large_blob;
bool supports_large_blob;
SupplementalPubKeysResponse? supplemental_pub_keys;
};
struct GetAssertionAuthenticatorResponse {
CommonCredentialInfo info;
// The attachment of the authenticator that created the credential.
AuthenticatorAttachment authenticator_attachment;
// Cryptographic signature proving possession of the credential private key.
array<uint8> signature;
// Only supported by CTAP devices, not by U2F devices.
// Equivalent of the `user.id` passed into create().
// Maximum 64 bytes.
array<uint8>? user_handle;
// Webauthn extension related output responses.
AuthenticationExtensionsClientOutputs extensions;
};
// Webauthn credential assertion extensions response values.
struct AuthenticationExtensionsClientOutputs {
// True if getClientExtensionResults() called on the returned
// PublicKeyCredential instance should contain an `appid` extension output.
// If so, |appid_extension| contains the actual value.
bool echo_appid_extension;
bool appid_extension;
// Only supported by fido2 devices on android, will eventually supported by
// other platform.
// True if getClientExtensionResults() called on the returned
// PublicKeyCredential instance should contain an 'uvm' extension output.
// If so, |user_verification_methods| contains the actual value.
[EnableIf=is_android]
bool echo_user_verification_methods;
[EnableIf=is_android]
array<UvmEntry>? user_verification_methods;
// echo_prf indicates whether the PRF extension should be present in the
// output.
bool echo_prf;
// prf_results contains PRF outputs to include in the extension, if any.
PRFValues? prf_results;
// prf_not_evaluated indicates the the PRF inputs could not be processed
// because of a lack of operating system support.
bool prf_not_evaluated;
// True if getClientExtensionResults() called on the returned
// PublicKeyCredential instance should contain a `largeBlob` extension output.
bool echo_large_blob;
// Value that getClientExtensionResults() called on the returned
// PublicKeyCredential instance should contain for the `largeBlob`
// extension output `blob` parameter.
array<uint8>? large_blob;
// True if getClientExtensionResults() called on the returned
// PublicKeyCredential instance should contain a `largeBlob` extension output
// with a `written` parameter. The value is indicated by |large_blob_written|.
bool echo_large_blob_written;
bool large_blob_written;
// The value of the `getCredBlob` extension output, which maybe empty, or
// null if none.
array<uint8>? get_cred_blob;
SupplementalPubKeysResponse? supplemental_pub_keys;
};
// Information about the relying party. These fields take arbitrary input.
struct PublicKeyCredentialRpEntity {
// An ASCII serialization of an origin.
string id;
// Friendly name associated with the relying party intended for display.
// e.g. "Acme Corporation".
string name;
};
// Informatiom about the account held by the user. These fields take
// arbitrary input.
struct PublicKeyCredentialUserEntity {
// Unique identifier for a user account An opaque byte sequence with a
// maximum size of 64 bytes.
array<uint8> id;
// Friendly name associated with the entity intended for display.
// e.g."[email protected]" or "+14255551234" for a user.
string name;
// Contains a friendly name for the user account (e.g., "John P. Smith").
string display_name;
};
// Parameters that are used to generate an appropriate public key credential.
struct PublicKeyCredentialParameters {
PublicKeyCredentialType type;
int32 algorithm_identifier;
};
// See https://w3c.github.io/webauthn/#enumdef-userverificationrequirement.
enum UserVerificationRequirement {
REQUIRED,
PREFERRED,
DISCOURAGED,
};
// Cloud-assisted BLE extension data for getAssertion.
struct CableAuthentication {
// The caBLE version requested.
uint8 version;
// A 16-byte ephemeral identifier that the browser will advertise.
// (Present iff version == 1.)
array<uint8, 16>? client_eid;
// A 16-byte ephemeral identifier that the browser expects to receive from a
// responding authenticator.
// (Present iff version == 1.)
array<uint8, 16>? authenticator_eid;
// A 32-byte pre-key used to compute a session key to encrypt messages between
// a paired client and authenticator following a successful discovery.
// (Present iff version == 1.)
array<uint8, 32>? session_pre_key;
// caBLEv2 server-link data, used to find and communicate with a caBLEv2
// device.
// (Present iff version == 2.)
array<uint8>? server_link_data;
// caBLEv2 experiment numbers.
// (Present iff version == 2.)
array<uint8>? experiments;
};
// See https://w3c.github.io/webauthn/#dictdef-authenticationextensionsprfvalues
struct PRFValues {
// In the Javascript-to-native direction, id is the credential ID for these
// inputs. If null then these are the default values for when no credential
// IDs match. In the other direction, id will always be null.
array<uint8>? id;
// The WebAuthn spec says that inputs are hashed with a "WebAuthn PRF\x00"
// prefix before being used. These values may, or may not be, hashed when used
// as inputs. See the `prf_inputs_hashed` flag.
array<uint8> first;
array<uint8>? second;
};
// Payment parameters passed into calls to GetAssertion for Secure Payment
// Confirmation.
// TODO(https://crbug.com/1239249): Convert to a non-mojo struct, because this
// is not used in any mojo interfaces.
struct PaymentOptions {
payments.mojom.PaymentCurrencyAmount total;
PaymentCredentialInstrument instrument;
string? payee_name;
url.mojom.Origin? payee_origin;
};
// TODO(https://crbug.com/1239249): Move to payment_request.mojom after this
// struct is no longer used in here.
struct PaymentCredentialInstrument {
// Friendly name for displaying this instrument to the user.
string display_name;
// URL for an icon to display alongside the display_name. The URL is secure,
// not required to share the same origin with the current page.
url.mojom.Url icon;
// Whether the icon is required to be shown in the UI.
bool iconMustBeShown;
};
// https://github.com/w3c/webauthn/wiki/Explainer:-WebAuthn-Remote-Desktop-Support
struct RemoteDesktopClientOverride {
url.mojom.Origin origin;
bool same_origin_with_ancestors;
};
struct SupplementalPubKeysRequest {
bool device_scope_requested;
bool provider_scope_requested;
AttestationConveyancePreference attestation;
array<string> attestation_formats;
};
// Parameters passed into calls to GetAssertion.
struct PublicKeyCredentialRequestOptions {
// If true, indicates that this request should prioritize showing a UI only if
// there are discoverable credentials available in this device's platform
// authenticator.
bool is_conditional;
// An indefinite-length blob passed from the the relying party server,
// to be sent to an authenticator for signing.
array<uint8> challenge;
// Time to wait for an authenticator to complete an operation provided by the
// relying party.
mojo_base.mojom.TimeDelta? timeout;
// An ASCII serialization of the origin claimed by the relying party.
string relying_party_id;
// A list of credentials the relying party knows about and would
// accept as the signing credential.
array<PublicKeyCredentialDescriptor> allow_credentials;
// https://w3c.github.io/webauthn/#enumdef-publickeycredentialhints
array<Hint> hints;
// Indicates the relying party's need for a user-verifying authenticator.
UserVerificationRequirement user_verification;
// Webauthn extension related input parameters.
AuthenticationExtensionsClientInputs extensions;
};
// Parameters for webauthn Extensions.
struct AuthenticationExtensionsClientInputs {
// The contents of the appid extension, if any. See
// https://w3c.github.io/webauthn/#sctn-appid-extension
string? appid;
// The contents of the cloud assisted BLE extension for getAssertion
// requests, if any. This extension permits browsers and authenticator
// devices to establish a pairingless BLE connection.
// TODO(crbug.com/842371): Add link to spec when available.
// There may be multiple sets if multiple caBLE credentials have been
// registered with the relying party.
array<CableAuthentication> cable_authentication_data;
// Only supported by fido2 devices on android, will eventually supported by
// other platform.
// Whether the user verification method extension is requested by
// the RP. See https://w3c.github.io/webauthn/#sctn-uvm-extension
[EnableIf=is_android]
bool user_verification_methods;
// prf is true if the request contained a PRF extension.
bool prf;
// List of PRF inputs. The first element may have a null |id| member,
// indicating that it's the default value when none of the elements with a
// credential ID match. Otherwise all elements must have an |id| member and
// must be sorted lexicographically by it.
array<PRFValues> prf_inputs;
// prf_inputs_hashed is true if the `first` and `second` members of
// `prf_inputs` have already been hashed.
bool prf_inputs_hashed;
// If true, attempt to read the large blob associated to the credential.
// https://w3c.github.io/webauthn/#dom-authenticationextensionslargeblobinputs-read
bool large_blob_read;
// If present, large blob to be written on the credential.
// https://w3c.github.io/webauthn/#dom-authenticationextensionslargeblobinputs-write
array<uint8>? large_blob_write;
// If true, attempt to read a credblob.
// https://fidoalliance.org/specs/fido-v2.1-rd-20201208/fido-client-to-authenticator-protocol-v2.1-rd-20201208.html#sctn-credBlob-extension
bool get_cred_blob;
// Indicates that a remote desktop client is making a forwarded request on
// behalf of another origin.
RemoteDesktopClientOverride? remote_desktop_client_override;
// If present, reflects the contents of the "supplementalPubKeys" extension.
// https://github.com/w3c/webauthn/pull/1663
SupplementalPubKeysRequest? supplemental_pub_keys;
};
// https://w3c.github.io/webauthn/#enum-residentKeyRequirement
enum ResidentKeyRequirement {
DISCOURAGED,
PREFERRED,
REQUIRED,
};
// https://w3c.github.io/webauthn/#enumdef-authenticatorattachment.
enum AuthenticatorAttachment {
NO_PREFERENCE,
PLATFORM,
CROSS_PLATFORM,
};
enum ProtectionPolicy {
// UNSPECIFIED means that no value was given at the Javascript level.
UNSPECIFIED,
NONE,
UV_OR_CRED_ID_REQUIRED,
UV_REQUIRED,
};
// https://w3c.github.io/webauthn#enumdef-largeblobsupport
enum LargeBlobSupport {
NOT_REQUESTED,
REQUIRED,
PREFERRED,
};
// See https://w3c.github.io/webauthn/#dictdef-authenticatorselectioncriteria.
struct AuthenticatorSelectionCriteria {
// Filter authenticators by attachment type.
AuthenticatorAttachment authenticator_attachment;
// Indicates a requirement or preference for creating a client-side
// discoverable credential. If set, overrides |require_resident_key|.
ResidentKeyRequirement resident_key;
// Indicates the relying party's need for a user-verifying authenticator.
UserVerificationRequirement user_verification;
};
// Parameters passed into calls to MakeCredential.
struct PublicKeyCredentialCreationOptions {
// Information about the relying party and user entities, respectively.
// Used by the authenticator to create or retrieve an appropriate public key
// credential for the requested account.
PublicKeyCredentialRpEntity relying_party;
PublicKeyCredentialUserEntity user;
// An indefinite-length blob passed from the the relying party server,
// to be sent to an authenticator to make a credential.
array<uint8> challenge;
// Parameters defining the type of created credential that the relying
// party would accept.
array<PublicKeyCredentialParameters> public_key_parameters;
// Time to wait for an authenticator to complete an operation provided by the
// relying party.
mojo_base.mojom.TimeDelta? timeout;
// A list of credentials the relying party knows about. If an
// authenticator has one of these credentials, it should not
// create a new one.
array<PublicKeyCredentialDescriptor> exclude_credentials;
// Specify the relying party's authenticator attribute requirements.
AuthenticatorSelectionCriteria? authenticator_selection;
// https://w3c.github.io/webauthn/#enumdef-publickeycredentialhints
array<Hint> hints;
// Specifies whether the RP wants attestation information for the created
// credential.
AttestationConveyancePreference attestation;
// The contents of the hmacCreateSecret extension, if any. See
// https://fidoalliance.org/specs/fido-v2.0-rd-20180702/fido-client-to-authenticator-protocol-v2.0-rd-20180702.html#sctn-hmac-secret-extension
bool hmac_create_secret;
// Whether the PRF extension was present.
// https://w3c.github.io/webauthn/#prf-extension
bool prf_enable;
// Optional PRF input. Cannot have the `id` field set.
PRFValues? prf_input;
// The value of the `credentialProtectionPolicy` extension, or UNSPECIFIED if
// none was provided.
ProtectionPolicy protection_policy;
// The value of the `enforceCredentialProtectionPolicy`, or false if none was
// provided.
bool enforce_protection_policy;
// The contents of the appidExclude extension, if any. See
// https://w3c.github.io/webauthn/#sctn-appid-exclude-extension
string? appid_exclude;
// Whether the credProps extension was requested.
// https://w3c.github.io/webauthn/#sctn-authenticator-credential-properties-extension
bool cred_props;
// The level of largeBlob support requested by the relying party.
// https://w3c.github.io/webauthn/#sctn-large-blob-extension
LargeBlobSupport large_blob_enable;
// Whether this request is for making a PaymentCredential.
bool is_payment_credential_creation;
// If present, attempt the store the given value as a credblob.
// https://fidoalliance.org/specs/fido-v2.1-rd-20201208/fido-client-to-authenticator-protocol-v2.1-rd-20201208.html#sctn-credBlob-extension
array<uint8>? cred_blob;
// Whether the minPinLength extension was set to true.
// https://fidoalliance.org/specs/fido-v2.1-ps-20210615/fido-client-to-authenticator-protocol-v2.1-ps-20210615.html#sctn-minpinlength-extension
bool min_pin_length_requested = false;
// Indicates that a remote desktop client is making a forwarded request on
// behalf of another origin.
RemoteDesktopClientOverride? remote_desktop_client_override;
// If present, reflects the contents of the "supplementalPubKeys" extension.
// https://github.com/w3c/webauthn/pull/1663
SupplementalPubKeysRequest? supplemental_pub_keys;
// https://w3c.github.io/webauthn/#dom-publickeycredentialcreationoptionsjson-attestationformats
array<string> attestation_formats;
};
// See https://w3c.github.io/webauthn/#enumdef-attestationconveyancepreference
enum AttestationConveyancePreference {
NONE,
INDIRECT,
DIRECT,
// A non-standard addition that we hope will become standard. This indicates
// that the RP desires individual attestation from the device.
ENTERPRISE,
};
enum PublicKeyCredentialType {
PUBLIC_KEY,
};
// Describes the credentials that the relying party already knows about for
// the given account. If any of these are known to the authenticator,
// it should not create a new credential.
struct PublicKeyCredentialDescriptor {
PublicKeyCredentialType type;
// Blob representing a credential key handle. Up to 255 bytes for
// U2F authenticators.
array<uint8> id;
array<AuthenticatorTransport> transports;
};
// Describes the DOMException to be returned to the caller if MakeCredential or
// GetAssertion returns ERROR_WITH_DOM_EXCEPTION_DETAILS.
struct WebAuthnDOMExceptionDetails {
string name;
string message;
};
// Parameters passed into calls to Report.
struct PublicKeyCredentialReportOptions {
string relying_party_id;
array<uint8>? unknown_credential_id;
AllAcceptedCredentialsOptions? all_accepted_credentials;
CurrentUserDetailsOptions? current_user_details;
};
// Parameters passed into calls to report all accepted credentials.
struct AllAcceptedCredentialsOptions {
array<uint8> user_id;
array<array<uint8>> all_accepted_credentials_ids;
};
// Parameters passed into calls to report current user details.
struct CurrentUserDetailsOptions {
array<uint8> user_id;
string name;
string display_name;
};
// Describes a single WebAuthn client capability and its support status.
struct WebAuthnClientCapability {
string name;
bool supported;
};
// Interface to direct authenticators to create or use a public key credential.
interface Authenticator {
// Gets the credential info for a new public key credential created by an
// authenticator for the given |PublicKeyCredentialCreationOptions|.
// [MakeCredentialAuthenticatorResponse] will be set if and only if status ==
// SUCCESS. [WebAuthnDOMExceptionDetails] will be set if and only if
// status == ERROR_WITH_DOM_EXCEPTION_DETAILS.
MakeCredential(PublicKeyCredentialCreationOptions options)
=> (AuthenticatorStatus status,
MakeCredentialAuthenticatorResponse? credential,
WebAuthnDOMExceptionDetails? dom_exception_details);
// Uses an existing credential to produce an assertion for the given
// |PublicKeyCredentialRequestOptions|.
// |GetAssertionResponse| will be set if and only if status == SUCCESS.
// [WebAuthnDOMExceptionDetails] will be set if and only if
// status == ERROR_WITH_DOM_EXCEPTION_DETAILS.
GetAssertion(PublicKeyCredentialRequestOptions options)
=> (AuthenticatorStatus status,
GetAssertionAuthenticatorResponse? credential,
WebAuthnDOMExceptionDetails? dom_exception_details);
// Returns true if the user platform provides an authenticator. Relying
// Parties use this method to determine whether they can create a new
// credential using a user-verifying platform authenticator.
IsUserVerifyingPlatformAuthenticatorAvailable() => (bool available);
// Returns true if Conditional Mediation is available. Relying Parties can use
// this method to determine whether they can pass "conditional" to the
// "mediation" parameter of a webauthn get call and have the browser autofill
// webauthn credentials on form inputs.
IsConditionalMediationAvailable() => (bool available);
// Reports the credentials info so that credentials can be updated or removed
// from a credential storage provider for the given
// |PublicKeyCredentialReportOptions|.
Report(PublicKeyCredentialReportOptions options)
=> (AuthenticatorStatus status,
WebAuthnDOMExceptionDetails? dom_exception_details);
// Returns an array of supported WebAuthn client capabilities.
GetClientCapabilities() => (array<WebAuthnClientCapability> capabilities);
// Cancel an ongoing MakeCredential or GetAssertion request
// Only one MakeCredential or GetAssertion call at a time is allowed,
// any future calls are cancelled
Cancel();
};
Codebase Browser
chromium