yubico/java-webauthn-server

The FidoMetadataService uses an "allow-list" policy via two types of filters. Any metadata entry that passes these filters is considered a valid trust root.

1. Prefilter: Executed once when the FidoMetadataService is constructed. It selects which metadata entries from the BLOB are included in the service's data source.
2. Registration-time Filter: Executed during credential registration and when calling findEntries(). It decides whether a specific metadata entry matches a particular authenticator.

Customizing Filters

Use .prefilter(Predicate) and .filter(Predicate) on the FidoMetadataServiceBuilder.

Warning: Setting a custom filter replaces the default filter. To keep the default behavior (which excludes REVOKED authenticators in the prefilter and ATTESTATION_KEY_COMPROMISE in the registration-time filter), you must combine your custom predicate with the default ones using FidoMetadataService.Filters.allOf().

Follow these steps to prepare and publish a pre-release (RC) version. This process involves updating release notes, verifying API changes, running tests, and publishing to Maven Central.

1. Preparation

• Update release notes in NEWS.
• Review public API changes. If new dependencies are exposed in method signatures or throws declarations, change their Gradle dependency type from implementation to api. Remove or downgrade dependencies no longer exposed in the public API.
• Add @since tags to JavaDoc for new features.
• Run tests: ./gradlew clean check.
• Update the Java version in .github/workflows/release-verify-signatures.yml to match your local java -version output.

2. Pushing Changes

• If the README needs significant updates that don't reflect the current stable version, push to a new release branch:

  git checkout -b release-1.4.0
  git push origin release-1.4.0

• Otherwise, push directly to main.

3. Verification and Tagging

• After the build workflow finishes, download artifact-checksums-java17-temurin.zip, unpack it, and verify checksums against a local build:

  unzip artifact-checksums-java17-temurin.zip
  VERSION=0.1.0-SNAPSHOT ./gradlew primaryPublishJar
  sha256sum -c java-webauthn-server-artifacts.sha256sum

• Tag the head commit with an X.Y.Z-RCN format:

  git tag -a -s 1.4.0-RC1 -m "Pre-release 1.4.0-RC1"

4. Publishing

• Publish to Sonatype Maven Central:

  ./gradlew publish jreleaserDeploy

• Push the tag to GitHub:

  git push origin 1.4.0-RC1

• Create a GitHub release using the tag, check the pre-release checkbox, and copy/reformat release notes from NEWS (convert ASCIIdoc to Markdown).

# See full procedure in content for multiple command blocks

To publish releases, you must configure JReleaser by creating or updating the $HOME/.jreleaser/config.properties file. This file requires your Sonatype user token credentials and your GPG key fingerprint.

1. Generate a Sonatype user token at https://central.sonatype.com/usertoken.
2. Add the following properties to $HOME/.jreleaser/config.properties:
   • JRELEASER_MAVENCENTRAL_USERNAME
   • JRELEASER_MAVENCENTRAL_PASSWORD
   • JRELEASER_GPG_KEYNAME (the fingerprint of your GPG key)
   • JRELEASER_MAVENCENTRAL_STAGE
   • JRELEASER_GITHUB_TOKEN (a placeholder value is acceptable if a valid token is not used)

JRELEASER_MAVENCENTRAL_USERNAME=PYgw7b
JRELEASER_MAVENCENTRAL_PASSWORD=QxExuJ0wwfBzbXVOsaSTUTBkXH8Fa2dFo
JRELEASER_GPG_KEYNAME=2D6753CFF0B0FB32F9EEBA485B9688125FF0B636
JRELEASER_MAVENCENTRAL_STAGE=FULL
JRELEASER_GITHUB_TOKEN=nope

The webauthn-server-attestation module extends the core library by interfacing with the FIDO Metadata Service (MDS). This allows you to verify attestation statements during credential registration.

Implementation Steps

1. Initialize the Downloader and Service: Use FidoMetadataDownloader to manage downloading and caching metadata BLOBs, and FidoMetadataService to provide the metadata to the RelyingParty.

   • Note: FidoMetadataDownloader is NOT thread-safe because it performs cache read/write operations. Ensure only one call to loadCachedBlob() or refreshBlob() executes at a time. FidoMetadataService is thread-safe.
   • Recommendation: Use .verifyDownloadsOnly(true) on the downloader to prevent cache expiration if the BLOB certificate expires.

2. Configure the RelyingParty: Set the attestationTrustSource to your FidoMetadataService instance. To request attestation, set attestationConveyancePreference to AttestationConveyancePreference.DIRECT. Optionally, set allowUntrustedAttestation(false) to reject authenticators not found in the MDS.

3. Inspect Registration Results: After finishRegistration(), check RegistrationResult.isAttestationTrusted() to see if the authenticator's attestation was verified against trusted certificates in the MDS.

4. Retrieve Metadata: Use FidoMetadataService.findEntries(result) to get additional metadata for a successful registration.

FidoMetadataDownloader downloader = FidoMetadataDownloader.builder()
  .expectLegalHeader("Lorem ipsum dolor sit amet")
  .useDefaultTrustRoot()
  .useTrustRootCacheFile(new File("/var/cache/webauthn-server/fido-mds-trust-root.bin"))
  .useDefaultBlob()
  .useBlobCacheFile(new File("/var/cache/webauthn-server/fido-mds-blob.bin"))
  .verifyDownloadsOnly(true)
  .build();

FidoMetadataService mds = FidoMetadataService.builder()
  .useBlob(downloader.loadCachedBlob())
  .build();

RelyingParty rp = RelyingParty.builder()
  .identity(/* ... */)
  .credentialRepository(/* ... */)
  .attestationTrustSource(mds)
  .attestationConveyancePreference(AttestationConveyancePreference.DIRECT)
  .allowUntrustedAttestation(true)
  .build();

RegistrationResult result = rp.finishRegistration(/* ... */);

if (result.isAttestationTrusted()) {
  // Do something...
} else {
  // Do something else...
}

Set<MetadataBLOBPayloadEntry> metadata = mds.findEntries(result);