Update TLS Sections of guides.md

[techjeffharris]

1. Added section for certificate requirements that links to Citrix TLS Certificate documentation
2. Added warning that as of this writing Citrix TLS Certificate document does not mention the SubjectAlternateName extension that is effectively required in modern environments
3. Added information regarding the SubjectAlternateName extension
4. Modified example for generating a CSR
   A. Added definition of a SubjectAlternateName extension
   b. Broke command into multiple lines using \ to improve readability
5. Added section detailing certificate requirements for hosts within resource pools
6. Added additional example for generating a CSR for a resource pool
   a. Added table outlining name-label, IP, and FQDN of 3 hosts in an example pool
   b. Included definitions of SubjectAlternateName extension for each IP/FQDN in example
   c. Broke command into multiple lines using \ to improve readability
7. Modified the instructions for installing the certificate to xcp-ng 8.2+ hosts
   a. Added (s) to Certificate to make it clear that a person may generate one or multiple certificates
   b. Added host= parameter which is required for resource pools (possibly for single-hosts as well?)
   c. Broke the command into multiple lines using \ because it was getting too long for a single line.

Signed-off-by: Jeff Harris [email protected]

Before submitting the pull request, you must agree with the following statements by checking both boxes with a 'x'.

• "I accept that my contribution is placed under the CC BY-SA 2.0 license [1]."
• "My contribution complies with the Developer Certificate of Origin [2]."

[1] https://creativecommons.org/licenses/by-sa/2.0/
[2] https://xcp-ng.org/docs/contributing.html#developer-certificate-of-origin-dco

[stormi]

Very nice contribution, well written in my opinion. Just added a few comments.

[stormi]

If you are motivated enough, you could try to extract the requirements from the Citrix Hypervisor doc. We sometimes link to this doc, but it's better to write things down in our own doc, with our own words. There's no guarantee about the links to Citrix Hypervisor docs (btw Citrix Hypervisor is being renamed to XenServer again).

[techjeffharris]

For the record, my laughter is about them renaming it back to XenServer.

I can look into this, but I don't want to copy/paste their words verbatim--I'm nowhere near a lawyer, but something tells me that would be frowned upon.

[psafont]

I would recommend to not add this, and instead say certificate chains for pools are best practice.

[techjeffharris]

@psafont could you please elaborate on "certificate chains for pools are best practice"? Exactly what you're suggesting is not totally clear here--perhaps that's the point? I understand there is risk associated with disseminating security recommendations.

[psafont]

By certificate chains I mean using a common certificate to sign all the host certificates in a pool, each certificate having a different subject (CN + SAN). This is most easily done locally generating a CSR for each of the host certificates and then filling the request with the common certificate. Then the publick key of the shared certificate can be installed in the all the clients connecting to the server.

This allows to use a single certificate to validate all the hosts, without them sharing subject.

[techjeffharris]

Thanks for elaborating, @psafont. I agree that it would be good to recommend using a dedicated intermediate CA Certificate for signing the certificates used by hosts. This is actually my setup at home.

However, as noted by @olivierlambert and as per my testing documented on my post the xcp-ng forums (self signed certificate in certificate chain), it appears that each host certificate needs to have SANs that match the IP addresses of all hosts in the pool. Given that that is a technical requirement, if we wanted each host to have a unique subject, the only variable we would be able to change would be the common name. However, as per RFC 2818 the common name is only used for identification as a fallback when no SANs are provided and is otherwise ignored.

If a subjectAltName extension of type dNSName is present, that MUST
be used as the identity. Otherwise, the (most specific) Common Name
field in the Subject field of the certificate MUST be used. Although
the use of the Common Name is existing practice, it is deprecated and
Certification Authorities are encouraged to use the dNSName instead.

If I understand this correctly, even though we could use a unique common-name for each host, if all hosts need to have SANs for all other hosts then signing certificates with unique common names for each host would be purely symbolic and for human eyes only.

I should note that I am an enthusiast and not a professional in this matter, so I would be grateful to be corrected if my understanding is limited or incorrect. 😅

[techjeffharris]

Ah, I think I see the key difference I was missing. Even though each host certificate would have all the same SANs, by generating a signing request for each host using the each host's unique keypair, even if they are signed by the same CA, they will still be unique to each host because the CSRs were generated with unique keypairs. Is that correct?

[psafont]

it appears that each host certificate needs to have SANs that match the IP addresses of all hosts in the pool.

I believe there is no such technical requirement, when following a redirect the new request should be done against a different IP/host and the TLS connection renegotiated with that host, meaning none of the hosts' certs should have identifying information from the other one.

For 8.3, the self-signed certificate has both hostname and IP as SANs and hostname in the CN as backup: https://github.com/xapi-project/xen-api/blob/master/ocaml/gencert/selfcert.ml#L149-L157

they will still be unique to each host because the CSRs were generated with unique keypairs. Is that correct?

Yes, that correct, they won't share private keys. I believe their subject should be unique in any case.

[stormi]

Hi @techjeffharris ! What's the current status for this pull request? It would be a nice improvements to the documentation once the last details of certificate handling are managed.

[techjeffharris]

Hi @stormi. Sorry for disappearing! Other life priorities have taken precedent over following up on and test feedback from @psafont. I just noticed the other day that my host certificates have expired, and since I have a bit more time on my hands these days, it's time to start working on this again.

I have been working on a tool that I'm calling step-renewer that uses a systemd unit and timer along with a config file and a few bash scripts to automate the use of step cli to use the ACME protocol to get certificates from a step-ca server then run a user-defined post-update script to say, move the cert and key and/or restart nginx, etc. The main goals are to eliminate human error and increase repeatability which is helpful for for testing scenarios like this, but it's also very helpful for fully automatic, regular certificate renewal at a specific time with expiration at a specific time etc. Anyhoo.. enough tooting my own horn.

In retrospect, I believe that around this time last year step-renewer did not have the means for manually specifying SANs to request and validate, but it is capable of that now. Given that a year has passed and perhaps things have changed, I intend to test using step-cli on each host to request its own certificate with only it's own SANs and IPs. If that results in /rrd-updates tasks stalling, then instead I'll create a CSR on each host each containing all SANs and IPs for all hosts, then sign those CSRs, then install the certificates on each host.

My hope is that I made a mistake in the past when creating each host cert with only its own SANs and IPs which resulted in seeing the continuous /rrd-updates issue as that method seems like the most principled solution (each host only attests its own valid identities) and it is more feasible to automate using the ACME http-challenge for automated certificate renewal.

Also, it appears that this document has changed and I'll need to rebase my branch against upstream before moving forward as well.

[stormi]

Thanks @techjeffharris! Looking forward to your updated contribution!