From 20cc16d188f530067eaf2feaf7e5ad4098f20596 Mon Sep 17 00:00:00 2001 From: Hayden Blauzvern Date: Tue, 2 Aug 2022 20:49:18 +0000 Subject: [PATCH] Add documentation for SCT formats Fixes #539 Signed-off-by: Hayden Blauzvern --- fulcio.proto | 9 ++++++++- fulcio.swagger.json | 4 ++-- pkg/generated/protobuf/fulcio.pb.go | 11 +++++++++-- pkg/generated/protobuf/legacy/fulcio_legacy.pb.go | 2 +- 4 files changed, 20 insertions(+), 6 deletions(-) diff --git a/fulcio.proto b/fulcio.proto index 46787e7d5..3348792ad 100644 --- a/fulcio.proto +++ b/fulcio.proto @@ -159,9 +159,12 @@ message SigningCertificateDetachedSCT { */ CertificateChain chain = 1; /* - * The signed certificate timestamp is a promise for including the certificate in + * The Signed Certificate Timestamp (SCT) is a promise for including the certificate in * a certificate transparency log. It can be "stapled" to verify the inclusion of * a certificate in the log in an offline fashion. + * + * The SCT format is an AddChainResponse struct, defined in + * https://github.com/google/certificate-transparency-go */ bytes signed_certificate_timestamp = 2; } @@ -172,6 +175,10 @@ message SigningCertificateEmbeddedSCT { * by all intermediate certificates (if present), finishing with the root certificate. * * All values are PEM-encoded certificates. + * + * The leaf certificate contains an embedded Signed Certificate Timestamp (SCT) to + * verify inclusion of the certificate in a log. The SCT format is a SignedCertificateTimestampList, + * as defined in https://datatracker.ietf.org/doc/html/rfc6962#section-3.3 */ CertificateChain chain = 1; } diff --git a/fulcio.swagger.json b/fulcio.swagger.json index 00d0f43bb..47aa207e7 100644 --- a/fulcio.swagger.json +++ b/fulcio.swagger.json @@ -295,7 +295,7 @@ "signedCertificateTimestamp": { "type": "string", "format": "byte", - "description": "The signed certificate timestamp is a promise for including the certificate in\na certificate transparency log. It can be \"stapled\" to verify the inclusion of\na certificate in the log in an offline fashion." + "description": "The Signed Certificate Timestamp (SCT) is a promise for including the certificate in\na certificate transparency log. It can be \"stapled\" to verify the inclusion of\na certificate in the log in an offline fashion.\n\nThe SCT format is an AddChainResponse struct, defined in\nhttps://github.com/google/certificate-transparency-go" } }, "title": "(-- api-linter: core::0142::time-field-type=disabled\n aip.dev/not-precedent: SCT is defined in RFC6962 and we keep the name consistent for easier understanding. --)" @@ -305,7 +305,7 @@ "properties": { "chain": { "$ref": "#/definitions/v2CertificateChain", - "description": "The certificate chain serialized with the leaf certificate first, followed\nby all intermediate certificates (if present), finishing with the root certificate.\n\nAll values are PEM-encoded certificates." + "description": "The certificate chain serialized with the leaf certificate first, followed\nby all intermediate certificates (if present), finishing with the root certificate.\n\nAll values are PEM-encoded certificates.\n\nThe leaf certificate contains an embedded Signed Certificate Timestamp (SCT) to\nverify inclusion of the certificate in a log. The SCT format is a SignedCertificateTimestampList,\nas defined in https://datatracker.ietf.org/doc/html/rfc6962#section-3.3" } } }, diff --git a/pkg/generated/protobuf/fulcio.pb.go b/pkg/generated/protobuf/fulcio.pb.go index 748d7cb3e..314fca537 100644 --- a/pkg/generated/protobuf/fulcio.pb.go +++ b/pkg/generated/protobuf/fulcio.pb.go @@ -15,7 +15,7 @@ // Code generated by protoc-gen-go. DO NOT EDIT. // versions: -// protoc-gen-go v1.28.0 +// protoc-gen-go v1.28.1 // protoc v3.12.4 // source: fulcio.proto @@ -472,9 +472,12 @@ type SigningCertificateDetachedSCT struct { // All values are PEM-encoded certificates. Chain *CertificateChain `protobuf:"bytes,1,opt,name=chain,proto3" json:"chain,omitempty"` // - // The signed certificate timestamp is a promise for including the certificate in + // The Signed Certificate Timestamp (SCT) is a promise for including the certificate in // a certificate transparency log. It can be "stapled" to verify the inclusion of // a certificate in the log in an offline fashion. + // + // The SCT format is an AddChainResponse struct, defined in + // https://github.com/google/certificate-transparency-go SignedCertificateTimestamp []byte `protobuf:"bytes,2,opt,name=signed_certificate_timestamp,json=signedCertificateTimestamp,proto3" json:"signed_certificate_timestamp,omitempty"` } @@ -534,6 +537,10 @@ type SigningCertificateEmbeddedSCT struct { // by all intermediate certificates (if present), finishing with the root certificate. // // All values are PEM-encoded certificates. + // + // The leaf certificate contains an embedded Signed Certificate Timestamp (SCT) to + // verify inclusion of the certificate in a log. The SCT format is a SignedCertificateTimestampList, + // as defined in https://datatracker.ietf.org/doc/html/rfc6962#section-3.3 Chain *CertificateChain `protobuf:"bytes,1,opt,name=chain,proto3" json:"chain,omitempty"` } diff --git a/pkg/generated/protobuf/legacy/fulcio_legacy.pb.go b/pkg/generated/protobuf/legacy/fulcio_legacy.pb.go index c7a34a244..220c45a91 100644 --- a/pkg/generated/protobuf/legacy/fulcio_legacy.pb.go +++ b/pkg/generated/protobuf/legacy/fulcio_legacy.pb.go @@ -15,7 +15,7 @@ // Code generated by protoc-gen-go. DO NOT EDIT. // versions: -// protoc-gen-go v1.28.0 +// protoc-gen-go v1.28.1 // protoc v3.12.4 // source: fulcio_legacy.proto