diff --git a/backend/src/ee/routes/v1/ssh-certificate-template-router.ts b/backend/src/ee/routes/v1/ssh-certificate-template-router.ts
index a85e6b0ca..233ef6d10 100644
--- a/backend/src/ee/routes/v1/ssh-certificate-template-router.ts
+++ b/backend/src/ee/routes/v1/ssh-certificate-template-router.ts
@@ -93,7 +93,7 @@ export const registerSshCertificateTemplateRouter = async (server: FastifyZodPro
allowCustomKeyIds: z.boolean().describe(SSH_CERTIFICATE_TEMPLATES.CREATE.allowCustomKeyIds)
})
.refine((data) => ms(data.maxTTL) > ms(data.ttl), {
- message: "Max TLL must be greater than TTL",
+ message: "Max TLL must be greater than or equal to TTL",
path: ["maxTTL"]
}),
response: {
diff --git a/docs/documentation/platform/ssh.mdx b/docs/documentation/platform/ssh.mdx
index 16faf1267..179fa9590 100644
--- a/docs/documentation/platform/ssh.mdx
+++ b/docs/documentation/platform/ssh.mdx
@@ -67,7 +67,7 @@ At a high-level, Infisical issues a signed SSH certificate to a client that can
To be more specific:
-1. The client authenticates with Infisical; this can be done using a machine identity [authentication method](/documentation/platform/identities/machine-identities) or a user [authentication method](/documentation/platform/identities/user-identities).
+1. The client authenticates with Infisical; this can be done using a user or machine identity [authentication method](/documentation/platform/identities/machine-identities) or a user [authentication method](/documentation/platform/identities/user-identities).
2. The client makes an authenticated request for an SSH certificate via either the `/api/v1/ssh/issue` or `/api/v1/ssh/sign` endpoints. Note that if the client wishes to use an existing SSH key pair, it can use the `/api/v1/ssh/sign` endpoint; otherwise, it can use the `/api/v1/ssh/issue` endpoint to have Infisical issue a new SSH key pair in conjunction with the certificate.
3. The client uses the issued SSH certificate (and potentially SSH key pair) to temporarily access the host.
@@ -83,62 +83,65 @@ In the following steps, we explore how to configure Infisical SSH to start issui
as part of the SSH operation.
-
+
1.1. Start by creating a SSH project in the SSH tab of your organization.
- 1.2. Next, create a CA in the **Certificate Authorities** tab of the
- project.
+ 1.2. Next, create a SSH CA in the **Certificate Authorities** tab of the
+ project; this CA will be used for client key signing.
- 
+ 
- 
+ 
Here's some guidance on each field:
- Friendly Name: A friendly name for the CA; this is only for display.
- Key Algorithm: The type of public key algorithm and size, in bits, of the key pair for the CA. Supported key algorithms are `RSA 2048`, `RSA 4096`, `ECDSA P-256`, and `ECDSA P-384` with the default being `RSA 2048`.
- 1.3. Next, create a certificate template in the **Certificate Templates** section of the newly-created CA.
+
+
+
+ 2.1. Next, create a certificate template in the **Certificate Templates** section of the newly-created CA.
A certificate template is a set of policies for certificates issued under that template; each template is bound to a specific CA.
- With certificate templates, you can specify, for example, that certificates issued under a template are only allowed for users with a specific username like `ec2-user` or perhaps that the max TTL requested cannot exceed 1 year.
+ With certificate templates, you can specify, for example, that certificates issued under a template are only allowed for users with a specific username like `ec2-user` or perhaps that the max TTL requested cannot exceed 1 hour.
- 
+ 
- 
+ 
Here's some guidance on each field:
- SSH Template Name: A name for the certificate template; this must be a valid slug.
- Allowed Users: A comma-separated list of valid usernames (e.g. `ec2-user`) on the remote host for which a client can request a certificate for. If you wish to allow a client to request a certificate for any username, set this to `*`; alternatively, if left blank, the template will not allow issuance of certificates under any username.
- Allowed Hosts: A comma-separated list of valid hostnames/domains on the remote host for which a client can request a certificate for. Each item in the list can be either a wildcard hostname (e.g. `*.acme.com`), a specific hostname (e.g. `example.com`), an IPv4 address (e.g. `192.168.1.1`), or an IPv6 address. If left empty, the template will not allow any hostnames; if set to `*`, the template will allow any hostname.
- - Default TTL: The default Time-to-Live (TTL) for certificates issued under this template when a client does not explicitly specify a TTL in the certificate request.
+ - Default TTL: The default Time-to-Live (TTL) for certificates issued under this template when a client does not explicitly specify a TTL in the certificate request. We recommend setting a shorter **Default TTL** for client certificates such as `30m`.
- Max TTL: The maximum TTL for certificates issued under this template.
- - Allow User Certificates: Whether or not to allow issuance of user certificates.
- - Allow Host Certificates: Whether or not to allow issuance of host certificates.
+ - Allow User Certificates: Whether or not to allow issuance of user certificates; this should be set to `true`.
+ - Allow Host Certificates: Whether or not to allow issuance of host certificates; this is not relevant for this step.
- Allow Custom Key IDs: Whether or not to allow clients to specify a custom key ID to be included on the certificate as part of the certificate request.
- 1.4. Finally, add the user(s) you wish to be able to request a SSH certificate to the SSH project through the **Access Control** tab.
+ 2.2. Finally, add the user(s) you wish to be able to request a SSH certificate to the SSH project through the **Access Control** tab.
-
+
- 2.1. Begin by downloading the CA's public key from the CA's details section.
+ 3.1. Begin by downloading the client CA's public key from the CA's details section.
- 
+ 
- The CA's public key can also be retrieved programmatically via API by making a `GET` request to the `/ssh/ca//public-key` endpoint.
+ The CA's public key can also be retrieved programmatically via API by making a `GET` request to the endpoint [here](/api-reference/endpoints/ssh/ca/public-key).
- 2.2. Next, create a file containing this public key in the SSH folder of the remote host; we'll call the file `ca.pub`.
+ 3.2. Next, create a file containing this public key in the SSH folder of the remote host; we'll call the file `ca.pub`.
This would result in the file at the path `/etc/ssh/ca.pub`.
- 2.3. Next, add the following lines to the `/etc/ssh/sshd_config` file on the remote host.
+ 3.3. Next, add the following lines to the `/etc/ssh/sshd_config` file on the remote host.
```bash
TrustedUserCAKeys /etc/ssh/ca.pub
@@ -146,7 +149,7 @@ as part of the SSH operation.
PubkeyAcceptedKeyTypes=+ssh-rsa,ssh-rsa-cert-v01@openssh.com
```
- 2.4. Finally, reload the SSH daemon on the remote host to apply the changes.
+ 3.4. Finally, reload the SSH daemon on the remote host to apply the changes.
```bash
sudo systemctl reload sshd
@@ -159,7 +162,7 @@ as part of the SSH operation.
## Guide to Using Infisical SSH to Access a Host
-We show how to obtain a SSH certificate and use it for a client to access a host via CLI:
+In the following steps, we show how to obtain a SSH certificate and use it for a client to access a host via CLI:
The subsequent guide assumes the following prerequisites:
@@ -181,7 +184,7 @@ infisical login
```
-
+
Run the `infisical ssh issue-credentials` command, specifying the `--addToAgent` flag to automatically load the SSH certificate into the SSH agent.
```bash
infisical ssh issue-credentials --certificateTemplateId= --principals= --addToAgent
@@ -191,9 +194,9 @@ infisical login
- `certificateTemplateId`: The ID of the certificate template to use for issuing the SSH certificate.
- `principals`: The comma-delimited username(s) or hostname(s) to include in the SSH certificate.
-
+
For fuller documentation on commands and flags supported by the Infisical CLI for SSH, refer to the docs [here](/cli/commands/ssh).
-
+
Finally, SSH into the desired host; the SSH operation will be performed using the SSH certificate loaded into the SSH agent.
@@ -201,10 +204,113 @@ infisical login
```bash
ssh username@hostname
```
+
Note that the above workflow can be executed via API or other client methods
such as SDK.
-
\ No newline at end of file
+
+
+## Guide to Configuring Host Key Signing
+
+In the following steps, we show how to configure host key signing for clients to verify the identity of a remote host before attempting the SSH operation; this is recommended to reduce the probability of a client accessing a malicious machine.
+
+
+
+ 1.1. In the same SSH project, create another SSH CA in the **Certificate Authorities** tab; this CA will be used for host key signing.
+
+ 
+
+ 
+
+ Here's some guidance on each field:
+
+ - Friendly Name: A friendly name for the CA; this is only for display.
+ - Key Algorithm: The type of public key algorithm and size, in bits, of the key pair for the CA. Supported key algorithms are `RSA 2048`, `RSA 4096`, `ECDSA P-256`, and `ECDSA P-384` with the default being `RSA 2048`.
+
+
+
+
+ 2.1. Next, create a certificate template in the **Certificate Templates** section of the newly-created CA.
+
+ 
+
+ 
+
+ Here's some guidance on each field:
+
+ - SSH Template Name: A name for the certificate template; this must be a valid slug.
+ - Allowed Users: A comma-separated list of valid usernames (e.g. `ec2-user`) on the remote host for which a client can request a certificate for. If you wish to allow a client to request a certificate for any username, set this to `*`; alternatively, if left blank, the template will not allow issuance of certificates under any username.
+ - Allowed Hosts: A comma-separated list of valid hostnames/domains on the remote host for which a client can request a certificate for. Each item in the list can be either a wildcard hostname (e.g. `*.acme.com`), a specific hostname (e.g. `example.com`), an IPv4 address (e.g. `192.168.1.1`), or an IPv6 address. If left empty, the template will not allow any hostnames; if set to `*`, the template will allow any hostname.
+ - Default TTL: The default Time-to-Live (TTL) for certificates issued under this template when a client does not explicitly specify a TTL in the certificate request. We recommend setting a longer **Default TTL** for host certificates such as `2y`.
+ - Max TTL: The maximum TTL for certificates issued under this template.
+ - Allow User Certificates: Whether or not to allow issuance of user certificates; this is not relevant for this step.
+ - Allow Host Certificates: Whether or not to allow issuance of host certificates; this should be set to `true`.
+ - Allow Custom Key IDs: Whether or not to allow clients to specify a custom key ID to be included on the certificate as part of the certificate request.
+
+
+
+
+ 2.1. Obtain a SSH certificate for the host by requesting one from the **Certificates** tab.
+
+ 
+
+ 
+
+
+ You should select **Sign SSH Key** under the **Operation** field.
+
+ Then input your host's public key under the **SSH Public Key** field and hostname under the **Principal(s)** field; the host's public key is likely in the `/etc/ssh` folder of the host.
+
+
+ 
+
+ 2.2. Create a file containing the certificate in the SSH folder of the remote host; we'll call it `key-cert.pub`.
+
+ 2.2. Set permissions on the certificate to be `0640`:
+
+ ```bash
+ sudo chmod 0640 /etc/ssh/ssh_host_key-cert.pub
+ ```
+
+ 2.3. Next, add the following lines to the `/etc/ssh/sshd_config` file on the remote host.
+
+ ```bash
+ HostKey /etc/ssh/ssh_host_key
+ HostCertificate /etc/ssh/ssh_host_key-cert.pub
+ ```
+
+ 2.4. Finally, reload the SSH daemon on the remote host to apply the changes.
+
+ ```bash
+ sudo systemctl reload sshd
+ ```
+
+
+
+ 3.1. Begin by downloading the host CA's public key from the CA's details section.
+
+ 
+
+
+ The CA's public key can also be retrieved programmatically via API by making a `GET` request to the endpoint [here](/api-reference/endpoints/ssh/ca/public-key).
+
+
+ 3.2. Next, add the resulting public key to the `known_hosts` file on the client machine (e.g. at the path `~/.ssh/known_hosts`).
+
+ ```bash
+ @cert-authority *.example.com ssh-rsa ...
+ ```
+
+
+
+ Finally, SSH into the desired host as usual; the SSH operation will now also include client-side host verification.
+
+ ```bash
+ ssh username@hostname
+ ```
+
+
+
diff --git a/docs/images/platform/ssh/ssh-client-ca-public-key.png b/docs/images/platform/ssh/ssh-client-ca-public-key.png
new file mode 100644
index 000000000..2f09756c4
Binary files /dev/null and b/docs/images/platform/ssh/ssh-client-ca-public-key.png differ
diff --git a/docs/images/platform/ssh/ssh-client-create-ca-1.png b/docs/images/platform/ssh/ssh-client-create-ca-1.png
new file mode 100644
index 000000000..c5a5f70e2
Binary files /dev/null and b/docs/images/platform/ssh/ssh-client-create-ca-1.png differ
diff --git a/docs/images/platform/ssh/ssh-client-create-ca-2.png b/docs/images/platform/ssh/ssh-client-create-ca-2.png
new file mode 100644
index 000000000..c6f997221
Binary files /dev/null and b/docs/images/platform/ssh/ssh-client-create-ca-2.png differ
diff --git a/docs/images/platform/ssh/ssh-client-create-template-1.png b/docs/images/platform/ssh/ssh-client-create-template-1.png
new file mode 100644
index 000000000..821d2b42c
Binary files /dev/null and b/docs/images/platform/ssh/ssh-client-create-template-1.png differ
diff --git a/docs/images/platform/ssh/ssh-client-create-template-2.png b/docs/images/platform/ssh/ssh-client-create-template-2.png
new file mode 100644
index 000000000..ef78dba8b
Binary files /dev/null and b/docs/images/platform/ssh/ssh-client-create-template-2.png differ
diff --git a/docs/images/platform/ssh/ssh-host-ca-public-key.png b/docs/images/platform/ssh/ssh-host-ca-public-key.png
new file mode 100644
index 000000000..e470aba4e
Binary files /dev/null and b/docs/images/platform/ssh/ssh-host-ca-public-key.png differ
diff --git a/docs/images/platform/ssh/ssh-host-create-ca-1.png b/docs/images/platform/ssh/ssh-host-create-ca-1.png
new file mode 100644
index 000000000..3cdeaca0b
Binary files /dev/null and b/docs/images/platform/ssh/ssh-host-create-ca-1.png differ
diff --git a/docs/images/platform/ssh/ssh-host-create-ca-2.png b/docs/images/platform/ssh/ssh-host-create-ca-2.png
new file mode 100644
index 000000000..bad174c90
Binary files /dev/null and b/docs/images/platform/ssh/ssh-host-create-ca-2.png differ
diff --git a/docs/images/platform/ssh/ssh-host-create-template-1.png b/docs/images/platform/ssh/ssh-host-create-template-1.png
new file mode 100644
index 000000000..b79f0f47e
Binary files /dev/null and b/docs/images/platform/ssh/ssh-host-create-template-1.png differ
diff --git a/docs/images/platform/ssh/ssh-host-create-template-2.png b/docs/images/platform/ssh/ssh-host-create-template-2.png
new file mode 100644
index 000000000..ad3f17e58
Binary files /dev/null and b/docs/images/platform/ssh/ssh-host-create-template-2.png differ
diff --git a/docs/images/platform/ssh/ssh-host-issue-cert-1.png b/docs/images/platform/ssh/ssh-host-issue-cert-1.png
new file mode 100644
index 000000000..3dab450f4
Binary files /dev/null and b/docs/images/platform/ssh/ssh-host-issue-cert-1.png differ
diff --git a/docs/images/platform/ssh/ssh-host-issue-cert-2.png b/docs/images/platform/ssh/ssh-host-issue-cert-2.png
new file mode 100644
index 000000000..eb0ecbcc2
Binary files /dev/null and b/docs/images/platform/ssh/ssh-host-issue-cert-2.png differ
diff --git a/docs/images/platform/ssh/ssh-host-issue-cert-3.png b/docs/images/platform/ssh/ssh-host-issue-cert-3.png
new file mode 100644
index 000000000..a5af747fb
Binary files /dev/null and b/docs/images/platform/ssh/ssh-host-issue-cert-3.png differ
diff --git a/frontend/src/pages/ssh/SshCaByIDPage/components/SshCertificateTemplateModal.tsx b/frontend/src/pages/ssh/SshCaByIDPage/components/SshCertificateTemplateModal.tsx
index 15a8d8c78..9790df292 100644
--- a/frontend/src/pages/ssh/SshCaByIDPage/components/SshCertificateTemplateModal.tsx
+++ b/frontend/src/pages/ssh/SshCaByIDPage/components/SshCertificateTemplateModal.tsx
@@ -60,8 +60,8 @@ const schema = z
allowHostCertificates: z.boolean().optional().default(false),
allowCustomKeyIds: z.boolean().optional().default(false)
})
- .refine((data) => ms(data.maxTTL) > ms(data.ttl), {
- message: "Max TLL must be greater than TTL",
+ .refine((data) => ms(data.maxTTL) >= ms(data.ttl), {
+ message: "Max TLL must be greater than or equal to TTL",
path: ["maxTTL"]
});