Local metadata workaround for older releases

This appendix describes the temporary workaround for nevisFIDO deployments that consume the FIDO Alliance Metadata Service and cannot be upgraded immediately.

note

This is a stopgap, not a supported long-term configuration. The permanent fix is to upgrade nevisFIDO and to add the GlobalSign Root R46 certificate to the truststore configured in fido2.metadata.mds3.metadata-truststore.

Symptoms

Metadata retrieval fails and nevisFIDO logs the warning Failed to refresh MetadataBLOB from MDS3 endpoint. The metadata cache is no longer updated and eventually expires.

Two independent problems can cause this on older releases:

1. The BLOB can no longer be parsed. The MDS3 BLOB contains a FIDO registry value that the metadata library used by older nevisFIDO releases does not know yet. Parsing is all-or-nothing, so the entire BLOB is rejected with InvalidFormatException: value is out of range and the affected entries cannot simply be skipped.
2. The BLOB can no longer be trusted. The FIDO Alliance moved the MDS BLOB signing chain to the GlobalSign Root R46 certificate. Truststores that only contain the retired GlobalSign Root CA - R3 fail the certificate path validation.

Upgrading nevisFIDO addresses the first problem, and adding the R46 root to your truststore addresses the second. Both are required. Note that the BLOB is parsed before its certificate chain is checked, so on a release that cannot parse the BLOB, adding the R46 root produces no visible change in the logs until nevisFIDO is upgraded.

The workaround

Besides the Metadata Service, nevisFIDO can load plain JSON metadata statements from the file system through fido2.metadata.path. That path is not affected by either problem.

Producing such a file correctly is not a manual exercise. It requires verifying the MDS BLOB signature and its certificate chain, and reproducing the status report filtering that the Metadata Service path applies, so that authenticators the FIDO Alliance no longer certifies are not silently re-admitted.

Contact Nevis support if you need this workaround. Support can provide a metadata file that is generated from the current MDS BLOB with those checks applied, together with the instructions matching your release.

warning

Do not assemble or hand-edit such a file yourself. nevisFIDO performs no signature, certificate path or revocation check on JSON metadata statements, so any mistake silently weakens authenticator trust instead of producing a visible error.

Configuring nevisFIDO

Once you have the metadata file, place it in a directory of its own and point nevisFIDO at that directory:

/var/opt/nevisfido/<instance>/conf/nevisfido.yml

fido2:
    metadata:
        path: /var/opt/nevisfido/<instance>/conf/metadata

Restart nevisFIDO afterwards.

Using nevisAdmin4

If you deploy with nevisAdmin4, set Metadata Location to local on the nevisFIDO FIDO2 Instance pattern and upload the file through Local Metadata. The pattern deploys it as conf/metadata.json and sets fido2.metadata.path accordingly.

Be aware that the pattern only generates the fido2.metadata.mds3 settings when Metadata Location is remote. Selecting local therefore drops the Metadata Service configuration altogether, so the note below about keeping both providers side by side does not apply.

note

You can leave fido2.metadata.mds3 configured alongside it. Both providers are independent and their trust anchors are aggregated, so a failing Metadata Service does not affect the file system path. nevisFIDO does keep retrying the endpoint, and the mds3 health indicator reports OUT_OF_SERVICE while a previously loaded cache has expired, or DOWN if no metadata was ever loaded. To keep that out of your readiness probe, exclude the indicator:

/var/opt/nevisfido/<instance>/conf/nevisfido.yml

management:
    healthchecks:
        ignore-indicators:
            - mds3

See Management Endpoints for details.

Limitations

• The file is a point-in-time snapshot, and it goes stale silently. It is read once while nevisFIDO starts and is never reloaded or re-read afterwards. Unlike the Metadata Service path, it has no expiry handling and no health indicator: the nextUpdate of the originating BLOB is not carried over into the file, nothing warns you that the snapshot is outdated, and no log entry or health state ever turns red. Until you renew it, authenticators certified in the meantime are not recognized and revocations published in the meantime are not applied.
• Because of this, renew the file on a schedule of your own and restart nevisFIDO afterwards. Ask Nevis support for a fresh file at least monthly. The FIDO Alliance moves nextUpdate roughly monthly but publishes new revisions considerably more often. The file itself carries no version marker, so record the BLOB number it was generated from alongside it, otherwise you cannot tell later how old it is.
• Local metadata is trusted as-is and bypasses the status report filtering of the Metadata Service path.
• If any file below fido2.metadata.path fails to parse, nevisFIDO does not start. Verify the change in a test environment first.
• fido2.metadata.value takes precedence over fido2.metadata.path. Do not configure both.
• The workaround covers the FIDO2 metadata of the official Metadata Service only. It does not replace any allow-listing or UAF metadata configuration.