cryptohome/vault_keyset.proto

// Copyright (c) 2009 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.

syntax = "proto2";

package cryptohome;

import "key.proto";
import "signature_sealed_data.proto";

message SerializedVaultKeyset {
  enum Flags {
    NONE = 0;
    TPM_WRAPPED = 1;
    SCRYPT_WRAPPED = 2;
    SCRYPT_DERIVED = 4;
    LE_CREDENTIAL = 8;
    // The keyset is encrypted via Scrypt, where the Scrypt KDF passphrase is
    // protected with the signing cryptographic key specified in
    // |signature_challenge_info.public_key_spki_der|. The process of obtaining
    // the KDF passphrase involves signature challenges against this key.
    SIGNATURE_CHALLENGE_PROTECTED = 16;
    // The keyset is valid only for two possible states of PCR. If this flag is
    // set, the tpm_key corresponds to the default PCR state while
    // extended_tpm_key corresponds to the state where PCR is extended by user
    // specific value.
    PCR_BOUND = 32;
  }
  required int32 flags = 1;
  required bytes salt = 2;
  required bytes wrapped_keyset = 3;
  optional bytes tpm_key = 4;
  optional bytes tpm_public_key_hash = 5;
  optional int32 password_rounds = 6;
  // A deprecated field was removed.
  optional int64 last_activity_timestamp = 8;

  // Metadata that should be defined in one file
  // per principal (not per key).
  // TODO(wad) ^^^
  // optional string human_readable_name;
  // required bytes identifier; // Unique to the origin
  // required string origin;
  // optional string idp_uri; // authoritative uri for the key
  // message OptionalMetadata {
  //   required string name = 1;
  //   required bytes value = 2;
  // }
  // repeated OptionalMetadata metadata;

  // This will come from system_api once we're finalized on the API.
  optional KeyData key_data = 9;

  optional bytes wrapped_chaps_key = 10;

  // Used to derive the high entropy reset secret.
  //
  // There is a single reset_seed per user. The reset_seed will be used
  // to generate a reset credential, which is stored in the Low Entropy (LE)
  // credential metadata. Since the reset_seed can be used to unlock
  // previously locked out LE credentials, it has to be stored in encrypted
  // form inside wrapped_reset_seed.
  //
  // We encrypt the reset_seed with the VKK, which is tied to the user
  // phrase. This way, the reset_seed will only be available during
  // sign-in.
  //
  // Once a user signs in, the VaultKeyset will have the unwrapped version,
  // i.e reset_seed.
  //
  // The reset_seed is kept in sync across different Keysets for a particular
  // user. When a new keyset is being added using Homedirs::AddKeyset()
  // we check whether a wrapped_reset_seed is already present in the
  // VaultKeyset. If one exists, we simply re-use it.
  //
  // If a previously created "normal" credential is being used to create
  // an LE credential in AddKeyset(), and it doesn't have a reset_seed,
  // we generate one and resave the credential before creating the
  // LE credential.
  optional bytes wrapped_reset_seed = 11;

  // Used during EncryptTPM/DecryptTPM to perform AES encryption of the
  // reset_seed.
  optional bytes reset_iv = 12;

  // Label under which this key's low entropy and high entropy secrets
  // are stored by LECredentialManager.
  optional uint64 le_label = 13;

  // Used during EncryptLECredential/DecryptLECredential to perform AES
  // encryption of the file encryption key and chaps key in VaultKeyset.
  optional bytes le_fek_iv = 14;
  optional bytes le_chaps_iv = 15;

  // Used *only* by EncryptLECredential/DecryptLECredential to derive the
  // per-credential reset_secret from the per-user |reset_seed| using
  // HMACSha256.
  optional bytes reset_salt = 16;

  // Fields specific to the challenge-response protection.
  // The Scrypt KDF passphrase, used for the protection of the keyset, is
  // defined as a concatenation of two values:
  // * The first is the blob which is sealed in |sealed_secret|.
  // * The second is the deterministic signature of |salt| using the
  //   |salt_signature_algorithm| algorithm.
  // The cryptographic key specified in |public_key_spki_der| is used for both.
  message SignatureChallengeInfo {
    // DER-encoded blob of the X.509 Subject Public Key Info of the key to be
    // challenged in order to obtain the KDF passphrase for decrypting the vault
    // keyset.
    optional bytes public_key_spki_der = 1;
    // Container with the secret data which is sealed using the TPM in a way
    // that the process of its unsealing involves signature challenges against
    // the specified key. This secret data is one of the sources for building
    // the KDF passphrase.
    optional SignatureSealedData sealed_secret = 2;
    // Salt whose signature is another source for building the KDF passphrase.
    optional bytes salt = 3;
    // Signature algorithm to be used for signing |salt|.
    // NOTE: the signature algorithm has to be deterministic (that is, always
    // produce the same output for the same input).
    optional ChallengeSignatureAlgorithm salt_signature_algorithm = 4;
  }

  // Set only when the |SIGNATURE_CHALLENGE_PROTECTED| flag is present.
  optional SignatureChallengeInfo signature_challenge_info = 17;

  // Set if the keyset has PCR_BOUND flag. Represents the encrypted vkk_key for
  // the case when PCR is extended with user specific value.
  optional bytes extended_tpm_key = 18;

  // Set if the vault keyset should be used with fscrypt v2 encryption policies.
  optional int32 fscrypt_policy_version = 20;

  // Deprecated fields that were removed.
  reserved 7, 19;
}