From ada732c4b602fdd0e443317aa3bcbf55a45cc68a Mon Sep 17 00:00:00 2001 From: Chris Morrow Date: Thu, 23 Jan 2025 00:33:58 -0500 Subject: [PATCH] Cleanup some words used in the documentation, mostly: * "switch" -> "network device" * wrap all documentation lines under 80 chars wide I don't enjoy the last section of documetation (TPM1.2 focused content), but can't decide the better wording for that right now. --- proto/tpm_enrollz.proto | 78 ++++++++++++++++++++++------------------- 1 file changed, 42 insertions(+), 36 deletions(-) diff --git a/proto/tpm_enrollz.proto b/proto/tpm_enrollz.proto index 04768d4..9b291a1 100644 --- a/proto/tpm_enrollz.proto +++ b/proto/tpm_enrollz.proto @@ -22,7 +22,7 @@ import "github.com/openconfig/attestz/proto/common_definitions.proto"; option go_package = "github.com/openconfig/attestz"; // Request for a given control card to return its Initial Attestation Key (IAK) -// certificate signed by the switch vendor CA. +// certificate signed by the network device vendor CA. message GetIakCertRequest { // Switch control card selected identifier. ControlCardSelection control_card_selection = 1; @@ -30,38 +30,39 @@ message GetIakCertRequest { } // Response from the specified control card containing its Initial Attestation -// Key (IAK) certificate signed by switch vendor CA. +// Key (IAK) certificate signed by network device vendor CA. message GetIakCertResponse { // Vendor identity fields of the selected control card. ControlCardVendorId control_card_id = 1; - // PEM-encoded initial attestation key certificate signed by the switch - // vendor CA. + // PEM-encoded initial attestation key certificate signed by the network + // device vendor CA. string iak_cert = 2; - // [Optional] PEM-encoded initial DevID certificate signed by the switch - // vendor CA. This field should always be populated on the primary control - // card. It should only be populated for standby/secondary control card when - // no direct communication to that control card is possible. + // [Optional] PEM-encoded initial DevID certificate signed by the network + // device vendor CA. This field should always be populated on the primary + // control card. It should only be populated for standby/secondary control + // card when no direct communication to that control card is possible. string idevid_cert = 3; } // Request for a given control card to rotate/install an owner Initial -// Attestation Key (oIAK) certificate signed by the switch owner/administrator -// CA. +// Attestation Key (oIAK) certificate signed by the network device +// owner/administrator CA. message RotateOIakCertRequest { // Switch control card selected identifier. ControlCardSelection control_card_selection = 1; // PEM-encoded owner initial attestation key certificate signed by the - // switch owner/administrator CA. The PEM formatted cert string can have - // more than one certificate block representing a certificate chain. + // network device owner/administrator CA. The PEM formatted cert string + // can have // more than one certificate block representing a certificate + // chain. string oiak_cert = 2; // [Optional] PEM-encoded owner initial DevID certificate signed by the - // switch owner/administrator CA. The PEM formatted cert string can have - // more than one certificate block representing a certificate chain. + // network device owner/administrator CA. The PEM formatted cert string + // can have more than one certificate block representing a certificate chain. // // Will be unassigned in these workflows: // 1. During oIak Installation, if `idevid_cert` was not @@ -76,8 +77,8 @@ message RotateOIakCertRequest { } // Response from the specified control card to rotate/install an owner Initial -// Attestation Key (oIAK) certificate signed by the switch owner/administrator -// CA. +// Attestation Key (oIAK) certificate signed by the network device +// owner/administrator CA. message RotateOIakCertResponse { // Leave empty for now to allow the addition of new fields without major // changes. @@ -96,9 +97,9 @@ message RotateAIKCertRequest { bytes symmetric_key_blob = 1; // AIK Cert in PEM format that is encrypted with the provided symmetric // key. - bytes aik_cert_blob = 2; + bytes aik_cert_blob = 2; } - + oneof value { bytes issuer_public_key = 1; // Encrypted payload that only the targeted device should be able @@ -118,30 +119,35 @@ message RotateAIKCertResponse { } } -// The service is responsible for TPM enrollment workflow on the switch -// owner/administrator side. In this workflow switch owner verifies device's -// Initial Attestation Key (IAK) and Initial DevID (IDevID) certificates (signed -// by the switch vendor CA) and installs/rotates owner IAK (oIAK) and owner -// IDevID (oIDevID) certificates (signed by switch owner CA). oIAK and oIDevID -// certs are based on the same underlying keys as IAK and IDevID certs -// respectively and give switch owner the ability to (1) fully control -// certificate structure, revocation and expiration policies and (2) remove -// external dependency on switch vendor CA during TPM attestation workflow. The -// assumption is that before the device is shipped to the switch owner, a switch -// vendor provisions each control card with an IAK and IDevID certificates -// following the TCG specification in Section 5.2 and Section 6.2: +// The service is responsible for TPM enrollment workflow on the network device +// owner/administrator side. In this workflow the network device owner verifies +// a device's Initial Attestation Key (IAK) and Initial DevID (IDevID) +// certificates (signed by the network device vendor CA) and installs or rotates +// owner IAK (oIAK) and owner IDevID (oIDevID) certificates (signed by the +// network device owner CA). oIAK and oIDevID certs are based on the same +// underlying keys as IAK and IDevID certs respectively and give network device +// owner the ability to: +// (1) Fully control certificate structure, revocation and expiration policies +// (2) Remove external dependencies upon the network device vendor CA during +// TPM attestation workflow. +// +// The assumption is that before the device is shipped to the network device +// owner, a network device vendor provisions each control card with an IAK and +// IDevID certificates following the TCG specification in Section 5.2 and +// Section 6.2: // protolint:disable MAX_LINE_LENGTH // https://trustedcomputinggroup.org/wp-content/uploads/TPM-2p0-Keys-for-Device-Identity-and-Attestation_v1_r12_pub10082021.pdf#page=20 -// Please consult Readme for more details on the workflow. +// Please consult the README.md for more details on the workflow. service TpmEnrollzService { // From a given control card fetch Initial Attestation Key (IAK) certificate - // signed by the switch vendor CA. + // signed by the network device vendor CA. rpc GetIakCert(GetIakCertRequest) returns (GetIakCertResponse); // For a given control card rotate owner Initial Attestation Key (oIAK) - // certificate signed by the switch owner/administrator CA. If no oIAK cert is - // present on the device, then a new one is persisted. Otherwise, a new oIAK - // cert should overwrite an existing oIAK cert on the device. + // certificate signed by the network device owner/administrator CA. If no + // oIAK cert is present on the device, then a new one is persisted. + // Otherwise, a new oIAK cert should overwrite an existing oIAK cert on the + // device. rpc RotateOIakCert(RotateOIakCertRequest) returns (RotateOIakCertResponse); // For TPM1.2 systems the following RPC's are used to enroll the device. @@ -159,4 +165,4 @@ service TpmEnrollzService { // the RPC. rpc RotateAIKCert(stream RotateAIKCertRequest) returns (stream RotateAIKCertRequest); -} \ No newline at end of file +}