docs: add signature algorithms reference

docs/pages/reference/signature-algorithms.mdx

@@ -0,0 +1,223 @@
+---
+title: Signature Algorithms
+h1: Signature Algorithms Reference
+description: "Signature algorithms used in Teleport."
+---
+
+An important role of the Teleport Auth Service is issuing short-lived SSH and
+TLS certificates to users and hosts that allow all connections to be
+authenticated, authorized, and encrypted.
+This page describes the various cryptographic signature algorithms used to sign
+each kind of certificate issued by Teleport.
+
+Historically, every Teleport-issued certificate was signed by a 2048-bit RSA key.
+RSA is one of the oldest and most well-known asymmetric cryptography algorithms.
+While it is still considered secure (as long as your keys are large enough),
+modern alternatives based on Elliptic-Curve Cryptography offer much better
+performance with smaller keys and better security.
+
+## Signature algorithm suites
+
+Unilaterally changing the signature algorithms used in Teleport would be a
+breaking change for our users, as certain environments may expect or rely on RSA
+signatures.
+Some users may also require different algorithms to be used if they are looking
+for FIPS compliance or they are storing key material in a Hardware Security
+Module (HSM) or Key Management Service (KMS) that only supports certain
+algorithms.
+
+To allow new and existing Teleport users to opt-in to the new signature
+algorithms when they are ready, we introduced the concept of "signature
+algorithm suites".
+By selecting a single algorithm suite, Teleport admins can control all of the
+cryptographic signature algorithms used across their cluster.
+
+### `legacy`
+
+The `legacy` suite identifies the original Teleport behavior where all
+signatures are based on 2048-bit RSA keys.
+Teleport clusters created on versions prior to 17.0.0 effectively have always
+used the `legacy` suite and this will not automatically change when they upgrade
+to newer versions.
+
+We recommend that users upgrade to one of the newer suites when they are able.
+
+### `balanced-v1`
+
+The `balanced-v1` suite is the default suite for self-hosted clusters created
+after version 17.0.0.
+It is our recommended suite for most self-hosted users.
+When this suite is configured, Ed25519 is used for all SSH certificates.
+ECDSA with the NIST P-256 curve is used for all TLS certificates.
+
+RSA is still used where compatibility with common third-party software that
+Teleport integrates with is known to be unable to support non-RSA algorithms.
+This includes Database Access certificates and certain JSON Web Tokens (JWTs)
+that are issued by Teleport.
+
+### `fips-v1`
+
+Users deploying Teleport in FIPS mode are recommended to use the `fips-v1`
+suite.
+New clusters created after version 17.0.0 in FIPS mode will use this suite by
+default.
+
+FIPS 186-5 only added approval for Ed25519 relatively recently (in February 2023)
+and there is some nuance to how the algorithm can be used.
+More importanly for Teleport, the `boringcrypto` module our FIPS Go binaries are
+compiled with does not yet support Ed25519.
+For these reasons, the `fips-v1` suite is based on the `balanced-v1` suite but
+replaces all uses of Ed25519 with ECSDA.
+
+### `hsm-v1`
+
+The `hsm-v1` suite is designed for Cloud customers and self-hosted users that
+have opted in to keeping their Certificate Authority key material in an HSM or KMS.
+It is the default suite for new clusters created after version 17.0.0 that have
+an HSM or KMS configured.
+It will be the default suite for new Teleport Cloud clusters on version 17.x+.
+
+Teleport's integration with PKCS#11 HSMs and cloud KMSs does not yet support
+Ed25519.
+For this reason, the `hsm-v1` suite is based on the `balanced-v1` suite but uses
+ECDSA in place of Ed25519 for all Certificate Authority keys.
+User and host SSH keys still use Ed25519.
+
+## Configuration
+
+The cluster signature algorithm suite can be configured statically in the Auth Service
+configuration file or dynamically in the `cluster_auth_preference` resource.
+
+### Static configuration
+
+Add the following to your Teleport Auth Service configuration file, which is stored in
+`/etc/teleport.yaml` by default.
+
+  ```yaml
+  auth_service:
+    authentication:
+      signature_algorithm_suite: "balanced-v1"
+  ```
+
+### Dynamic resource
+
+Edit your `cluster_auth_preference` resource:
+
+```code
+$ tctl edit cap
+```
+
+Ensure that the resource includes the following content:
+
+```yaml
+kind: cluster_auth_preference
+metadata:
+  name: cluster-auth-preference
+spec:
+  signature_algorithm_suite: "balanced-v1"
+version: v2
+```
+
+## Certificate Authorities
+
+The `tctl status` command will display the status of each of your Teleport
+cluster's Certificate Authorities, including the algorithm used for each key pair.
+
+```code
+$ tctl status
+Cluster: example.teleport.sh
+Version: 17.0.0
+CA pins: sha256:b1419d94442b2b1ba70f967157bf177c7605020c59ee93a10b0e4d3fc526e7df
+
+authority rotation                protocol status algorithm   storage
+--------- ----------------------- -------- ------ ----------- --------
+host      standby (never rotated) SSH      active Ed25519     software
+                                  TLS      active ECDSA P-256 software
+user      standby (never rotated) SSH      active Ed25519     software
+                                  TLS      active ECDSA P-256 software
+db        standby (never rotated) TLS      active RSA 2048    software
+db_client standby (never rotated) TLS      active RSA 2048    software
+openssh   standby (never rotated) SSH      active Ed25519     software
+jwt       standby (never rotated) JWT      active ECDSA P-256 software
+saml_idp  standby (never rotated) TLS      active RSA 2048    software
+oidc_idp  standby (never rotated) JWT      active RSA 2048    software
+spiffe    standby (never rotated) JWT      active RSA 2048    software
+                                  TLS      active ECDSA P-256 software
+okta      standby (never rotated) JWT      active ECDSA P-256 software
+```
+
+Each certificate authority is automatically generated the first time your Auth
+Service starts up when you create a new Teleport cluster.
+If you change your cluster's signature algorithm suite after the cluster has
+already been created, new user and host keys will use the new algorithms, but
+the key material of each Certificate Authority will not automatically be
+updated.
+
+In order to use new signature algorithms for your existing Certificate
+Authorities, you will need to complete a CA rotation for each authority.
+This may require manual steps to update the trust relationships in your Cluster.
+The procedure is documented [here](../admin-guides/management/operations/ca-rotation.mdx).
+This process is optional, your cluster will continue to function with the
+existing Certificate Authority keys if you don't complete a CA rotation.
+
+## Algorithms
+
+The following table lists the key algorithm used for each key Teleport generates
+in each suite.
+
+| key purpose            | `legacy`    | `balanced-v1` | `fips-v1`   | `hsm-v1`    |
+|------------------------|-------------|---------------|-------------|-------------|
+| User CA (SSH)          | RSA 2048    | Ed25519       | ECDSA P-256 | ECDSA P-256 |
+| User CA (TLS)          | RSA 2048    | ECDSA P-256   | ECDSA P-256 | ECDSA P-256 |
+| Host CA (SSH)          | RSA 2048    | Ed25519       | ECDSA P-256 | ECDSA P-256 |
+| Host CA (TLS)          | RSA 2048    | ECDSA P-256   | ECDSA P-256 | ECDSA P-256 |
+| Database CA            | RSA 2048    | RSA 2048      | RSA 2048    | RSA 2048    |
+| Database Client CA     | RSA 2048    | RSA 2048      | RSA 2048    | RSA 2048    |
+| OpenSSH CA             | RSA 2048    | Ed25519       | ECDSA P-256 | ECDSA P-256 |
+| JWT CA                 | RSA 2048    | ECDSA P-256   | ECDSA P-256 | ECDSA P-256 |
+| OIDC IdP CA            | RSA 2048    | RSA 2048      | RSA 2048    | RSA 2048    |
+| SAML IdP CA            | RSA 2048    | RSA 2048      | RSA 2048    | RSA 2048    |
+| SPIFFE CA (TLS)        | RSA 2048    | ECDSA P-256   | ECDSA P-256 | ECDSA P-256 |
+| SPIFFE CA (JWT)        | RSA 2048    | RSA 2048      | RSA 2048    | RSA 2048    |
+| Okta CA                | ECDSA P-256 | ECDSA P-256   | ECDSA P-256 | ECDSA P-256 |
+| User SSH               | RSA 2048    | Ed25519       | ECDSA P-256 | Ed25519     |
+| User TLS               | RSA 2048    | ECDSA P-256   | ECDSA P-256 | ECDSA P-256 |
+| Database Client        | RSA 2048    | RSA 2048      | RSA 2048    | RSA 2048    |
+| Database Server        | RSA 2048    | RSA 2048      | RSA 2048    | RSA 2048    |
+| Host SSH               | RSA 2048    | Ed25519       | ECDSA P-256 | Ed25519     |
+| Host Identity          | RSA 2048    | ECDSA P-256   | ECDSA P-256 | ECDSA P-256 |
+| MachineID Identity     | RSA 2048    | ECDSA P-256   | ECDSA P-256 | ECDSA P-256 |
+| Workload ID SVID       | RSA 2048    | ECDSA P-256   | ECDSA P-256 | ECDSA P-256 |
+| EC2 Instance Connect   | Ed25519     | Ed25519       | ECDSA P-256 | Ed25519     |
+| Windows Desktop Client | RSA 2048    | RSA 2048      | RSA 2048    | RSA 2048    |
+
+## FAQ
+
+### What if my use-case doesn't support the new algorithms?
+
+Try it and let us know!
+We aim to balance security, performance, and compatibility with the chosen
+signature algorithm suites.
+It is okay to continue using the `legacy` suite for the forseeable future and we
+expect it may be required for some user's environments.
+
+### How did you choose these algorithms?
+
+Ed25519 is a modern, fast, secure algorithm with small keys that has become the
+de-facto standard for new SSH keys.
+It is our preference in cases where it is compatible with everything Teleport
+needs to interact with.
+
+ECDSA with the NIST P-256 curve is widely used and supported for TLS and we use
+it in cases where there is not good support for Ed25519.
+It has similar speed and security properties to Ed25519.
+
+We only continue to use RSA where we interact with third-party software that
+does not support Ed25519 or ECDSA.
+
+### Why can't I pick a specific algorithm for a specific Teleport cert?
+
+The signature algorithm suites are designed to simplify the configuration burden.
+We did not want to expose 100 configuration knobs to modify every single
+signature Teleport does, which could lead to thousands of possible combinations
+we'd have to support, and could create the possibility for insecure combinations.