cryptohome/flatbuffer_schemas/auth_block_state.fbs

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

include "structures.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_;

// Defined the attributes that may be used in this schema file.
attribute "optional";
attribute "secure";
attribute "serializable";

// Fields in AuthBlockState are all marked optional because they can be read
// from objects stored on disk, such as the SerializedVaultKeyset. As a result
// cryptohome cannot assume all fields are always populated. However, the
// fields should always be defined or the auth block cannot operate.

table TpmNotBoundToPcrAuthBlockState (secure) {
  // Marks if the password is run through scrypt before going to the TPM.
  scrypt_derived:bool = null (id: 0);
  // The salt used to bind to the TPM.
  // Must be set.
  salt:[ubyte] (id: 1, optional);
  // Optional, the number of rounds key derivation is called.
  // This is only used for legacy non-scrypt key derivation.
  password_rounds:uint = null (id: 2, optional);
  // The VKK wrapped with the user's password by the tpm.
  // Must be set.
  tpm_key:[ubyte] (id: 3,  optional);
  // Optional, served as a TPM identity, useful when checking if the TPM is
  // the same one sealed the tpm_key.
  tpm_public_key_hash:[ubyte] (id: 4, optional);
}

table TpmBoundToPcrAuthBlockState (secure) {
  // Marks if the password is run through scrypt before going to the TPM.
  scrypt_derived:bool = null (id: 0);
  // The salt used to bind to the TPM.
  salt:[ubyte] (id: 1, optional);
  // The VKK wrapped with the user's password by the tpm.
  tpm_key:[ubyte] (id: 2, optional);
  // Same as tpm_key, but extends the PCR to only allow one user until reboot.
  extended_tpm_key:[ubyte] (id: 3, optional);
  // Optional, served as a TPM identity, useful when checking if the TPM is
  // the same one sealed the tpm_key.
  tpm_public_key_hash:[ubyte] (id: 4, optional);
}

table PinWeaverAuthBlockState (secure) {
  // The label for the credential in the LE hash tree.
  le_label:ulong = null (id: 0, optional);
  // The salt used to first scrypt the user input.
  salt:[ubyte] (id: 1, optional);
  // The IV used to derive the chaps key.
  chaps_iv:[ubyte] (id: 2, optional);
  // The IV used to derive the file encryption key.
  // TODO(b/204202689): rename fek_iv to vkk_iv.
  fek_iv:[ubyte] (id: 3, optional);
}

// This is a unique AuthBlockState for backwards compatibility. libscrypt puts
// the metadata, such as IV and salt, into the header of the encrypted
// buffer. Thus this is the only auth block state to pass wrapped secrets. See
// the LibScryptCompatAuthBlock header for a full explanation.
table LibScryptCompatAuthBlockState (secure) {
  // The wrapped filesystem keys.
  // This is for in memory data holding only and will not be serialized.
  wrapped_keyset:[ubyte] (id: 0, optional);
  // The wrapped chaps keys.
  // This is for in memory data holding only and will not be serialized.
  wrapped_chaps_key:[ubyte] (id: 1, optional);
  // The wrapped reset seed keys.
  // This is for in memory data holding only and will not be serialized.
  wrapped_reset_seed:[ubyte] (id: 2, optional);
  // The random salt.
  // TODO(b/198394243): We should remove it because it's not actually used.
  salt:[ubyte] (id: 3, optional);
}

table ChallengeCredentialAuthBlockState (secure) {
  scrypt_state:LibScryptCompatAuthBlockState (id: 0);
  keyset_challenge_info:cryptohome.structure._serialized_.SignatureChallengeInfo (id: 1, optional);
}

table DoubleWrappedCompatAuthBlockState (secure) {
  scrypt_state:LibScryptCompatAuthBlockState (id: 0);
  tpm_state:TpmNotBoundToPcrAuthBlockState (id: 1);
}

table CryptohomeRecoveryAuthBlockState (secure) {
  // HSM Payload is created at onboarding and contains all the data that are
  // persisted on a chromebook and will be eventually used for recovery,
  // serialized to CBOR.
  hsm_payload:[ubyte] (id: 0, optional);
  // The salt used to first scrypt the user input.
  salt:[ubyte] (id: 1, optional);
  // Secret share of the destination (plaintext).
  // TODO(b/184924489): store encrypted destination share.
  plaintext_destination_share:[ubyte] (id: 2, optional);
  // Channel keys that will be used for secure communication during recovery.
  // TODO(b/196192089): store encrypted keys.
  channel_pub_key:[ubyte] (id: 3, optional);
  channel_priv_key:[ubyte] (id: 4, optional);
}

table TpmEccAuthBlockState (secure) {
  // The salt used to derive the user input with scrypt.
  salt:[ubyte] (id: 0, optional);
  // The IV to decrypt EVK.
  vkk_iv:[ubyte] (id: 1, optional);
  // The number of rounds the auth value generating process is called.
  auth_value_rounds:uint = null (id: 2, optional);
  // HVKKM: Hardware Vault Keyset Key Material.
  // SVKKM: Software Vault Keyset Key Material.
  // We would use HVKKM and SVKKM to derive the VKK.
  // The HVKKM are encrypted with the user's password, TPM, and binds to empty
  // current user state.
  sealed_hvkkm:[ubyte] (id: 3, optional);
  // Same as |sealed_hvkkm|, but extends the current user state to the specific
  // user.
  extended_sealed_hvkkm:[ubyte] (id: 4, optional);
  // A check if this is the same TPM that wrapped the credential.
  tpm_public_key_hash:[ubyte] (id: 5, optional);
  // The wrapped reset seed to reset LE credentials.
  wrapped_reset_seed:[ubyte] (id: 6, optional);
}

union AuthBlockStateUnion (secure) {
  TpmBoundToPcrAuthBlockState,
  TpmNotBoundToPcrAuthBlockState,
  PinWeaverAuthBlockState,
  LibScryptCompatAuthBlockState,
  ChallengeCredentialAuthBlockState,
  DoubleWrappedCompatAuthBlockState,
  CryptohomeRecoveryAuthBlockState,
  TpmEccAuthBlockState
}

table RevocationState (secure) {
  // The label for the credential in the LE hash tree.
  le_label:ulong = null (id: 0, optional);
}

table AuthBlockState (serializable, secure) {
  state:AuthBlockStateUnion (id:1);
  revocation_state:RevocationState (id: 2, optional);
}

root_type AuthBlockState;