Skip to content

Commit 7694886

Browse files
emlunemlun
committed
Add JavaDoc for hints and PublicKeyCredentialHint
1 parent d220ef2 commit 7694886

File tree

5 files changed

+619
-15
lines changed

5 files changed

+619
-15
lines changed

‎webauthn-server-core/src/main/java/com/yubico/webauthn/StartAssertionOptions.java

Lines changed: 135 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,7 @@
2626

2727
import com.yubico.webauthn.data.AssertionExtensionInputs;
2828
import com.yubico.webauthn.data.ByteArray;
29+
import com.yubico.webauthn.data.PublicKeyCredentialDescriptor;
2930
import com.yubico.webauthn.data.PublicKeyCredentialHint;
3031
import com.yubico.webauthn.data.PublicKeyCredentialRequestOptions;
3132
import com.yubico.webauthn.data.UserVerificationRequirement;
@@ -83,6 +84,38 @@ public class StartAssertionOptions {
8384
*/
8485
private final Long timeout;
8586

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

88121
private StartAssertionOptions(
@@ -392,16 +425,118 @@ private StartAssertionOptionsBuilder timeout(Long timeout) {
392425
return this.timeout(Optional.ofNullable(timeout));
393426
}
394427

428+
/**
429+
* Zero or more hints, in descending order of preference, to guide the user agent in interacting
430+
* with the user during this authentication operation.
431+
*
432+
* <p>Setting this property multiple times overwrites any value set previously.
433+
*
434+
* <p>For example, the {@link PublicKeyCredentialHint#SECURITY_KEY} hint may be used to ask the
435+
* client to emphasize the option of authenticating with an external security key, or the {@link
436+
* PublicKeyCredentialHint#CLIENT_DEVICE} hint may be used to ask the client to emphasize the
437+
* option of authenticating a built-in passkey provider.
438+
*
439+
* <p>These hints are not requirements, and do not bind the user-agent, but may guide it in
440+
* providing the best experience by using contextual information about the request.
441+
*
442+
* <p>Hints MAY contradict information contained in {@link
443+
* PublicKeyCredentialDescriptor#getTransports()}. When this occurs, the hints take precedence.
444+
*
445+
* <p>This library does not take these hints into account in any way, other than passing them
446+
* through to the {@link PublicKeyCredentialRequestOptions} so they can be used in the argument
447+
* to <code>navigator.credentials.get()</code> on the client side.
448+
*
449+
* <p>The default is empty.
450+
*
451+
* @see PublicKeyCredentialHint
452+
* @see PublicKeyCredentialRequestOptions#getHints()
453+
* @see StartAssertionOptions#getHints()
454+
* @see StartAssertionOptionsBuilder#hints(List)
455+
* @see StartAssertionOptionsBuilder#hints(PublicKeyCredentialHint...)
456+
* @see <a
457+
* href="https://www.w3.org/TR/2023/WD-webauthn-3-20230927/#dom-publickeycredentialrequestoptions-hints">PublicKeyCredentialRequestOptions.hints</a>
458+
* @see <a
459+
* href="https://www.w3.org/TR/2023/WD-webauthn-3-20230927/#enumdef-publickeycredentialhints">§5.8.7.
460+
* User-agent Hints Enumeration (enum PublicKeyCredentialHints)</a>
461+
*/
395462
public StartAssertionOptionsBuilder hints(@NonNull String... hints) {
396463
this.hints = Arrays.asList(hints);
397464
return this;
398465
}
399466

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

506+
/**
507+
* Zero or more hints, in descending order of preference, to guide the user agent in interacting
508+
* with the user during this authentication operation.
509+
*
510+
* <p>Setting this property multiple times overwrites any value set previously.
511+
*
512+
* <p>For example, the {@link PublicKeyCredentialHint#SECURITY_KEY} hint may be used to ask the
513+
* client to emphasize the option of authenticating with an external security key, or the {@link
514+
* PublicKeyCredentialHint#CLIENT_DEVICE} hint may be used to ask the client to emphasize the
515+
* option of authenticating a built-in passkey provider.
516+
*
517+
* <p>These hints are not requirements, and do not bind the user-agent, but may guide it in
518+
* providing the best experience by using contextual information about the request.
519+
*
520+
* <p>Hints MAY contradict information contained in {@link
521+
* PublicKeyCredentialDescriptor#getTransports()}. When this occurs, the hints take precedence.
522+
*
523+
* <p>This library does not take these hints into account in any way, other than passing them
524+
* through to the {@link PublicKeyCredentialRequestOptions} so they can be used in the argument
525+
* to <code>navigator.credentials.get()</code> on the client side.
526+
*
527+
* <p>The default is empty.
528+
*
529+
* @see PublicKeyCredentialHint
530+
* @see PublicKeyCredentialRequestOptions#getHints()
531+
* @see StartAssertionOptions#getHints()
532+
* @see StartAssertionOptionsBuilder#hints(String...)
533+
* @see StartAssertionOptionsBuilder#hints(PublicKeyCredentialHint...)
534+
* @see <a
535+
* href="https://www.w3.org/TR/2023/WD-webauthn-3-20230927/#dom-publickeycredentialrequestoptions-hints">PublicKeyCredentialRequestOptions.hints</a>
536+
* @see <a
537+
* href="https://www.w3.org/TR/2023/WD-webauthn-3-20230927/#enumdef-publickeycredentialhints">§5.8.7.
538+
* User-agent Hints Enumeration (enum PublicKeyCredentialHints)</a>
539+
*/
405540
public StartAssertionOptionsBuilder hints(@NonNull List<String> hints) {
406541
this.hints = hints;
407542
return this;

‎webauthn-server-core/src/main/java/com/yubico/webauthn/StartRegistrationOptions.java

Lines changed: 130 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -68,6 +68,37 @@ public class StartRegistrationOptions {
6868
*/
6969
private final Long timeout;
7070

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

73104
private StartRegistrationOptions(
@@ -177,16 +208,115 @@ public StartRegistrationOptionsBuilder timeout(long timeout) {
177208
return this.timeout(Optional.of(timeout));
178209
}
179210

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

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

287+
/**
288+
* Zero or more hints, in descending order of preference, to guide the user agent in interacting
289+
* with the user during this registration operation.
290+
*
291+
* <p>Setting this property multiple times overwrites any value set previously.
292+
*
293+
* <p>For example, the {@link PublicKeyCredentialHint#SECURITY_KEY} hint may be used to ask the
294+
* client to emphasize the option of registering with an external security key, or the {@link
295+
* PublicKeyCredentialHint#CLIENT_DEVICE} hint may be used to ask the client to emphasize the
296+
* option of registering a built-in passkey provider.
297+
*
298+
* <p>These hints are not requirements, and do not bind the user-agent, but may guide it in
299+
* providing the best experience by using contextual information about the request.
300+
*
301+
* <p>Hints MAY contradict preferences in {@link #getAuthenticatorSelection()}. When this
302+
* occurs, the hints take precedence.
303+
*
304+
* <p>This library does not take these hints into account in any way, other than passing them
305+
* through to the {@link PublicKeyCredentialCreationOptions} so they can be used in the argument
306+
* to <code>navigator.credentials.create()</code> on the client side.
307+
*
308+
* <p>The default is empty.
309+
*
310+
* @see PublicKeyCredentialHint
311+
* @see StartRegistrationOptions#getHints()
312+
* @see StartRegistrationOptionsBuilder#hints(String...)
313+
* @see StartRegistrationOptionsBuilder#hints(PublicKeyCredentialHint...)
314+
* @see <a
315+
* href="https://www.w3.org/TR/2023/WD-webauthn-3-20230927/#dom-publickeycredentialcreationoptions-hints">PublicKeyCredentialCreationOptions.hints</a>
316+
* @see <a
317+
* href="https://www.w3.org/TR/2023/WD-webauthn-3-20230927/#enumdef-publickeycredentialhints">§5.8.7.
318+
* User-agent Hints Enumeration (enum PublicKeyCredentialHints)</a>
319+
*/
190320
public StartRegistrationOptionsBuilder hints(@NonNull List<String> hints) {
191321
this.hints = hints;
192322
return this;

0 commit comments

Comments
 (0)