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() and refreshBlob() methods.

Use the builder to configure settings, then use the loadCachedBlob() and refreshBlob() methods 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.
MetadataBLOB	refreshBlob()	Download and cache a fresh metadata BLOB, or read it from cache if the downloaded BLOB is not up to date.

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,
                                   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 this method; 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 this method periodically to refresh the BLOB when appropriate. Each call will return a new MetadataBLOB instance; ones already returned will not be updated by subsequent calls.

Returns:

the successfully retrieved and validated metadata BLOB.

Throws:

Base64UrlException - if the explicitly configured or newly downloaded BLOB is not a well-formed JWT in compact serialization.

java.security.cert.CertPathValidatorException - if the explicitly configured or newly downloaded 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 or newly downloaded BLOB (if any) has a bad signature and there is no cached BLOB to fall back to.

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.

refreshBlob

public MetadataBLOB refreshBlob()
                         throws java.security.cert.CertPathValidatorException,
                                java.security.InvalidAlgorithmParameterException,
                                Base64UrlException,
                                java.security.cert.CertificateException,
                                java.io.IOException,
                                java.security.NoSuchAlgorithmException,
                                java.security.SignatureException,
                                java.security.InvalidKeyException,
                                UnexpectedLegalHeader,
                                java.security.DigestException,
                                FidoMetadataDownloaderException

Download and cache a fresh metadata BLOB, or read it from cache if the downloaded BLOB is not up to date.

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.
4. Check the "no" property of the downloaded BLOB 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 the downloaded BLOB has a newer "no", or if no BLOB was cached, verify that the value of the downloaded BLOB's "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 the downloaded BLOB has an expected "legalHeader", cache it using the configured File or Consumer (see FidoMetadataDownloader.FidoMetadataDownloaderBuilder.Step5).

No internal mutable state is maintained between invocations of this method; 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 this method periodically to refresh the BLOB. Each call will return a new MetadataBLOB instance; ones already returned will not be updated by subsequent calls.

Returns:

the successfully retrieved and validated metadata BLOB.

Throws:

Base64UrlException - if the explicitly configured or newly downloaded BLOB is not a well-formed JWT in compact serialization.

java.security.cert.CertPathValidatorException - if the explicitly configured or newly downloaded 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 or newly downloaded BLOB (if any) has a bad signature and there is no cached BLOB to fall back to.

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.