Package com.yubico.fido.metadata

Class FidoMetadataDownloader.FidoMetadataDownloaderBuilder

java.lang.Object

com.yubico.fido.metadata.FidoMetadataDownloader.FidoMetadataDownloaderBuilder

Enclosing class:

FidoMetadataDownloader

public static class FidoMetadataDownloader.FidoMetadataDownloaderBuilder
extends Object

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	FidoMetadataDownloader.FidoMetadataDownloaderBuilder.Step1	Step 1: Set the legal header to expect from the FIDO Metadata Service.
static class	FidoMetadataDownloader.FidoMetadataDownloaderBuilder.Step2	Step 2: Configure how to retrieve the FIDO Metadata Service trust root certificate when necessary.
static class	FidoMetadataDownloader.FidoMetadataDownloaderBuilder.Step3	Step 3: Configure how to cache the trust root certificate.
static class	FidoMetadataDownloader.FidoMetadataDownloaderBuilder.Step4	Step 4: Configure how to fetch the FIDO Metadata Service metadata BLOB.
static class	FidoMetadataDownloader.FidoMetadataDownloaderBuilder.Step5	Step 5: Configure how to cache the metadata BLOB.

Method Summary

Modifier and Type	Method	Description
FidoMetadataDownloader	build()
FidoMetadataDownloader.FidoMetadataDownloaderBuilder	cachePolicy(Function<Exception,FidoMetadataDownloader.CachePolicyDecision> cachePolicy)	Define a policy for how FidoMetadataDownloader.refreshBlob() and FidoMetadataDownloader.loadCachedBlob() should behave when a BLOB download fails.
FidoMetadataDownloader.FidoMetadataDownloaderBuilder	clock(@NonNull Clock clock)	Use clock as the source of the current time for some application-level logic.
FidoMetadataDownloader.FidoMetadataDownloaderBuilder	trustHttpsCerts(@NonNull X509Certificate... certificates)	Use the provided X509Certificates as trust roots for HTTPS downloads.
FidoMetadataDownloader.FidoMetadataDownloaderBuilder	useCrls(@NonNull Collection<CRL> crls)	Use the provided CRLs.
FidoMetadataDownloader.FidoMetadataDownloaderBuilder	useCrls(CertStore certStore)	Use CRLs in the provided CertStore.
FidoMetadataDownloader.FidoMetadataDownloaderBuilder	verifyDownloadsOnly(boolean verifyDownloadsOnly)	If set to true, the BLOB signature will not be verified when loading the BLOB from cache or when explicitly set via FidoMetadataDownloader.FidoMetadataDownloaderBuilder.Step4.useBlob(String).

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Details

build

public FidoMetadataDownloader build()

clock

public FidoMetadataDownloader.FidoMetadataDownloaderBuilder clock(@NonNull
 @NonNull Clock clock)

Use clock as the source of the current time for some application-level logic.

This is primarily intended for testing.

The default is Clock.systemUTC().

Parameters:

clock - a Clock which the finished FidoMetadataDownloader will use to tell the time.

useCrls

public FidoMetadataDownloader.FidoMetadataDownloaderBuilder useCrls(@NonNull
 @NonNull Collection<CRL> crls)
                                                             throws InvalidAlgorithmParameterException,
NoSuchAlgorithmException

Use the provided CRLs.

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 CertStore.getInstance(String, CertStoreParameters) does.

NoSuchAlgorithmException - if a "Collection" type CertStore provider is not available.

See Also:

• useCrls(CertStore)

useCrls

public FidoMetadataDownloader.FidoMetadataDownloaderBuilder useCrls(CertStore certStore)

Use CRLs in the provided CertStore.

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 Also:

• useCrls(Collection)

trustHttpsCerts

public FidoMetadataDownloader.FidoMetadataDownloaderBuilder trustHttpsCerts(@NonNull
 @NonNull X509Certificate... certificates)

Use the provided X509Certificates as trust roots for HTTPS downloads.

This is primarily useful when setting downloadTrustRoot and/or downloadBlob to download from custom servers instead of the defaults.

If provided, these will be used for downloading

• the trust root certificate for the BLOB signature chain, and
• the metadata BLOB.

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

verifyDownloadsOnly

public FidoMetadataDownloader.FidoMetadataDownloaderBuilder verifyDownloadsOnly(boolean verifyDownloadsOnly)

If set to true, the BLOB signature will not be verified when loading the BLOB from cache or when explicitly set via FidoMetadataDownloader.FidoMetadataDownloaderBuilder.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.

If set to false, 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.

The default setting is false.

Parameters:

verifyDownloadsOnly - true if the BLOB signature should be ignored when loading the BLOB from cache or when explicitly set via FidoMetadataDownloader.FidoMetadataDownloaderBuilder.Step4.useBlob(String).

cachePolicy

public FidoMetadataDownloader.FidoMetadataDownloaderBuilder cachePolicy(Function<Exception,FidoMetadataDownloader.CachePolicyDecision> cachePolicy)

Define a policy for how FidoMetadataDownloader.refreshBlob() and FidoMetadataDownloader.loadCachedBlob() should behave when a BLOB download fails.

cachePolicy 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 Exception that caused the failure. If cachePolicy returns FidoMetadataDownloader.CachePolicyDecision.USE_CACHED, then the FidoMetadataDownloader.refreshBlob() or FidoMetadataDownloader.loadCachedBlob() invocation will log a warning and return the cached BLOB as a successful result. If cachePolicy returns FidoMetadataDownloader.CachePolicyDecision.THROW, then the exception will be re-thrown and the FidoMetadataDownloader.refreshBlob() or FidoMetadataDownloader.loadCachedBlob() invocation will fail.

cachePolicy MUST NOT return null.

When no cached BLOB is available, the exception is automatically re-thrown and cachePolicy is not invoked.

See the documentation of FidoMetadataDownloader.refreshBlob() and FidoMetadataDownloader.loadCachedBlob() for what kinds of exceptions may be thrown.

The default policy always returns FidoMetadataDownloader.CachePolicyDecision.USE_CACHED.

Parameters:

cachePolicy - the policy used to decide whether to throw or fall back to cache when a BLOB download fails. MUST NOT return null.

See Also:

• FidoMetadataDownloader.CachePolicyDecision
• FidoMetadataDownloader.refreshBlob()
• ()