components/arc/mojom/keymaster.mojom

// Copyright 2019 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.

// Next MinVersion: 1

// This file defines the mojo interface between Android and Chrome OS for the
// keymaster implementation used in ARC.

module arc.mojom;

// Host is implemented in Chrome. Listens until server and instance come online
// and forwards a server handle to the instance.
interface KeymasterHost {
  GetServer@0() => (KeymasterServer server_ptr);
};

// Instance is implemented in ARC. Retrieves a server pointer from the host and
// uses it to fulfill Android Keymaster operations.
interface KeymasterInstance {
  Init@0(KeymasterHost host_ptr) => ();
};

// Server is implemented in arc-keymasterd in Chrome OS. This interface is the
// mojo equivalent of the Keymaster 3.0 HIDL interface. Please refer to
// Android's IKeymasterDevice.hal for a more detailed description on how the
// methods and structs below should function.
interface KeymasterServer {

  // Sets the Android version information used.
  SetSystemVersion@0(uint32 os_version, uint32 os_patchlevel);

  AddRngEntropy@1(array<uint8> data) => (int32 error);

  // Returns the characteristics of the specified key if it is valid.
  GetKeyCharacteristics@2(GetKeyCharacteristicsRequest request) =>
      (GetKeyCharacteristicsResult response);

  GenerateKey@3(array<KeyParameter> key_params) => (GenerateKeyResult response);

  ImportKey@4(ImportKeyRequest request) => (ImportKeyResult response);

  // Exports a public key, returning the key in the specified format.
  ExportKey@5(ExportKeyRequest request) => (ExportKeyResult response);

  // Generates a signed X.509 certificate chain attesting to the presence of
  // keyToAttest in Keymaster.
  AttestKey@6(AttestKeyRequest request) => (AttestKeyResult result);

  // Upgrades a key generated by an older version of the Keymaster.
  UpgradeKey@7(UpgradeKeyRequest request) => (UpgradeKeyResult response);

  DeleteKey@8(array<uint8> key_blob) => (int32 error);

  DeleteAllKeys@9() => (int32 error);

  // Begins a cryptographic operation using the specified key.
  Begin@10(BeginRequest request) => (BeginResult result);

  // Provides data and possibly receives output from an ongoing operation.
  Update@11(UpdateRequest request) => (UpdateResult response);

  // Finalizes a cryptographic operation and invalidates operation handle.
  Finish@12(FinishRequest request) => (FinishResult response);

  // Aborts an operation and invalidates the operation handle.
  Abort@13(uint64 op_handle) => (int32 error);
};

////////////////////////////////////////////////////////////////////////////////
// KeymasterServer helper enums and structs

[Extensible]
enum KeyPurpose {
  ENCRYPT = 0,    // Usable with RSA, EC and AES keys.
  DECRYPT = 1,    // Usable with RSA, EC and AES keys.
  SIGN = 2,       // Usable with RSA, EC and HMAC keys.
  VERIFY = 3,     // Usable with RSA, EC and HMAC keys.
  DERIVE_KEY = 4, // Usable with EC keys.
  WRAP_KEY = 5,   // Usable with wrapping keys.
};

[Extensible]
enum KeyFormat {
  X509 = 0,  // for public key export
  PKCS8 = 1, // for asymmetric key pair import
  RAW = 3,   // for symmetric key import and export
};

// Helper union for key parameter values.
union IntegerKeyParam {
  bool boolean_value;  // KM_BOOL
  uint32 integer;      // KM_ENUM, KM_ENUM_REP, KM_INT and KM_INT_REP
  uint64 long_integer; // KM_LONG
  uint64 date_time;    // KM_DATE
  array<uint8> blob;   // KM_BIGNUM and KM_BYTES
};

struct KeyParameter {
  // Discriminates the IntegerKeyParam union field used.
  uint32 tag;
  IntegerKeyParam param;
};

// Defines the attributes of a key, including cryptographic parameters, and
// usage restrictions.
struct KeyCharacteristics {
  array<KeyParameter> software_enforced;
  array<KeyParameter> tee_enforced;
};

////////////////////////////////////////////////////////////////////////////////
// KeymasterServer request and response structs

struct GetKeyCharacteristicsRequest {
  array<uint8> key_blob;
  array<uint8> client_id;
  array<uint8> app_data;
};

struct GetKeyCharacteristicsResult {
  KeyCharacteristics key_characteristics;
  int32 error;
};

struct GenerateKeyResult {
  array<uint8> key_blob;
  KeyCharacteristics key_characteristics;
  int32 error;
};

struct ImportKeyRequest {
  array<KeyParameter> key_description;
  KeyFormat key_format;
  array<uint8> key_data;
};

struct ImportKeyResult {
  array<uint8> key_blob;
  KeyCharacteristics key_characteristics;
  int32 error;
};

struct ExportKeyRequest {
  KeyFormat key_format;
  array<uint8> key_blob;
  array<uint8> client_id;
  array<uint8> app_data;
};

struct ExportKeyResult {
  array<uint8> key_material;
  int32 error;
};

struct AttestKeyRequest {
  array<uint8> key_to_attest;
  array<KeyParameter> attest_params;
};

struct AttestKeyResult {
  array<array<uint8>> cert_chain;
  int32 error;
};

struct UpgradeKeyRequest {
  array<uint8> key_blob_to_upgrade;
  array<KeyParameter> upgrade_params;
};

struct UpgradeKeyResult {
  array<uint8> upgraded_key_blob;
  int32 error;
};

struct BeginRequest {
  KeyPurpose purpose;
  array<uint8> key;
  array<KeyParameter> in_params;
};

struct BeginResult {
  array<KeyParameter> out_params;
  uint64 op_handle;
  int32 error;
};

struct UpdateRequest {
  uint64 op_handle;
  array<KeyParameter> in_params;
  array<uint8> input;
};

struct UpdateResult {
  uint32 input_consumed;
  array<KeyParameter> out_params;
  array<uint8> output;
  int32 error;
};

struct FinishRequest {
  uint64 op_handle;
  array<KeyParameter> in_params;
  array<uint8> input;
  array<uint8> signature;
};

struct FinishResult {
  array<KeyParameter> out_params;
  array<uint8> output;
  int32 error;
};