Skip to content

Commit

Permalink
Merge pull request #2047 from w3c/1859-differentiate-errors
Browse files Browse the repository at this point in the history
Help RP's understand actionable exceptions from `create()` and `get()`
MasterKale authored Aug 7, 2024

Verified

This commit was created on GitHub.com and signed with GitHub’s verified signature.
2 parents 30061db + 2b692fa commit 056ed8b
Showing 1 changed file with 96 additions and 4 deletions.
100 changes: 96 additions & 4 deletions index.bs
Original file line number Diff line number Diff line change
@@ -261,10 +261,6 @@ spec: SP800-800-63r3; urlPrefix: https://pages.nist.gov/800-63-3/sp800-63-3.html
text: something you have; url: af
text: something you are; url: af

spec: webidl; urlPrefix: https://heycam.github.io/webidl
type: dfn;
text: get a copy of the bytes held by the buffer source; url: dfn-get-buffer-source-copy

spec: webdriver; urlPrefix: https://w3c.github.io/webdriver/
type: dfn
text: WebDriver error; url: dfn-error
@@ -2251,6 +2247,61 @@ During the above process, the user agent SHOULD show some UI to the user to guid
authorizing an authenticator. When <code>|options|.{{CredentialCreationOptions/mediation}}</code> is set to {{CredentialMediationRequirement/conditional}}, prominent modal UI should <i>not</i> be shown <i>unless</i> credential creation was previously consented to via means determined by the user agent.
</div>

#### Create Request Exceptions #### {#sctn-create-request-exceptions}

[INFORMATIVE]

[=[WRPS]=] can encounter a number of exceptions from a call to {{CredentialsContainer/create()|navigator.credentials.create()}}.
Some exceptions can have multiple reasons for why they happened,
requiring the [=[WRPS]=] to infer the actual reason based on their use of WebAuthn.

Note: Exceptions that can be raised during processing of any [=WebAuthn Extensions=],
including ones defined outside of this specification,
are not listed here.

The following {{DOMException}} exceptions can be raised:

<dl>
: {{AbortError}}
:: The ceremony was cancelled by an {{AbortController}}.
See [[#sctn-abortoperation]] and [[#sctn-sample-aborting]].

: {{ConstraintError}}
:: Either {{residentKey}} was set to {{ResidentKeyRequirement/required}} and no available authenticator supported resident keys,
or {{AuthenticatorSelectionCriteria/userVerification}} was set to {{UserVerificationRequirement/required}} and no available authenticator could perform [=user verification=].

: {{InvalidStateError}}
:: The authenticator used in the ceremony recognized an entry in {{PublicKeyCredentialCreationOptions/excludeCredentials}}
after the user [=user consent|consented=] to registering a credential.

: {{NotSupportedError}}
:: No entry in {{PublicKeyCredentialCreationOptions/pubKeyCredParams}} had a {{PublicKeyCredentialDescriptor/type}} property of {{PublicKeyCredentialType/public-key}},
or the [=authenticator=] did not support any of the signature algorithms specified in {{PublicKeyCredentialCreationOptions/pubKeyCredParams}}.

: {{SecurityError}}
:: The [=effective domain=] was not a [=valid domain=],
or <code>{{PublicKeyCredentialCreationOptions/rp}}.{{PublicKeyCredentialRpEntity/id}}</code> was not equal to or a registrable domain suffix of the [=effective domain=].
In the latter case,
the [=client=] does not support [[#sctn-related-origins|related origin requests]]
or the [$related origins validation procedure$] failed.

: {{NotAllowedError}}
:: A catch-all error covering a wide range of possible reasons,
including common ones like the user canceling out of the ceremony.
Some of these causes are documented throughout this spec,
while others are client-specific.

</dl>

The following [=simple exceptions=] can be raised:

<dl>

: {{TypeError}}
:: The <code>|options|</code> argument was not a valid <code>[[#sctn-credentialcreationoptions-extension|CredentialCreationOptions]]</code> value,
or the value of <code>{{PublicKeyCredentialCreationOptions/user}}.{{PublicKeyCredentialUserEntity/id}}</code> was empty or was longer than 64 bytes.

</dl>

### Use an Existing Credential to Make an Assertion - PublicKeyCredential's `[[Get]](options)` Method ### {#sctn-getAssertion}

@@ -2766,6 +2817,47 @@ The steps for [=issuing a credential request to an authenticator=] are as follow

1. Return [TRUE].

#### Get Request Exceptions #### {#sctn-get-request-exceptions}

[INFORMATIVE]

[=[WRPS]=] can encounter a number of exceptions from a call to {{CredentialsContainer/get()|navigator.credentials.get()}}.
Some exceptions can have multiple reasons for why they happened,
requiring the [=[WRPS]=] to infer the actual reason based on their use of WebAuthn.

Note: Exceptions that can be raised during processing of any [=WebAuthn Extensions=],
including ones defined outside of this specification,
are not listed here.

The following {{DOMException}} exceptions can be raised:

<dl>
: {{AbortError}}
:: The ceremony was cancelled by an {{AbortController}}.
See [[#sctn-abortoperation]] and [[#sctn-sample-aborting]].

: {{SecurityError}}
:: The [=effective domain=] was not a [=valid domain=],
or <code>{{PublicKeyCredentialCreationOptions/rp}}.{{PublicKeyCredentialRpEntity/id}}</code> was not equal to or a registrable domain suffix of the [=effective domain=].
In the latter case,
the [=client=] does not support [[#sctn-related-origins|related origin requests]]
or the [$related origins validation procedure$] failed.

: {{NotAllowedError}}
:: A catch-all error covering a wide range of possible reasons,
including common ones like the user canceling out of the ceremony.
Some of these causes are documented throughout this spec,
while others are client-specific.
</dl>

The following [=simple exceptions=] can be raised:

<dl>

: {{TypeError}}
:: The <code>|options|</code> argument was not a valid <code>[[#sctn-credentialrequestoptions-extension|CredentialRequestOptions]]</code> value.

</dl>

### Store an Existing Credential - PublicKeyCredential's `[[Store]](credential, sameOriginWithAncestors)` Method ### {#sctn-storeCredential}

0 comments on commit 056ed8b

Please sign in to comment.