Skip to content

Update TLS Sections of guides.md #216

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 3 commits into
base: master
Choose a base branch
from
Open

Update TLS Sections of guides.md #216

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
badf79e
Update guides.md
techjeffharris Jan 19, 2023
91fe524
Update docs/guides.md
techjeffharris Jan 20, 2023
6f29d6e
Update guides.md
techjeffharris Jan 20, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
56 changes: 53 additions & 3 deletions docs/guides.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -493,21 +493,71 @@ If you would like to replace this certificate by a valid one, either from an int

Note that if you use an non-public certificate authority and XenOrchestra, you have [additional configuration to specify on XenOrchestra side](https://xen-orchestra.com/docs/configuration.html#custom-certificate-authority).

### Certificate Requirements

Please see the [Install a TLS certificate on your server](https://docs.citrix.com/en-us/citrix-hypervisor/hosts-pools.html#install-a-tls-certificate-on-your-server) documentation from Citrix for details regarding the specific requirements for TLS certificates.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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).

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.


:::warning
As of this writing, the Citrix documentation makes no mention of the `SubjectAlternateName` extension that is effectively required in modern environments. Please see the Subject Alternate Names section below for details.
:::

### Subject Alternate Names
Many, if not most, modern TLS and HTTPS clients reject certificates that do not include at least one `SubjectAlternateName` extension. See the [Remove support for commonName matching in certificates](https://developer.chrome.com/blog/chrome-58-deprecations/#remove-support-for-commonname-matching-in-certificates) section of the [Deprecations and Removals in Chrome 58](https://developer.chrome.com/blog/chrome-58-deprecations/) post from March 2017 to the Chrome Developer Blog from for further details.

### Generate certificate signing request

#### Single Hosts
You can use the auto-generated key to create a certificate signing request:

```
openssl req -new -subj '/CN=XCP-ng hypervisor/' \
-addext "subjectAltName = DNS:xcp-ng.example.com" \
-key /etc/xensource/xapi-ssl.pem \
-out xcp-ng.csr
```

#### Resource Pools
Stats, consoles and other parts of a pool are served locally on a node within a pool. E.g., when we ask to display the stats of a host, XAPI will tell us to ask the slave (with an HTTP redirect code). In order to prevent certificates on the slave hosts from being rejected after this redirect, each host must use a ceritficate that is configured with a `SubjectAlternateName` for each DNS name and IP address used by all hosts in the pool, not just the master.

:::tip
It is possible to generate a single certificate that encompasses all IPs and DNS Names used by all hosts in the pool, then deploy that certificate to each host in the pool.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@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.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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. 😅

Copy link
Author

@techjeffharris techjeffharris Jan 20, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?

Copy link

@psafont psafont Jan 23, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

:::

For example, with a pool of 3 hosts:
```
name-label: xcp-ng-1, FQDN: xcp-ng-1.example.com, IP: 10.0.0.11
name-label: xcp-ng-2, FQDN: xcp-ng-2.example.com, IP: 10.0.0.12
name-label: xcp-ng-3, FQDN: xcp-ng-3.example.com, IP: 10.0.0.13
```

You can use the auto-generated key to create a certificate signing request:

```
openssl req -new -key /etc/xensource/xapi-ssl.pem -subj '/CN=XCP-ng hypervisor/' -out xcp-ng.csr
openssl req -new -subj '/CN=XCP-ng resource pool/' \
-addext "subjectAltName = DNS:xcp-ng-1.example.com" \
-addext "subjectAltName = DNS:xcp-ng-1.example.com" \
-addext "subjectAltName = DNS:xcp-ng-1.example.com" \
-addext "subjectAltName = IP:10.0.0.11" \
-addext "subjectAltName = IP:10.0.0.12" \
-addext "subjectAltName = IP:10.0.0.13" \
-key /etc/xensource/xapi-ssl.pem \
-out xcp-ng.csr
```

### Install the certificate chain (for XCP-ng v8.2+)

Once you have your certificates, upload the certificates to your XCP-ng host, then use the following command to install the certificates:
Once you have your certificate(s), upload the certificate(s) to your XCP-ng host, then use the following command to install the certificates:

```
xe host-server-certificate-install certificate=<path to certificate> private-key=<path to key> certificate-chain=<path to chain>
xe host-server-certificate-install \
certificate=<path to certificate> \
private-key=<path to key> \
certificate-chain=<path to chain> \
host=xcp-ng-1
```
:::tip
When deploying certificate(s) to a resource pool, repeat this process for each host in the resource pool.
:::

:::tip
The `certificate-chain` parameter is optional. The private key can be deleted after certificate is installed for additional security. For additional details check Citrix [documentation](https://docs.citrix.com/en-us/citrix-hypervisor/hosts-pools.html#install-a-tls-certificate-on-your-server).
Expand Down