Add @since tags to AttestationTrustSource and FidoMetadataService javadoc

Author: emlun

NEWS

@@ -1,11 +1,21 @@
 == Version 2.9.0 (unreleased) ==
 
+`webauthn-server-core`:
+
+Fixes:
+
+* Added `@since` tags to `AttestationTrustSource` javadoc.
+
 `webauthn-server-attestation`:
 
 New features:
 
 * Added `AuthenticatorStatus.RETIRED` and `Filters.notRetired()`.
 
+Fixes:
+
+* Added `@since` tags to `FidoMetadataService` javadoc.
+
 
 == Version 2.8.1 ==
 

webauthn-server-attestation/src/main/java/com/yubico/fido/metadata/FidoMetadataService.java

@@ -87,6 +87,8 @@
  *
  * <p>Use the {@link #builder() builder} to configure settings, then use the {@link
  * #findEntries(List, AAGUID)} method or its overloads to retrieve metadata entries.
+ *
+ * @since 2.0.0
  */
 @Slf4j
 public final class FidoMetadataService implements AttestationTrustSource {
@@ -234,6 +236,7 @@ public static class Step1 {
        *
        * <p>This is an alias of <code>useBlob(blob.getPayload()</code>.
        *
+       * @since 2.0.0
        * @see FidoMetadataDownloader#loadCachedBlob()
        * @see #useBlob(MetadataBLOBPayload)
        */
@@ -247,6 +250,7 @@ public FidoMetadataServiceBuilder useBlob(@NonNull MetadataBLOB blob) {
        * <p>The {@link FidoMetadataDownloader#loadCachedBlob()} method returns a value whose {@link
        * MetadataBLOB#getPayload() .getPayload()} result is suitable for use here.
        *
+       * @since 2.0.0
        * @see FidoMetadataDownloader#loadCachedBlob()
        * @see #useBlob(MetadataBLOB)
        */
@@ -268,6 +272,7 @@ public FidoMetadataServiceBuilder useBlob(@NonNull MetadataBLOBPayload blobPaylo
      * Filters#notRetired() Filters.notRetired()} filter, use: <code>
      * .prefilter(Filters.allOf(Filters.notRevoked(), Filters.notRetired()))</code>.
      *
+     * @since 2.0.0
      * @param prefilter a {@link Predicate} which returns <code>true</code> for metadata entries to
      *     include in the data source.
      * @see #filter(Predicate)
@@ -302,6 +307,7 @@ public FidoMetadataServiceBuilder prefilter(
      * @param filter a {@link Predicate} which returns <code>true</code> for metadata entries to
      *     allow for the corresponding authenticator during credential registration and metadata
      *     lookup.
+     * @since 2.0.0
      * @see #prefilter(Predicate)
      * @see AuthenticatorToBeFiltered
      * @see Filters#allOf(Predicate[])
@@ -320,6 +326,7 @@ public FidoMetadataServiceBuilder filter(
      *
      * @param certStore a {@link CertStore} of additional CRLs and/or intermediate certificates to
      *     use while validating attestation certificate paths.
+     * @since 2.0.0
      */
     public FidoMetadataServiceBuilder certStore(@NonNull CertStore certStore) {
       this.certStore = certStore;
@@ -347,6 +354,7 @@ public FidoMetadataService build()
    * FidoMetadataServiceBuilder#prefilter(Predicate) prefilter} and {@link
    * FidoMetadataServiceBuilder#filter(Predicate) filter} settings.
    *
+   * @since 2.0.0
    * @see FidoMetadataServiceBuilder#prefilter(Predicate)
    * @see FidoMetadataServiceBuilder#filter(Predicate)
    */
@@ -360,6 +368,7 @@ public static class Filters {
      * @param filters A set of filters.
      * @return A filter which only accepts inputs that satisfy ALL of the given <code>
      *     filters</code>.
+     * @since 2.0.0
      */
     @SafeVarargs
     public static <T> Predicate<T> allOf(Predicate<T>... filters) {
@@ -371,6 +380,7 @@ public static <T> Predicate<T> allOf(Predicate<T>... filters) {
      * statusReports} array contains no entry with {@link AuthenticatorStatus#REVOKED REVOKED}
      * status.
      *
+     * @since 2.0.0
      * @see AuthenticatorStatus#REVOKED
      */
     public static Predicate<MetadataBLOBPayloadEntry> notRevoked() {
@@ -407,6 +417,7 @@ public static Predicate<MetadataBLOBPayloadEntry> notRetired() {
      * {@link AuthenticatorToBeFiltered#getAttestationCertificateChain() attestation certificate
      * chain}.
      *
+     * @since 2.0.0
      * @see AuthenticatorStatus#ATTESTATION_KEY_COMPROMISE
      */
     public static Predicate<AuthenticatorToBeFiltered> noAttestationKeyCompromise() {
@@ -434,6 +445,8 @@ public static Predicate<AuthenticatorToBeFiltered> noAttestationKeyCompromise()
     /**
      * This class encapsulates parameters for filtering authenticators in the {@link
      * FidoMetadataServiceBuilder#filter(Predicate) filter} setting of {@link FidoMetadataService}.
+     *
+     * @since 2.0.0
      */
     @Value
     @AllArgsConstructor(access = AccessLevel.PRIVATE)
@@ -443,12 +456,16 @@ public static class AuthenticatorToBeFiltered {
        * The attestation certificate chain from the <a
        * href="https://www.w3.org/TR/2021/REC-webauthn-2-20210408/#attestation-statement">attestation
        * statement</a> from an authenticator about ot be registered.
+       *
+       * @since 2.0.0
        */
       @NonNull List<X509Certificate> attestationCertificateChain;
 
       /**
        * A metadata BLOB entry that matches the {@link #getAttestationCertificateChain()} and {@link
        * #getAaguid()} in this same {@link AuthenticatorToBeFiltered} object.
+       *
+       * @since 2.0.0
        */
       @NonNull MetadataBLOBPayloadEntry metadataEntry;
 
@@ -461,6 +478,8 @@ public static class AuthenticatorToBeFiltered {
        *
        * <p>This will not be present if the attested credential data contained an AAGUID of all
        * zeroes.
+       *
+       * @since 2.0.0
        */
       public Optional<AAGUID> getAaguid() {
         return Optional.ofNullable(aaguid);
@@ -508,6 +527,7 @@ public Optional<AAGUID> getAaguid() {
    *                             attestationCertificateChain</code>, if any.
    *     </ul>
    *
+   * @since 2.0.0
    * @see #findEntries(List)
    * @see #findEntries(List, AAGUID)
    */
@@ -583,6 +603,7 @@ public Set<MetadataBLOBPayloadEntry> findEntries(
   /**
    * Alias of <code>findEntries(attestationCertificateChain, Optional.empty())</code>.
    *
+   * @since 2.0.0
    * @see #findEntries(List, Optional)
    */
   public Set<MetadataBLOBPayloadEntry> findEntries(
@@ -593,6 +614,7 @@ public Set<MetadataBLOBPayloadEntry> findEntries(
   /**
    * Alias of <code>findEntries(attestationCertificateChain, Optional.of(aaguid))</code>.
    *
+   * @since 2.0.0
    * @see #findEntries(List, Optional)
    */
   public Set<MetadataBLOBPayloadEntry> findEntries(
@@ -611,6 +633,7 @@ public Set<MetadataBLOBPayloadEntry> findEntries(
    *   .orElseGet(Collections::emptySet)
    * </pre>
    *
+   * @since 2.0.0
    * @see #findEntries(List, Optional)
    */
   public Set<MetadataBLOBPayloadEntry> findEntries(@NonNull RegistrationResult registrationResult) {
@@ -623,6 +646,7 @@ public Set<MetadataBLOBPayloadEntry> findEntries(@NonNull RegistrationResult reg
   /**
    * Find metadata entries matching the given AAGUID.
    *
+   * @since 2.0.0
    * @see #findEntries(List, Optional)
    */
   public Set<MetadataBLOBPayloadEntry> findEntries(@NonNull AAGUID aaguid) {
@@ -640,6 +664,7 @@ public Set<MetadataBLOBPayloadEntry> findEntries(@NonNull AAGUID aaguid) {
    * @return All metadata entries which satisfy the {@link
    *     FidoMetadataServiceBuilder#prefilter(Predicate) prefilter} AND for which the <code>filter
    *     </code> returns <code>true</code>.
+   * @since 2.0.0
    * @see #findEntries(List, Optional)
    */
   public Set<MetadataBLOBPayloadEntry> findEntries(
@@ -654,6 +679,9 @@ public Set<MetadataBLOBPayloadEntry> findEntries(
         .collect(Collectors.toSet());
   }
 
+  /**
+   * @since 2.0.0
+   */
   @Override
   public TrustRootsResult findTrustRoots(
       List<X509Certificate> attestationCertificateChain, Optional<ByteArray> aaguid) {

webauthn-server-core/src/main/java/com/yubico/webauthn/attestation/AttestationTrustSource.java

@@ -57,6 +57,7 @@ public interface AttestationTrustSource {
    *     an empty result. Implementations MAY reuse the same result object, or parts of it, for
    *     multiple calls of this method, even with different arguments, but MUST return an empty set
    *     of trust roots for authenticators that should not be trusted.
+   * @since 2.0.0
    */
   TrustRootsResult findTrustRoots(
       List<X509Certificate> attestationCertificateChain, Optional<ByteArray> aaguid);
@@ -77,6 +78,8 @@ TrustRootsResult findTrustRoots(
    *   <li>define a policy tree validator for the PKIX policy tree result - see {@link
    *       TrustRootsResultBuilder#policyTreeValidator(Predicate) policyTreeValidator(Predicate)}.
    * </ul>
+   *
+   * @since 2.0.0
    */
   @Value
   @Builder(toBuilder = true)
@@ -86,6 +89,8 @@ class TrustRootsResult {
      * A set of attestation root certificates trusted to certify the relevant attestation statement.
      * If the attestation statement is not trusted, or if no trust roots were found, this should be
      * an empty set.
+     *
+     * @since 2.0.0
      */
     @NonNull private final Set<X509Certificate> trustRoots;
 
@@ -99,13 +104,17 @@ class TrustRootsResult {
      * trustRoots}.
      *
      * <p>The default is <code>null</code>.
+     *
+     * @since 2.0.0
      */
     @Builder.Default private final CertStore certStore = null;
 
     /**
      * Whether certificate revocation should be checked during certificate path validation.
      *
      * <p>The default is <code>true</code>.
+     *
+     * @since 2.0.0
      */
     @Builder.Default private final boolean enableRevocationChecking = true;
 
@@ -129,6 +138,8 @@ class TrustRootsResult {
      * Predicate}.
      *
      * <p>The default is <code>null</code>.
+     *
+     * @since 2.1.0
      */
     @Builder.Default private final Predicate<PolicyNode> policyTreeValidator = null;
 
@@ -153,6 +164,8 @@ private TrustRootsResult(
      * trustRoots}.
      *
      * <p>The default is <code>null</code>.
+     *
+     * @since 2.0.0
      */
     public Optional<CertStore> getCertStore() {
       return Optional.ofNullable(certStore);
@@ -178,6 +191,8 @@ public Optional<CertStore> getCertStore() {
      * Predicate}.
      *
      * <p>The default is <code>null</code>.
+     *
+     * @since 2.1.0
      */
     public Optional<Predicate<PolicyNode>> getPolicyTreeValidator() {
       return Optional.ofNullable(policyTreeValidator);
@@ -193,6 +208,8 @@ public static class Step1 {
          * A set of attestation root certificates trusted to certify the relevant attestation
          * statement. If the attestation statement is not trusted, or if no trust roots were found,
          * this should be an empty set.
+         *
+         * @since 2.0.0
          */
         public TrustRootsResultBuilder trustRoots(@NonNull Set<X509Certificate> trustRoots) {
           return new TrustRootsResultBuilder().trustRoots(trustRoots);
@@ -203,6 +220,8 @@ public TrustRootsResultBuilder trustRoots(@NonNull Set<X509Certificate> trustRoo
        * A set of attestation root certificates trusted to certify the relevant attestation
        * statement. If the attestation statement is not trusted, or if no trust roots were found,
        * this should be an empty set.
+       *
+       * @since 2.0.0
        */
       // TODO: Let this auto-generate (investigate why Lombok fails to copy javadoc)
       public AttestationTrustSource.TrustRootsResult.TrustRootsResultBuilder trustRoots(
@@ -224,6 +243,8 @@ public AttestationTrustSource.TrustRootsResult.TrustRootsResultBuilder trustRoot
        * TrustRootsResultBuilder#trustRoots(Set) trustRoots}.
        *
        * <p>The default is <code>null</code>.
+       *
+       * @since 2.0.0
        */
       // TODO: Let this auto-generate (investigate why Lombok fails to copy javadoc)
       public AttestationTrustSource.TrustRootsResult.TrustRootsResultBuilder certStore(
@@ -237,6 +258,8 @@ public AttestationTrustSource.TrustRootsResult.TrustRootsResultBuilder certStore
        * Whether certificate revocation should be checked during certificate path validation.
        *
        * <p>The default is <code>true</code>.
+       *
+       * @since 2.0.0
        */
       // TODO: Let this auto-generate (investigate why Lombok fails to copy javadoc)
       public AttestationTrustSource.TrustRootsResult.TrustRootsResultBuilder
@@ -267,6 +290,8 @@ public AttestationTrustSource.TrustRootsResult.TrustRootsResultBuilder certStore
        * Predicate}.
        *
        * <p>The default is <code>null</code>.
+       *
+       * @since 2.1.0
        */
       // TODO: Let this auto-generate (investigate why Lombok fails to copy javadoc)
       public AttestationTrustSource.TrustRootsResult.TrustRootsResultBuilder policyTreeValidator(
@@ -281,6 +306,8 @@ public AttestationTrustSource.TrustRootsResult.TrustRootsResultBuilder policyTre
      * A set of attestation root certificates trusted to certify the relevant attestation statement.
      * If the attestation statement is not trusted, or if no trust roots were found, this should be
      * an empty set.
+     *
+     * @since 2.0.0
      */
     // TODO: Let this auto-generate (investigate why Lombok fails to copy javadoc)
     @NonNull