Version 2.6.0 (unreleased)

Added method getParsedPublicKey(): java.security.PublicKey to RegistrationResult and RegisteredCredential.

Added enum parsing functions:

Added public builder to CredentialPropertiesOutput.

Added public factory function LargeBlobRegistrationOutput.supported(boolean).

Added public factory functions to LargeBlobAuthenticationOutput.

Added hints property to StartRegistrationOptions, StartAssertionOptions, PublicKeyCredentialCreationOptions and PublicKeyCredentialRequestOptions, and class PublicKeyCredentialHint to support them, to support the hints parameter introduced in WebAuthn L3: https://www.w3.org/TR/2023/WD-webauthn-3-20230927/#dom-publickeycredentialcreationoptions-hints

(Experimental) Added option isSecurePaymentConfirmation(boolean) to FinishAssertionOptions. When set, RelyingParty.finishAssertion() will adapt the validation logic for a Secure Payment Confirmation (SPC) response instead of an ordinary WebAuthn response. See the JavaDoc for details.

(Experimental) Added a new suite of interfaces, starting with CredentialRepositoryV2. RelyingParty can now be configured with a CredentialRepositoryV2 instance instead of a CredentialRepository instance. This changes the result of the RelyingParty builder to RelyingPartyV2. CredentialRepositoryV2 and RelyingPartyV2 enable a suite of new features:

(Experimental) Added property RegisteredCredential.transports.

(Experimental) Added property credProps.authenticatorDisplayName.

(Experimental) Added credProps extension to assertion extension outputs.

FidoMetadataDownloader no longer rejects FIDO MDS metadata BLOBs with unknown properties.

Allow unknown properties in credProps client extension output.

Dropped dependency on COSE-Java.

Fixed incompatibility with Jackson version 2.17.0-rc1.

Added Jackson annotation @JsonProperty to method RegisteredCredential.isBackedUp(), changing the property name from backedUp to backupState. backedUp is still accepted during deserialization but will no longer be emitted during serialization.

Added method .isUserVerified() to RegistrationResult and AssertionResult as a shortcut for accessing the UV flag in authenticator data.

Updated README and JavaDoc to use the "passkey" term and provide more guidance around passkey use cases.

Added Automatic-Module-Name to jar manifest.

AuthenticatorAttestationResponse now tolerates and ignores properties "publicKey" and "publicKeyAlgorithm" during JSON deserialization. These properties are emitted by the PublicKeyCredential.toJSON() method added in WebAuthn Level 3.

Relaxed Guava dependency version constraint to include major version 32.

RelyingParty.finishAssertion now behaves the same if StartAssertionOptions.allowCredentials is explicitly set to a present, empty list as when absent.

Added option verifyDownloadsOnly(boolean) to FidoMetadataDownloader. When set to true, the BLOB signature will not be verified when loading a BLOB from cache or when explicitly given. Default setting is false, which preserves the previous behaviour.

Added Automatic-Module-Name to jar manifest.

Made Jackson setting PROPAGATE_TRANSIENT_MARKER unnecessary for JSON serialization with Jackson version 2.15.0-rc1 and later.

Added explicit version constraint on jackson-bom.

Fixed incompatibility with Jackson version 2.15.0-rc1 and later.

Fixed linking issue when running in Java 8.

Added support for RS384 and RS512 signature algorithms.

Added userHandle field to AssertionRequest as part of the second bug fix below. userHandle is mutually exclusive with username. This was originally released in pre-release 1.12.3-RC3, but was accidentally left out of the 1.12.3 release.

During RelyingParty.finishRegistration() if an attestationTrustSource is configured, if the aaguid in the authenticator data is zero, the call to AttestationTrustSource.findTrustRoots will fall back to reading the AAGUID from the attestation certificate if possible.

Fixed bug in RelyingParty.finishAssertion where if StartAssertionOptions.userHandle was set, it did not propagate to RelyingParty.finishAssertion and caused an error saying username and user handle are both absent unless a user handle was returned by the authenticator. This was originally released in pre-release 1.12.3-RC3, but was accidentally left out of the 1.12.3 release.

Fixed regression in PublicKeyCredentialCreationOptions.toCredentialsCreateJson(), which has not been emitting a requireResidentKey member since version 2.0.0. This meant the JSON output was not backwards compatible with browsers that only support the Level 1 version of the WebAuthn spec.

findEntries and findTrustRoots methods in FidoMetadataService now attempt to read AAGUID from the attestation certificate if the aaguid argument is absent or zero.

Method FidoMetadataService.Filters.allOf now has @SafeVarargs annotation.

(Experimental) Added authenticatorAttachment property to response objects:

Fixed the README description of SemVer exceptions: @Deprecated features are still part of the public API unless they also have an EXPERIMENTAL: tag in JavaDoc.

Brought com.yubico.webauthn package JavaDoc up to date with new library features.

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.

(Experimental) Added support for the new BE (backup eligible) and BS (backup state) flags in authenticator data:

Fixed TPM attestation verification rejecting attestation certificates with TPM Device Attributes split between multiple RelativeDistinguishedName structures in the Subject Alternative Names extension.

Fixed various errors in JavaDoc.

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

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

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

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

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.

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.

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.

Added method FidoMetadataDownloader.refreshBlob().

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.

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:

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.

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.

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 types FidoMetadataService and FidoMetadataDownloader which integrate with the FIDO Metadata Service for retrieving authenticator metadata and attestation trust roots.

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.

Fixed PublicKeyCredential failing to parse from JSON if an "authenticatorAttachment" attribute was present.

Bumped Jackson dependency to version [2.13.2.1,3) in response to CVE-2020-36518

Fixed bug in RelyingParty.finishAssertion that would throw a nondescript NoSuchElementException if username and user handle are both absent, instead of an IllegalArgumentException with a better error message.

com.upokecenter:cbor dependency bumped to minimum version 4.5.1 due to a known vulnerability, see: https://github.com/advisories/GHSA-fj2w-wfgv-mwq6

Fixed crash in AuthenticatorData deserialization with com.upokecenter:cbor versions later than 4.0.1

RelyingParty.finishAssertion() no longer makes multiple (redundant) calls to CredentialRepository.lookup().

New method RegisteredCredential.builder().publicKeyEs256Raw(ByteArray). This is a mutually exclusive alternative to .publicKeyCose(ByteArray), for easier backwards-compatibility with U2F-formatted (Raw ANSI X9.62) public keys.

"Migrating from U2F" section added to project README

AuthenticatorSelectionCriteria methods builder().requireResidentKey(boolean) and isRequireResidentKey() deprecated in favor of a new option, see below.

The icon field in RelyingPartyIdentity and UserIdentity, and its associated methods, are now deprecated. The corresponding property was removed in WebAuthn Level 2.

RelyingParty.startAssertion() no longer overwrites the appid extension input in the StartAssertionOptions argument.

RelyingParty.appId setting now also activates the appidExclude extension in addition to the appid extension.

RelyingParty.startRegistration() now enables the credProps extension by default. The extension output, if any, is available as RegistrationResult.isDiscoverable() and RegistrationResult.getClientExtensionOutputs().getCredProps().

RegistrationResult.keyId() now includes transports if any were included in the AuthenticatorAttestatationResponse. To get transports passed through, call PublicKeyCredential.response.getTransports() on the client side after successful registration, and add the result as the property response.transports in the JSON passed into PublicKeyCredential.parseRegistrationResponseJson. See the project README for an example.

Added support for the appidExclude, credProps, largeBlob and uvm extensions.

Added support for the new authenticatorSelectionCriteria.residentKey option:

Added methods PublicKeyCredentialCreationOptions.toCredentialsCreateJson(), PublicKeyCredentialRequestOptions.toCredentialsGetJson() and AssertionRequest.toCredentialsGetJson() for serializing to JSON without having to use Jackson directly.

Added methods PublicKeyCredentialCreationOptions.toJson() and .fromJson(String) suitable for encoding to and decoding from JSON.

Added methods AssertionRequest.toJson() and .fromJson(String) suitable for encoding to and decoding from JSON.

Added methods StartAssertionOptions.builder().userHandle(ByteArray) and .userHandle(Optional<ByteArray>) as alternatives to .username(String) and .username(Optional<String>). The userHandle methods fill the same function as, and are mutually exclusive with, the username methods.

Added missing JavaDoc for id and name methods of initial RelyingPartyIdentityBuilder stages.

Added and improved JavaDoc for required builder methods.

Javadoc for TokenBindingInfo.id incorrectly stated that the value is base64url encoded.

Javadoc for TokenBindingStatus.PRESENT incorrectly referenced its own (private) id member instead of TokenBindingInfo.id.

Improved JavaDoc for StartRegistrationOptions.authenticatorSelection

Improved JavaDoc for RelyingParty.appid

Make the RelyingParty.validateSignatureCounter JavaDoc also cover the success case where stored and received signature count are both zero.

Fixed name of YubiKey Bio - FIDO edition in attestation metadata.

Added attestation metadata for YubiKey Bio.

Added missing <dependencyManagement> declaration to webauthn-server-attestation and webauthn-server-core POMs.

Added attestation metadata for YubiKey 5 FIPS series.

Fixed that SimpleAttestationResolver would return empty transports when transports are unknown.

Added support for the "apple" attestation statement format.

Dependency versions moved to new meta-module webauthn-server-parent. Users should never need to depend on webauthn-server-parent directly.

BouncyCastle dependency is now optional.

In order to opt out, depend on `webauthn-server-core-minimal` instead of
`webauthn-server-core`.
This is not recommended unless you know your JVM includes JCA providers for
all signature algorithms.

Note that `webauthn-server-attestation` still depends on BouncyCastle.

Jackson deserializer for PublicKeyCredential now allows a rawId property to be present if id is not present, or if rawId equals id.

Updated name of AAGUID 2fc0579f811347eab116bb5a8db9202a to "YubiKey 5/5C NFC"

Changed name of "YubiKey 5 Series security key" to "YubiKey 5 Series"

Fixed crash on unknown attestation statement formats

Disambiguated Jackson deserialization of class AuthenticatorTransport

Class RegisteredCredential can now be serialized to and deserialized from JSON.

Changed dependency declarations to version ranges

Bumped Guava dependency to version [24.1.1,30) in response to CVE-2018-10237

Added new YubiKey AAGUIDs to metadata.json

Bumped Jackson dependency to version 2.11.0 in response to CVEs:

Fixed incorrect JavaDoc on AssertionResult.isSignatureCounterValid(): it will also return true if both counters are zero.

Fixed dependencies missing from release POM metadata

Bumped Jackson dependency to version 2.9.10.3 in response to CVE-2019-20330 and CVE-2020-8840

Bumped Jackson dependency to version 2.9.10.1 which has patched CVE-2019-16942

Fixed bug introduced in 1.4.0, which caused RegistrationResult.attestationMetadata to always be empty.

New enum constant Transport.LIGHTNING

Fixed transports field of YubiKey NEO/NEO-n in metadata.json.

Added YubiKey 5Ci to metadata.json.

Most deviceUrl fields in metadata.json changed to point to stable addresses in Yubico knowledge base instead of dead redirects in store.

RelyingParty now makes an immutable copy of the origins argument, instead of storing a reference to a possibly mutable value.

The enum AuthenticatorTransport has been replaced by a value class containing methods and value constants equivalent to the previous enum.

The return type of PublicKeyCredentialDescriptor.getTransports() is now a SortedSet instead of Set. The builder still accepts a plain Set.

Registration ceremony now verifies that the returned credential public key matches one of the algorithms specified in RelyingParty.preferredPubkeyParams and can be successfully parsed.

Origin matching can now be relaxed via two new RelyingParty options:

allowOriginPort (default false): Allow any port number in the origin

allowOriginSubdomain (default false): Allow any subdomain of any origin listed in RelyingParty.origins

See JavaDoc for details and examples.

The new AuthenticatorTransport can now contain any string value as the transport identifier, as required in the editor’s draft of the L2 spec. See: https://github.com/w3c/webauthn/pull/1275

Added support for RS1 credentials. Registration of RS1 credentials is not enabled by default, but can be enabled by setting RelyingParty.preferredPubKeyCredParams to a list containing PublicKeyCredentialParameters.RS1.

New constant PublicKeyCredentialParameters.RS1

New constant COSEAlgorithmIdentifier.RS1

Fixed dependency declarations so API dependencies are correctly propagated as compile-time dependencies of dependent projects.

Fixed Specification-Version release date in webauthn-server-core jar manifest.

Class com.yubico.internal.util.WebAuthnCodecs is no longer public. The package com.yubico.internal.util was already declared non-public in JavaDoc, but this is now also enforced via Java visibility rules.

Class com.yubico.webauthn.meta.Specification.SpecificationBuilder is no longer public. It was never intended to be, although this was not documented explicitly.

Default value for RelyingParty.preferredPubKeyParams changed from [ES256, RS256] to [ES256, EdDSA, RS256]

Data classes no longer use Optional internally in field types. This should not meaningfully affect the public API, but might improve compatibility with frameworks that use reflection.

Added support for Ed25519 signatures.

New constants COSEAlgorithmIdentifier.EdDSA and PublicKeyCredentialParameters.EdDSA

Artifacts are now built reproducibly; fresh builds from source should now be verifiable by signature files from Maven Central.

Bumped Jackson dependency to version 2.9.9.3 which has patched CVE-2019-12814, CVE-2019-14439, CVE-2019-14379

Bumped Jackson dependency to version 2.9.9 which has patched CVE-2019-12086

New optional parameter timeout added to StartRegistrationOptions and StartAssertionOptions

Fixed polarity error in javadoc for RelyingParty.allowUntrustedAttestation

RSA keys are now supported.

New constructor functions PublicKeyCredential.parseRegistrationResponseJson and .parseAssertionResponseJson

So users don’t have to deal with the `TypeReference`s imposed by the generics, unless they want to.

android-key attestation statements now don’t throw an exception if allowUntrustedAttestation is set to true.

tpm attestation statements now don’t throw an exception if allowUntrustedAttestation is set to true.

AssertionExtensionInputsBuilder.appid(Optional<AppId>) now fails fast if the argument is null

ClientAssertionExtensionOutputsBuilder.appid(Optional<Boolean>) now fails fast if the argument is null

Public API methods that take Optional parameters now come with Optional-less aliases.

Registration no longer fails for unimplemented attestation statement formats if allowUnknownAttestation is set to true.

Fixed URL in artifact POM

Improved a few javadoc wordings

User Presence (UP) is now always required by the spec, not only when UV is not required; implementation updated to reflect this.

Added support for android-safetynet attestation statement format

Implementation updated to reflect Proposed Recommendation version of the spec, released 2019-01-17

Fixed validation of zero-valued assertion signature counter

Classes moved from package com.yubico.webauthn.data to com.yubico.webauthn:

All public classes are now final.

All builders now enforce mandatory arguments at compile time. Some usages may therefore need to adjust the order of calls on the builder instance.

All classes that take collections as constructor (builder) arguments now make shallow copies of those collections, so that mutations of the collections don’t propagate into the class instance.

Deleted interface Crypto and constructor parameter crypto of RelyingParty

Deleted interface ChallengeGenerator and constructor parameter challengeGenerator of RelyingParty

Updated implementation to agree with current editor’s draft of the spec

Renamed class AuthenticationDataFlags to AuthenticatorDataFlags

Deleted constant UserVerificationRequirement.DEFAULT

Deleted method AttestationObject.getAuthData()

Changed type of field RelyingParty.origins from List to Set

Fixed (reduced) visibility of RegisteredCredential fields

Class MetadataObject moved to webauthn-server-attestation module

Updated and greatly expanded Javadoc

Constructor parameter pubKeyCredParams of RelyingParty is now optional with a default value.

Constructor parameter origins of RelyingParty is now optional and defaults to a list whose only element is the RP ID prefixed with https://.

All classes with a builder now also have a .toBuilder() method.

Field StartRegistrationOptions.requireResidentKey: boolean replaced with field authenticatorSelection: Optional<AuthenticatorSelectionCriteria>

Major API overhaul; public API changes include but are not limited to:

Fixed a bug in AuthenticatorDataFlags that caused the ED (0x80) flag to never be set

All classes in com.yubico.webauthn.data can now be serialized and deserialized using Jackson

New methods ByteArray.size(): int and .isEmpty(): boolean

ByteArray is now Comparable to itself

Added support for appid extension

Core library now recognises username as an internally relevant concept

Source code translated from Scala to Java

Too many other changes to count

First release of Web Authentication support

Merged U2F subprojects into webauthn-server-core and deleted lots of unused code

Overhauled exception hierarchy

DeviceRegistration.getAttestationCertificate() now returns null instead of throwing NoSuchFieldException

static ClientData.getString(JsonNode, String) now throws U2fBadInputException instead of NullPointerException, or if the returned field is not a String value

Some `AssertionError`s and `IllegalArgumentException`s are now `U2fBadInputException`s instead

BouncyCastleCrypto now throws more descriptive exceptions

Improved error handling in client data input validation

Lombok now longer leaks into runtime dependencies

u2flib-server-attestation module now uses SLF4J logging instead of Throwable.printStackTrace

Changed demo server URL to localhost:8080.

Added the method ClientData.getString to get arbitrary clientData fields.

Added u2flib-server-attestation for device attestation and metadata.

Added built-in support for multiple devices per user.

Fixed demo server bug when running from jar. Thanks to axianx.