dom/webidl/WebAuthentication.webidl

   1 /* -*- Mode: IDL; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* This Source Code Form is subject to the terms of the Mozilla Public
   3  * License, v. 2.0. If a copy of the MPL was not distributed with this file,
   4  * You can obtain one at http://mozilla.org/MPL/2.0/.
   5  *
   6  * The origin of this IDL file is
   7  * https://w3c.github.io/webauthn/
   8  */
   9
  10 /***** Interfaces to Data *****/
  11
  12 [SecureContext, Pref="security.webauth.webauthn",
  13  Exposed=Window]
  14 interface PublicKeyCredential : Credential {
  15     [SameObject, Throws] readonly attribute ArrayBuffer      rawId;
  16     [SameObject] readonly attribute AuthenticatorResponse    response;
  17     readonly attribute DOMString?                            authenticatorAttachment;
  18     AuthenticationExtensionsClientOutputs getClientExtensionResults();
  19     [NewObject] static Promise<boolean> isConditionalMediationAvailable();
  20     [Throws, Pref="security.webauthn.enable_json_serialization_methods"] object toJSON();
  21 };
  22
  23 typedef DOMString Base64URLString;
  24
  25 [GenerateConversionToJS]
  26 dictionary RegistrationResponseJSON {
  27     required Base64URLString id;
  28     required Base64URLString rawId;
  29     required AuthenticatorAttestationResponseJSON response;
  30     DOMString authenticatorAttachment;
  31     required AuthenticationExtensionsClientOutputsJSON clientExtensionResults;
  32     required DOMString type;
  33 };
  34
  35 [GenerateConversionToJS]
  36 dictionary AuthenticatorAttestationResponseJSON {
  37     required Base64URLString clientDataJSON;
  38     required Base64URLString authenticatorData;
  39     required sequence<DOMString> transports;
  40     // The publicKey field will be missing if pubKeyCredParams was used to
  41     // negotiate a public-key algorithm that the user agent doesn’t
  42     // understand. (See section “Easily accessing credential data” for a
  43     // list of which algorithms user agents must support.) If using such an
  44     // algorithm then the public key must be parsed directly from
  45     // attestationObject or authenticatorData.
  46     Base64URLString publicKey;
  47     required long long publicKeyAlgorithm;
  48     // This value contains copies of some of the fields above. See
  49     // section “Easily accessing credential data”.
  50     required Base64URLString attestationObject;
  51 };
  52
  53 [GenerateConversionToJS]
  54 dictionary AuthenticationResponseJSON {
  55     required Base64URLString id;
  56     required Base64URLString rawId;
  57     required AuthenticatorAssertionResponseJSON response;
  58     DOMString authenticatorAttachment;
  59     required AuthenticationExtensionsClientOutputsJSON clientExtensionResults;
  60     required DOMString type;
  61 };
  62
  63 [GenerateConversionToJS]
  64 dictionary AuthenticatorAssertionResponseJSON {
  65     required Base64URLString clientDataJSON;
  66     required Base64URLString authenticatorData;
  67     required Base64URLString signature;
  68     Base64URLString userHandle;
  69     Base64URLString attestationObject;
  70 };
  71
  72 [GenerateConversionToJS]
  73 dictionary AuthenticationExtensionsClientOutputsJSON {
  74 };
  75
  76 [SecureContext]
  77 partial interface PublicKeyCredential {
  78     [NewObject] static Promise<boolean> isUserVerifyingPlatformAuthenticatorAvailable();
  79 };
  80
  81 [SecureContext]
  82 partial interface PublicKeyCredential {
  83     [Throws, Pref="security.webauthn.enable_json_serialization_methods"] static PublicKeyCredentialCreationOptions parseCreationOptionsFromJSON(PublicKeyCredentialCreationOptionsJSON options);
  84 };
  85
  86 dictionary PublicKeyCredentialCreationOptionsJSON {
  87     required PublicKeyCredentialRpEntity                    rp;
  88     required PublicKeyCredentialUserEntityJSON              user;
  89     required Base64URLString                                challenge;
  90     required sequence<PublicKeyCredentialParameters>        pubKeyCredParams;
  91     unsigned long                                           timeout;
  92     sequence<PublicKeyCredentialDescriptorJSON>             excludeCredentials = [];
  93     AuthenticatorSelectionCriteria                          authenticatorSelection;
  94     sequence<DOMString>                                     hints = [];
  95     DOMString                                               attestation = "none";
  96     sequence<DOMString>                                     attestationFormats = [];
  97     AuthenticationExtensionsClientInputsJSON                extensions;
  98 };
  99
 100 dictionary PublicKeyCredentialUserEntityJSON {
 101     required Base64URLString        id;
 102     required DOMString              name;
 103     required DOMString              displayName;
 104 };
 105
 106 dictionary PublicKeyCredentialDescriptorJSON {
 107     required Base64URLString        id;
 108     required DOMString              type;
 109     sequence<DOMString>             transports;
 110 };
 111
 112 dictionary AuthenticationExtensionsClientInputsJSON {
 113 };
 114
 115 [SecureContext]
 116 partial interface PublicKeyCredential {
 117     [Throws, Pref="security.webauthn.enable_json_serialization_methods"] static PublicKeyCredentialRequestOptions parseRequestOptionsFromJSON(PublicKeyCredentialRequestOptionsJSON options);
 118 };
 119
 120 dictionary PublicKeyCredentialRequestOptionsJSON {
 121     required Base64URLString                                challenge;
 122     unsigned long                                           timeout;
 123     DOMString                                               rpId;
 124     sequence<PublicKeyCredentialDescriptorJSON>             allowCredentials = [];
 125     DOMString                                               userVerification = "preferred";
 126     sequence<DOMString>                                     hints = [];
 127     DOMString                                               attestation = "none";
 128     sequence<DOMString>                                     attestationFormats = [];
 129     AuthenticationExtensionsClientInputsJSON                extensions;
 130 };
 131
 132 [SecureContext, Pref="security.webauth.webauthn",
 133  Exposed=Window]
 134 interface AuthenticatorResponse {
 135     [SameObject, Throws] readonly attribute ArrayBuffer clientDataJSON;
 136 };
 137
 138 [SecureContext, Pref="security.webauth.webauthn",
 139  Exposed=Window]
 140 interface AuthenticatorAttestationResponse : AuthenticatorResponse {
 141     [SameObject, Throws] readonly attribute ArrayBuffer attestationObject;
 142     sequence<DOMString>                                 getTransports();
 143     [Throws] ArrayBuffer                                getAuthenticatorData();
 144     [Throws] ArrayBuffer?                               getPublicKey();
 145     [Throws] COSEAlgorithmIdentifier                    getPublicKeyAlgorithm();
 146 };
 147
 148 [SecureContext, Pref="security.webauth.webauthn",
 149  Exposed=Window]
 150 interface AuthenticatorAssertionResponse : AuthenticatorResponse {
 151     [SameObject, Throws] readonly attribute ArrayBuffer      authenticatorData;
 152     [SameObject, Throws] readonly attribute ArrayBuffer      signature;
 153     [SameObject, Throws] readonly attribute ArrayBuffer?     userHandle;
 154 };
 155
 156 dictionary PublicKeyCredentialParameters {
 157     required DOMString                type;
 158     required COSEAlgorithmIdentifier  alg;
 159 };
 160
 161 dictionary PublicKeyCredentialCreationOptions {
 162     required PublicKeyCredentialRpEntity   rp;
 163     required PublicKeyCredentialUserEntity user;
 164
 165     required BufferSource                            challenge;
 166     required sequence<PublicKeyCredentialParameters> pubKeyCredParams;
 167
 168     unsigned long                                timeout;
 169     sequence<PublicKeyCredentialDescriptor>      excludeCredentials = [];
 170     // FIXME: bug 1493860: should this "= {}" be here?
 171     AuthenticatorSelectionCriteria               authenticatorSelection = {};
 172     DOMString                                    attestation = "none";
 173     // FIXME: bug 1493860: should this "= {}" be here?
 174     AuthenticationExtensionsClientInputs         extensions = {};
 175 };
 176
 177 dictionary PublicKeyCredentialEntity {
 178     required DOMString    name;
 179 };
 180
 181 dictionary PublicKeyCredentialRpEntity : PublicKeyCredentialEntity {
 182     DOMString      id;
 183 };
 184
 185 dictionary PublicKeyCredentialUserEntity : PublicKeyCredentialEntity {
 186     required BufferSource   id;
 187     required DOMString      displayName;
 188 };
 189
 190 dictionary AuthenticatorSelectionCriteria {
 191     DOMString                    authenticatorAttachment;
 192     DOMString                    residentKey;
 193     boolean                      requireResidentKey = false;
 194     DOMString                    userVerification = "preferred";
 195 };
 196
 197 dictionary PublicKeyCredentialRequestOptions {
 198     required BufferSource                challenge;
 199     unsigned long                        timeout;
 200     USVString                            rpId;
 201     sequence<PublicKeyCredentialDescriptor> allowCredentials = [];
 202     DOMString                            userVerification = "preferred";
 203     // FIXME: bug 1493860: should this "= {}" be here?
 204     AuthenticationExtensionsClientInputs extensions = {};
 205 };
 206
 207 dictionary AuthenticationExtensionsClientInputs {
 208 };
 209
 210 dictionary AuthenticationExtensionsClientOutputs {
 211 };
 212
 213 typedef record<DOMString, DOMString> AuthenticationExtensionsAuthenticatorInputs;
 214
 215 [GenerateToJSON]
 216 dictionary CollectedClientData {
 217     required DOMString           type;
 218     required DOMString           challenge;
 219     required DOMString           origin;
 220     TokenBinding                 tokenBinding;
 221 };
 222
 223 dictionary TokenBinding {
 224     required DOMString status;
 225     DOMString id;
 226 };
 227
 228 dictionary PublicKeyCredentialDescriptor {
 229     required DOMString                    type;
 230     required BufferSource                 id;
 231     // Transports is a string that is matched against the AuthenticatorTransport
 232     // enumeration so that we have forward-compatibility for new transports.
 233     sequence<DOMString>                   transports;
 234 };
 235
 236 typedef long COSEAlgorithmIdentifier;
 237
 238 typedef sequence<AAGUID>      AuthenticatorSelectionList;
 239
 240 typedef BufferSource      AAGUID;
 241
 242 partial dictionary AuthenticationExtensionsClientInputs {
 243     USVString appid;
 244 };
 245
 246 partial dictionary AuthenticationExtensionsClientOutputs {
 247     boolean appid;
 248 };
 249
 250 // The spec does not define any partial dictionaries that modify
 251 // AuthenticationExtensionsClientInputsJSON, but this seems to be an error. All changes to
 252 // AuthenticationExtensionsClientInputs must be accompanied by changes to
 253 // AuthenticationExtensionsClientInputsJSON for parseCreationOptionsFromJSON and
 254 // parseRequestOptionsFromJSON to function correctly.
 255 // (see: https://github.com/w3c/webauthn/issues/1968).
 256 partial dictionary AuthenticationExtensionsClientInputsJSON {
 257     USVString appid;
 258 };
 259
 260 // We also deviate from the spec by mirroring changes to AuthenticationExtensionsClientOutputs in
 261 // AuthenticationExtensionsClientOutputsJSON.
 262 partial dictionary AuthenticationExtensionsClientOutputsJSON {
 263     boolean appid;
 264 };
 265
 266 partial dictionary AuthenticationExtensionsClientInputs {
 267     boolean credProps;
 268 };
 269
 270 partial dictionary AuthenticationExtensionsClientInputsJSON {
 271     boolean credProps;
 272 };
 273
 274 dictionary CredentialPropertiesOutput {
 275     boolean rk;
 276 };
 277
 278 partial dictionary AuthenticationExtensionsClientOutputs {
 279     CredentialPropertiesOutput credProps;
 280 };
 281
 282 partial dictionary AuthenticationExtensionsClientOutputsJSON {
 283     CredentialPropertiesOutput credProps;
 284 };
 285
 286 /*
 287  * CTAP2 Extensions
 288  * <https://fidoalliance.org/specs/fido-v2.1-ps-20210615/fido-client-to-authenticator-protocol-v2.1-ps-errata-20220621.html#sctn-defined-extensions>
 289  */
 290
 291 // hmac-secret
 292 // <https://fidoalliance.org/specs/fido-v2.1-ps-20210615/fido-client-to-authenticator-protocol-v2.1-ps-errata-20220621.html#sctn-hmac-secret-extension>
 293 // note: we don't support hmac-secret in get(), so we only define the create()
 294 // inputs and outputs here.
 295
 296 partial dictionary AuthenticationExtensionsClientInputs {
 297     boolean hmacCreateSecret;
 298 };
 299
 300 partial dictionary AuthenticationExtensionsClientOutputs {
 301     boolean hmacCreateSecret;
 302 };
 303
 304 partial dictionary AuthenticationExtensionsClientInputsJSON {
 305     boolean hmacCreateSecret;
 306 };
 307
 308 partial dictionary AuthenticationExtensionsClientOutputsJSON {
 309     boolean hmacCreateSecret;
 310 };
 311
 312 // hmac-secret
 313 // <https://fidoalliance.org/specs/fido-v2.1-ps-20210615/fido-client-to-authenticator-protocol-v2.1-ps-errata-20220621.html#sctn-minpinlength-extension>
 314 partial dictionary AuthenticationExtensionsClientInputs {
 315   boolean minPinLength;
 316 };
 317
 318 partial dictionary AuthenticationExtensionsClientInputsJSON {
 319   boolean minPinLength;
 320 };