system_api/dbus/cryptohome/key.proto

// Copyright (c) 2014 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.
//
// Provides wire-type for cryptohome Key objects.  It does not
// represent the entirety of the bookkeeping data needed by Cryptohome.
//
// Anything in this file may be persisted on disk.  Update carefully!

syntax = "proto2";

option optimize_for = LITE_RUNTIME;

package cryptohome;

message KeyAuthorizationSecretUsage {
  optional bool encrypt = 1;
  optional bool sign = 2;
}

message KeyAuthorizationSecret {
  optional KeyAuthorizationSecretUsage usage = 1;
  optional bytes symmetric_key = 2;
  optional bytes public_key = 3;
  // Indicates if the symmetric_key is wrapped.
  optional bool wrapped = 4 [default=false];
}

message KeyAuthorizationData {
  enum KeyAuthorizationType {
    KEY_AUTHORIZATION_TYPE_HMACSHA256 = 0;
    KEY_AUTHORIZATION_TYPE_AES256CBC_HMACSHA256 = 1;
  }
  optional KeyAuthorizationType type = 1;
  repeated KeyAuthorizationSecret secrets = 2;
}

// Software-enforced privileges.
message KeyPrivileges {
  // Allows the key to mount the cryptohome.
  optional bool mount = 1 [default=true];
  // Allows new keys to be added.
  optional bool add = 2 [default=true];
  // Allows other existing keys to be removed.
  optional bool remove = 3 [default=true];
  // Allows the key to update itself.
  optional bool update = 4 [default=true];
  // Allows a key to update itself iff the requested change
  // is authorized as per KeyAuthorizationData.
  optional bool authorized_update = 5 [default=false];
}

// Public metadata stored on behalf of the KeyProvider.
message KeyProviderData {
  message Entry {
    optional string name = 1;
    optional int64 number = 2;
    optional bytes bytes = 3;
  }
  repeated Entry entry = 1;
}

message KeyData {
  // The KeyType should specify the handling needed by Cryptohome
  // and not a provider KeyType.
  enum KeyType {
    KEY_TYPE_PASSWORD = 0;
  }
  optional KeyType type = 1;
  // All keys must be labeled when persisted to disk, but when KeyData
  // is used in an UpdateKeyRequest, only defined fields are necessary
  // (so that the caller doesn't need the full KeyData first).
  optional string label = 2;
  // If undefined, use the default settings.
  optional KeyPrivileges privileges = 3;
  optional int64 revision = 4;
  // At present, only support for one authorization mechanism is implemented.
  repeated KeyAuthorizationData authorization_data = 5;
  // Data stored for use by the provider of the key, often for pre-processing
  // of passwords or custom provider key typing.
  // This will be size-limited by serialized size (e.g., 4096 bytes).
  optional KeyProviderData provider_data = 6;
}

// Key is not presently persisted to disk, but it acts as the single authority
// for what comprises a key.
message Key {
  // In most cases, |data| is required.  When used in an UpdateKeyRequest, it
  // is only required if KeyData is changing.  If only the |secret| is changing,
  // this field may be left unset.
  optional KeyData data = 1;
  // |secret| is required for many requests, like AddKeyRequest, but not all.
  // An UpdateKeyRequest only requires the changes to the Key that was
  // was authorized in the AuthorizationRequest. Making |secret| required would
  // logically force a key rotation even if the values were the same.
  optional bytes secret = 2;
}