Talk about key rotation downtime and "rotationPolicy: Always"

[maelvls]

Questions around possible downtime while rotating the private key secret were asked multiple times on the Kubernetes Slack: 1, 2. This PR is about mentioning that there is no expected downtime.

Preview: https://deploy-preview-521--cert-manager.netlify.app/docs/usage/certificate/#rotation-private-key

Related:

• Allow private key rotation when renewing certificates cert-manager#2402 (PR introducing private key auto-rotation when cert renewed)

[maelvls]

I needed to use {id="key-usages"} to avoid breaking people's links anchored to the "Key Usages" section. But our old version of hugo does not support setting custom id anchors. As discussed in #507, upgrading to the latest Hugo version isn't trivial either.

Update: using {#id} anchors instead of {id="id"} seems to have done the trick.

[maelvls]

/hold

[wallrj]

Thanks @maelvls

I spotted a few typos and made a few suggestions.
Also suggest going through all the changes in the PR and ensuring that references to cert-manager or Kubernetes resource types are capitalized. E.g. Certificate, Secret etc....I didn't highlight them all below.

[maelvls]

TODO: add a note that says "changing Never to Always does not immediately trigger a rotation of the private key. done

[maelvls]

/assign @wallrj

[JoshVanL]

This good to me, reads really well :)

/lgtm

[wallrj]

I spotted a few more typos.

[wallrj]

Suggested change

	Setting the `rotationPolicy: Always` or change the Certificate's spec won't
	rotate the private key immediately. In order to get the private key secret
	rotated, the certificate objects must be reissued. A certificate object is
	reissued with either:
	Setting the `rotationPolicy: Always` or changing other fields in the Certificate spec won't
	rotate the private key immediately. In order to rotate the private key, the certificate objects must be reissued. A certificate object is
	reissued under the following circumstances:

[wallrj]

It's not showing the diff for some reason. s/or change the/or changing the/.

And maybe it would read better as:

Changing the Certificate spec does not trigger the renewal process, so if you change the value to rotationPolicy: Always and you want the private key to be rotated immediately, you will have to manually trigger the renewal by:

[munnerz]

Also:

Changing the Certificate spec does not trigger the renewal process,

This statement in isolation is not true, and may cause confusion. The majority of fields will cause a re-issuance (e.g. changing dnsNames, commonName, usages etc). Changing the rotationPolicy (or any other fields that control how a renewal happens) won't cause a re-issuance immediately.

[maelvls]

In #521 (comment), Richard proposed to remove the line:

The certificate object is reissued when a change to the certificate object's spec is made.

I think I misunderstood Richard's suggestion back in May. I should have understood Richard's comment as:

The certificate object is reissued when a change to one of the certificate object's fields commonName, dnsNames, ipAddresses, uris, emailAddresses, subject, isCA, usages, duration or issuerRef is made.

(as per RequestMatchesSpec)

Apologies for my misunderstanding.

I re-added the line about reissuing on spec change in ea1f25b.

[wallrj]

Suggested change

	👉 It is recommended you configure `rotationPolicy: Always` on your certificate
	resources. It is considered to be a good practice to rotate private keys when a
	certificate is renewed.
	👉 We recommend that you configure `rotationPolicy: Always` on your certificate
	resources. It is considered to be a good practice to rotate private keys when a
	certificate is renewed.

Can we link to a reference backing up this claim good practice?

[maelvls]

I cannot find any good reference to support this claim. By reading some discussions:

• https://community.letsencrypt.org/t/should-i-always-generate-a-new-csr-private-key/100985
• https://security.stackexchange.com/questions/27810/should-i-change-the-private-key-when-renewing-a-certificate

People seem to suggest that:

1. RSA/ECDSA private keys can't (mostly) be guessed, which means there is less of a need for renewing them (unlike passwords that are way shorter),
2. But at the same time, an RSA/ECDSA private keys may be leaked through some old backup, leading to a possible man-in-the-middle situation.

Looking around, I found that:

• certbot renews the private key while renewing the cert by default, but there is nothing explaining why;

• NIST's Guidelines for the Selection, Configuration, and Use of Transport Layer Security (TLS) Implementations does not indicate when to renew the private key; the only bit that talks about what to do with a server private key is this:

  The security of the server’s private key is critical to the security of TLS. If the server’s private key is weak or can be obtained by a third party, the third party can masquerade as the server to
  all clients.

• NIST's Recommendation for Key Management has a nice table but no claim on when the private key should be renewweed:
  

• f5-bigip suggests to renew the private key (https://support.f5.com/csp/article/K14620):

  Note: When renewing an SSL certificate from a CA, F5 recommends that you generate a new certificate signing request (CSR) and private key. Although some CAs allow you to renew a certificate by using the existing CSR on file, this method is less secure as it retains the existing private key. To generate a new CSR, follow the procedure for Creating an SSL CSR and private key.

@SgtCoDFish Do you know a place where that would be written? Or should I rather remove this claim and say that "the cert-manager team suggests users renewing the private key along with the certificate"?

[munnerz]

I think one big reason why you would want to, is that if you were to renew a certificate using the same private key, and then after the initial certificates expiry learn that the private key had actually been leaked, the new certificate would be valid to use with the old private key, thus the 'rotation' didn't really provide any more protection and really just extended the lifetime of the existing certificate.

[SgtCoDFish]

James is spot on. I don't have like an authoritative source to hand for why you'd want to rotate as much as possible, but certainly I think it's best practice.

The longer a key is used, the more likely it is to be exposed. Keys should be renewed "as often as possible" for me; not only for security reasons but also operational reasons to show that it can be done, so that if it has to be done in an emergency the org has confidence that they can carry it out.

[maelvls]

I tried my best to formulate a paragraph that "justifies" our point of view. Please correct me if any of this is wrong. 🔥

👉 We recommend that you configure rotationPolicy: Always on your Certificate resources.

Rotating both the certificate and the private key simultaneously prevents the risk of issuing a certificate associated with an exposed private key.

Another benefit to renewing the private key regularly is to let you be confident that the private key rotation can be done in case of an emergency.

More generally, it is a good practice to be rotating the keys as often as possible, reducing the risk associated with compromised keys.

[JoshVanL]

/hold
Since there are more review comments

[wallrj]

/lgtm

[jetstack-bot]

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: maelvls, wallrj

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Needs approval from an approver in each of these files:

• OWNERS [maelvls]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[SgtCoDFish]

/lgtm

[maelvls]

/unhold