pa.proto

// Copyright lowRISC contributors (OpenTitan project).
// Licensed under the Apache License, Version 2.0, see LICENSE for details.
// SPDX-License-Identifier: Apache-2.0

// Provisioning Appliance service definition.
syntax = "proto3";

package pa;

import "src/proto/crypto/cert.proto";
import "src/proto/crypto/wrap.proto";
import "src/proto/device_id.proto";

option go_package = "pa_go_pb";

// The ProvisioningApplianceService is a bridge service to a trusted SPM server.
service ProvisioningApplianceService {
  rpc InitSession(InitSessionRequest)
    returns (InitSessionResponse) {}
  rpc CloseSession(CloseSessionRequest)
    returns (CloseSessionResponse) {}
  rpc CreateKeyAndCert(CreateKeyAndCertRequest)
    returns (CreateKeyAndCertResponse) {}
  rpc EndorseCerts(EndorseCertsRequest)
    returns (EndorseCertsResponse) {}
  rpc DeriveSymmetricKeys(DeriveSymmetricKeysRequest)
    returns (DeriveSymmetricKeysResponse) {}
  rpc SendDeviceRegistrationPayload(RegistrationRequest)
    returns (RegistrationResponse) {}
}

// Endorse certs request.
message EndorseCertsRequest {
  // SKU identifier. Required.
  string sku = 1;
  // (Per SKU) Serial number of CA that should endorse these certificates.
  // Required. Size enforced by SKU implementation.
  bytes ca_serial_number = 2;
  // Array of TBS certificates to be endorsed.
  repeated crypto.cert.Certificate certs = 3;
}

// Endorse certs response.
message EndorseCertsResponse {
  // Array of complete (endorsed) certificates to be installed in a device.
  repeated crypto.cert.Certificate certs = 1;
}

// Symmetric key seed type (seed is provisioned into HSM).
enum SymmetricKeySeed {
  // Unspecified.
  SYMMETRIC_KEY_SEED_UNSPECIFIED = 0;
  // Low Security: seed is rotated infrequently.
  SYMMETRIC_KEY_SEED_LOW_SECURITY = 1;
  // High Security: seed is rotated frequently.
  SYMMETRIC_KEY_SEED_HIGH_SECURITY = 2;
}

// Symmetric key type.
enum SymmetricKeyType {
  // Unspecified.
  SYMMETRIC_KEY_TYPE_UNSPECIFIED = 0;
  // Raw.
  //
  // This format is used when the raw plaintext key must be generated.
  SYMMETRIC_KEY_TYPE_RAW = 1;
  // Hashed.
  //
  // This format is used when the cSHAKE128 hashed (with "LC_CTRL" customization
  // string) form of the key needs to be generated. This type supports
  // provisioning of OpenTitan lifecycle tokens, which are programmed into a
  // device's OTP memory in this form.
  //
  // protolint:disable:next MAX_LINE_LENGTH
  // See https://opentitan.org/book/hw/ip/lc_ctrl/doc/theory_of_operation.html#token-hashing-mechanism
  // for more details.
  SYMMETRIC_KEY_TYPE_HASHED_OT_LC_TOKEN = 2;
}

// Symmetric key size.
enum SymmetricKeySize {
  // Unspecified.
  SYMMETRIC_KEY_SIZE_UNSPECIFIED = 0;
  // 128 bits.
  SYMMETRIC_KEY_SIZE_128_BITS = 1;
  // 256 bits.
  SYMMETRIC_KEY_SIZE_256_BITS = 2;
}

message SymmetricKeygenParams{
  // Symmetric key seed to use. Required.
  SymmetricKeySeed seed = 1;
  // Symmetric key type to generate. Required.
  SymmetricKeyType type = 2;
  // Symmetric key size. Required.
  SymmetricKeySize size = 3;
  // Diversifier string to use in KDF operation. Required.
  string diversifier = 4;
}

// Derive symmetric keys request.
message DeriveSymmetricKeysRequest{
  // SKU identifier. Required.
  string sku = 1;
  // Key generation parameters. Required.
  repeated SymmetricKeygenParams params = 2;
}

// Derive symmetric keys response.
message DeriveSymmetricKeysResponse{
  // Key bytes. Size is provided in the request.
  repeated bytes keys = 1;
}

// Create key and endorsement certificates request.
// The `sku` fields is used as an unique key to
// implement the specific key gen and endorsement certificate flow for a
// class of Devices.
message CreateKeyAndCertRequest {
  // SKU identifier. Required.
  string sku = 1;
  // Device identifier. Optional.
  device_id.DeviceId device_id = 2;
  // Serial Number per sku. Required.
  bytes serial_number = 3;
}

// Endorsed key bundle.
message EndorsedKey {
  // Certificate endorsing the public portion of the private key encapsulated
  // inside `wrapped_key`. This field is not set if `wrapped_key` encapsulates
  // a symmetric key.
  crypto.cert.Certificate cert = 1;
  // Wrapped key object.
  crypto.wrap.WrappedKey wrapped_key = 2;
}

// Create key and endorsement certificates reponse.
message CreateKeyAndCertResponse {
  // List of keys.
  repeated EndorsedKey keys = 1;
}

// Initialize SKU session request.
message InitSessionRequest {
  // SKU identifier. Required.
  string sku = 1;
  // SKU authentication token used to authenticate the client. This will be
  // moved to the authentication layer in the future. Required.
  string sku_auth = 2;
}

// Initialize SKU session response.
message InitSessionResponse {
  // SKU session token. Used to identify the client session. This will be moved
  // to the authentication layer in the future.
  string sku_session_token = 1;
  // PA endpoint. The client should select connections to this client to issue
  // any provisioning calls (e.g. CreateKeyAndCertRequest).
  string pa_endpoint = 2;
  // List of authenticate methods. Required.
  repeated string auth_methods = 3;
}

// Close SKU session request.
message CloseSessionRequest {
  // Empty.
}
// Close SKU session response.
message CloseSessionResponse {
  // Empty.
}

// Device Registration request.
message RegistrationRequest {
  // Device record. Required.
  device_id.DeviceRecord device_record = 1;
}

// Device Registration reponse.
message RegistrationResponse {
  // Empty.
}