Package com.yubico.fido.metadata

Class FidoMetadataDownloader

java.lang.Object

com.yubico.fido.metadata.FidoMetadataDownloader

public final class FidoMetadataDownloader
extends java.lang.Object

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

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 loadCachedBlob() method.

Use the builder to configure settings, then use the loadCachedBlob() method to load the metadata BLOB.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	FidoMetadataDownloader.FidoMetadataDownloaderBuilder

Method Summary

Modifier and Type	Method	Description
static FidoMetadataDownloader.FidoMetadataDownloaderBuilder.Step1	builder()	Begin configuring a FidoMetadataDownloader instance.
MetadataBLOB	loadCachedBlob()	Load the metadata BLOB from cache, or download a fresh one if necessary.

Methods inherited from class java.lang.Object

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

Method Detail

builder

public static FidoMetadataDownloader.FidoMetadataDownloaderBuilder.Step1 builder()

Begin configuring a FidoMetadataDownloader instance. See the Step1 type.

See Also:

FidoMetadataDownloader.FidoMetadataDownloaderBuilder.Step1

loadCachedBlob

public MetadataBLOB loadCachedBlob()
                            throws java.security.cert.CertPathValidatorException,
                                   java.security.InvalidAlgorithmParameterException,
                                   com.yubico.webauthn.data.exception.Base64UrlException,
                                   java.security.cert.CertificateException,
                                   java.io.IOException,
                                   java.security.NoSuchAlgorithmException,
                                   java.security.SignatureException,
                                   java.security.InvalidKeyException,
                                   UnexpectedLegalHeader,
                                   java.security.DigestException,
                                   FidoMetadataDownloaderException

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

This method is NOT THREAD SAFE since it reads and writes caches.

On each execution this will, in order:

1. 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 clock setting).
2. If downloaded, cache the trust root certificate using the configured File or Consumer (see FidoMetadataDownloader.FidoMetadataDownloaderBuilder.Step3)
3. Download the metadata BLOB, if necessary: if the cache is empty, the cache fails to load, or the "nextUpdate" property in the cached BLOB is the current date (as determined by the clock setting) or earlier.
4. Check the "no" property of the downloaded BLOB, if any, and compare it with the "no" of the cached BLOB, if any. The one with a greater "no" overrides the other, even if its "nextUpdate" is in the past.
5. If a BLOB with a newer "no" was downloaded, verify that the value of its "legalHeader" appears in the configured expectLegalHeader setting. If not, throw an UnexpectedLegalHeader exception containing the cached BLOB, if any, and the downloaded BLOB.
6. If a BLOB with a newer "no" was downloaded and had an expected "legalHeader", cache the new BLOB using the configured File or Consumer (see FidoMetadataDownloader.FidoMetadataDownloaderBuilder.Step5).

No internal mutable state is maintained between invocations of loadBlob(); each invocation will reload/rewrite caches, perform downloads and check the "legalHeader" as necessary. You may therefore reuse a FidoMetadataDownloader instance and, for example, call loadBlob() periodically to refresh the BLOB when appropriate. Each call will return a new MetadataBLOB instance; ones already returned will not be updated by subsequent loadBlob() calls.

Returns:

the successfully retrieved and validated metadata BLOB.

Throws:

com.yubico.webauthn.data.exception.Base64UrlException - if the metadata BLOB is not a well-formed JWT in compact serialization.

java.security.cert.CertPathValidatorException - if the downloaded or explicitly configured BLOB fails certificate path validation.

java.security.cert.CertificateException - if the trust root certificate was downloaded and passed the SHA-256 integrity check, but does not contain a currently valid X.509 DER certificate; or if the BLOB signing certificate chain fails to parse.

java.security.DigestException - if the trust root certificate was downloaded but failed the SHA-256 integrity check.

FidoMetadataDownloaderException - if the explicitly configured BLOB (if any) has a bad signature.

java.io.IOException - if any of the following fails: downloading the trust root certificate, downloading the BLOB, reading or writing any cache file (if any), or parsing the BLOB contents.

java.security.InvalidAlgorithmParameterException - if certificate path validation fails.

java.security.InvalidKeyException - if signature verification fails.

java.security.NoSuchAlgorithmException - if signature verification fails, or if the SHA-256 algorithm is not available.

java.security.SignatureException - if signature verification fails.

UnexpectedLegalHeader - if the downloaded BLOB (if any) contains a "legalHeader" value not configured in expectLegalHeader(String...) but is otherwise valid. The downloaded BLOB will not be written to cache in this case.