com.yubico.webauthn.data.PublicKeyCredential Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of webauthn-server-core Show documentation
Yubico WebAuthn server core API
The newest version!
// 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.data;

import com.fasterxml.jackson.annotation.JsonCreator;
import com.fasterxml.jackson.annotation.JsonProperty;
import com.fasterxml.jackson.core.type.TypeReference;
import com.yubico.internal.util.JacksonCodecs;
import com.yubico.webauthn.AssertionResult;
import com.yubico.webauthn.FinishAssertionOptions;
import com.yubico.webauthn.FinishRegistrationOptions;
import com.yubico.webauthn.RegistrationResult;
import com.yubico.webauthn.RelyingParty;
import java.io.IOException;
import java.util.Optional;
import lombok.AllArgsConstructor;
import lombok.Builder;
import lombok.NonNull;
import lombok.Value;

/**
 * The PublicKeyCredential interface inherits from Credential [CREDENTIAL-MANAGEMENT-1], and contains
 * the attributes that are returned to the caller when a new credential is created, or a new
 * assertion is requested.
 *
 * @see §5.1.
 *     PublicKeyCredential Interface
 */
@Value
@Builder(toBuilder = true)
public class PublicKeyCredential<
    A extends AuthenticatorResponse, B extends ClientExtensionOutputs> {

  /**
   * The raw Credential ID of this credential, corresponding to the rawId attribute in
   * the WebAuthn API.
   */
  @NonNull private final ByteArray id;

  /**
   * The authenticator's response to the client’s request to either create a public key credential,
   * or generate an authentication assertion.
   *
   * If the {@link PublicKeyCredential} was created in response to 
   * navigator.credentials.create(), this attribute’s value will be an {@link
   * AuthenticatorAttestationResponse}, otherwise, the {@link PublicKeyCredential} was created in
   * response to navigator.credentials.get(), and this attribute’s value will be an
   * {@link AuthenticatorAssertionResponse}.
   */
  @NonNull private final A response;

  private final AuthenticatorAttachment authenticatorAttachment;

  /**
   * A map containing extension identifier → client extension output entries produced by the
   * extension’s client extension processing.
   */
  @NonNull private final B clientExtensionResults;

  /** The {@link PublicKeyCredential}'s type value is the string "public-key". */
  @NonNull @Builder.Default
  private final PublicKeyCredentialType type = PublicKeyCredentialType.PUBLIC_KEY;

  @JsonCreator
  private PublicKeyCredential(
      @JsonProperty("id") ByteArray id,
      @JsonProperty("rawId") ByteArray rawId,
      @NonNull @JsonProperty("response") A response,
      @JsonProperty("authenticatorAttachment") AuthenticatorAttachment authenticatorAttachment,
      @NonNull @JsonProperty("clientExtensionResults") B clientExtensionResults,
      @NonNull @JsonProperty("type") PublicKeyCredentialType type) {
    if (id == null && rawId == null) {
      throw new NullPointerException("At least one of \"id\" and \"rawId\" must be non-null.");
    }
    if (id != null && rawId != null && !id.equals(rawId)) {
      throw new IllegalArgumentException(
          String.format("\"id\" and \"rawId\" are not equal: %s != %s", id, rawId));
    }

    this.id = id == null ? rawId : id;
    this.response = response;
    this.authenticatorAttachment = authenticatorAttachment;
    this.clientExtensionResults = clientExtensionResults;
    this.type = type;
  }

  private PublicKeyCredential(
      ByteArray id,
      @NonNull A response,
      AuthenticatorAttachment authenticatorAttachment,
      @NonNull B clientExtensionResults,
      @NonNull PublicKeyCredentialType type) {
    this(id, null, response, authenticatorAttachment, clientExtensionResults, type);
  }

  /**
   * The authenticator
   * attachment modality in effect at the time the credential was created or used.
   *
   * 
If parsed from JSON, this will be present if and only if the input was a valid value of
   * {@link AuthenticatorAttachment}.
   *
   * 
The same value will also be available via {@link
   * RegistrationResult#getAuthenticatorAttachment()} or {@link
   * AssertionResult#getAuthenticatorAttachment()} on the result from {@link
   * RelyingParty#finishRegistration(FinishRegistrationOptions)} or {@link
   * RelyingParty#finishAssertion(FinishAssertionOptions)}.
   *
   * @see RegistrationResult#getAuthenticatorAttachment()
   * @see AssertionResult#getAuthenticatorAttachment()
   * @deprecated EXPERIMENTAL: This feature is from a not yet mature standard; it could change as
   *     the standard matures.
   */
  @Deprecated
  public Optional getAuthenticatorAttachment() {
    return Optional.ofNullable(authenticatorAttachment);
  }

  public static 
      PublicKeyCredentialBuilder.MandatoryStages builder() {
    return new PublicKeyCredentialBuilder().start();
  }

  public static class PublicKeyCredentialBuilder<
      A extends AuthenticatorResponse, B extends ClientExtensionOutputs> {
    private MandatoryStages start() {
      return new MandatoryStages(this);
    }

    @AllArgsConstructor
    public class MandatoryStages {
      private final PublicKeyCredentialBuilder builder;

      /**
       * {@link PublicKeyCredentialBuilder#id(ByteArray) id} is a required parameter.
       *
       * @see PublicKeyCredentialBuilder#id(ByteArray)
       */
      public Step2 id(ByteArray id) {
        builder.id(id);
        return new Step2();
      }

      public class Step2 {
        /**
         * {@link PublicKeyCredentialBuilder#response(AuthenticatorResponse) response} is a required
         * parameter.
         *
         * @see PublicKeyCredentialBuilder#response(AuthenticatorResponse)
         */
        public Step3 response(A response) {
          builder.response(response);
          return new Step3();
        }
      }

      public class Step3 {
        /**
         * {@link PublicKeyCredentialBuilder#clientExtensionResults(ClientExtensionOutputs)
         * clientExtensionResults} is a required parameter.
         *
         * @see PublicKeyCredentialBuilder#clientExtensionResults(ClientExtensionOutputs)
         */
        public PublicKeyCredentialBuilder clientExtensionResults(B clientExtensionResults) {
          return builder.clientExtensionResults(clientExtensionResults);
        }
      }
    }
  }

  /**
   * Parse a {@link PublicKeyCredential} object from JSON.
   *
   * 
The json should be of the following format:
   *
   * 
   * {
   *   "id": "(resp.id)",
   *   "response": {
   *     "attestationObject": "(Base64Url encoded resp.attestationObject)",
   *     "clientDataJSON": "(Base64Url encoded resp.clientDataJSON)"
   *   },
   *   "clientExtensionResults": { (resp.getClientExtensionResults()) },
   *   "type": "public-key"
   * }
   * 

   *
   * 
   *   resp:
   *   The PublicKeyCredential
   *       object returned from a registration ceremony.
   *   
id:
   *   
The string value of resp.id
   *   
response.attestationObject:
   *   
The value of resp.attestationObject, Base64Url encoded as a string
   *   
response.clientDataJSON:
   *   
The value of resp.clientDataJSON, Base64Url encoded as a string
   *   
clientExtensionResults:
   *   
The return value of resp.getClientExtensionResults()
   *   
type:
   *   
The literal string value "public-key"
   * 
   *
   * @param json a JSON string of the above format
   * @throws IOException if the json is invalid or cannot be decoded as a {@link
   *     PublicKeyCredential}
   */
  public static PublicKeyCredential<
          AuthenticatorAttestationResponse, ClientRegistrationExtensionOutputs>
      parseRegistrationResponseJson(String json) throws IOException {
    return JacksonCodecs.json()
        .readValue(
            json,
            new TypeReference<
                PublicKeyCredential<
                    AuthenticatorAttestationResponse, ClientRegistrationExtensionOutputs>>() {});
  }

  /**
   * Parse a {@link PublicKeyCredential} object from JSON.
   *
   * The json should be of the following format:
   *
   * 
   * {
   *   "id": "(resp.id)",
   *   "response": {
   *     "authenticatorData": "(Base64Url encoded resp.authenticatorData)",
   *     "signature": "(Base64Url encoded resp.signature)",
   *     "clientDataJSON": "(Base64Url encoded resp.clientDataJSON)",
   *     "userHandle": "(null, undefined or Base64Url encoded resp.userHandle)"
   *   },
   *   "clientExtensionResults": { (resp.getClientExtensionResults()) },
   *   "type": "public-key"
   * }
   * 
   *
   * 
   *   resp:
   *   
The PublicKeyCredential
   *       object returned from an authentication ceremony.
   *   
id:
   *   
The string value of resp.id
   *   
response.authenticatorData:
   *   
The value of resp.authenticatorData, Base64Url encoded as a string
   *   
response.signature:
   *   
The value of resp.signature, Base64Url encoded as a string
   *   
response.clientDataJSON:
   *   
The value of resp.clientDataJSON, Base64Url encoded as a string
   *   
response.userHandle:
   *   
The value of resp.userHandle Base64Url encoded as a string if present,
   *       otherwise null or undefined
   *   
clientExtensionResults:
   *   
The return value of resp.getClientExtensionResults()
   *   
type:
   *   
The literal string value "public-key"
   * 
   *
   * @param json a JSON string of the above format
   * @throws IOException if the json is invalid or cannot be decoded as a {@link
   *     PublicKeyCredential}
   */
  public static PublicKeyCredential
      parseAssertionResponseJson(String json) throws IOException {
    return JacksonCodecs.json()
        .readValue(
            json,
            new TypeReference<
                PublicKeyCredential<
                    AuthenticatorAssertionResponse, ClientAssertionExtensionOutputs>>() {});
  }
}