Skip to content

Commit

Permalink
Add JavaDoc for hints and PublicKeyCredentialHint
Browse files Browse the repository at this point in the history
  • Loading branch information
@emlun
emlun committed Sep 13, 2024
1 parent d220ef2 commit 7694886
Show file tree
Hide file tree
Showing 5 changed files with 619 additions and 15 deletions.
135 changes: 135 additions & 0 deletions webauthn-server-core/src/main/java/com/yubico/webauthn/StartAssertionOptions.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,7 @@

import com.yubico.webauthn.data.AssertionExtensionInputs;
import com.yubico.webauthn.data.ByteArray;
import com.yubico.webauthn.data.PublicKeyCredentialDescriptor;
import com.yubico.webauthn.data.PublicKeyCredentialHint;
import com.yubico.webauthn.data.PublicKeyCredentialRequestOptions;
import com.yubico.webauthn.data.UserVerificationRequirement;
Expand Down Expand Up @@ -83,6 +84,38 @@ public class StartAssertionOptions {
*/
private final Long timeout;

/**
* Zero or more hints, in descending order of preference, to guide the user agent in interacting
* with the user during this authentication operation.
*
* <p>For example, the {@link PublicKeyCredentialHint#SECURITY_KEY} hint may be used to ask the
* client to emphasize the option of authenticating with an external security key, or the {@link
* PublicKeyCredentialHint#CLIENT_DEVICE} hint may be used to ask the client to emphasize the
* option of authenticating a built-in passkey provider.
*
* <p>These hints are not requirements, and do not bind the user-agent, but may guide it in
* providing the best experience by using contextual information about the request.
*
* <p>Hints MAY contradict information contained in {@link
* PublicKeyCredentialDescriptor#getTransports()}. When this occurs, the hints take precedence.
*
* <p>This library does not take these hints into account in any way, other than passing them
* through to the {@link PublicKeyCredentialRequestOptions} so they can be used in the argument to
* <code>navigator.credentials.get()</code> on the client side.
*
* <p>The default is empty.
*
* @see PublicKeyCredentialHint
* @see PublicKeyCredentialRequestOptions#getHints()
* @see StartAssertionOptionsBuilder#hints(List)
* @see StartAssertionOptionsBuilder#hints(String...)
* @see StartAssertionOptionsBuilder#hints(PublicKeyCredentialHint...)
* @see <a
* href="https://www.w3.org/TR/2023/WD-webauthn-3-20230927/#dom-publickeycredentialrequestoptions-hints">PublicKeyCredentialRequestOptions.hints</a>
* @see <a
* href="https://www.w3.org/TR/2023/WD-webauthn-3-20230927/#enumdef-publickeycredentialhints">§5.8.7.
* User-agent Hints Enumeration (enum PublicKeyCredentialHints)</a>
*/
private final List<String> hints;

private StartAssertionOptions(
Expand Down Expand Up @@ -392,16 +425,118 @@ private StartAssertionOptionsBuilder timeout(Long timeout) {
return this.timeout(Optional.ofNullable(timeout));
}

/**
* Zero or more hints, in descending order of preference, to guide the user agent in interacting
* with the user during this authentication operation.
*
* <p>Setting this property multiple times overwrites any value set previously.
*
* <p>For example, the {@link PublicKeyCredentialHint#SECURITY_KEY} hint may be used to ask the
* client to emphasize the option of authenticating with an external security key, or the {@link
* PublicKeyCredentialHint#CLIENT_DEVICE} hint may be used to ask the client to emphasize the
* option of authenticating a built-in passkey provider.
*
* <p>These hints are not requirements, and do not bind the user-agent, but may guide it in
* providing the best experience by using contextual information about the request.
*
* <p>Hints MAY contradict information contained in {@link
* PublicKeyCredentialDescriptor#getTransports()}. When this occurs, the hints take precedence.
*
* <p>This library does not take these hints into account in any way, other than passing them
* through to the {@link PublicKeyCredentialRequestOptions} so they can be used in the argument
* to <code>navigator.credentials.get()</code> on the client side.
*
* <p>The default is empty.
*
* @see PublicKeyCredentialHint
* @see PublicKeyCredentialRequestOptions#getHints()
* @see StartAssertionOptions#getHints()
* @see StartAssertionOptionsBuilder#hints(List)
* @see StartAssertionOptionsBuilder#hints(PublicKeyCredentialHint...)
* @see <a
* href="https://www.w3.org/TR/2023/WD-webauthn-3-20230927/#dom-publickeycredentialrequestoptions-hints">PublicKeyCredentialRequestOptions.hints</a>
* @see <a
* href="https://www.w3.org/TR/2023/WD-webauthn-3-20230927/#enumdef-publickeycredentialhints">§5.8.7.
* User-agent Hints Enumeration (enum PublicKeyCredentialHints)</a>
*/
public StartAssertionOptionsBuilder hints(@NonNull String... hints) {
this.hints = Arrays.asList(hints);
return this;
}

/**
* Zero or more hints, in descending order of preference, to guide the user agent in interacting
* with the user during this authentication operation.
*
* <p>Setting this property multiple times overwrites any value set previously.
*
* <p>For example, the {@link PublicKeyCredentialHint#SECURITY_KEY} hint may be used to ask the
* client to emphasize the option of authenticating with an external security key, or the {@link
* PublicKeyCredentialHint#CLIENT_DEVICE} hint may be used to ask the client to emphasize the
* option of authenticating a built-in passkey provider.
*
* <p>These hints are not requirements, and do not bind the user-agent, but may guide it in
* providing the best experience by using contextual information about the request.
*
* <p>Hints MAY contradict information contained in {@link
* PublicKeyCredentialDescriptor#getTransports()}. When this occurs, the hints take precedence.
*
* <p>This library does not take these hints into account in any way, other than passing them
* through to the {@link PublicKeyCredentialRequestOptions} so they can be used in the argument
* to <code>navigator.credentials.get()</code> on the client side.
*
* <p>The default is empty.
*
* @see PublicKeyCredentialHint
* @see PublicKeyCredentialRequestOptions#getHints()
* @see StartAssertionOptions#getHints()
* @see StartAssertionOptionsBuilder#hints(List)
* @see StartAssertionOptionsBuilder#hints(String...)
* @see <a
* href="https://www.w3.org/TR/2023/WD-webauthn-3-20230927/#dom-publickeycredentialrequestoptions-hints">PublicKeyCredentialRequestOptions.hints</a>
* @see <a
* href="https://www.w3.org/TR/2023/WD-webauthn-3-20230927/#enumdef-publickeycredentialhints">§5.8.7.
* User-agent Hints Enumeration (enum PublicKeyCredentialHints)</a>
*/
public StartAssertionOptionsBuilder hints(@NonNull PublicKeyCredentialHint... hints) {
return this.hints(
Arrays.stream(hints).map(PublicKeyCredentialHint::getValue).toArray(String[]::new));
}

/**
* Zero or more hints, in descending order of preference, to guide the user agent in interacting
* with the user during this authentication operation.
*
* <p>Setting this property multiple times overwrites any value set previously.
*
* <p>For example, the {@link PublicKeyCredentialHint#SECURITY_KEY} hint may be used to ask the
* client to emphasize the option of authenticating with an external security key, or the {@link
* PublicKeyCredentialHint#CLIENT_DEVICE} hint may be used to ask the client to emphasize the
* option of authenticating a built-in passkey provider.
*
* <p>These hints are not requirements, and do not bind the user-agent, but may guide it in
* providing the best experience by using contextual information about the request.
*
* <p>Hints MAY contradict information contained in {@link
* PublicKeyCredentialDescriptor#getTransports()}. When this occurs, the hints take precedence.
*
* <p>This library does not take these hints into account in any way, other than passing them
* through to the {@link PublicKeyCredentialRequestOptions} so they can be used in the argument
* to <code>navigator.credentials.get()</code> on the client side.
*
* <p>The default is empty.
*
* @see PublicKeyCredentialHint
* @see PublicKeyCredentialRequestOptions#getHints()
* @see StartAssertionOptions#getHints()
* @see StartAssertionOptionsBuilder#hints(String...)
* @see StartAssertionOptionsBuilder#hints(PublicKeyCredentialHint...)
* @see <a
* href="https://www.w3.org/TR/2023/WD-webauthn-3-20230927/#dom-publickeycredentialrequestoptions-hints">PublicKeyCredentialRequestOptions.hints</a>
* @see <a
* href="https://www.w3.org/TR/2023/WD-webauthn-3-20230927/#enumdef-publickeycredentialhints">§5.8.7.
* User-agent Hints Enumeration (enum PublicKeyCredentialHints)</a>
*/
public StartAssertionOptionsBuilder hints(@NonNull List<String> hints) {
this.hints = hints;
return this;
Expand Down
130 changes: 130 additions & 0 deletions webauthn-server-core/src/main/java/com/yubico/webauthn/StartRegistrationOptions.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -68,6 +68,37 @@ public class StartRegistrationOptions {
*/
private final Long timeout;

/**
* Zero or more hints, in descending order of preference, to guide the user agent in interacting
* with the user during this registration operation.
*
* <p>For example, the {@link PublicKeyCredentialHint#SECURITY_KEY} hint may be used to ask the
* client to emphasize the option of registering with an external security key, or the {@link
* PublicKeyCredentialHint#CLIENT_DEVICE} hint may be used to ask the client to emphasize the
* option of registering a built-in passkey provider.
*
* <p>These hints are not requirements, and do not bind the user-agent, but may guide it in
* providing the best experience by using contextual information about the request.
*
* <p>Hints MAY contradict preferences in {@link #getAuthenticatorSelection()}. When this occurs,
* the hints take precedence.
*
* <p>This library does not take these hints into account in any way, other than passing them
* through to the {@link PublicKeyCredentialCreationOptions} so they can be used in the argument
* to <code>navigator.credentials.create()</code> on the client side.
*
* <p>The default is empty.
*
* @see PublicKeyCredentialHint
* @see StartRegistrationOptionsBuilder#hints(List)
* @see StartRegistrationOptionsBuilder#hints(String...)
* @see StartRegistrationOptionsBuilder#hints(PublicKeyCredentialHint...)
* @see <a
* href="https://www.w3.org/TR/2023/WD-webauthn-3-20230927/#dom-publickeycredentialcreationoptions-hints">PublicKeyCredentialCreationOptions.hints</a>
* @see <a
* href="https://www.w3.org/TR/2023/WD-webauthn-3-20230927/#enumdef-publickeycredentialhints">§5.8.7.
* User-agent Hints Enumeration (enum PublicKeyCredentialHints)</a>
*/
private final List<String> hints;

private StartRegistrationOptions(
Expand Down Expand Up @@ -177,16 +208,115 @@ public StartRegistrationOptionsBuilder timeout(long timeout) {
return this.timeout(Optional.of(timeout));
}

/**
* Zero or more hints, in descending order of preference, to guide the user agent in interacting
* with the user during this registration operation.
*
* <p>Setting this property multiple times overwrites any value set previously.
*
* <p>For example, the {@link PublicKeyCredentialHint#SECURITY_KEY} hint may be used to ask the
* client to emphasize the option of registering with an external security key, or the {@link
* PublicKeyCredentialHint#CLIENT_DEVICE} hint may be used to ask the client to emphasize the
* option of registering a built-in passkey provider.
*
* <p>These hints are not requirements, and do not bind the user-agent, but may guide it in
* providing the best experience by using contextual information about the request.
*
* <p>Hints MAY contradict preferences in {@link #getAuthenticatorSelection()}. When this
* occurs, the hints take precedence.
*
* <p>This library does not take these hints into account in any way, other than passing them
* through to the {@link PublicKeyCredentialCreationOptions} so they can be used in the argument
* to <code>navigator.credentials.create()</code> on the client side.
*
* <p>The default is empty.
*
* @see PublicKeyCredentialHint
* @see StartRegistrationOptions#getHints()
* @see StartRegistrationOptionsBuilder#hints(List)
* @see StartRegistrationOptionsBuilder#hints(PublicKeyCredentialHint...)
* @see <a
* href="https://www.w3.org/TR/2023/WD-webauthn-3-20230927/#dom-publickeycredentialcreationoptions-hints">PublicKeyCredentialCreationOptions.hints</a>
* @see <a
* href="https://www.w3.org/TR/2023/WD-webauthn-3-20230927/#enumdef-publickeycredentialhints">§5.8.7.
* User-agent Hints Enumeration (enum PublicKeyCredentialHints)</a>
*/
public StartRegistrationOptionsBuilder hints(@NonNull String... hints) {
this.hints = Arrays.asList(hints);
return this;
}

/**
* Zero or more hints, in descending order of preference, to guide the user agent in interacting
* with the user during this registration operation.
*
* <p>Setting this property multiple times overwrites any value set previously.
*
* <p>For example, the {@link PublicKeyCredentialHint#SECURITY_KEY} hint may be used to ask the
* client to emphasize the option of registering with an external security key, or the {@link
* PublicKeyCredentialHint#CLIENT_DEVICE} hint may be used to ask the client to emphasize the
* option of registering a built-in passkey provider.
*
* <p>These hints are not requirements, and do not bind the user-agent, but may guide it in
* providing the best experience by using contextual information about the request.
*
* <p>Hints MAY contradict preferences in {@link #getAuthenticatorSelection()}. When this
* occurs, the hints take precedence.
*
* <p>This library does not take these hints into account in any way, other than passing them
* through to the {@link PublicKeyCredentialCreationOptions} so they can be used in the argument
* to <code>navigator.credentials.create()</code> on the client side.
*
* <p>The default is empty.
*
* @see PublicKeyCredentialHint
* @see StartRegistrationOptions#getHints()
* @see StartRegistrationOptionsBuilder#hints(List)
* @see StartRegistrationOptionsBuilder#hints(String...)
* @see <a
* href="https://www.w3.org/TR/2023/WD-webauthn-3-20230927/#dom-publickeycredentialcreationoptions-hints">PublicKeyCredentialCreationOptions.hints</a>
* @see <a
* href="https://www.w3.org/TR/2023/WD-webauthn-3-20230927/#enumdef-publickeycredentialhints">§5.8.7.
* User-agent Hints Enumeration (enum PublicKeyCredentialHints)</a>
*/
public StartRegistrationOptionsBuilder hints(@NonNull PublicKeyCredentialHint... hints) {
return this.hints(
Arrays.stream(hints).map(PublicKeyCredentialHint::getValue).toArray(String[]::new));
}

/**
* Zero or more hints, in descending order of preference, to guide the user agent in interacting
* with the user during this registration operation.
*
* <p>Setting this property multiple times overwrites any value set previously.
*
* <p>For example, the {@link PublicKeyCredentialHint#SECURITY_KEY} hint may be used to ask the
* client to emphasize the option of registering with an external security key, or the {@link
* PublicKeyCredentialHint#CLIENT_DEVICE} hint may be used to ask the client to emphasize the
* option of registering a built-in passkey provider.
*
* <p>These hints are not requirements, and do not bind the user-agent, but may guide it in
* providing the best experience by using contextual information about the request.
*
* <p>Hints MAY contradict preferences in {@link #getAuthenticatorSelection()}. When this
* occurs, the hints take precedence.
*
* <p>This library does not take these hints into account in any way, other than passing them
* through to the {@link PublicKeyCredentialCreationOptions} so they can be used in the argument
* to <code>navigator.credentials.create()</code> on the client side.
*
* <p>The default is empty.
*
* @see PublicKeyCredentialHint
* @see StartRegistrationOptions#getHints()
* @see StartRegistrationOptionsBuilder#hints(String...)
* @see StartRegistrationOptionsBuilder#hints(PublicKeyCredentialHint...)
* @see <a
* href="https://www.w3.org/TR/2023/WD-webauthn-3-20230927/#dom-publickeycredentialcreationoptions-hints">PublicKeyCredentialCreationOptions.hints</a>
* @see <a
* href="https://www.w3.org/TR/2023/WD-webauthn-3-20230927/#enumdef-publickeycredentialhints">§5.8.7.
* User-agent Hints Enumeration (enum PublicKeyCredentialHints)</a>
*/
public StartRegistrationOptionsBuilder hints(@NonNull List<String> hints) {
this.hints = hints;
return this;
Expand Down
Loading

0 comments on commit 7694886

Please sign in to comment.