From 7121c78d34dd346a3aeb2c300c40d4b63281a53c Mon Sep 17 00:00:00 2001 From: Daniel Nephin Date: Thu, 25 Nov 2021 13:24:35 -0500 Subject: [PATCH] ca: update godoc To clarify what to expect from the data stored in this field, and the behaviour of this function. --- agent/consul/leader_connect_ca.go | 10 ++++++---- agent/structs/connect_ca.go | 23 ++++++++++++++++------- 2 files changed, 22 insertions(+), 11 deletions(-) diff --git a/agent/consul/leader_connect_ca.go b/agent/consul/leader_connect_ca.go index 0a6b0b47a4..2cf6fce970 100644 --- a/agent/consul/leader_connect_ca.go +++ b/agent/consul/leader_connect_ca.go @@ -602,10 +602,12 @@ func (c *CAManager) getLeafSigningCertFromRoot(root *structs.CARoot) string { return root.IntermediateCerts[len(root.IntermediateCerts)-1] } -// secondaryInitializeIntermediateCA runs the routine for generating an intermediate CA CSR and getting -// it signed by the primary DC if the root CA of the primary DC has changed since the last -// intermediate. It should only be called while the state lock is held by setting the state -// to non-ready. +// secondaryInitializeIntermediateCA generates a Certificate Signing Request (CSR) +// for the intermediate CA that is used to sign leaf certificates in the secondary. +// The CSR is signed by the primary DC and then persisted in the state store. +// +// This method should only be called while the state lock is held by setting the +// state to non-ready. func (c *CAManager) secondaryInitializeIntermediateCA(provider ca.Provider, config *structs.CAConfiguration) error { activeIntermediate, err := provider.ActiveIntermediate() if err != nil { diff --git a/agent/structs/connect_ca.go b/agent/structs/connect_ca.go index f3d175d350..4b4549b7ae 100644 --- a/agent/structs/connect_ca.go +++ b/agent/structs/connect_ca.go @@ -76,9 +76,14 @@ type CARoot struct { // SerialNumber is the x509 serial number of the certificate. SerialNumber uint64 - // SigningKeyID is the ID of the public key that corresponds to the private - // key used to sign leaf certificates. Is is the HexString format of the - // raw AuthorityKeyID bytes. + // SigningKeyID is the connect.HexString encoded id of the public key that + // corresponds to the private key used to sign leaf certificates in the + // local datacenter. + // + // The value comes from x509.Certificate.SubjectKeyId of the local leaf + // signing cert. + // + // See https://www.rfc-editor.org/rfc/rfc3280#section-4.2.1.1 for more detail. SigningKeyID string // ExternalTrustDomain is the trust domain this root was generated under. It @@ -192,10 +197,14 @@ type IssuedCert struct { // This is encoded in standard hex separated by :. SerialNumber string - // CertPEM and PrivateKeyPEM are the PEM-encoded certificate and private - // key for that cert, respectively. This should not be stored in the - // state store, but is present in the sign API response. - CertPEM string `json:",omitempty"` + // CertPEM is a PEM encoded bundle of a leaf certificate, optionally followed + // by one or more intermediate certificates that will form a chain of trust + // back to a root CA. + // + // This field is not persisted in the state store, but is present in the + // sign API response. + CertPEM string `json:",omitempty"` + // PrivateKeyPEM is the PEM encoded private key associated with CertPEM. PrivateKeyPEM string `json:",omitempty"` // Service is the name of the service for which the cert was issued.