cryptohome/flatbuffer_schemas/auth_factor.fbs

// Copyright 2021 The Chromium Authors
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

include "cryptohome/flatbuffer_schemas/auth_block_state.fbs";

// Our Python generator removes the "_serialized_" namespace when generating
// the code, to avoid symbol clash with the code generated by flatc.
namespace cryptohome._serialized_;

attribute "serializable";

// The lockout mechanism user per AuthFactor.
enum SerializedLockoutPolicy : int {
  // Default.
  UNKNOWN = 0,
  // No lockout policy, and is the ideal for most factors,
  // but needs to be explicitly set.
  NO_LOCKOUT = 1,
  // Attempt limited policy is enforces an absolute number
  // of consecutive wrong attempts a factor can have before
  // it is locked out.
  ATTEMPT_LIMITED = 2,
  // Time limited auth factors will unlock themselves
  // automatically after a certain timeout.
  TIME_LIMITED = 3,
}

// Refer to the KnowledgeFactorHashAlgorithm proto.
enum SerializedKnowledgeFactorHashAlgorithm : int {
  // Used for hashing PINs in Chrome.
  PBKDF2_AES256_1234 = 1,

  // Used for hashing passwords in Chrome.
  SHA256_TOP_HALF = 2,
}

// Refer to the KnowledgeFactorHashInfo proto.
table SerializedKnowledgeFactorHashInfo {
  // This field should always be non-null in practice.
  algorithm:SerializedKnowledgeFactorHashAlgorithm = null (id:0);
  salt:[ubyte] (id:1);
  should_generate_key_store:bool = null (id:2);
}

// Metadata common to all auth factors.
table CommonMetadata {
  // ChromeOS version.
  // Contains CHROMEOS_RELEASE_VERSION from /etc/lsb-release.
  // See: https://chromium.googlesource.com/chromiumos/docs/+/HEAD/os_config.md
  // Captured whenever the serialized factor is created or updated.
  chromeos_version_last_updated:string (id:0);
  // Chrome version.
  // The format is defined by and the value supplied by the client.
  // Captured whenever the serialized factor is created or updated.
  chrome_version_last_updated:string (id:1);
  // Each factor needs to define its lockout policy.
  // For most factors, it is currenlty NO_LOCKOUT.
  lockout_policy:SerializedLockoutPolicy = null (id:2);
  // User supplied name of each auth factor.
  // This is supplied by client, updated through Add/Update requests.
  user_specified_name:string (id:3);
}

// Metadata for a `PASSWORD` auth factor.
table PasswordMetadata {
  hash_info:SerializedKnowledgeFactorHashInfo (id:0, optional);
}

// Metadata for a `PIN` auth factor.
table PinMetadata {
  hash_info:SerializedKnowledgeFactorHashInfo (id:0, optional);
}

// Metadata for a `Recovery` auth factor.
table CryptohomeRecoveryMetadata {
  // Public key of the mediator for Cryptohome recovery flow.
  mediator_pub_key:[ubyte] (id: 0);
}

// Metadata for a `KIOSK` auth factor.
table KioskMetadata {}

// Metadata for a "Smart Card" auth factor.
table SmartCardMetadata {
  // DER-encoded blob of the X.509 Subject Public Key Info.
  public_key_spki_der:[ubyte] (id: 0);
}

// Metadata for a `Fingerprint` auth factor.
table FingerprintMetadata {
  // Set to true when migrated from a legacy fingerprint template.
  was_migrated:bool = null (id: 0);
}

// Union that holds the auth factor's type-specific metadata.
union TypeSpecificMetadata {
  PasswordMetadata,
  PinMetadata,
  CryptohomeRecoveryMetadata,
  KioskMetadata,
  SmartCardMetadata,
  FingerprintMetadata
}

// Container that stores information about auth factor to be persisted on disk.
table SerializedAuthFactor (serializable) {
  auth_block_state:AuthBlockState (id: 0);
  metadata:TypeSpecificMetadata (id: 2);
  common_metadata:CommonMetadata (id: 3);
}

root_type SerializedAuthFactor;