Version 2.2.0

webauthn-server-core:

Changes:

• Changed internal structure of RegistrationResult and AssertionResult. This may affect you if you use Jackson or similar tools to serialize these values to JSON, for example. This is not an officially supported use case and thus does not warrant a major version bump.
• Removed methods RegistrationResult.toBuilder() and AssertionResult.toBuilder(). Both had package-private return types, and thus were not usable by outside callers.

New features:

• (Experimental) Added support for the new BE (backup eligible) and BS (backup state) flags in authenticator data:
  • NOTE: Experimental features may receive breaking changes without a major version increase.
  • Added BE and BS properties to AuthenticatorDataFlags, reflecting the respective flags (bits 0x08 and 0x10).
  • Added methods isBackupEligible() and isBackedUp() to RegistrationResult and AssertionResult, reflecting respectively the BE and BS flags.
  • Added properties backupEligible and backupState, getters isBackupEligible() and isBackedUp(), and corresponding builder methods to RegisteredCredential. RelyingParty.finishAssertion(...) will now validate that if RegisteredCredential.isBackupEligible() is present, then the BE flag of any assertion of that credential must match the stored value.

Fixes:

• Fixed TPM attestation verification rejecting attestation certificates with TPM Device Attributes split between multiple RelativeDistinguishedName structures in the Subject Alternative Names extension.
  • Thanks to Oussama Zgheb for the contribution, see #241
• Fixed various errors in JavaDoc.

webauthn-server-attestation:

Fixes:

• Improved documentation of guarantees provided by FidoMetadataDownloader and required of its parameters.

Artifacts built with openjdk 17.0.5 2022-10-18.

Pre-release 2.2.0-RC1

webauthn-server-core:

Changes:

• Changed internal structure of RegistrationResult and AssertionResult. This may affect you if you use Jackson or similar tools to serialize these values to JSON, for example. This is not an officially supported use case and thus does not warrant a major version bump.
• Removed methods RegistrationResult.toBuilder() and AssertionResult.toBuilder(). Both had package-private return types, and thus were not usable by outside callers.

New features:

• (Experimental) Added support for the new BE (backup eligible) and BS (backup state) flags in authenticator data:
  • Added BE and BS properties to AuthenticatorDataFlags, reflecting the respective flags (bits 0x08 and 0x10).
  • Added methods isBackupEligible() and isBackedUp() to RegistrationResult and AssertionResult, reflecting respectively the BE and BS flags.
  • Added properties backupEligible and backupState, getters isBackupEligible() and isBackedUp(), and corresponding builder methods to RegisteredCredential. RelyingParty.finishAssertion(...) will now validate that if RegisteredCredential.isBackupEligible() is present, then the BE flag of any assertion of that credential must match the stored value.

Fixes:

• Fixed TPM attestation verification rejecting attestation certificates with TPM Device Attributes split between multiple RelativeDistinguishedName structures in the Subject Alternative Names extension.
  • Thanks to Oussama Zgheb for the contribution, see #241
• Fixed various errors in JavaDoc.

webauthn-server-attestation:

Fixes:

• Improved documentation of guaranteed provided by FidoMetadataDownloader and required of its parameters.

Artifacts built with openjdk 17.0.5 2022-10-18.

Version 2.1.0

webauthn-server-core:

Changes:

• Log messages on attestation certificate path validation failure now include the attestation object.

Deprecations:

• Deprecated method AssertionResult.getCredentialId(): ByteArray. Use .getCredential().getCredentialId() instead.
• Deprecated method AssertionResult.getUserHandle(): ByteArray. Use .getCredential().getUserHandle() instead.

New features:

• Added function COSEAlgorithmIdentifier.fromPublicKey(ByteArray).
• Added method AssertionResult.getCredential(): RegisteredCredential.
• Added support for the "tpm" attestation statement format.
• Added support for ES384 and ES512 signature algorithms.
• Added property policyTreeValidator to TrustRootsResult. If set, the given predicate function will be used to validate the certificate policy tree after successful attestation certificate path validation. This may be required for some JCA providers to accept attestation certificates with critical certificate policy extensions. See the JavaDoc for TrustRootsResultBuilder.policyTreeValidator(Predicate) for more information.
• Added enum value AttestationConveyancePreference.ENTERPRISE.
• (Experimental) Added constant AuthenticatorTransport.HYBRID.

Fixes:

• Fixed various typos and mistakes in JavaDocs.
• Moved version constraints for test dependencies from meta-module webauthn-server-parent to unpublished test meta-module.
• yubico-util dependency removed from downstream compile scope.
• Fixed missing JavaDoc on TrustRootsResult getters and builder setters.

webauthn-server-attestation:

Changes:

• The AuthenticatorToBeFiltered argument of the FidoMetadataService runtime filter now omits zero AAGUIDs.
• Promoted log messages in FidoMetadataDownloader about BLOB signature failure and cache corruption from DEBUG level to WARN level.

New features:

• Added method FidoMetadataDownloader.refreshBlob().

Fixes:

• Fixed various typos and mistakes in JavaDocs.
• FidoMetadataDownloader now verifies the SHA-256 hash of the cached trust root certificate, as promised in the JavaDoc of useTrustRootCacheFile and useTrustRootCache.
• BouncyCastle dependency dropped.
• Guava dependency dropped (but still remains in core module).
• If BLOB download fails, FidoMetadataDownloader now correctly falls back to cache if available.

Artifacts built with openjdk 17.0.4.1 2022-08-12.

Pre-release 2.1.0-RC2

webauthn-server-attestation:

Changes:

• Promoted log messages in FidoMetadataDownloader about BLOB signature failure and cache corruption from DEBUG level to WARN level.

Fixes:

• If BLOB download fails, FidoMetadataDownloader now correctly falls back to cache if available.

Artifacts built with openjdk 17.0.4.1 2022-08-12.

Pre-release 2.1.0-RC1

webauthn-server-core:

Changes:

• Log messages on attestation certificate path validation failure now include the attestation object.

New features:

• Added method FidoMetadataDownloader.refreshBlob().
• Added support for the "tpm" attestation statement format.
• Added support for ES384 and ES512 signature algorithms.
• Added property policyTreeValidator to TrustRootsResult. If set, the given predicate function will be used to validate the certificate policy tree after successful attestation certificate path validation. This may be required for some JCA providers to accept attestation certificates with critical certificate policy extensions. See the JavaDoc for TrustRootsResultBuilder.policyTreeValidator(Predicate) for more information.
• Added enum value AttestationConveyancePreference.ENTERPRISE.
• (Experimental) Added constant AuthenticatorTransport.HYBRID.

Fixes:

• Fixed various typos and mistakes in JavaDocs.
• Moved version constraints for test dependencies from meta-module webauthn-server-parent to unpublished test meta-module.
• yubico-util dependency removed from downstream compile scope.

webauthn-server-attestation:

Changes:

• The AuthenticatorToBeFiltered argument of the FidoMetadataService runtime filter now omits zero AAGUIDs.

Fixes:

• Fixed various typos and mistakes in JavaDocs.
• FidoMetadataDownloader now verifies the SHA-256 hash of the cached trust root certificate, as promised in the JavaDoc of useTrustRootCacheFile and useTrustRootCache.
• BouncyCastle dependency dropped.
• Guava dependency dropped (but still remains in core module).

Artifacts built with openjdk 17.0.4.1 2022-08-12.

Pre-release 2.1.0-alpha2

Deprecations:

• Deprecated method AssertionResult.getCredentialId(): ByteArray. Use .getCredential().getCredentialId() instead.
• Deprecated method AssertionResult.getUserHandle(): ByteArray. Use .getCredential().getUserHandle() instead.

New features:

• Added function COSEAlgorithmIdentifier.fromPublicKey(ByteArray).
• Added method AssertionResult.getCredential(): RegisteredCredential.

Artifacts built with openjdk 11.0.15 2022-04-19.

Pre-release 2.1.0-alpha1

New features:

• Added method FidoMetadataDownloader.refreshBlob().

Artifacts built with openjdk 11.0.15 2022-04-19.

Version 2.0.0

This release removes deprecated APIs and changes some defaults to better align with the L2 version of the WebAuthn spec. It also adds a new major feature: optional integration with the FIDO Metadata Service for retrieving authenticator metadata and attestation trust roots. See below for details.

webauthn-server-core:

Breaking changes:

• Deleted deprecated icon field in RelyingPartyIdentity and UserIdentity, and its associated methods.
• Deleted deprecated AuthenticatorSelectionCriteria methods builder().requireResidentKey(boolean) and isRequireResidentKey().
• RelyingParty parameter allowUnrequestedExtensions removed. The library will now always accept unrequested extensions.
• Class ClientAssertionExtensionOutputs now silently ignores unknown extensions instead of rejecting them.
• webauthn-server-core-minimal module deleted.
• webauthn-server-core no longer depends on BouncyCastle and will no longer attempt to automatically fall back to it. Therefore, EdDSA keys are no longer supported by default in JDK 14 and earlier. The library will log warnings if configured for algorithms with no JCA provider available, in which case the dependent project may need to add additional dependencies and configure JCA providers externally.
• Enum value AttestationType.ECDAA removed without replacement.
• Deleted methods RegistrationResult.getWarnings() and AssertionResult.getWarnings() since they are now always empty.
• Framework for attestation metadata has been fully overhauled. See the webauthn-server-attestation module documentation for the new ways to work with attestation metadata:
  • Deleted method RegistrationResult.getAttestationMetadata().
  • Interface MetadataService replaced with AttestationTrustSource, and optional RelyingParty setting .metadataService(MetadataService) replaced with .attestationTrustSource(AttestationTrustSource).
  • Deleted types Attestation and Transport.
  • Deleted method AuthenticatorTransport.fromU2fTransport.
• RelyingParty.finishRegistration() now uses a JCA CertPathValidator to validate attestation certificate paths, if an attestation trust source has been configured. This requires a compatible JCA provider, but should already be available in most environments.
• Classes in package com.yubico.fido.metadata moved to com.yubico.webauthn.extension.uvm to avoid name clash with webauthn-server-attestation module in JPMS.
• Changed return type of PublicKeyCredentialRequestOptions.getUserVerification(), AuthenticatorSelectionCriteria.getUserVerification() and AuthenticatorSelectionCriteria.getResidentKey() to Optional, and changed defaults for userVerification and residentKey to empty. This means we won't inadvertently suppress warnings that browsers might issue in the browser console if for example userVerification is not set explicitly.

New features:

• Method getAaguid() added to RegistrationResult.
• Method getAttestationTrustPath() added to RegistrationResult.
• Setting .clock(Clock) added to RelyingParty. It is used for attestation path validation if an attestationTrustSource is configured.

webauthn-server-attestation:

Breaking changes:

• Types AttestationResolver, CompositeAttestationResolver, CompositeTrustResolver, DeviceMatcher, ExtensionMatcher, FingerprintMatcher, MetadataObject, SimpleAttestationResolver, SimpleTrustResolver, StandardMetadataService and TrustResolver deleted in favour of a new attestation metadata framework. Some of the functionality is retained as the new YubicoJsonMetadataService class in the webauthn-server-demo subproject in the library sources, but no longer exposed in either library module.
• Library no longer contains a /metadata.json resource.

New features:

• New types FidoMetadataService and FidoMetadataDownloader which integrate with the FIDO Metadata Service for retrieving authenticator metadata and attestation trust roots.

Artifacts built with openjdk 11.0.15 2022-04-19.

NOTICE: Psychic signatures in Java

In April 2022, a vulnerability was disclosed in Oracle's OpenJDK (and other JVMs derived from it) which can impact applications using java-webauthn-server. The impact is that for the most common type of WebAuthn credential, invalid signatures are accepted as valid, allowing authentication bypass for users with such a credential. Please read Oracle's advisory and make sure you are not using one of the impacted OpenJDK versions. If you are, we urge you to upgrade your Java deployment to a version that is safe.

Pre-release 2.0.0-RC2

Breaking changes:

• Method FidoMetadataDownloader.loadBlob() renamed to loadCachedBlob().

Artifacts built with openjdk 11.0.15 2022-04-19.

Version 1.12.4

Deprecated features:

• Option RelyingParty.allowUnrequestedExtensions deprecated. The false setting (default) is not compatible with WebAuthn Level 2 since authenticators are now always allowed to add unsolicited extensions. The next major version release will remove this option and always behave as if the option had been set to true.
• Enum value AttestationType.ECDAA. ECDAA was removed in WebAuthn Level 2.
• Function TokenBindingStatus.fromJsonString(String) deprecated. It should not have been part of the public API to begin with.

Artifacts built with openjdk 11.0.15 2022-04-19.

NOTICE: Psychic signatures in Java

In April 2022, a vulnerability was disclosed in Oracle's OpenJDK (and other JVMs derived from it) which can impact applications using java-webauthn-server. The impact is that for the most common type of WebAuthn credential, invalid signatures are accepted as valid, allowing authentication bypass for users with such a credential. Please read Oracle's advisory and make sure you are not using one of the impacted OpenJDK versions. If you are, we urge you to upgrade your Java deployment to a version that is safe.