[SSL] Keyless SSL style and new guide (#17518)

RebeccaTamachiro · pedrosousa · web-flow · commit 2fef82e539a6 · 2024-10-18T14:25:38.000+01:00
* Create fortanix HSM guide and fill in Requirements section

* Add instructions to generate Keyless certs

* Fix broken link

* Fix weird line breaks in keyless-delegation.mdx

* Fix apostrophes

* We police, improve hyperlinks text, and other text refinements

* Adjust frontmatter so that hsm tutorials order alphabetically

* List Fortanix in index.mdx and reorder alphabetically

* Suggestion not to duplicate content

* Apply suggestion from code review

Co-authored-by: Pedro Sousa &lt;680496+pedrosousa@users.noreply.github.com&gt;

* Rename file to more specifically reflect Fortanix product name

---------

Co-authored-by: Pedro Sousa &lt;680496+pedrosousa@users.noreply.github.com&gt;
diff --git a/src/content/docs/ssl/keyless-ssl/configuration/public-dns.mdx b/src/content/docs/ssl/keyless-ssl/configuration/public-dns.mdx
@@ -72,6 +72,6 @@ To create a Keyless certificate with the API, send a [`POST`](/api/operations/ke
 
 ### Allow incoming connections from Cloudflare
 
-During TLS handshakes, Cloudflare’s keyless client will initiate connections to the key server hostname or IP address you specify during certificate upload. By default, the keyless client will use a destination TCP port of 2407, but this can be changed during certificate upload or by editing the certificate details after upload.
+During TLS handshakes, Cloudflare's keyless client will initiate connections to the key server hostname or IP address you specify during certificate upload. By default, the keyless client will use a destination TCP port of 2407, but this can be changed during certificate upload or by editing the certificate details after upload.
 
-Create WAF custom rules that allow your key server to accept connections from only Cloudflare. We publish our IPv4 and IPv6 addresses [via our API](/api/operations/cloudflare-i-ps-cloudflare-ip-details).
+Create WAF custom rules that allow your key server to accept connections from only Cloudflare. You can get Cloudflare's IPv4 and IPv6 addresses via the [IP details API endpoint](/api/operations/cloudflare-i-ps-cloudflare-ip-details).
diff --git a/src/content/docs/ssl/keyless-ssl/glossary.mdx b/src/content/docs/ssl/keyless-ssl/glossary.mdx
@@ -12,10 +12,10 @@ description: Learn more about the common terms related to Keyless SSL.
 
 ## Cloudflare Keyless SSL key server (“key server”)
 
-The key server is a daemon that you run on your own infrastructure. The key server receives inbound requests from Cloudflare’s keyless client on TCP port `2407` (by default) so you must make sure that your firewall and other access control lists permit these requests from [Cloudflare’s IP ranges](https://www.cloudflare.com/ips/).
+The key server is a daemon that you run on your own infrastructure. The key server receives inbound requests from Cloudflare's keyless client on TCP port `2407` (by default) so you must make sure that your firewall and other access control lists permit these requests from [Cloudflare's IP ranges](https://www.cloudflare.com/ips/).
 
 Your key servers are contacted by Cloudflare during the TLS handshake process and must be online to terminate new TLS connections. Existing sessions can be resumed using unexpired TLS session tickets without needing to contact the key server.
 
 ## Cloudflare Keyless SSL client (“keyless client”)
 
-The keyless client is a process that runs on Cloudflare’s infrastructure. The keyless client makes outbound requests to your key server on TCP port `2407` for assistance in establishing new TLS sessions.
+The keyless client is a process that runs on Cloudflare's infrastructure. The keyless client makes outbound requests to your key server on TCP port `2407` for assistance in establishing new TLS sessions.
diff --git a/src/content/docs/ssl/keyless-ssl/hardware-security-modules/aws-cloud-hsm.mdx b/src/content/docs/ssl/keyless-ssl/hardware-security-modules/aws-cloud-hsm.mdx
@@ -1,8 +1,6 @@
 ---
 pcx_content_type: tutorial
 title: AWS cloud HSM
-sidebar:
-  order: 2
 ---
 
 :::note[Note]
diff --git a/src/content/docs/ssl/keyless-ssl/hardware-security-modules/azure-dedicated-hsm.mdx b/src/content/docs/ssl/keyless-ssl/hardware-security-modules/azure-dedicated-hsm.mdx
@@ -1,8 +1,6 @@
 ---
 pcx_content_type: tutorial
 title: Azure Dedicated HSM
-sidebar:
-  order: 3
 ---
 
 This tutorial uses [Azure Dedicated HSM](https://azure.microsoft.com/en-us/services/azure-dedicated-hsm/) — a FIPS 140-2 Level 3 certified implementation based on the Gemalto SafeNet Luna a790.
diff --git a/src/content/docs/ssl/keyless-ssl/hardware-security-modules/azure-managed-hsm.mdx b/src/content/docs/ssl/keyless-ssl/hardware-security-modules/azure-managed-hsm.mdx
@@ -1,8 +1,6 @@
 ---
 pcx_content_type: tutorial
 title: Azure Managed HSM
-sidebar:
-  order: 4
 ---
 
 This tutorial uses [Microsoft Azure’s Managed HSM](https://azure.microsoft.com/en-us/updates/akv-managed-hsm-public-preview/) — a FIPS 140-2 Level 3 certified implementation — to deploy a VM with the Keyless SSL daemon.
diff --git a/src/content/docs/ssl/keyless-ssl/hardware-security-modules/entrust-nshield-connect.mdx b/src/content/docs/ssl/keyless-ssl/hardware-security-modules/entrust-nshield-connect.mdx
@@ -1,8 +1,6 @@
 ---
 pcx_content_type: tutorial
 title: Entrust nShield Connect
-sidebar:
-  order: 6
 ---
 
 :::note[Note]
diff --git a/src/content/docs/ssl/keyless-ssl/hardware-security-modules/fortanix-dsm.mdx b/src/content/docs/ssl/keyless-ssl/hardware-security-modules/fortanix-dsm.mdx
@@ -0,0 +1,14 @@
+---
+pcx_content_type: reference
+title: Fortanix Data Security Manager
+sidebar:
+  label: Fortanix DSM
+---
+
+import { Example } from "~/components";
+
+You can use Cloudfare Keyless SSL with [Fortanix Data Security Manager (DSM)](https://www.fortanix.com/platform/data-security-manager), a FIPS 140-2 Level 3 certified implementation.
+
+You must have a [Data Security Manager Enterprise Tier](https://www.fortanix.com/start-your-free-trial) and set up a group and an application assigned to the group.
+
+For detailed guidance, follow the tutorial in the [Fortanix documentation](https://support.fortanix.com/docs/fortanix-data-security-manager-with-cloudflare-integration#50-configure-fortanix-dsm). This guide is based on the Keyless SSL [public DNS](/ssl/keyless-ssl/configuration/public-dns/) option and has been tested using a virtual machine (VM) deployed to Azure running Ubuntu 22.04.3 LTS.
diff --git a/src/content/docs/ssl/keyless-ssl/hardware-security-modules/google-cloud-hsm.mdx b/src/content/docs/ssl/keyless-ssl/hardware-security-modules/google-cloud-hsm.mdx
@@ -1,8 +1,6 @@
 ---
 pcx_content_type: tutorial
 title: Google Cloud HSM
-sidebar:
-  order: 8
 ---
 
 This tutorial uses [Google Cloud HSM](https://cloud.google.com/kms/docs/hsm) — a FIPS 140-2 Level 3 certified implementation.
diff --git a/src/content/docs/ssl/keyless-ssl/hardware-security-modules/ibm-cloud-hsm.mdx b/src/content/docs/ssl/keyless-ssl/hardware-security-modules/ibm-cloud-hsm.mdx
@@ -1,8 +1,6 @@
 ---
 pcx_content_type: tutorial
 title: IBM cloud HSM
-sidebar:
-  order: 7
 ---
 
 The example below was tested using [IBM Cloud HSM 7.0](https://console.bluemix.net/docs/infrastructure/hardware-security-modules/about.html#about-ibm-cloud-hsm), a FIPS 140-2 Level 3 certified implementation based on the Gemalto SafeNet Luna a750.
diff --git a/src/content/docs/ssl/keyless-ssl/hardware-security-modules/index.mdx b/src/content/docs/ssl/keyless-ssl/hardware-security-modules/index.mdx
@@ -28,19 +28,20 @@ For more details on initializing your PKCS#11 token, refer to [Configuration](/s
 
 ### Compatibility
 
-We have verified interoperability with the following modules:
+Keyless SSL has interoperability with the following modules:
 
-* [Gemalto SafeNet Luna](https://cpl.thalesgroup.com/compliance/fips-common-criteria-validations)
-* [SoftHSMv2](https://github.com/opendnssec/SoftHSMv2)
-* [Entrust nShield Connect](https://www.entrust.com/digital-security/hsm)
-* [YubiKey Neo](https://www.yubico.com/product/yubikey-neo/)
+- [Entrust nShield Connect](https://www.entrust.com/digital-security/hsm)
+- [Gemalto SafeNet Luna](https://cpl.thalesgroup.com/compliance/fips-common-criteria-validations)
+- [SoftHSMv2](https://github.com/opendnssec/SoftHSMv2)
+- [YubiKey Neo](https://www.yubico.com/product/yubikey-neo/)
 
-We’ve also tested with the following Cloud HSM offerings:
+Also, the following cloud HSM offerings have been tested with Keyless SSL:
 
-* [AWS CloudHSM](/ssl/keyless-ssl/hardware-security-modules/aws-cloud-hsm/)
-* [IBM Cloud HSM](/ssl/keyless-ssl/hardware-security-modules/ibm-cloud-hsm/)
-* [Azure Dedicated HSM](/ssl/keyless-ssl/hardware-security-modules/azure-dedicated-hsm/)
-* [Azure Managed HSM](/ssl/keyless-ssl/hardware-security-modules/azure-managed-hsm/)
-* [Google Cloud HSM](/ssl/keyless-ssl/hardware-security-modules/google-cloud-hsm/)
+- [AWS CloudHSM](/ssl/keyless-ssl/hardware-security-modules/aws-cloud-hsm/)
+- [Azure Dedicated HSM](/ssl/keyless-ssl/hardware-security-modules/azure-dedicated-hsm/)
+- [Azure Managed HSM](/ssl/keyless-ssl/hardware-security-modules/azure-managed-hsm/)
+- [Fortanix DSM](/ssl/keyless-ssl/hardware-security-modules/fortanix-dsm/)
+- [IBM Cloud HSM](/ssl/keyless-ssl/hardware-security-modules/ibm-cloud-hsm/)
+- [Google Cloud HSM](/ssl/keyless-ssl/hardware-security-modules/google-cloud-hsm/)
 
 If you have deployed Keyless SSL with an HSM model not listed above, please email [keyless@cloudflare.com](mailto:keyless@cloudflare.com) with details.
diff --git a/src/content/docs/ssl/keyless-ssl/hardware-security-modules/softhsmv2.mdx b/src/content/docs/ssl/keyless-ssl/hardware-security-modules/softhsmv2.mdx
@@ -1,8 +1,6 @@
 ---
 pcx_content_type: tutorial
 title: SoftHSMv2
-sidebar:
-  order: 5
 ---
 
 :::caution[Important]
diff --git a/src/content/docs/ssl/keyless-ssl/reference/high-availability.mdx b/src/content/docs/ssl/keyless-ssl/reference/high-availability.mdx
@@ -6,8 +6,8 @@ sidebar:
 
 ---
 
-The Cloudflare Keyless SSL server runs as a single binary with minimal dependencies and is designed to be robust and reliable. The network between your key server and Cloudflare may not be however, which could prevent new TLS connections.
+The Cloudflare Keyless SSL server runs as a single binary with minimal dependencies and is designed to be robust and reliable. However, the network between your key server and Cloudflare may not be, which could prevent new TLS connections.
 
 For this reason, we strongly recommend that you run at least two key servers in a high availability configuration behind a load balancer. Set up health checks for each key server on the configured TCP port—2407 by default and failover as necessary or round-robin between active (healthy) key servers.
 
-From a network availability and performance perspective, advertise the IP address of your key server from multiple data centers (an anycast setup) so the Cloudflare edge can route to the closest key server via BGP. When you use anycast routing, you can also safely take a data center offline to perform maintenance.
+From a network availability and performance perspective, advertise the IP address of your key server from multiple data centers (an anycast setup) so the Cloudflare global network can route to the closest key server via BGP. When you use anycast routing, you can also safely take a data center offline to perform maintenance.
diff --git a/src/content/docs/ssl/keyless-ssl/reference/keyless-delegation.mdx b/src/content/docs/ssl/keyless-ssl/reference/keyless-delegation.mdx
@@ -6,29 +6,10 @@ sidebar:
 
 ---
 
-Keyless Delegation is [our implementation of the emerging delegated credentials standard](https://datatracker.ietf.org/doc/draft-ietf-tls-subcerts/). When you upload a certificate for use with Keyless that has
-the special extension permitting the use of delegated credentials,
-Cloudflare will automatically produce a delegated credential and use
-it at the edge with clients that support this feature. The handshakes
-will complete without the extra latency induced by reaching back to
-the Keyless Server, and there are [additional advantages to flexibility in algorithm choice](https://blog.cloudflare.com/keyless-delegation/).
+Keyless Delegation is Cloudflare's implementation of the emerging delegated credentials standard ([RFC 9345](https://www.rfc-editor.org/rfc/rfc9345.html)). When you upload a certificate for use with Keyless that has the special extension permitting the use of delegated credentials, Cloudflare will automatically produce a delegated credential and use it at the edge with clients that support this feature. The handshakes will complete without the extra latency induced by reaching back to the Keyless Server, and there are [additional advantages to flexibility in algorithm choice](https://blog.cloudflare.com/keyless-delegation/).
 
-Behind the scenes we periodically create delegated credentials and
-sign them via Keyless, through the same mechanism used to sign the
-Certificate Verify messages our servers send when using Keyless. These
-credentials have a short lifetime, ensuring that if you disable
-Keyless the credentials created will become invalid within 24
-hours. Supporting clients validate the credential, and the server can
-use the key it generated to sign the response to the TLS handshake
-without the round trip.
+Behind the scenes we periodically create delegated credentials and sign them via Keyless, through the same mechanism used to sign the Certificate Verify messages our servers send when using Keyless. These credentials have a short lifetime, ensuring that if you disable Keyless the credentials created will become invalid within 24 hours. Supporting clients validate the credential, and the server can use the key it generated to sign the response to the TLS handshake without the round trip.
 
-For security reasons certificates must contain a special identifier
-for use with delegated credentials. This takes the form of an optional
-X509 extension with NULL contents and the OID 1.3.6.1.4.1.44363.44
-. Your CA may need to make code changes to support delegated
-credentials.
+For security reasons certificates must contain a special identifier for use with delegated credentials. This takes the form of an optional X509 extension with NULL contents and the OID 1.3.6.1.4.1.44363.44. Your CA may need to make code changes to support delegated credentials.
 
-Currently very few clients support delegated credentials, and only a
-handful of certificate authorities will issue certificates with the
-extension. We have had success with DigiCert. Firefox 77 and later
-support delegated credentials.
+Currently very few clients support delegated credentials, and only a handful of certificate authorities will issue certificates with the extension. We have had success with DigiCert. Firefox 77 and later support delegated credentials.
diff --git a/src/content/docs/ssl/keyless-ssl/reference/scaling-and-benchmarking.mdx b/src/content/docs/ssl/keyless-ssl/reference/scaling-and-benchmarking.mdx
@@ -6,7 +6,7 @@ sidebar:
 
 ---
 
-Cloudflare’s Keyless SSL technology was designed to scale to accommodate any sized workload using vertical and horizontal scaling, and pre-computation techniques wherever possible, such as ECDSA. The goals of the architectural design of the key server are to minimize latency while maximizing signing operations per second.
+Cloudflare's Keyless SSL technology was designed to scale to accommodate any sized workload using vertical and horizontal scaling, and pre-computation techniques wherever possible, such as ECDSA. The goals of the architectural design of the key server are to minimize latency while maximizing signing operations per second.
 
 Each key server uses a worker pool model, with incoming client connections handled by its own pair of reader/writer goroutines and cryptographic work done in separate worker goroutines pulled from a global pool.
 
@@ -26,7 +26,7 @@ Additional details can be found in the [gokeyless server readme file](https://gi
 
 ## Benchmarks
 
-We conducted benchmarks using [Cloudflare’s gokeyless bench tool](https://github.com/cloudflare/gokeyless/tree/master/cmd/bench) on a then current-generation, compute-optimized EC2 instance ([c5.xlarge](https://aws.amazon.com/ec2/instance-types/c5/)). This particular instance has 4 vCPUs powered by 3.0 GHz Intel Xeon processors:
+We conducted benchmarks using [Cloudflare's gokeyless bench tool](https://github.com/cloudflare/gokeyless/tree/master/cmd/bench) on a then current-generation, compute-optimized EC2 instance ([c5.xlarge](https://aws.amazon.com/ec2/instance-types/c5/)). This particular instance has 4 vCPUs powered by 3.0 GHz Intel Xeon processors:
 
 ```txt
 c5$ cat /proc/cpuinfo|grep "model name"
diff --git a/src/content/docs/ssl/keyless-ssl/troubleshooting.mdx b/src/content/docs/ssl/keyless-ssl/troubleshooting.mdx
@@ -82,9 +82,9 @@ You will need to either provide a certificate for only those hosts or change the
 
 ## Key servers on Windows
 
-We currently only provide packages for the supported GNU/Linux distributions as per [https://pkg.cloudflare.com/](https://pkg.cloudflare.com/).
+Cloudflare currently only provide packages for the supported GNU/Linux distributions as per the [Cloudflare package repository](https://pkg.cloudflare.com/).
 
-However, the key server is open source so you may attempt to build and deploy a binary, but running on Windows is not a supported configuration so you may experience problems that we will not be able to help with.
+However, the key server is open source so you may attempt to build and deploy a binary, but running on Windows is not a supported configuration so you may experience problems that Cloudflare will not be able to help with.
 
 ## Key server multi-domain support
 
diff --git a/src/content/docs/ssl/keyless-ssl/upgrading-your-key-server.mdx b/src/content/docs/ssl/keyless-ssl/upgrading-your-key-server.mdx
@@ -23,7 +23,7 @@ To upgrade your key server:
 :::caution
 
 
-If you are running a [high availability configuration](/ssl/keyless-ssl/reference/high-availability/), upgrade one server at a time as new TLS connections will fail to terminate at Cloudflare’s edge without a functioning key server.
+If you are running a [high availability configuration](/ssl/keyless-ssl/reference/high-availability/), upgrade one server at a time as new TLS connections will fail to terminate at Cloudflare's global network without a functioning key server.
 
 
 :::
diff --git a/src/content/partials/ssl/keyless-key-server-setup.mdx b/src/content/partials/ssl/keyless-key-server-setup.mdx
@@ -14,7 +14,7 @@ If you plan to run Keyless SSL in a [high availability setup](/ssl/keyless-ssl/r
 
 ### Install
 
-These steps are also at [pkg.cloudflare.com](https://pkg.cloudflare.com/index.html).
+These steps are also at the [Cloudflare package repository](https://pkg.cloudflare.com/).
 
 #### Debian/Ubuntu packages
 
