FidoMetadataDownloader.java

// Copyright (c) 2015-2021, Yubico AB

// All rights reserved.

//

// Redistribution and use in source and binary forms, with or without

// modification, are permitted provided that the following conditions are met:

//

// 1. Redistributions of source code must retain the above copyright notice, this

//    list of conditions and the following disclaimer.

//

// 2. Redistributions in binary form must reproduce the above copyright notice,

//    this list of conditions and the following disclaimer in the documentation

//    and/or other materials provided with the distribution.

//

// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"

// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE

// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE

// DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE

// FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL

// DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR

// SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER

// CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,

// OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE

// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package com.yubico.fido.metadata;

import com.fasterxml.jackson.core.Base64Variants;

import com.fasterxml.jackson.databind.ObjectMapper;

import com.yubico.fido.metadata.FidoMetadataDownloaderException.Reason;

import com.yubico.internal.util.BinaryUtil;

import com.yubico.internal.util.CertificateParser;

import com.yubico.internal.util.CollectionUtil;

import com.yubico.internal.util.OptionalUtil;

import com.yubico.webauthn.data.ByteArray;

import com.yubico.webauthn.data.exception.Base64UrlException;

import com.yubico.webauthn.data.exception.HexException;

import java.io.ByteArrayInputStream;

import java.io.File;

import java.io.FileInputStream;

import java.io.FileNotFoundException;

import java.io.FileOutputStream;

import java.io.IOException;

import java.io.InputStream;

import java.net.MalformedURLException;

import java.net.URL;

import java.net.URLConnection;

import java.nio.charset.StandardCharsets;

import java.security.DigestException;

import java.security.InvalidAlgorithmParameterException;

import java.security.InvalidKeyException;

import java.security.KeyManagementException;

import java.security.KeyStore;

import java.security.KeyStoreException;

import java.security.MessageDigest;

import java.security.NoSuchAlgorithmException;

import java.security.Signature;

import java.security.SignatureException;

import java.security.cert.CRL;

import java.security.cert.CRLException;

import java.security.cert.CertPath;

import java.security.cert.CertPathValidator;

import java.security.cert.CertPathValidatorException;

import java.security.cert.CertStore;

import java.security.cert.CertStoreParameters;

import java.security.cert.CertificateException;

import java.security.cert.CertificateFactory;

import java.security.cert.CollectionCertStoreParameters;

import java.security.cert.PKIXParameters;

import java.security.cert.TrustAnchor;

import java.security.cert.X509Certificate;

import java.time.Clock;

import java.util.ArrayList;

import java.util.Collection;

import java.util.Collections;

import java.util.Date;

import java.util.HashSet;

import java.util.List;

import java.util.Optional;

import java.util.Scanner;

import java.util.Set;

import java.util.UUID;

import java.util.function.Consumer;

import java.util.function.Function;

import java.util.function.Supplier;

import java.util.stream.Collectors;

import java.util.stream.Stream;

import javax.net.ssl.HttpsURLConnection;

import javax.net.ssl.SSLContext;

import javax.net.ssl.TrustManagerFactory;

import lombok.AccessLevel;

import lombok.AllArgsConstructor;

import lombok.Builder;

import lombok.NonNull;

import lombok.RequiredArgsConstructor;

import lombok.Value;

import lombok.extern.jackson.Jacksonized;

import lombok.extern.slf4j.Slf4j;

/**

 * Utility for downloading, caching and verifying Fido Metadata Service BLOBs and associated

 * certificates.

 *

 * <p>This class is NOT THREAD SAFE since it reads and writes caches. However, it has no internal

 * mutable state, so instances MAY be reused in single-threaded or externally synchronized contexts.

 * See also the {@link #loadCachedBlob()} and {@link #refreshBlob()} methods.

 *

 * <p>Use the {@link #builder() builder} to configure settings, then use the {@link

 * #loadCachedBlob()} and {@link #refreshBlob()} methods to load the metadata BLOB.

 */

public final class FidoMetadataDownloader {

  @NonNull private final Set<String> expectedLegalHeaders;

  private final Set<TrustAnchor> trustAnchors;

  private final List<URL> trustRootUrls;

  private final Set<ByteArray> trustRootSha256;

  private final File trustRootCacheFile;

  private final Supplier<Optional<ByteArray>> trustRootCacheSupplier;

  private final Consumer<ByteArray> trustRootCacheConsumer;

  private final String blobJwt;

  private final URL blobUrl;

  private final File blobCacheFile;

  private final Supplier<Optional<ByteArray>> blobCacheSupplier;

  private final Consumer<ByteArray> blobCacheConsumer;

  private final CertStore certStore;

  @NonNull private final Clock clock;

  private final KeyStore httpsTrustStore;

  private final boolean verifyDownloadsOnly;

  private final Function<Exception, CachePolicyDecision> cachePolicy;

  /** For overriding JSON mapper settings in tests. */

  private final Supplier<ObjectMapper> makeHeaderJsonMapper;

  /** For overriding JSON mapper settings in tests. */

  private final Supplier<ObjectMapper> makePayloadJsonMapper;

  /**

   * Begin configuring a {@link FidoMetadataDownloader} instance. See the {@link

   * FidoMetadataDownloaderBuilder.Step1 Step1} type.

   *

   * @see FidoMetadataDownloaderBuilder.Step1

   */

  public static FidoMetadataDownloaderBuilder.Step1 builder() {

  }

  public static class FidoMetadataDownloaderBuilder {

    @NonNull private final Set<String> expectedLegalHeaders;

    private final Set<TrustAnchor> trustAnchors;

    private final List<URL> trustRootUrls;

    private final Set<ByteArray> trustRootSha256;

    private final File trustRootCacheFile;

    private final Supplier<Optional<ByteArray>> trustRootCacheSupplier;

    private final Consumer<ByteArray> trustRootCacheConsumer;

    private final String blobJwt;

    private final URL blobUrl;

    private final File blobCacheFile;

    private final Supplier<Optional<ByteArray>> blobCacheSupplier;

    private final Consumer<ByteArray> blobCacheConsumer;

        FidoMetadataDownloader::defaultHeaderJsonMapper;

        FidoMetadataDownloader::defaultPayloadJsonMapper;

    public FidoMetadataDownloader build() {

          expectedLegalHeaders,

          trustAnchors,

          trustRootUrls,

          trustRootSha256,

          trustRootCacheFile,

          trustRootCacheSupplier,

          trustRootCacheConsumer,

          blobJwt,

          blobUrl,

          blobCacheFile,

          blobCacheSupplier,

          blobCacheConsumer,

          certStore,

          clock,

          httpsTrustStore,

          verifyDownloadsOnly,

          cachePolicy,

          makeHeaderJsonMapper,

          makePayloadJsonMapper);

    }

    /**

     * Step 1: Set the legal header to expect from the FIDO Metadata Service.

     *

     * <p>By using the FIDO Metadata Service, you will be subject to its terms of service. This step

     * serves two purposes:

     *

     * <ol>

     *   <li>To remind you and any code reviewers that you need to read those terms of service

     *       before using this feature.

     *   <li>To help you detect if the legal header changes, so you can take appropriate action.

     * </ol>

     *

     * <p>See {@link Step1#expectLegalHeader(String...)}.

     *

     * @see Step1#expectLegalHeader(String...)

     */

    public static class Step1 {

      /**

       * Set legal headers expected in the metadata BLOB.

       *

       * <p>By using the FIDO Metadata Service, you will be subject to its terms of service. This

       * builder step serves two purposes:

       *

       * <ol>

       *   <li>To remind you and any code reviewers that you need to read those terms of service

       *       before using this feature.

       *   <li>To help you detect if the legal header changes, so you can take appropriate action.

       * </ol>

       *

       * <p>If the legal header in the downloaded BLOB does not equal any of the <code>

       * expectedLegalHeaders</code>, an {@link UnexpectedLegalHeader} exception will be thrown in

       * the finalizing builder step.

       *

       * <p>Note that this library makes no guarantee that a change to the FIDO Metadata Service

       * terms of service will also cause a change to the legal header in the BLOB.

       *

       * <p>At the time of this library release, the current legal header is <code>

       * "Retrieval and use of this BLOB indicates acceptance of the appropriate agreement located at https://fidoalliance.org/metadata/metadata-legal-terms/"

       * </code>.

       *

       * @param expectedLegalHeaders the set of BLOB legal headers you expect in the metadata BLOB

       *     payload.

       */

      }

    }

    /**

     * Step 2: Configure how to retrieve the FIDO Metadata Service trust root certificate when

     * necessary.

     *

     * <p>This step offers three mutually exclusive options:

     *

     * <ol>

     *   <li>Use the default download URL and certificate hash. This is the main intended use case.

     *       See {@link #useDefaultTrustRoot()}.

     *   <li>Use custom download URLs and certificate hashes. This is for future-proofing in case

     *       the upstream trust roots change and there is no new release of this library. See {@link

     *       #downloadTrustRoot(URL, Set)} and {@link #downloadTrustRoots(List, Set)}.

     *   <li>Use a pre-retrieved trust root certificate or set of trust anchors. It is up to you to

     *       perform any integrity checks and caching as desired. See {@link

     *       #useTrustRoot(X509Certificate)} and {@link #useTrustRoots(Set)}.

     * </ol>

     */

    public static class Step2 {

      @NonNull private final Set<String> expectedLegalHeaders;

      /**

       * Download the trust root certificate from a hard-coded URL and verify it against a

       * hard-coded SHA-256 hash.

       *

       * <p>This is an alias of:

       *

       * <pre>

       * downloadTrustRoot(

       *   new URL("https://secure.globalsign.com/cacert/rootr46.crt"),

       *   Collections.singletonList(ByteArray.fromHex("4fa3126d8d3a11d1c4855a4f807cbad6cf919d3a5a88b03bea2c6372d93c40c9"))

       * )

       * </pre>

       *

       * This is the current FIDO Metadata Service trust root certificate at the time of this

       * library release.

       *

       * @see #downloadTrustRoot(URL, Set)

       * @see #downloadTrustRoots(List, Set)

       */

      public Step3 useDefaultTrustRoot() {

        try {

              new URL("https://secure.globalsign.com/cacert/rootr46.crt"),

                      "4fa3126d8d3a11d1c4855a4f807cbad6cf919d3a5a88b03bea2c6372d93c40c9")));

              "Bad hard-coded trust root certificate URL. Please file a bug report.", e);

              "Bad hard-coded trust root certificate hash. Please file a bug report.", e);

        }

      }

      /**

       * Download the trust root certificate from the given HTTPS <code>url</code> and verify its

       * SHA-256 hash against <code>acceptedCertSha256</code>.

       *

       * <p>The certificate will be downloaded if it does not exist in the cache, or if the cached

       * certificate is not currently valid.

       *

       * <p>If the cert is downloaded, it is also written to the cache {@link File} or {@link

       * Consumer} configured in the {@link Step3 next step}.

       *

       * <p>This is an alias of <code>

       * downloadTrustRoots(Collections.singletonList(url), acceptedCertSha256)</code>. See {@link

       * #downloadTrustRoots(List, Set)}.

       *

       * @param url the HTTP URL to download. It MUST use the <code>https:</code> scheme.

       * @param acceptedCertSha256 a set of SHA-256 hashes to verify the downloaded certificate

       *     against. The downloaded certificate MUST match at least one of these hashes.

       * @throws IllegalArgumentException if <code>url</code> is not a HTTPS URL.

       * @see #downloadTrustRoots(List, Set)

       */

      }

      /**

       * Download the trust root certificate from the given HTTPS <code>url</code> and verify its

       * SHA-256 hash against <code>acceptedCertSha256</code>.

       *

       * <p>The certificate will be downloaded if it does not exist in the cache, or if the cached

       * certificate is not currently valid.

       *

       * <p>If the cert is downloaded, it is also written to the cache {@link File} or {@link

       * Consumer} configured in the {@link Step3 next step}.

       *

       * @param urls a non-empty list of HTTPS URLs to download. Each URL MUST use the <code>https:

       *     </code> scheme.

       * @param acceptedCertSha256 a set of SHA-256 hashes to verify downloaded certificates

       *     against. Each downloaded certificate MUST match at least one of these hashes.

       * @throws IllegalArgumentException if <code>urls</code> is empty or if any element of <code>

       *     urls</code> is not a HTTPS URL.

       * @see #downloadTrustRoot(URL, Set)

       */

      public Step3 downloadTrustRoots(

              "List of trust certificate download URLs must not be empty.");

        }

        }

      }

      /**

       * Use the given trust root certificate. It is the caller's responsibility to perform any

       * integrity checks and/or caching logic.

       *

       * <p>This is a shortcut for {@link #useTrustRoots(Set)} with <code>trustRootCertificate

       * </code> imported into a singleton set.

       *

       * @param trustRootCertificate the certificate to use as the FIDO Metadata Service trust root.

       * @see #useTrustRoots(Set)

       */

      }

      /**

       * Use the given set of trust anchors. It is the caller's responsibility to perform any

       * integrity checks and/or caching logic.

       *

       * @param trustAnchors the trust anchors to use as the FIDO Metadata Service trust root. The

       *     set will be copied, so subsequent modifications to <code>trustAnchors</code> will not

       *     affect the <code>FidoMetadataDownloader</code> instance.

       * @see #useTrustRoot(X509Certificate)

       */

            null,

            null,

            null);

      }

    }

    /**

     * Step 3: Configure how to cache the trust root certificate.

     *

     * <p>This step offers two mutually exclusive options:

     *

     * <ol>

     *   <li>Cache trust root certificates in a {@link File}. See {@link

     *       Step3#useTrustRootCacheFile(File)}.

     *   <li>Cache trust root certificates using a {@link Supplier} to read the cache and a {@link

     *       Consumer} to write the cache. See {@link Step3#useTrustRootCache(Supplier, Consumer)}.

     * </ol>

     */

    public static class Step3 {

      @NonNull private final Step2 step2;

      private final Set<TrustAnchor> trustAnchors;

      private final List<URL> trustRootUrls;

      private final Set<ByteArray> trustRootSha256;

      /**

       * Cache trust root certificates in the file <code>cacheFile</code>.

       *

       * <p>If <code>cacheFile</code> exists, is a normal file and is readable, then trust root

       * certificates will be attempted to be read from this file. The internal format of the file

       * is opaque and subject to change without a major version release of the library.

       *

       * <p>If reading from the cache fails, then trust root certificates will instead be downloaded

       * and written to this file.

       *

       * <p>The cache is invalidated whenever the configured list of trust root download URLs

       * changes or differs in length from the number of cached certificates, or whenever any cached

       * certificate matches none of the configured SHA-256 hashes.

       */

      }

      /**

       * Cache the trust root certificate using a {@link Supplier} to read the cache, and using a

       * {@link Consumer} to write the cache.

       *

       * <p>If <code>getCachedTrustRootCerts</code> returns non-empty, then trust root certificates

       * will be attempted to be read from the contained {@link ByteArray}. The internal format of

       * the byte array is opaque and subject to change without a major version release of the

       * library.

       *

       * <p>If the supplier returns empty or reading from the contained byte array fails, then trust

       * root certificates will be downloaded and written to <code>

       * writeCachedTrustRootCerts</code>.

       *

       * <p>The cache is invalidated whenever the configured list of trust root download URLs

       * changes or differs in length from the number of cached certificates, or whenever any cached

       * certificate matches none of the configured SHA-256 hashes.

       *

       * @param getCachedTrustRootCerts a {@link Supplier} that fetches cached trust root

       *     certificates if they exist. MUST NOT return <code>null</code>. The format of the

       *     returned value, if present, is opaque to the supplier.

       * @param writeCachedTrustRootCerts a {@link Consumer} that accepts trust root certificates in

       *     an unspecified opaque format and writes it to the cache. Its argument will never be

       *     <code>null</code>.

       */

      public Step4 useTrustRootCache(

      }

    }

    /**

     * Step 4: Configure how to fetch the FIDO Metadata Service metadata BLOB.

     *

     * <p>This step offers three mutually exclusive options:

     *

     * <ol>

     *   <li>Use the default download URL. This is the main intended use case. See {@link

     *       #useDefaultBlob()}.

     *   <li>Use a custom download URL. This is for future-proofing in case the BLOB download URL

     *       changes and there is no new release of this library. See {@link #downloadBlob(URL)}.

     *   <li>Use a pre-retrieved BLOB. The signature will still be verified, but it is up to you to

     *       renew it when appropriate and perform any caching as desired. See {@link

     *       #useBlob(String)}.

     * </ol>

     */

    public static class Step4 {

      @NonNull private final Step3 step3;

      private final File trustRootCacheFile;

      private final Supplier<Optional<ByteArray>> trustRootCacheSupplier;

      private final Consumer<ByteArray> trustRootCacheConsumer;

      /**

       * Download the metadata BLOB from a hard-coded URL.

       *

       * <p>This is an alias of <code>downloadBlob(new URL("https://mds.fidoalliance.org/"))</code>.

       *

       * <p>This is the current FIDO Metadata Service BLOB download URL at the time of this library

       * release.

       *

       * @see #downloadBlob(URL)

       */

      public Step5 useDefaultBlob() {

        try {

              "Bad hard-coded trust root certificate URL. Please file a bug report.", e);

        }

      }

      /**

       * Download the metadata BLOB from the given HTTP or HTTPS <code>url</code>.

       *

       * <p>The BLOB will be downloaded if it does not exist in the cache, or if the <code>

       * nextUpdate</code> property of the cached BLOB is the current date or earlier.

       *

       * <p>If the BLOB is downloaded, it is also written to the cache {@link File} or {@link

       * Consumer} configured in the next step.

       *

       * <p>It is RECOMMENDED to use a HTTPS URL for improved transport security. Most notably this

       * helps prevent attacks that could force the application to continue using a stale cached

       * BLOB even after the real MDS has a newer BLOB available.

       *

       * @param url the HTTP or HTTPS URL to download.

       */

        }

      }

      /**

       * Use the given metadata BLOB; never download it.

       *

       * <p>The blob signature and trust chain will still be verified, but it is the caller's

       * responsibility to renew the metadata BLOB according to the <a

       * href="https://fidoalliance.org/specs/mds/fido-metadata-service-v3.0-ps-20210518.html#metadata-blob-object-processing-rules">FIDO

       * Metadata Service specification</a>.

       *

       * @param blobJwt the Metadata BLOB in JWT format as defined in <a

       *     href="https://fidoalliance.org/specs/mds/fido-metadata-service-v3.0-ps-20210518.html#metadata-blob">FIDO

       *     Metadata Service §3.1.7. Metadata BLOB</a>. The byte array MUST NOT be Base64-decoded.

       * @see <a

       *     href="https://fidoalliance.org/specs/mds/fido-metadata-service-v3.0-ps-20210518.html#metadata-blob">FIDO

       *     Metadata Service §3.1.7. Metadata BLOB</a>

       * @see <a

       *     href="https://fidoalliance.org/specs/mds/fido-metadata-service-v3.0-ps-20210518.html#metadata-blob-object-processing-rules">FIDO

       *     Metadata Service §3.2. Metadata BLOB object processing rules</a>

       */

      }

    }

    /**

     * Step 5: Configure how to cache the metadata BLOB.

     *

     * <p>This step offers two mutually exclusive options:

     *

     * <ol>

     *   <li>Cache the metadata BLOB in a {@link File}. See {@link Step5#useBlobCacheFile(File)}.

     *   <li>Cache the metadata BLOB using a {@link Supplier} to read the cache and a {@link

     *       Consumer} to write the cache. See {@link Step5#useBlobCache(Supplier, Consumer)}.

     * </ol>

     */

    public static class Step5 {

      @NonNull private final Step4 step4;

      private final String blobJwt;

      private final URL blobUrl;

      /**

       * Cache metadata BLOB in the file <code>cacheFile</code>.

       *

       * <p>If <code>cacheFile</code> exists, is a normal file, is readable, and is not out of date,

       * then it will be used as the FIDO Metadata Service BLOB.

       *

       * <p>Otherwise, the metadata BLOB will be downloaded and written to this file.

       *

       * @param cacheFile a {@link File} which may or may not exist. If it exists, it MUST contain

       *     the metadata BLOB in JWS compact serialization format <a

       *     href="https://datatracker.ietf.org/doc/html/rfc7515#section-3.1">[RFC7515]</a>.

       */

      }

      /**

       * Cache the metadata BLOB using a {@link Supplier} to read the cache, and using a {@link

       * Consumer} to write the cache.

       *

       * <p>If <code>getCachedBlob</code> returns non-empty and the content is not out of date, then

       * it will be used as the FIDO Metadata Service BLOB.

       *

       * <p>Otherwise, the metadata BLOB will be downloaded and written to <code>writeCachedBlob

       * </code>.

       *

       * @param getCachedBlob a {@link Supplier} that fetches the cached metadata BLOB if it exists.

       *     MUST NOT return <code>null</code>. The returned value, if present, MUST be in JWS

       *     compact serialization format <a

       *     href="https://datatracker.ietf.org/doc/html/rfc7515#section-3.1">[RFC7515]</a>.

       * @param writeCachedBlob a {@link Consumer} that accepts the metadata BLOB in JWS compact

       *     serialization format <a

       *     href="https://datatracker.ietf.org/doc/html/rfc7515#section-3.1">[RFC7515]</a> and

       *     writes it to the cache. Its argument will never be <code>null</code>.

       */

      public FidoMetadataDownloaderBuilder useBlobCache(

      }

    }

    private static FidoMetadataDownloaderBuilder finishRequiredSteps(

        FidoMetadataDownloaderBuilder.Step5 step5,

        File blobCacheFile,

        Supplier<Optional<ByteArray>> blobCacheSupplier,

        Consumer<ByteArray> blobCacheConsumer) {

          blobCacheFile,

          blobCacheSupplier,

          blobCacheConsumer);

    }

    /**

     * Use <code>clock</code> as the source of the current time for some application-level logic.

     *

     * <p>This is primarily intended for testing.

     *

     * <p>The default is {@link Clock#systemUTC()}.

     *

     * @param clock a {@link Clock} which the finished {@link FidoMetadataDownloader} will use to

     *     tell the time.

     */

    }

    /**

     * Use the provided CRLs.

     *

     * <p>CRLs will also be downloaded from distribution points for any certificates with a

     * CRLDistributionPoints extension, if the extension can be successfully interpreted. A warning

     * message will be logged CRLDistributionPoints parsing fails.

     *

     * @throws InvalidAlgorithmParameterException if {@link CertStore#getInstance(String,

     *     CertStoreParameters)} does.

     * @throws NoSuchAlgorithmException if a <code>"Collection"</code> type {@link CertStore}

     *     provider is not available.

     * @see #useCrls(CertStore)

     */

        throws InvalidAlgorithmParameterException, NoSuchAlgorithmException {

    }

    /**

     * Use CRLs in the provided {@link CertStore}.

     *

     * <p>CRLs will also be downloaded from distribution points for any certificates with a

     * CRLDistributionPoints extension, if the extension can be successfully interpreted. A warning

     * message will be logged CRLDistributionPoints parsing fails.

     *

     * @see #useCrls(Collection)

     */

    public FidoMetadataDownloaderBuilder useCrls(CertStore certStore) {

    }

    /**

     * Use the provided {@link X509Certificate}s as trust roots for HTTPS downloads.

     *

     * <p>This is primarily useful when setting {@link Step2#downloadTrustRoot(URL, Set)

     * downloadTrustRoot} or {@link Step2#downloadTrustRoots(List, Set) downloadTrustRoots} and/or

     * {@link Step4#downloadBlob(URL) downloadBlob} to download from custom servers instead of the

     * defaults.

     *

     * <p>If provided, these will be used for downloading

     *

     * <ul>

     *   <li>the trust root certificate for the BLOB signature chain, and

     *   <li>the metadata BLOB.

     * </ul>

     *

     * If not set, the system default certificate store will be used.

     */

      final KeyStore trustStore;

      try {

          | IOException

          | NoSuchAlgorithmException

          | CertificateException e) {

            "Failed to instantiate or initialize KeyStore. This should not be possible, please file a bug report.",

            e);

        try {

              "Failed to import HTTPS cert into KeyStore. This should not be possible, please file a bug report.",

              e);

      }

    }

    /**

     * If set to <code>true</code>, the BLOB signature will not be verified when loading the BLOB

     * from cache or when explicitly set via {@link Step4#useBlob(String)}. This means that if a

     * BLOB was successfully verified once and written to cache, that cached value will be

     * implicitly trusted when loaded in the future.

     *

     * <p>If set to <code>false</code>, the BLOB signature will always be verified no matter where

     * the BLOB came from. This means that a cached BLOB may become invalid if the BLOB certificate

     * expires, even if the BLOB was successfully verified at the time it was downloaded.

     *

     * <p>The default setting is <code>false</code>.

     *

     * @param verifyDownloadsOnly <code>true</code> if the BLOB signature should be ignored when

     *     loading the BLOB from cache or when explicitly set via {@link Step4#useBlob(String)}.

     */

    public FidoMetadataDownloaderBuilder verifyDownloadsOnly(final boolean verifyDownloadsOnly) {

    }

    /**

     * Define a policy for how {@link #refreshBlob()} and {@link #loadCachedBlob()} should behave

     * when a BLOB download fails.

     *

     * <p><code>cachePolicy</code> will be invoked when a cached BLOB is available and any attempt

     * to download, parse and verify a new BLOB fails. Its argument will be the {@link Exception}

     * that caused the failure. If <code>cachePolicy</code> returns {@link

     * CachePolicyDecision#USE_CACHED}, then the {@link #refreshBlob()} or {@link #loadCachedBlob()}

     * invocation will log a warning and return the cached BLOB as a successful result. If <code>

     * cachePolicy</code> returns {@link CachePolicyDecision#THROW}, then the exception will be

     * re-thrown and the {@link #refreshBlob()} or {@link #loadCachedBlob()} invocation will fail.

     *

     * <p><code>cachePolicy</code> MUST NOT return <code>null</code>.

     *

     * <p>When no cached BLOB is available, the exception is automatically re-thrown and <code>

     * cachePolicy</code> is not invoked.

     *

     * <p>See the documentation of {@link #refreshBlob()} and {@link #loadCachedBlob()} for what

     * kinds of exceptions may be thrown.

     *

     * <p>The default policy always returns {@link CachePolicyDecision#USE_CACHED}.

     *

     * @param cachePolicy the policy used to decide whether to throw or fall back to cache when a

     *     BLOB download fails. MUST NOT return <code>null</code>.

     * @see CachePolicyDecision

     * @see #refreshBlob()

     * @see #loadCachedBlob() ()

     */

    public FidoMetadataDownloaderBuilder cachePolicy(

        final Function<Exception, CachePolicyDecision> cachePolicy) {

    }

    /** For internal testing use only. */

    FidoMetadataDownloaderBuilder headerJsonMapper(

        final Supplier<ObjectMapper> makeHeaderJsonMapper) {

    }

    /** For internal testing use only. */

    FidoMetadataDownloaderBuilder payloadJsonMapper(

        final Supplier<ObjectMapper> makePayloadJsonMapper) {

    }

  }

  /**

   * Load the metadata BLOB from cache, or download a fresh one if necessary.

   *

   * <p>This method is NOT THREAD SAFE since it reads and writes caches.

   *

   * <p>On each execution this will, in order:

   *

   * <ol>

   *   <li>Download the trust root certificate, if necessary: if the cache is empty, the cache fails

   *       to load, or the cached cert is not valid at the current time (as determined by the {@link

   *       FidoMetadataDownloaderBuilder#clock(Clock) clock} setting).

   *   <li>If downloaded, cache the trust root certificate using the configured {@link File} or

   *       {@link Consumer} (see {@link FidoMetadataDownloaderBuilder.Step3})