Merge pull request #454 from Yubico/mds-3.1.1-retired

Add RETIRED status to AuthenticatorStatus

Author: fdennis

NEWS

@@ -1,3 +1,22 @@
+== 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 `AuthenticatorStatus` and `FidoMetadataService` javadoc.
+
+
 == Version 2.8.1 ==
 
 Fixes:

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

@@ -7,18 +7,24 @@
  * or attestationCertificateKeyIdentifiers and potentially some additional information (such as a
  * specific attestation key).
  *
+ * @since 2.0.0
  * @see <a
  *     href="https://fidoalliance.org/specs/mds/fido-metadata-service-v3.0-ps-20210518.html#enumdef-authenticatorstatus">FIDO
  *     Metadata Service §3.1.4. AuthenticatorStatus enum</a>
  */
 public enum AuthenticatorStatus {
-  /** (NOT DEFINED IN SPEC) Placeholder for any unknown {@link AuthenticatorStatus} value. */
+  /**
+   * (NOT DEFINED IN SPEC) Placeholder for any unknown {@link AuthenticatorStatus} value.
+   *
+   * @since 2.0.0
+   */
   @JsonEnumDefaultValue
   UNKNOWN(0),
 
   /**
    * This authenticator is not FIDO certified.
    *
+   * @since 2.0.0
    * @see <a
    *     href="https://fidoalliance.org/specs/mds/fido-metadata-service-v3.0-ps-20210518.html#enumdef-authenticatorstatus">FIDO
    *     Metadata Service §3.1.4. AuthenticatorStatus enum</a>
@@ -29,6 +35,7 @@ public enum AuthenticatorStatus {
    * This authenticator has passed FIDO functional certification. This certification scheme is
    * phased out and will be replaced by {@link #FIDO_CERTIFIED_L1}.
    *
+   * @since 2.0.0
    * @see <a
    *     href="https://fidoalliance.org/specs/mds/fido-metadata-service-v3.0-ps-20210518.html#enumdef-authenticatorstatus">FIDO
    *     Metadata Service §3.1.4. AuthenticatorStatus enum</a>
@@ -40,6 +47,7 @@ public enum AuthenticatorStatus {
    * authenticator could be used without the user’s consent and potentially even without the user’s
    * knowledge.
    *
+   * @since 2.0.0
    * @see <a
    *     href="https://fidoalliance.org/specs/mds/fido-metadata-service-v3.0-ps-20210518.html#enumdef-authenticatorstatus">FIDO
    *     Metadata Service §3.1.4. AuthenticatorStatus enum</a>
@@ -53,6 +61,7 @@ public enum AuthenticatorStatus {
    * new registrations of the compromised authenticator. The Authenticator manufacturer should set
    * the date to the date when compromise has occurred.
    *
+   * @since 2.0.0
    * @see <a
    *     href="https://fidoalliance.org/specs/mds/fido-metadata-service-v3.0-ps-20210518.html#enumdef-authenticatorstatus">FIDO
    *     Metadata Service §3.1.4. AuthenticatorStatus enum</a>
@@ -65,6 +74,7 @@ public enum AuthenticatorStatus {
    * to be generated or side channels that allow keys or signatures to be forged, guessed or
    * extracted.
    *
+   * @since 2.0.0
    * @see <a
    *     href="https://fidoalliance.org/specs/mds/fido-metadata-service-v3.0-ps-20210518.html#enumdef-authenticatorstatus">FIDO
    *     Metadata Service §3.1.4. AuthenticatorStatus enum</a>
@@ -75,6 +85,7 @@ public enum AuthenticatorStatus {
    * This authenticator has known weaknesses in its key protection mechanism(s) that allow user keys
    * to be extracted by an adversary in physical possession of the device.
    *
+   * @since 2.0.0
    * @see <a
    *     href="https://fidoalliance.org/specs/mds/fido-metadata-service-v3.0-ps-20210518.html#enumdef-authenticatorstatus">FIDO
    *     Metadata Service §3.1.4. AuthenticatorStatus enum</a>
@@ -93,17 +104,32 @@ public enum AuthenticatorStatus {
    * #USER_KEY_PHYSICAL_COMPROMISE}, {@link #REVOKED}. The Relying party MUST reject the Metadata
    * Statement if the authenticatorVersion has not increased
    *
+   * @since 2.0.0
    * @see <a
    *     href="https://fidoalliance.org/specs/mds/fido-metadata-service-v3.0-ps-20210518.html#enumdef-authenticatorstatus">FIDO
    *     Metadata Service §3.1.4. AuthenticatorStatus enum</a>
    */
   UPDATE_AVAILABLE(0),
 
+  /**
+   * The authenticator vendor has decided to retire the product, that this authenticator should not
+   * be accepted any longer. For example if a prototype version of the authenticator was added to
+   * FIDO MDS and has now been superseded by the final product, the entry for the prototype might be
+   * set to "retired".
+   *
+   * @since 2.9.0
+   * @see <a
+   *     href="https://fidoalliance.org/specs/mds/fido-metadata-service-v3.1.1-rd-20251016.html#enumdef-authenticatorstatus">FIDO
+   *     Metadata Service §3.1.4. AuthenticatorStatus enum</a>
+   */
+  RETIRED(0),
+
   /**
    * The FIDO Alliance has determined that this authenticator should not be trusted for any reason.
    * For example if it is known to be a fraudulent product or contain a deliberate backdoor. Relying
    * parties SHOULD reject any future registration of this authenticator model.
    *
+   * @since 2.0.0
    * @see <a
    *     href="https://fidoalliance.org/specs/mds/fido-metadata-service-v3.0-ps-20210518.html#enumdef-authenticatorstatus">FIDO
    *     Metadata Service §3.1.4. AuthenticatorStatus enum</a>
@@ -115,6 +141,7 @@ public enum AuthenticatorStatus {
    * FIDO Alliance. If this completed checklist is publicly available, the URL will be specified in
    * url.
    *
+   * @since 2.0.0
    * @see <a
    *     href="https://fidoalliance.org/specs/mds/fido-metadata-service-v3.0-ps-20210518.html#enumdef-authenticatorstatus">FIDO
    *     Metadata Service §3.1.4. AuthenticatorStatus enum</a>
@@ -125,6 +152,7 @@ public enum AuthenticatorStatus {
    * The authenticator has passed FIDO Authenticator certification at level 1. This level is the
    * more strict successor of {@link #FIDO_CERTIFIED}.
    *
+   * @since 2.0.0
    * @see <a
    *     href="https://fidoalliance.org/specs/mds/fido-metadata-service-v3.0-ps-20210518.html#enumdef-authenticatorstatus">FIDO
    *     Metadata Service §3.1.4. AuthenticatorStatus enum</a>
@@ -135,6 +163,7 @@ public enum AuthenticatorStatus {
    * The authenticator has passed FIDO Authenticator certification at level 1+. This level is the
    * more than level 1.
    *
+   * @since 2.0.0
    * @see <a
    *     href="https://fidoalliance.org/specs/mds/fido-metadata-service-v3.0-ps-20210518.html#enumdef-authenticatorstatus">FIDO
    *     Metadata Service §3.1.4. AuthenticatorStatus enum</a>
@@ -145,6 +174,7 @@ public enum AuthenticatorStatus {
    * The authenticator has passed FIDO Authenticator certification at level 2. This level is more
    * strict than level 1+.
    *
+   * @since 2.0.0
    * @see <a
    *     href="https://fidoalliance.org/specs/mds/fido-metadata-service-v3.0-ps-20210518.html#enumdef-authenticatorstatus">FIDO
    *     Metadata Service §3.1.4. AuthenticatorStatus enum</a>
@@ -155,6 +185,7 @@ public enum AuthenticatorStatus {
    * The authenticator has passed FIDO Authenticator certification at level 2+. This level is more
    * strict than level 2.
    *
+   * @since 2.0.0
    * @see <a
    *     href="https://fidoalliance.org/specs/mds/fido-metadata-service-v3.0-ps-20210518.html#enumdef-authenticatorstatus">FIDO
    *     Metadata Service §3.1.4. AuthenticatorStatus enum</a>
@@ -165,6 +196,7 @@ public enum AuthenticatorStatus {
    * The authenticator has passed FIDO Authenticator certification at level 3. This level is more
    * strict than level 2+.
    *
+   * @since 2.0.0
    * @see <a
    *     href="https://fidoalliance.org/specs/mds/fido-metadata-service-v3.0-ps-20210518.html#enumdef-authenticatorstatus">FIDO
    *     Metadata Service §3.1.4. AuthenticatorStatus enum</a>
@@ -175,6 +207,7 @@ public enum AuthenticatorStatus {
    * The authenticator has passed FIDO Authenticator certification at level 3+. This level is more
    * strict than level 3.
    *
+   * @since 2.0.0
    * @see <a
    *     href="https://fidoalliance.org/specs/mds/fido-metadata-service-v3.0-ps-20210518.html#enumdef-authenticatorstatus">FIDO
    *     Metadata Service §3.1.4. AuthenticatorStatus enum</a>

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)
        */
@@ -263,9 +267,12 @@ public FidoMetadataServiceBuilder useBlob(@NonNull MetadataBLOBPayload blobPaylo
      *
      * <p>The default is {@link Filters#notRevoked() Filters.notRevoked()}. Setting a different
      * filter overrides this default; to preserve the "not revoked" condition in addition to the new
-     * filter, you must explicitly include the condition in the few filter. For example, by using
-     * {@link Filters#allOf(Predicate[]) Filters.allOf(Predicate...)}.
+     * filter, you must explicitly include the condition in the new filter, for example by using
+     * {@link Filters#allOf(Predicate[]) Filters.allOf(Predicate...)}. To add the {@link
+     * 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)
@@ -300,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[])
@@ -318,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;
@@ -345,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)
    */
@@ -358,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) {
@@ -369,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() {
@@ -378,6 +390,21 @@ public static Predicate<MetadataBLOBPayloadEntry> notRevoked() {
                   statusReport -> AuthenticatorStatus.REVOKED.equals(statusReport.getStatus()));
     }
 
+    /**
+     * Include any metadata entry whose {@link MetadataBLOBPayloadEntry#getStatusReports()
+     * statusReports} array contains no entry with {@link AuthenticatorStatus#RETIRED RETIRED}
+     * status.
+     *
+     * @since 2.9.0
+     * @see AuthenticatorStatus#RETIRED
+     */
+    public static Predicate<MetadataBLOBPayloadEntry> notRetired() {
+      return (entry) ->
+          entry.getStatusReports().stream()
+              .noneMatch(
+                  statusReport -> AuthenticatorStatus.RETIRED.equals(statusReport.getStatus()));
+    }
+
     /**
      * Accept any authenticator whose matched metadata entry does NOT indicate a compromised
      * attestation key.
@@ -390,6 +417,7 @@ public static Predicate<MetadataBLOBPayloadEntry> notRevoked() {
      * {@link AuthenticatorToBeFiltered#getAttestationCertificateChain() attestation certificate
      * chain}.
      *
+     * @since 2.0.0
      * @see AuthenticatorStatus#ATTESTATION_KEY_COMPROMISE
      */
     public static Predicate<AuthenticatorToBeFiltered> noAttestationKeyCompromise() {
@@ -417,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)
@@ -426,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;
 
@@ -444,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);
@@ -491,6 +527,7 @@ public Optional<AAGUID> getAaguid() {
    *                             attestationCertificateChain</code>, if any.
    *     </ul>
    *
+   * @since 2.0.0
    * @see #findEntries(List)
    * @see #findEntries(List, AAGUID)
    */
@@ -566,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(
@@ -576,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(
@@ -594,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) {
@@ -606,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) {
@@ -623,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(
@@ -637,6 +679,9 @@ public Set<MetadataBLOBPayloadEntry> findEntries(
         .collect(Collectors.toSet());
   }
 
+  /**
+   * @since 2.0.0
+   */
   @Override
   public TrustRootsResult findTrustRoots(
       List<X509Certificate> attestationCertificateChain, Optional<ByteArray> aaguid) {