Clarify some parameter javadocs

Author: emlun

NEWS

@@ -64,6 +64,10 @@ Fixes:
   base64url encoded.
 * Javadoc for `TokenBindingStatus.PRESENT` incorrectly referenced its own
   (private) `id` member instead of `TokenBindingInfo.id`.
+* Improved JavaDoc for `StartRegistrationOptions.authenticatorSelection`
+* Improved JavaDoc for `RelyingParty.appid`
+* Make the `RelyingParty.validateSignatureCounter` JavaDoc also cover the
+  success case where stored and received signature count are both zero.
 
 
 == Version 1.10.1 ==

webauthn-server-core/src/main/java/com/yubico/webauthn/RelyingParty.java

@@ -143,6 +143,14 @@ public class RelyingParty {
    * The extension input to set for the <code>appid</code> extension when initiating authentication
    * operations.
    *
+   * <p>You do not need this extension if you have not previously supported U2F. Its purpose is to
+   * make already-registered U2F credentials forward-compatible with the WebAuthn API. It is not
+   * needed for new registrations, even of U2F authenticators.
+   *
+   * <p>You do not need this extension if you have not previously supported U2F. Its purpose is to
+   * make already-registered U2F credentials forward-compatible with the WebAuthn API. It is not
+   * needed for new registrations, even of U2F authenticators.
+   *
    * <p>If this member is set, {@link #startAssertion(StartAssertionOptions) startAssertion} will
    * automatically set the <code>appid</code> extension input, and {@link
    * #finishAssertion(FinishAssertionOptions) finishAssertion} will adjust its verification logic to
@@ -327,9 +335,9 @@ public class RelyingParty {
 
   /**
    * If <code>true</code>, {@link #finishAssertion(FinishAssertionOptions) finishAssertion} will
-   * fail if the {@link AuthenticatorData#getSignatureCounter() signature counter value} in the
-   * response is not strictly greater than the {@link RegisteredCredential#getSignatureCount()
-   * stored signature counter value}.
+   * succeed only if the {@link AuthenticatorData#getSignatureCounter() signature counter value} in
+   * the response is strictly greater than the {@link RegisteredCredential#getSignatureCount()
+   * stored signature counter value}, or if both counters are exactly zero.
    *
    * <p>The default is <code>true</code>.
    */
@@ -558,6 +566,14 @@ public RelyingPartyBuilder credentialRepository(CredentialRepository credentialR
      * The extension input to set for the <code>appid</code> extension when initiating
      * authentication operations.
      *
+     * <p>You do not need this extension if you have not previously supported U2F. Its purpose is to
+     * make already-registered U2F credentials forward-compatible with the WebAuthn API. It is not
+     * needed for new registrations, even of U2F authenticators.
+     *
+     * <p>You do not need this extension if you have not previously supported U2F. Its purpose is to
+     * make already-registered U2F credentials forward-compatible with the WebAuthn API. It is not
+     * needed for new registrations, even of U2F authenticators.
+     *
      * <p>If this member is set, {@link #startAssertion(StartAssertionOptions) startAssertion} will
      * automatically set the <code>appid</code> extension input, and {@link
      * #finishAssertion(FinishAssertionOptions) finishAssertion} will adjust its verification logic
@@ -579,6 +595,14 @@ public RelyingPartyBuilder appId(@NonNull Optional<AppId> appId) {
      * The extension input to set for the <code>appid</code> extension when initiating
      * authentication operations.
      *
+     * <p>You do not need this extension if you have not previously supported U2F. Its purpose is to
+     * make already-registered U2F credentials forward-compatible with the WebAuthn API. It is not
+     * needed for new registrations, even of U2F authenticators.
+     *
+     * <p>You do not need this extension if you have not previously supported U2F. Its purpose is to
+     * make already-registered U2F credentials forward-compatible with the WebAuthn API. It is not
+     * needed for new registrations, even of U2F authenticators.
+     *
      * <p>If this member is set, {@link #startAssertion(StartAssertionOptions) startAssertion} will
      * automatically set the <code>appid</code> extension input, and {@link
      * #finishAssertion(FinishAssertionOptions) finishAssertion} will adjust its verification logic

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

@@ -42,7 +42,8 @@ public class StartRegistrationOptions {
   @NonNull private final UserIdentity user;
 
   /**
-   * Constraints on what kind of authenticator the user is allowed to use to create the credential.
+   * Constraints on what kind of authenticator the user is allowed to use to create the credential,
+   * and on features that authenticator must or should support.
    */
   private final AuthenticatorSelectionCriteria authenticatorSelection;
 
@@ -64,7 +65,8 @@ public class StartRegistrationOptions {
   private final Long timeout;
 
   /**
-   * Constraints on what kind of authenticator the user is allowed to use to create the credential.
+   * Constraints on what kind of authenticator the user is allowed to use to create the credential,
+   * and on features that authenticator must or should support.
    */
   public Optional<AuthenticatorSelectionCriteria> getAuthenticatorSelection() {
     return Optional.ofNullable(authenticatorSelection);
@@ -107,7 +109,7 @@ public StartRegistrationOptionsBuilder user(UserIdentity user) {
 
     /**
      * Constraints on what kind of authenticator the user is allowed to use to create the
-     * credential.
+     * credential, and on features that authenticator must or should support.
      */
     public StartRegistrationOptionsBuilder authenticatorSelection(
         @NonNull Optional<AuthenticatorSelectionCriteria> authenticatorSelection) {
@@ -116,7 +118,7 @@ public StartRegistrationOptionsBuilder authenticatorSelection(
 
     /**
      * Constraints on what kind of authenticator the user is allowed to use to create the
-     * credential.
+     * credential, and on features that authenticator must or should support.
      */
     public StartRegistrationOptionsBuilder authenticatorSelection(
         AuthenticatorSelectionCriteria authenticatorSelection) {