Package com.yubico.webauthn

Class RelyingPartyV2.RelyingPartyV2Builder<C extends CredentialRecord>

java.lang.Object

com.yubico.webauthn.RelyingPartyV2.RelyingPartyV2Builder<C>

Enclosing class:

RelyingPartyV2<C extends CredentialRecord>

public static class RelyingPartyV2.RelyingPartyV2Builder<C extends CredentialRecord>
extends Object

Method Summary

Modifier and Type	Method	Description
RelyingPartyV2.RelyingPartyV2Builder<C>	allowOriginPort(boolean allowOriginPort)	If true, the origin matching rule is relaxed to allow any port number.
RelyingPartyV2.RelyingPartyV2Builder<C>	allowOriginSubdomain(boolean allowOriginSubdomain)	If true, the origin matching rule is relaxed to allow any subdomain, of any depth, of the values of origins.
RelyingPartyV2.RelyingPartyV2Builder<C>	allowUntrustedAttestation(boolean allowUntrustedAttestation)	If false, finishRegistration will only allow registrations where the attestation signature can be linked to a trusted attestation root.
RelyingPartyV2.RelyingPartyV2Builder<C>	appId(@NonNull AppId appId)	The extension input to set for the appid and appidExclude extensions.
RelyingPartyV2.RelyingPartyV2Builder<C>	appId(@NonNull Optional<AppId> appId)	The extension input to set for the appid and appidExclude extensions.
RelyingPartyV2.RelyingPartyV2Builder<C>	attestationConveyancePreference(@NonNull AttestationConveyancePreference attestationConveyancePreference)	The argument for the attestation parameter in registration operations.
RelyingPartyV2.RelyingPartyV2Builder<C>	attestationConveyancePreference(@NonNull Optional<AttestationConveyancePreference> attestationConveyancePreference)	The argument for the attestation parameter in registration operations.
RelyingPartyV2.RelyingPartyV2Builder<C>	attestationTrustSource(@NonNull AttestationTrustSource attestationTrustSource)	An AttestationTrustSource instance to use for looking up trust roots for authenticator attestation.
RelyingPartyV2.RelyingPartyV2Builder<C>	attestationTrustSource(@NonNull Optional<AttestationTrustSource> attestationTrustSource)	An AttestationTrustSource instance to use for looking up trust roots for authenticator attestation.
RelyingPartyV2<C>	build()
RelyingPartyV2.RelyingPartyV2Builder<C>	clock(@NonNull Clock clock)	A Clock which will be used to tell the current time while verifying attestation certificate chains.
RelyingPartyV2.RelyingPartyV2Builder<C>	credentialRepository(@NonNull CredentialRepositoryV2<C> credentialRepository)	An abstract database which can look up credentials, usernames and user handles from usernames, user handles and credential IDs.
RelyingPartyV2.RelyingPartyV2Builder<C>	identity(@NonNull RelyingPartyIdentity identity)	The RelyingPartyIdentity that will be set as the rp parameter when initiating registration operations, and which AuthenticatorData.getRpIdHash() will be compared against.
RelyingPartyV2.RelyingPartyV2Builder<C>	origins(@NonNull Optional<Set<String>> origins)	The allowed origins that returned authenticator responses will be compared against.
RelyingPartyV2.RelyingPartyV2Builder<C>	origins(@NonNull Set<String> origins)	The allowed origins that returned authenticator responses will be compared against.
RelyingPartyV2.RelyingPartyV2Builder<C>	preferredPubkeyParams(@NonNull List<PublicKeyCredentialParameters> preferredPubkeyParams)	The argument for the pubKeyCredParams parameter in registration operations.
String	toString()
RelyingPartyV2.RelyingPartyV2Builder<C>	usernameRepository(UsernameRepository usernameRepository)	Deprecated. EXPERIMENTAL: This is an experimental feature.
RelyingPartyV2.RelyingPartyV2Builder<C>	validateSignatureCounter(boolean validateSignatureCounter)	If true, finishAssertion will succeed only if the signature counter value in the response is strictly greater than the stored signature counter value, or if both counters are exactly zero.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Method Details

origins

public RelyingPartyV2.RelyingPartyV2Builder<C> origins(@NonNull
 @NonNull Set<String> origins)

The allowed origins that returned authenticator responses will be compared against.

The default is the set containing only the string "https://" + RelyingPartyV2.getIdentity().getId().

If allowOriginPort and allowOriginSubdomain are both false (the default), then a successful registration or authentication operation requires CollectedClientData.getOrigin() to exactly equal one of these values.

If allowOriginPort is true , then the above rule is relaxed to allow any port number in CollectedClientData.getOrigin(), regardless of any port specified.

If allowOriginSubdomain is true, then the above rule is relaxed to allow any subdomain, of any depth, of any of these values.

For either of the above relaxations to take effect, both the allowed origin and the client data origin must be valid URLs. Origins that are not valid URLs are matched only by exact string equality.

Since:

2.7.0

See Also:

• RelyingPartyV2.getIdentity()
• origins(Optional)

origins

public RelyingPartyV2.RelyingPartyV2Builder<C> origins(@NonNull
 @NonNull Optional<Set<String>> origins)

The allowed origins that returned authenticator responses will be compared against.

If set to empty, this setting reverts to the default value.

The default is the set containing only the string "https://" + RelyingPartyV2.getIdentity().getId().

If allowOriginPort and allowOriginSubdomain are both false (the default), then a successful registration or authentication operation requires CollectedClientData.getOrigin() to exactly equal one of these values.

If allowOriginPort is true , then the above rule is relaxed to allow any port number in CollectedClientData.getOrigin(), regardless of any port specified.

If allowOriginSubdomain is true, then the above rule is relaxed to allow any subdomain, of any depth, of any of these values.

For either of the above relaxations to take effect, both the allowed origin and the client data origin must be valid URLs. Origins that are not valid URLs are matched only by exact string equality.

Since:

2.7.0

See Also:

• RelyingPartyV2.getIdentity()
• origins(Set)

appId

public RelyingPartyV2.RelyingPartyV2Builder<C> appId(@NonNull
 @NonNull Optional<AppId> appId)

The extension input to set for the appid and appidExclude extensions.

You do not need this extension if you have not previously supported U2F. Its purpose is to make already-registered U2F credentials forward-compatible with the WebAuthn API. It is not needed for new registrations, even of U2F authenticators.

If this member is set, startAssertion will automatically set the appid extension input, and finishAssertion will adjust its verification logic to also accept this AppID as an alternative to the RP ID. Likewise, RelyingPartyV2.startRegistration(StartRegistrationOptions) startRegistration} will automatically set the appidExclude extension input.

By default, this is not set.

See Also:

• AssertionExtensionInputs.getAppid()
• RegistrationExtensionInputs.getAppidExclude()
• §10.1. FIDO AppID Extension (appid)
• §10.2. FIDO AppID Exclusion Extension (appidExclude)

appId

public RelyingPartyV2.RelyingPartyV2Builder<C> appId(@NonNull
 @NonNull AppId appId)

The extension input to set for the appid and appidExclude extensions.

You do not need this extension if you have not previously supported U2F. Its purpose is to make already-registered U2F credentials forward-compatible with the WebAuthn API. It is not needed for new registrations, even of U2F authenticators.

If this member is set, startAssertion will automatically set the appid extension input, and finishAssertion will adjust its verification logic to also accept this AppID as an alternative to the RP ID. Likewise, RelyingPartyV2.startRegistration(StartRegistrationOptions) startRegistration} will automatically set the appidExclude extension input.

By default, this is not set.

See Also:

• AssertionExtensionInputs.getAppid()
• RegistrationExtensionInputs.getAppidExclude()
• §10.1. FIDO AppID Extension (appid)
• §10.2. FIDO AppID Exclusion Extension (appidExclude)

attestationConveyancePreference

public RelyingPartyV2.RelyingPartyV2Builder<C> attestationConveyancePreference(@NonNull
 @NonNull Optional<AttestationConveyancePreference> attestationConveyancePreference)

The argument for the attestation parameter in registration operations.

Unless your application has a concrete policy for authenticator attestation, it is recommended to leave this parameter undefined.

If you set this, you may want to explicitly set allowUntrustedAttestation and attestationTrustSource too.

By default, this is not set.

See Also:

• PublicKeyCredentialCreationOptions.getAttestation()
• §6.4. Attestation

attestationConveyancePreference

public RelyingPartyV2.RelyingPartyV2Builder<C> attestationConveyancePreference(@NonNull
 @NonNull AttestationConveyancePreference attestationConveyancePreference)

The argument for the attestation parameter in registration operations.

Unless your application has a concrete policy for authenticator attestation, it is recommended to leave this parameter undefined.

If you set this, you may want to explicitly set allowUntrustedAttestation and attestationTrustSource too.

By default, this is not set.

See Also:

• PublicKeyCredentialCreationOptions.getAttestation()
• §6.4. Attestation

attestationTrustSource

public RelyingPartyV2.RelyingPartyV2Builder<C> attestationTrustSource(@NonNull
 @NonNull Optional<AttestationTrustSource> attestationTrustSource)

An AttestationTrustSource instance to use for looking up trust roots for authenticator attestation. This matters only if RelyingPartyV2.getAttestationConveyancePreference() is non-empty and not set to AttestationConveyancePreference.NONE.

By default, this is not set.

See Also:

• PublicKeyCredentialCreationOptions.getAttestation()
• §6.4. Attestation

attestationTrustSource

public RelyingPartyV2.RelyingPartyV2Builder<C> attestationTrustSource(@NonNull
 @NonNull AttestationTrustSource attestationTrustSource)

An AttestationTrustSource instance to use for looking up trust roots for authenticator attestation. This matters only if RelyingPartyV2.getAttestationConveyancePreference() is non-empty and not set to AttestationConveyancePreference.NONE.

By default, this is not set.

See Also:

• PublicKeyCredentialCreationOptions.getAttestation()
• §6.4. Attestation

identity

public RelyingPartyV2.RelyingPartyV2Builder<C> identity(@NonNull
 @NonNull RelyingPartyIdentity identity)

The RelyingPartyIdentity that will be set as the rp parameter when initiating registration operations, and which AuthenticatorData.getRpIdHash() will be compared against. This is a required parameter.

A successful registration or authentication operation requires AuthenticatorData.getRpIdHash() to exactly equal the SHA-256 hash of this member's id member. Alternatively, it may instead equal the SHA-256 hash of appId if the latter is present.

Returns:

this.

See Also:

• RelyingPartyV2.startRegistration(StartRegistrationOptions)
• PublicKeyCredentialCreationOptions

credentialRepository

public RelyingPartyV2.RelyingPartyV2Builder<C> credentialRepository(@NonNull
 @NonNull CredentialRepositoryV2<C> credentialRepository)

An abstract database which can look up credentials, usernames and user handles from usernames, user handles and credential IDs. This is a required parameter.

This is used to look up:

• the user handle for a user logging in via user name
• the user name for a user logging in via user handle
• the credential IDs to include in PublicKeyCredentialCreationOptions.getExcludeCredentials()
• the credential IDs to include in PublicKeyCredentialRequestOptions.getAllowCredentials()
• that the correct user owns the credential when verifying an assertion
• the public key to use to verify an assertion
• the stored signature counter when verifying an assertion

Returns:

this.

usernameRepository

@Deprecated
public RelyingPartyV2.RelyingPartyV2Builder<C> usernameRepository(UsernameRepository usernameRepository)

Deprecated.

EXPERIMENTAL: This is an experimental feature. It is likely to change or be deleted before reaching a mature release.

Enable support for identifying users by username.

If set, then RelyingPartyV2.startAssertion(StartAssertionOptions) allows setting the username parameter when starting an assertion.

By default, this is not set.

Returns:

this.

preferredPubkeyParams

public RelyingPartyV2.RelyingPartyV2Builder<C> preferredPubkeyParams(@NonNull
 @NonNull List<PublicKeyCredentialParameters> preferredPubkeyParams)

The argument for the pubKeyCredParams parameter in registration operations.

This is a list of acceptable public key algorithms and their parameters, ordered from most to least preferred.

The default is the following list, in order:

1. ES256
2. EdDSA
3. ES384
4. ES512
5. Ed448
6. RS256
7. RS384
8. RS512

Returns:

this.

See Also:

• PublicKeyCredentialCreationOptions.getAttestation()
• §6.4. Attestation

allowOriginPort

public RelyingPartyV2.RelyingPartyV2Builder<C> allowOriginPort(boolean allowOriginPort)

If true, the origin matching rule is relaxed to allow any port number.

The default is false.

Examples with origins: ["https://example.org", "https://accounts.example.org", "https://acme.com:8443"]

• allowOriginPort: false

  Accepted:

  • https://example.org
  • https://accounts.example.org
  • https://acme.com:8443

  Rejected:

  • https://example.org:8443
  • https://shop.example.org
  • https://acme.com
  • https://acme.com:9000

• allowOriginPort: true

  Accepted:

  • https://example.org
  • https://example.org:8443
  • https://accounts.example.org
  • https://acme.com
  • https://acme.com:8443
  • https://acme.com:9000

  Rejected:

  • https://shop.example.org

Returns:

this.

allowOriginSubdomain

public RelyingPartyV2.RelyingPartyV2Builder<C> allowOriginSubdomain(boolean allowOriginSubdomain)

If true, the origin matching rule is relaxed to allow any subdomain, of any depth, of the values of origins.

The default is false.

Examples with origins: ["https://example.org", "https://acme.com:8443"]

• allowOriginSubdomain: false

  Accepted:

  • https://example.org
  • https://acme.com:8443

  Rejected:

  • https://example.org:8443
  • https://accounts.example.org
  • https://acme.com
  • https://eu.shop.acme.com:8443

• allowOriginSubdomain: true

  Accepted:

  • https://example.org
  • https://accounts.example.org
  • https://acme.com:8443
  • https://eu.shop.acme.com:8443

  Rejected:

  • https://example.org:8443
  • https://acme.com

Returns:

this.

allowUntrustedAttestation

public RelyingPartyV2.RelyingPartyV2Builder<C> allowUntrustedAttestation(boolean allowUntrustedAttestation)

If false, finishRegistration will only allow registrations where the attestation signature can be linked to a trusted attestation root. This excludes none attestation, and self attestation unless the self attestation key is explicitly trusted.

Regardless of the value of this option, invalid attestation statements of supported formats will always be rejected. For example, a "packed" attestation statement with an invalid signature will be rejected even if this option is set to true.

The default is true.

Returns:

this.

validateSignatureCounter

public RelyingPartyV2.RelyingPartyV2Builder<C> validateSignatureCounter(boolean validateSignatureCounter)

If true, finishAssertion will succeed only if the signature counter value in the response is strictly greater than the stored signature counter value, or if both counters are exactly zero.

The default is true.

Returns:

this.

clock

public RelyingPartyV2.RelyingPartyV2Builder<C> clock(@NonNull
 @NonNull Clock clock)

A Clock which will be used to tell the current time while verifying attestation certificate chains.

This is intended primarily for testing, and relevant only if attestationTrustSource(AttestationTrustSource) is set.

The default is Clock.systemUTC().

Returns:

this.

build

public RelyingPartyV2<C> build()

toString

public String toString()

Overrides:

toString in class Object