Home | History | Annotate | Download | only in cryptohome
      1 // Copyright (c) 2014 The Chromium Authors. All rights reserved.
      2 // Use of this source code is governed by a BSD-style license that can be
      3 // found in the LICENSE file.
      4 //
      5 // The messages in this file comprise the DBus/Proto interface for
      6 // Cryptohome where there is an AccountIdentifer argument, an
      7 // AuthorizationRequest (if needed for the call), and the call's
      8 // parameters as <Call>Request.
      9 //
     10 // 'optional' annotations are used heavily in the RPC definition
     11 // because the RPC endpoints most properly sanity check the contents
     12 // for application-specific logic, and the more optional-with-default
     13 // parameters exist, the less data is actually transferred on the wire
     14 // in "default" situations.
     15 
     16 syntax = "proto2";
     17 
     18 option optimize_for = LITE_RUNTIME;
     19 
     20 package cryptohome;
     21 
     22 import "key.proto";
     23 
     24 // Error codes do not need to be sequential per-call.
     25 // Prefixes by Request/Reply type should be used to help
     26 // callers know if specialized errors apply.
     27 enum CryptohomeErrorCode {
     28   // 0 is the default value of BaseReply::error. It
     29   // should never be used.
     30   CRYPTOHOME_ERROR_NOT_SET = 0;
     31 
     32   CRYPTOHOME_ERROR_ACCOUNT_NOT_FOUND = 1;
     33   CRYPTOHOME_ERROR_AUTHORIZATION_KEY_NOT_FOUND = 2;
     34   CRYPTOHOME_ERROR_AUTHORIZATION_KEY_FAILED = 3;
     35   CRYPTOHOME_ERROR_NOT_IMPLEMENTED = 4;
     36   CRYPTOHOME_ERROR_MOUNT_FATAL = 5;
     37   CRYPTOHOME_ERROR_MOUNT_MOUNT_POINT_BUSY = 6;
     38   CRYPTOHOME_ERROR_TPM_COMM_ERROR = 7;
     39   CRYPTOHOME_ERROR_TPM_DEFEND_LOCK = 8;
     40   CRYPTOHOME_ERROR_TPM_NEEDS_REBOOT = 9;
     41   CRYPTOHOME_ERROR_AUTHORIZATION_KEY_DENIED = 10;
     42   CRYPTOHOME_ERROR_KEY_QUOTA_EXCEEDED = 11;
     43   CRYPTOHOME_ERROR_KEY_LABEL_EXISTS = 12;
     44   CRYPTOHOME_ERROR_BACKING_STORE_FAILURE = 13;
     45   CRYPTOHOME_ERROR_UPDATE_SIGNATURE_INVALID = 14;
     46   CRYPTOHOME_ERROR_KEY_NOT_FOUND = 15;
     47   CRYPTOHOME_ERROR_LOCKBOX_SIGNATURE_INVALID = 16;
     48   CRYPTOHOME_ERROR_LOCKBOX_CANNOT_SIGN = 17;
     49   CRYPTOHOME_ERROR_BOOT_ATTRIBUTE_NOT_FOUND = 18;
     50   CRYPTOHOME_ERROR_BOOT_ATTRIBUTES_CANNOT_SIGN = 19;
     51   CRYPTOHOME_ERROR_TPM_EK_NOT_AVAILABLE = 20;
     52   CRYPTOHOME_ERROR_ATTESTATION_NOT_READY = 21;
     53   CRYPTOHOME_ERROR_CANNOT_CONNECT_TO_CA = 22;
     54   CRYPTOHOME_ERROR_CA_REFUSED_ENROLLMENT = 23;
     55   CRYPTOHOME_ERROR_CA_REFUSED_CERTIFICATE = 24;
     56   CRYPTOHOME_ERROR_INTERNAL_ATTESTATION_ERROR = 25;
     57   CRYPTOHOME_ERROR_FIRMWARE_MANAGEMENT_PARAMETERS_INVALID = 26;
     58   CRYPTOHOME_ERROR_FIRMWARE_MANAGEMENT_PARAMETERS_CANNOT_STORE = 27;
     59   CRYPTOHOME_ERROR_FIRMWARE_MANAGEMENT_PARAMETERS_CANNOT_REMOVE = 28;
     60   CRYPTOHOME_ERROR_MOUNT_OLD_ENCRYPTION = 29;
     61   CRYPTOHOME_ERROR_MOUNT_PREVIOUS_MIGRATION_INCOMPLETE = 30;
     62 }
     63 
     64 message AccountIdentifier {
     65   // |email| is deprecated. Don't use it.
     66   optional string email = 1;
     67 
     68   optional string account_id = 2;
     69 }
     70 
     71 message AuthorizationRequest {
     72   // |key| must supply at least a |key.secret()|.  If no |key.data()| or
     73   // |key.data().label()| is supplied, the |key.secret()| will be tested
     74   // against all compatible |key.data().type()| keys, where
     75   // KEY_TYPE_PASSWORD is the default type.  If
     76   // |key.data().label()| is supplied, then the |key.secret()| will only be
     77   // tested against the matching VaultKeyset.
     78   optional Key key = 1;
     79 };
     80 
     81 // These parameters are for inbound data to Cryptohome RPC
     82 // interfaces.  When calls are added that return data, a
     83 // <Call>Response should be defined.
     84 message MountRequest {
     85   // Perform an ephemeral mount only.
     86   optional bool require_ephemeral = 1 [default=false];
     87   // If defined, the account will be created if it does not exist.
     88   // Additionally, a failed AuthorizationRequest will be expected as
     89   // there will be no existing keys.
     90   optional CreateRequest create = 2;
     91   // If set to true, and cryptohomed supports the new "dircrypto" encryption,
     92   // forces to use the new encryption. That is, makes it an error to mount
     93   // an existing home directory encrypted in the old way (ecryptfs).
     94   optional bool force_dircrypto_if_available = 3;
     95   // If set to true, mounts the existing ecryptfs vault to a temporary location
     96   // while setting up a new dircrypto directory.
     97   optional bool to_migrate_from_ecryptfs = 4;
     98   // Performs a public mount, which is used for a Kiosk session. Credentials are
     99   // not needed in the request; they are synthesized by cryptohomed from id.
    100   optional bool public_mount = 5;
    101   // If set to true, mounts the vault to a temporary location. The mount is not
    102   // exposed to the usual locations (/home/user, /home/root).
    103   optional bool hidden_mount = 6;
    104 }
    105 
    106 // A BaseReply type is used for all cryptohomed responses. A shared base class
    107 // is used because all calls will always reply with no-error or an error value.
    108 // A centralized definition allows for a reusable reply handler for cases where
    109 // there is no Request-specific reply data.  Any specialized data will live in
    110 // an extension as per MountReply below:
    111 //   if (reply.HasExtension(MountReply::reply)) { ... }
    112 //
    113 message BaseReply {
    114   // If a call was successful, error will not be defined (clear_error()).
    115   // If a call failed, it must set an error code (set_error(CODE)).
    116   // In either case, call-specific data may be added as an extension.
    117   optional CryptohomeErrorCode error = 1;
    118 
    119   extensions 1000 to max;
    120 }
    121 
    122 // The MountRequest call may return more than just success or failure
    123 // so it embeds itself in a BaseReply as an extension.
    124 message MountReply {
    125   extend BaseReply {
    126     optional MountReply reply = 1000;
    127   }
    128   // |recreated| is set when the cryptohome had to be wiped
    129   // because the key or data was an unrecoverable.  It does not imply
    130   // failure to Mount nor is it 'true' when a CreateRequest creates
    131   // a cryptohome for the first time.
    132   optional bool recreated = 1 [default=false];
    133   // Returns the filesystem-sanitized username.
    134   optional string sanitized_username = 2;
    135 };
    136 
    137 message CreateRequest {
    138   repeated Key keys = 1;
    139   // Explicitly use the |key| from the AuthorizationRequest.
    140   // Setting this value means that the KeyData is filled as it
    141   // would be with a Key above or in an AddKeyRequest.
    142   optional bool copy_authorization_key = 2 [default=false];
    143   // If set to true, always use eCryptfs as the encryption method.
    144   optional bool force_ecryptfs = 3 [default=false];
    145   // In the future, this will contain account-wide data like
    146   // the deletion priority or the IdP's origin.
    147 }
    148 
    149 message AddKeyRequest {
    150   optional Key key = 1;
    151   optional bool clobber_if_exists = 2 [default=false];
    152 }
    153 
    154 message UpdateKeyRequest {
    155   optional Key changes = 1;
    156   optional bytes authorization_signature = 2;
    157 }
    158 
    159 message CheckKeyRequest {
    160 }
    161 
    162 message RemoveKeyRequest {
    163   // Only key.data().label() is used at present.
    164   optional Key key = 1;
    165 }
    166 
    167 message SignBootLockboxRequest {
    168   // The data to be signed.
    169   optional bytes data = 1;
    170 }
    171 
    172 message SignBootLockboxReply {
    173   extend BaseReply {
    174     optional SignBootLockboxReply reply = 1001;
    175   }
    176   optional bytes signature = 1;
    177 }
    178 
    179 message VerifyBootLockboxRequest {
    180   // The signed data to be verified.
    181   optional bytes data = 1;
    182   // The signature to be verified.
    183   optional bytes signature = 2;
    184 }
    185 
    186 message FinalizeBootLockboxRequest {
    187 }
    188 
    189 message GetKeyDataRequest {
    190   // |key| must supply at least one attribute and all others will be treated as
    191   // wildcards.  Currently only |key.data().label()| may be supplied.  Like
    192   // AuthorizationRequest, support can be added for queries by
    193   // |key.data().type()| to return all keys of a certain class, testing
    194   // |key.secret()|, or |key.data().provider_data()| entries.
    195   optional Key key = 1;
    196 }
    197 
    198 message GetKeyDataReply {
    199   extend BaseReply {
    200     optional GetKeyDataReply reply = 1002;
    201   }
    202   repeated KeyData key_data = 1;
    203 }
    204 
    205 message GetBootAttributeRequest {
    206   optional string name = 1;
    207 }
    208 
    209 message GetBootAttributeReply {
    210   extend BaseReply {
    211     optional GetBootAttributeReply reply = 1003;
    212   }
    213   optional bytes value = 1;
    214 }
    215 
    216 message SetBootAttributeRequest {
    217   optional string name = 1;
    218   optional bytes value = 2;
    219 }
    220 
    221 message FlushAndSignBootAttributesRequest {
    222 }
    223 
    224 message ListKeysRequest {
    225   // The default behavior is by label so any extension here should honor that.
    226 }
    227 
    228 message ListKeysReply {
    229   extend BaseReply {
    230     optional ListKeysReply reply = 1004;
    231   }
    232   repeated string labels = 1;
    233 }
    234 
    235 message GetLoginStatusRequest {
    236 }
    237 
    238 message GetLoginStatusReply {
    239   extend BaseReply {
    240     optional GetLoginStatusReply reply = 1005;
    241   }
    242   optional bool owner_user_exists=1;
    243   optional bool boot_lockbox_finalized=2;
    244 }
    245 
    246 message GetTpmStatusRequest {
    247 }
    248 
    249 message GetTpmStatusReply {
    250   extend BaseReply {
    251     optional GetTpmStatusReply reply = 1006;
    252   }
    253   // Whether a TPM is enabled on the system.
    254   optional bool enabled = 1;
    255   // Whether the TPM has been owned.
    256   optional bool owned = 2;
    257   // Whether the TPM initialization flow has completed. This includes taking
    258   // ownership, preparing attestation data, and finalizing lockbox NVRAM.
    259   optional bool initialized = 3;
    260   // The TPM owner password. This is only available when (owned &&
    261   // !initialized) and sometimes not even then.
    262   optional string owner_password = 4;
    263   // Whether attestation data has been prepared. This includes reading the
    264   // endorsement certificate out of NVRAM and generating an identity key. This
    265   // does not include any kind of enrollment with a Privacy CA.
    266   optional bool attestation_prepared = 7;
    267   // Whether the device has enrolled with a Privacy CA. This means the identity
    268   // key has been successfully certified.
    269   optional bool attestation_enrolled = 8;
    270   // The current dictionary attack counter value.
    271   optional int32 dictionary_attack_counter = 9;
    272   // The current dictionary attack counter threshold.
    273   optional int32 dictionary_attack_threshold = 10;
    274   // Whether the TPM is in some form of dictionary attack lockout.
    275   optional bool dictionary_attack_lockout_in_effect = 11;
    276   // The number of seconds remaining in the lockout.
    277   optional int32 dictionary_attack_lockout_seconds_remaining = 12;
    278   // Whether the install lockbox has been finalized.
    279   optional bool install_lockbox_finalized = 13;
    280   // Whether the boot lockbox has been finalized.
    281   optional bool boot_lockbox_finalized = 14;
    282   // Whether the current PCR values show a verified boot.
    283   optional bool verified_boot_measured = 15;
    284 }
    285 
    286 message GetEndorsementInfoRequest {
    287 }
    288 
    289 message GetEndorsementInfoReply {
    290   extend BaseReply {
    291     optional GetEndorsementInfoReply reply = 1007;
    292   }
    293   // The endorsement public key (PKCS #1 RSAPublicKey).
    294   optional bytes ek_public_key = 1;
    295   // The endorsement certificate (X.509).
    296   optional bytes ek_certificate = 2;
    297 }
    298 
    299 message InitializeCastKeyRequest {
    300 }
    301 
    302 // Flags for GetFirmwareManagementParametersReply and
    303 // SetFirmwareManagementParametersRequest
    304 enum FirmwareManagementParametersFlags {
    305   NONE = 0;
    306   DEVELOPER_DISABLE_BOOT = 1;
    307   DEVELOPER_DISABLE_RECOVERY_INSTALL = 2;
    308   DEVELOPER_DISABLE_RECOVERY_ROOTFS = 4;
    309   DEVELOPER_ENABLE_USB = 8;
    310   DEVELOPER_ENABLE_LEGACY = 16;
    311   DEVELOPER_USE_KEY_HASH = 32;
    312   DEVELOPER_DISABLE_CASE_CLOSED_DEBUGGING_UNLOCK = 64;
    313 }
    314 
    315 message GetFirmwareManagementParametersRequest {
    316 }
    317 
    318 message GetFirmwareManagementParametersReply {
    319   extend BaseReply {
    320     optional GetFirmwareManagementParametersReply reply = 1008;
    321   }
    322 
    323   // Flags (zero or more from FirmwareManagementParametersFlags)
    324   optional int32 flags = 1;
    325   optional bytes developer_key_hash = 2;
    326 }
    327 
    328 message SetFirmwareManagementParametersRequest {
    329   // Flags (zero or more from FirmwareManagementParametersFlags)
    330   optional int32 flags = 1;
    331   optional bytes developer_key_hash = 2;
    332 }
    333 
    334 message RemoveFirmwareManagementParametersRequest {
    335 }
    336 
    337 message GetAccountDiskUsageReply {
    338   extend BaseReply {
    339     optional GetAccountDiskUsageReply reply = 1009;
    340   }
    341   // The size of cryptohome in bytes.
    342   optional int64 size = 1;
    343 }
    344