From cc7719c9d014ca8c16828a84ccc95c0344bb34ed Mon Sep 17 00:00:00 2001 From: Tomasz Zurkowski Date: Mon, 14 Mar 2022 22:23:52 +0100 Subject: [PATCH] docs: improve comments in security proto The existing comments did not match the service definition (they look like copy paste from another service). I also added a little bit more comments for the fields in the request and response. Signed-off-by: Tomasz Zurkowski Signed-off-by: Andrey Smirnov --- api/security/security.proto | 7 +++++-- pkg/machinery/api/security/security.pb.go | 9 ++++++--- website/content/docs/v1.0/Reference/api.md | 10 +++++----- 3 files changed, 16 insertions(+), 10 deletions(-) diff --git a/api/security/security.proto b/api/security/security.proto index f28df2f8e..a6704aee7 100644 --- a/api/security/security.proto +++ b/api/security/security.proto @@ -9,13 +9,16 @@ service SecurityService { rpc Certificate(CertificateRequest) returns (CertificateResponse); } -// The request message containing the process name. +// The request message containing the certificate signing request. message CertificateRequest { + // Certificate Signing Request in PEM format. bytes csr = 1; } -// The response message containing the requested logs. +// The response message containing signed certificate. message CertificateResponse { + // Certificate of the CA that signed the requested certificate in PEM format. bytes ca = 1; + // Signed X.509 requested certificate in PEM format. bytes crt = 2; } diff --git a/pkg/machinery/api/security/security.pb.go b/pkg/machinery/api/security/security.pb.go index 3ef7739dc..59df90f3a 100644 --- a/pkg/machinery/api/security/security.pb.go +++ b/pkg/machinery/api/security/security.pb.go @@ -21,12 +21,13 @@ const ( _ = protoimpl.EnforceVersion(protoimpl.MaxVersion - 20) ) -// The request message containing the process name. +// The request message containing the certificate signing request. type CertificateRequest struct { state protoimpl.MessageState sizeCache protoimpl.SizeCache unknownFields protoimpl.UnknownFields + // Certificate Signing Request in PEM format. Csr []byte `protobuf:"bytes,1,opt,name=csr,proto3" json:"csr,omitempty"` } @@ -69,13 +70,15 @@ func (x *CertificateRequest) GetCsr() []byte { return nil } -// The response message containing the requested logs. +// The response message containing signed certificate. type CertificateResponse struct { state protoimpl.MessageState sizeCache protoimpl.SizeCache unknownFields protoimpl.UnknownFields - Ca []byte `protobuf:"bytes,1,opt,name=ca,proto3" json:"ca,omitempty"` + // Certificate of the CA that signed the requested certificate in PEM format. + Ca []byte `protobuf:"bytes,1,opt,name=ca,proto3" json:"ca,omitempty"` + // Signed X.509 requested certificate in PEM format. Crt []byte `protobuf:"bytes,2,opt,name=crt,proto3" json:"crt,omitempty"` } diff --git a/website/content/docs/v1.0/Reference/api.md b/website/content/docs/v1.0/Reference/api.md index d346d85fe..3a2dff63a 100644 --- a/website/content/docs/v1.0/Reference/api.md +++ b/website/content/docs/v1.0/Reference/api.md @@ -3067,12 +3067,12 @@ ResourceService provides user-facing API for the Talos resources. ### CertificateRequest -The request message containing the process name. +The request message containing the certificate signing request. | Field | Type | Label | Description | | ----- | ---- | ----- | ----------- | -| csr | [bytes](#bytes) | | | +| csr | [bytes](#bytes) | | Certificate Signing Request in PEM format. | @@ -3082,13 +3082,13 @@ The request message containing the process name. ### CertificateResponse -The response message containing the requested logs. +The response message containing signed certificate. | Field | Type | Label | Description | | ----- | ---- | ----- | ----------- | -| ca | [bytes](#bytes) | | | -| crt | [bytes](#bytes) | | | +| ca | [bytes](#bytes) | | Certificate of the CA that signed the requested certificate in PEM format. | +| crt | [bytes](#bytes) | | Signed X.509 requested certificate in PEM format. |