PL286/system/tpm/tpm_manager/common/tpm_manager.proto

//
// Copyright (C) 2015 The Android Open Source Project
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//      http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
//

// NOTE: All tpm_manager protobufs are in the same file because the Android
// build system cannot handle import statements without using Android-specific
// paths.

option optimize_for = LITE_RUNTIME;
package tpm_manager;

enum TpmManagerStatus {
  STATUS_SUCCESS = 0;
  STATUS_DEVICE_ERROR = 1;
  STATUS_NOT_AVAILABLE = 2;
}

// Result codes. For convenience, keep these in sync with Brillo NVRAM HAL
// values defined in hardware/nvram_defs.h.
enum NvramResult {
  NVRAM_RESULT_SUCCESS = 0;
  // An unexpected TPM error occurred. More information should be in logs.
  NVRAM_RESULT_DEVICE_ERROR = 1;
  // The caller is not authorized to perform the requested operation. This may
  // be due to a bad authorization value or to system state.
  NVRAM_RESULT_ACCESS_DENIED = 2;
  NVRAM_RESULT_INVALID_PARAMETER = 3;
  NVRAM_RESULT_SPACE_DOES_NOT_EXIST = 4;
  NVRAM_RESULT_SPACE_ALREADY_EXISTS = 5;
  // This may be because a space is locked or because an operation has been
  // explicitly disabled.
  NVRAM_RESULT_OPERATION_DISABLED = 6;
  // Literally, the TPM is out of non-volatile storage.
  NVRAM_RESULT_INSUFFICIENT_SPACE = 7;
  // An error occurred sending the request to the system service.
  NVRAM_RESULT_IPC_ERROR = 100;
}

// More background on these attributes can be found by looking up the TPMA_NV_*
// constants in the TPM 2.0 specification or the TPM_NV_PER_* constants in the
// TPM 1.2 specification.
enum NvramSpaceAttribute {
  // The space can be locked for writing until it is destroyed. Without TPM
  // owner privilege this is always after the TPM is cleared. This typically
  // occurs during device factory reset.
  NVRAM_PERSISTENT_WRITE_LOCK = 0;
  // The space can be locked for writing until the next boot.
  NVRAM_BOOT_WRITE_LOCK = 1;
  // The space can be locked for reading until the next boot.
  NVRAM_BOOT_READ_LOCK = 2;
  // The space requires an authorization value for writing.
  NVRAM_WRITE_AUTHORIZATION = 3;
  // The space requires an authorization value for reading.
  NVRAM_READ_AUTHORIZATION = 4;
  // The space can not be written directly, only extended.
  // E.g. new_value = HASH(old_value + input)
  NVRAM_WRITE_EXTEND = 5;
  // The space is tied to the global lock (bGlobalLock). This global lock is
  // typically locked early in boot. This is defined for inspecting existing
  // spaces, this interface cannot be used to define spaces with this attribute.
  NVRAM_GLOBAL_LOCK = 6;
  // The space is tied to the platform rather than the TPM owner. The 'platform'
  // is whatever executes first after boot. Typically this access is locked
  // early in boot. This is defined for inspecting existing spaces, this
  // interface cannot be used to define spaces with this attribute.
  NVRAM_PLATFORM_WRITE = 7;
  // The space can only be written by the TPM owner. For TPM 2.0 this can be
  // used only for inspecting existing spaces, not for defining new spaces.
  NVRAM_OWNER_WRITE = 8;
  // The space can only be read by the TPM owner. For TPM 2.0 this can be used
  // only for inspecting existing spaces, not for defining new spaces.
  NVRAM_OWNER_READ = 9;
}

enum NvramSpacePolicy {
  // No policy. Authorization values are still enforced. This is the default.
  NVRAM_POLICY_NONE = 0;
  // Bind both read and write access to the current PCR0 value in addition to
  // enforcing any authorization value.
  NVRAM_POLICY_PCR0 = 1;
}

// Tracks the expected policy for a particular NVRAM space.
message NvramPolicyRecord {
  optional uint32 index = 1;
  optional NvramSpacePolicy policy = 2;
  // This will be true if the NVRAM_READ_AUTHORIZATION attribute was not
  // specified when the space was created.
  optional bool world_read_allowed = 3;
  // This will be true if the NVRAM_WRITE_AUTHORIZATION attribute was not
  // specified when the space was created.
  optional bool world_write_allowed = 4;
  repeated bytes policy_digests = 5;
}

// The format of persistent local TPM management data stored on the device.
// When TPM ownership is taken, this protobuf is populated with the passwords
// used to take ownership, and with a list of clients who have a dependency on
// the owner password (like Attestation, InstallAttributes and BootLockbox).
// when all the clients have the owner password injected, this protobuf is
// cleared of all passwords.
message LocalData {
  optional bytes owner_password = 2;
  repeated string owner_dependency = 3;
  optional bytes endorsement_password = 4;
  optional bytes lockout_password = 5;
  repeated NvramPolicyRecord nvram_policy = 6;
}

////////////////////////////////////////////////////////////////////////////////
// A series of request and reply messages for the NVRAM interface methods.
////////////////////////////////////////////////////////////////////////////////
message DefineSpaceRequest {
  optional uint32 index = 1;
  optional uint32 size = 2;
  repeated NvramSpaceAttribute attributes = 3;
  optional bytes authorization_value = 4;
  optional NvramSpacePolicy policy = 5;
}

message DefineSpaceReply {
  optional NvramResult result = 1;
}

message DestroySpaceRequest {
  optional uint32 index = 1;
}

message DestroySpaceReply {
  optional NvramResult result = 1;
}

message WriteSpaceRequest {
  optional uint32 index = 1;
  optional bytes data = 2;
  optional bytes authorization_value = 3;
  optional bool use_owner_authorization = 4;
}

message WriteSpaceReply {
  optional NvramResult result = 1;
}

message ReadSpaceRequest {
  optional uint32 index = 1;
  optional bytes authorization_value = 2;
  optional bool use_owner_authorization = 3;
}

message ReadSpaceReply {
  optional NvramResult result = 1;
  optional bytes data = 2;
}

message LockSpaceRequest {
  optional uint32 index = 1;
  optional bool lock_read = 2;
  optional bool lock_write = 3;
  optional bytes authorization_value = 4;
  optional bool use_owner_authorization = 5;
}

message LockSpaceReply {
  optional NvramResult result = 1;
}

message ListSpacesRequest {
}

message ListSpacesReply {
  optional NvramResult result = 1;
  repeated uint32 index_list = 2;
}

message GetSpaceInfoRequest {
  optional uint32 index = 1;
}

message GetSpaceInfoReply {
  optional NvramResult result = 1;
  optional uint32 size = 2;
  optional bool is_read_locked = 3;
  optional bool is_write_locked = 4;
  repeated NvramSpaceAttribute attributes = 5;
  optional NvramSpacePolicy policy = 6;
}

////////////////////////////////////////////////////////////////////////////////
// A series of request and reply messages for the ownership interface methods.
////////////////////////////////////////////////////////////////////////////////
message GetTpmStatusRequest {
}

message GetTpmStatusReply {
  optional TpmManagerStatus status = 1;
  // Whether a TPM is enabled on the system.
  optional bool enabled = 2;
  // Whether the TPM has been owned.
  optional bool owned = 3;
  // Local TPM management data (including the owner password if available).
  optional LocalData local_data = 4;
  // The current dictionary attack counter value.
  optional uint32 dictionary_attack_counter = 5;
  // The current dictionary attack counter threshold.
  optional uint32 dictionary_attack_threshold = 6;
  // Whether the TPM is in some form of dictionary attack lockout.
  optional bool dictionary_attack_lockout_in_effect = 7;
  // The number of seconds remaining in the lockout.
  optional uint32 dictionary_attack_lockout_seconds_remaining = 8;
}

message TakeOwnershipRequest {
}

message TakeOwnershipReply {
  optional TpmManagerStatus status = 1;
}

message RemoveOwnerDependencyRequest {
  optional bytes owner_dependency = 1;
}

message RemoveOwnerDependencyReply {
  optional TpmManagerStatus status = 1;
}