com.yubico.webauthn.AssertionResult Maven / Gradle / Ivy
Show all versions of webauthn-server-core Show documentation
// Copyright (c) 2018, Yubico AB
// All rights reserved.
//
// Redistribution and use in source and binary forms, with or without
// modification, are permitted provided that the following conditions are met:
//
// 1. Redistributions of source code must retain the above copyright notice, this
// list of conditions and the following disclaimer.
//
// 2. Redistributions in binary form must reproduce the above copyright notice,
// this list of conditions and the following disclaimer in the documentation
// and/or other materials provided with the distribution.
//
// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
// DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
// FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
// DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
// SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
// CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
// OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
package com.yubico.webauthn;
import com.fasterxml.jackson.annotation.JsonCreator;
import com.fasterxml.jackson.annotation.JsonIgnore;
import com.fasterxml.jackson.annotation.JsonProperty;
import com.yubico.webauthn.data.AuthenticatorAssertionExtensionOutputs;
import com.yubico.webauthn.data.AuthenticatorAssertionResponse;
import com.yubico.webauthn.data.AuthenticatorAttachment;
import com.yubico.webauthn.data.AuthenticatorData;
import com.yubico.webauthn.data.AuthenticatorDataFlags;
import com.yubico.webauthn.data.AuthenticatorResponse;
import com.yubico.webauthn.data.ByteArray;
import com.yubico.webauthn.data.ClientAssertionExtensionOutputs;
import com.yubico.webauthn.data.PublicKeyCredential;
import com.yubico.webauthn.data.PublicKeyCredentialRequestOptions;
import com.yubico.webauthn.data.UserIdentity;
import java.util.Optional;
import lombok.AccessLevel;
import lombok.Getter;
import lombok.NonNull;
import lombok.Value;
/** The result of a call to {@link RelyingParty#finishAssertion(FinishAssertionOptions)}. */
@Value
public class AssertionResult {
/** true if the assertion was verified successfully. */
private final boolean success;
@JsonProperty
@Getter(AccessLevel.NONE)
private final PublicKeyCredential
credentialResponse;
/**
* The {@link RegisteredCredential} that was returned by {@link
* CredentialRepository#lookup(ByteArray, ByteArray)} and whose public key was used to
* successfully verify the assertion signature.
*
* NOTE: The {@link RegisteredCredential#getSignatureCount() signature count}, {@link
* RegisteredCredential#isBackupEligible() backup eligibility} and {@link
* RegisteredCredential#isBackedUp() backup state} properties in this object will reflect the
* state before the assertion operation, not the new state. When updating your database
* state, use the signature counter and backup state from {@link #getSignatureCount()}, {@link
* #isBackupEligible()} and {@link #isBackedUp()} instead.
*/
private final RegisteredCredential credential;
/**
* The username of the authenticated user.
*
* @see #getUserHandle()
*/
@NonNull private final String username;
/**
* true if and only if at least one of the following is true:
*
*
* - The {@link AuthenticatorData#getSignatureCounter() signature counter value} in the
* assertion was strictly greater than {@link RegisteredCredential#getSignatureCount() the
* stored one}.
*
- The {@link AuthenticatorData#getSignatureCounter() signature counter value} in the
* assertion and {@link RegisteredCredential#getSignatureCount() the stored one} were both
* zero.
*
*
* @see §6.1.
* Authenticator Data
* @see AuthenticatorData#getSignatureCounter()
* @see RegisteredCredential#getSignatureCount()
* @see com.yubico.webauthn.RelyingParty.RelyingPartyBuilder#validateSignatureCounter(boolean)
*/
private final boolean signatureCounterValid;
@JsonCreator
AssertionResult(
@JsonProperty("success") boolean success,
@NonNull @JsonProperty("credentialResponse")
PublicKeyCredential
credentialResponse,
@NonNull @JsonProperty("credential") RegisteredCredential credential,
@NonNull @JsonProperty("username") String username,
@JsonProperty("signatureCounterValid") boolean signatureCounterValid) {
this.success = success;
this.credentialResponse = credentialResponse;
this.credential = credential;
this.username = username;
this.signatureCounterValid = signatureCounterValid;
}
/**
* The credential
* ID of the credential used for the assertion.
*
* @see Credential
* ID
* @see PublicKeyCredentialRequestOptions#getAllowCredentials()
* @deprecated Use {@link #getCredential()}.{@link RegisteredCredential#getCredentialId()
* getCredentialId()} instead.
*/
@Deprecated
@JsonIgnore
public ByteArray getCredentialId() {
return credential.getCredentialId();
}
/**
* The user handle
* of the authenticated user.
*
* @see User Handle
* @see UserIdentity#getId()
* @see #getUsername()
* @deprecated Use {@link #getCredential()}.{@link RegisteredCredential#getUserHandle()
* getUserHandle()} instead.
*/
@Deprecated
@JsonIgnore
public ByteArray getUserHandle() {
return credential.getUserHandle();
}
/**
* Check whether the user
* verification as performed during the authentication ceremony.
*
* This flag is also available via
* {@link PublicKeyCredential}.{@link PublicKeyCredential#getResponse() getResponse()}.{@link AuthenticatorResponse#getParsedAuthenticatorData() getParsedAuthenticatorData()}.{@link AuthenticatorData#getFlags() getFlags()}.{@link AuthenticatorDataFlags#UV UV}
* .
*
* @return true if and only if the authenticator claims to have performed user
* verification during the authentication ceremony.
* @see User Verification
* @see UV flag in §6.1. Authenticator
* Data
*/
@JsonIgnore
public boolean isUserVerified() {
return credentialResponse.getResponse().getParsedAuthenticatorData().getFlags().UV;
}
/**
* Check whether the asserted credential is backup eligible, using the BE flag in the authenticator data.
*
*
You SHOULD store this value in your representation of the corresponding {@link
* RegisteredCredential} if no value is stored yet. {@link CredentialRepository} implementations
* SHOULD set this value as the {@link
* RegisteredCredential.RegisteredCredentialBuilder#backupEligible(Boolean)
* backupEligible(Boolean)} value when reconstructing that {@link RegisteredCredential}.
*
* @return true if and only if the created credential is backup eligible. NOTE that
* this is only a hint and not a guarantee, unless backed by a trusted authenticator
* attestation.
* @see Backup Eligible in §4.
* Terminology
* @see BE flag in §6.1. Authenticator
* Data
* @deprecated EXPERIMENTAL: This feature is from a not yet mature standard; it could change as
* the standard matures.
*/
@Deprecated
@JsonIgnore
public boolean isBackupEligible() {
return credentialResponse.getResponse().getParsedAuthenticatorData().getFlags().BE;
}
/**
* Get the current backup state of the
* asserted credential, using the BS
* flag in the authenticator data.
*
*
You SHOULD update this value in your representation of a {@link RegisteredCredential}.
* {@link CredentialRepository} implementations SHOULD set this value as the {@link
* RegisteredCredential.RegisteredCredentialBuilder#backupState(Boolean) backupState(Boolean)}
* value when reconstructing that {@link RegisteredCredential}.
*
* @return true if and only if the created credential is believed to currently be
* backed up. NOTE that this is only a hint and not a guarantee, unless backed by a trusted
* authenticator attestation.
* @see Backup State in §4. Terminology
* @see BS flag in §6.1. Authenticator
* Data
* @deprecated EXPERIMENTAL: This feature is from a not yet mature standard; it could change as
* the standard matures.
*/
@Deprecated
@JsonIgnore
public boolean isBackedUp() {
return credentialResponse.getResponse().getParsedAuthenticatorData().getFlags().BS;
}
/**
* The authenticator
* attachment modality in effect at the time the asserted credential was used.
*
* @see PublicKeyCredential#getAuthenticatorAttachment()
* @deprecated EXPERIMENTAL: This feature is from a not yet mature standard; it could change as
* the standard matures.
*/
@Deprecated
@JsonIgnore
public Optional getAuthenticatorAttachment() {
return credentialResponse.getAuthenticatorAttachment();
}
/**
* The new signature
* count of the credential used for the assertion.
*
* You should update this value in your database.
*
* @see AuthenticatorData#getSignatureCounter()
*/
@JsonIgnore
public long getSignatureCount() {
return credentialResponse.getResponse().getParsedAuthenticatorData().getSignatureCounter();
}
/**
* The client
* extension outputs, if any.
*
*
This is present if and only if at least one extension output is present in the return value.
*
* @see §9.4.
* Client Extension Processing
* @see ClientAssertionExtensionOutputs
* @see #getAuthenticatorExtensionOutputs() ()
*/
@JsonIgnore
public Optional getClientExtensionOutputs() {
return Optional.of(credentialResponse.getClientExtensionResults())
.filter(ceo -> !ceo.getExtensionIds().isEmpty());
}
/**
* The authenticator
* extension outputs, if any.
*
* This is present if and only if at least one extension output is present in the return value.
*
* @see §9.5.
* Authenticator Extension Processing
* @see AuthenticatorAssertionExtensionOutputs
* @see #getClientExtensionOutputs()
*/
@JsonIgnore
public Optional getAuthenticatorExtensionOutputs() {
return AuthenticatorAssertionExtensionOutputs.fromAuthenticatorData(
credentialResponse.getResponse().getParsedAuthenticatorData());
}
}