arc/keymaster/mojo/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 mplemented 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 ChromeOS.
//
// This interface is the mojo equivalent of the Keymaster 3.0 HIDL interface:
// http://cs/pi-arc-dev/hardware/interfaces/keymaster/3.0/IKeymasterDevice.hal
//
// The request/result structs are modeled after the keymaster messages:
// http://cs/pi-arc-dev/system/keymaster/include/keymaster/android_keymaster_messages.h
interface KeymasterServer {

  SetSystemVersion@0(uint32 os_version, uint32 os_patchlevel);

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

  GetKeyCharacteristics@2(GetKeyCharacteristicsRequest request) => (GetKeyCharacteristicsResult response);

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

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

  ExportKey@5(ExportKeyRequest request) => (ExportKeyResult response);

  AttestKey@6(AttestKeyRequest request) => (AttestKeyResult result);

  UpgradeKey@7(UpgradeKeyRequest request) => (UpgradeKeyResult response);

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

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

  Begin@10(BeginRequest request) => (BeginResult result);

  Update@11(UpdateRequest request) => (UpdateResult response);

  Finish@12(FinishRequest request) => (FinishResult response);

  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*/
};

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;
};

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;
};