nugget/proto/nugget/app/keymaster/keymaster.proto

/*
 * Copyright (C) 2017 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.
 */

syntax = "proto3";

package nugget.app.keymaster;

import "nugget/app/keymaster/keymaster_defs.proto";
import "nugget/app/keymaster/keymaster_types.proto";
import "nugget/protobuf/options.proto";

/*
 * Keymaster service methods.
 *
 * TODO: some methods may be implemented in the host side HAL implementation.
 */
service Keymaster {
  option (nugget.protobuf.app_id) = "KEYMASTER";
  option (nugget.protobuf.app_name) = "Keymaster";
  option (nugget.protobuf.app_version) = 1;
  /*
   * Both request and response buffers are sized such
   * that a key-blob may be fully contained.
   *
   * TODO: revisit this choice in the event that memory
   * is running out.  Supporting smaller buffers will
   * require that the keymaster app switch from the
   * transport API to the datagram API.
   */
  option (nugget.protobuf.request_buffer_size) = 2048;
  option (nugget.protobuf.response_buffer_size) = 2048;

  /*
   * KM3 methods, from:
   *     ::android::hardware::keymaster::V3_0::IKeymasterDevice
   */
  rpc AddRngEntropy (AddRngEntropyRequest) returns (AddRngEntropyResponse);
  rpc GenerateKey (GenerateKeyRequest) returns (GenerateKeyResponse);
  rpc GetKeyCharacteristics (GetKeyCharacteristicsRequest) returns (GetKeyCharacteristicsResponse);
  rpc ImportKey (ImportKeyRequest) returns (ImportKeyResponse);
  rpc ExportKey (ExportKeyRequest) returns (ExportKeyResponse);
  rpc AttestKey (AttestKeyRequest) returns (AttestKeyResponse);
  rpc UpgradeKey (UpgradeKeyRequest) returns (UpgradeKeyResponse);
  rpc DeleteKey (DeleteKeyRequest) returns (DeleteKeyResponse);
  rpc DeleteAllKeys (DeleteAllKeysRequest) returns (DeleteAllKeysResponse);
  rpc DestroyAttestationIds (DestroyAttestationIdsRequest) returns (DestroyAttestationIdsResponse);
  rpc BeginOperation (BeginOperationRequest) returns (BeginOperationResponse);
  rpc UpdateOperation (UpdateOperationRequest) returns (UpdateOperationResponse);
  rpc FinishOperation (FinishOperationRequest) returns (FinishOperationResponse);
  rpc AbortOperation (AbortOperationRequest) returns (AbortOperationResponse);

  /*
   * KM4 methods.
   */
  rpc ImportWrappedKey (ImportWrappedKeyRequest) returns (ImportWrappedKeyResponse);

  /*
   * Vendor specific methods (manufacturing, status, factory reset, upgrade).
   */
}

/*
 *  KM3 messages.
 */

// AddEntropy
message AddRngEntropyRequest {
  bytes data = 1;
}
message AddRngEntropyResponse {
  // TODO: replace with ErrorCode enum
  uint32 error_code = 1;
}

// GenerateKey
message GenerateKeyRequest {
  KeyParameters params = 1;
}
message GenerateKeyResponse {
  uint32 error_code = 1;
  KeyBlob blob = 2;
  KeyCharacteristics characteristics = 3;
}

// GetKeyCharacteristics
message GetKeyCharacteristicsRequest {
  KeyBlob blob = 1;
  bytes client_id = 2;
  bytes app_data = 3;
}
message GetKeyCharacteristicsResponse {
  uint32 error_code = 1;
  KeyCharacteristics characteristics = 2;
}

// ImportKey
message ImportKeyRequest {
  KeyParameters params = 1;
  RSAKey rsa = 2;
  ECKey ec = 3;
  SymmetricKey symmetric_key = 4;
};
message ImportKeyResponse {
  // TODO: include an ErrorCode field
  uint32 error_code = 1;
  KeyBlob blob = 2;
  KeyCharacteristics characteristics = 3;
};

// ExportKey
message ExportKeyRequest {
  KeyFormat format = 1;
  KeyBlob blob = 2;
  bytes client_id = 3;
  bytes app_data = 4;
};
message ExportKeyResponse {
  uint32 error_code = 1;
  bytes key_material = 2;
};

// AttestKey
message AttestKeyRequest {
  KeyBlob blob = 1;
  KeyParameters params = 2;
}
message AttestKeyResponse {
  uint32 error_code = 1;
  CertificateChain chain = 2;
}

// UpgradeKey
message UpgradeKeyRequest {
  KeyBlob blob = 1;
  KeyParameters params = 2;
}
message UpgradeKeyResponse {
  uint32 error_code = 1;
  KeyBlob blob = 2;
}

// DeleteKey
message DeleteKeyRequest {
  KeyBlob blob = 1;
}
message DeleteKeyResponse {
  uint32 error_code = 1;
}

// DeleteAllKeys
message DeleteAllKeysRequest {}
message DeleteAllKeysResponse {
  uint32 error_code = 1;
}

// DestroyAttestationIds
message DestroyAttestationIdsRequest {}
message DestroyAttestationIdsResponse {
  uint32 error_code = 1;
}

// BeginOperation
message BeginOperationRequest {
  KeyPurpose purpose = 1;
  KeyBlob blob = 2;
  KeyParameters params = 3;
}
message BeginOperationResponse {
  uint32 error_code = 1;
  KeyParameters params = 2;
  OperationHandle handle = 3;
}

// UpdateOperation
message UpdateOperationRequest {
  OperationHandle handle = 1;
  KeyParameters params = 2;
  bytes input = 3;
}
message UpdateOperationResponse {
  uint32 error_code = 1;
  uint32 consumed = 2;
  KeyParameters params = 3;
  bytes output = 4;
}

// FinishOperation
message FinishOperationRequest {
  OperationHandle handle = 1;
  KeyParameters params = 2;
  bytes input = 3;
  bytes signature = 4;
};
message FinishOperationResponse {
  uint32 error_code = 1;
  KeyParameters params = 2;
  bytes output = 3;
};

// AbortOperation
message AbortOperationRequest {
  OperationHandle handle = 1;
};
message AbortOperationResponse {
  uint32 error_code = 1;
};

/*
 * KM4 messages.
 */
message ImportWrappedKeyRequest {
  KeyBlob wrapping_key_blob = 1;
  bytes wrapped_key = 2;
}
message ImportWrappedKeyResponse {
  uint32 error_code = 1;
  KeyBlob blob = 2;
  KeyCharacteristics characteristics = 3;
}