diff --git a/docs/src/operate/security/certificate-signing-request.md b/docs/src/operate/security/certificate-signing-request.md new file mode 100644 index 00000000000..b1ba0b51e3a --- /dev/null +++ b/docs/src/operate/security/certificate-signing-request.md @@ -0,0 +1,78 @@ +--- +title: Certificate signing request +tags: [Operate, Security, Cloud] +description: Generate certificate signing request for %%te%% +--- + +If you want to use a device certificate which is signed by a Certificate Authority (CA), you can generate the Certificate Signing Request (CSR), which is later used by CA to generate a device certificate. This process requires additional tooling as %%te%% provides you only with the CSR. + +## Create a certificate signing request + +To create a CSR you can use [`tedge cert create-csr`](../../references/cli/tedge-cert.md) %%te%% command: + +```sh +sudo tedge cert create-csr --device-id alpha +``` + +or + +```sh +sudo tedge cert create-csr +``` +if public key already exists and you want to reuse device name. + +```text title="Output" +Certificate Signing Request was successfully created. +``` + +:::note +`tedge cert` requires `sudo` privilege. This command provides no output on success. +::: + +[`sudo tedge cert create-csr`](../../references/cli/tedge-cert.md) creates the certificate signing request in a default location (`/etc/tedge/device-certs/`). +To use a custom location, refer to [`tedge config`](../../references/cli/tedge-config.md). + +Now you should have a CSR in the `/etc/tedge/device-certs/` directory. + +```sh +ls -l /etc/tedge/device-certs/ +``` + +```text title="Output" +total 8 +-r--r--r-- 1 mosquitto mosquitto 664 May 31 09:26 tedge-csr.csr +-r-------- 1 mosquitto mosquitto 246 May 31 09:26 tedge-private-key.pem +``` + +:::note +`tedge cert create-csr` will reuse private key if it was already created, e.g by the `tedge cert create` command +::: + +## Errors + +### Certificate Signing Request creation fails due to invalid device id + +If non-supported characters are used for the device id then the cert create-csr will fail with below error: + +```text +Error: failed to Generate the Certificate Signing Request. + +Caused by: + 0: DeviceID Error + 1: The string '"+"' contains characters which cannot be used in a name [use only A-Z, a-z, 0-9, ' = ( ) , - . ? % * _ ! @] +``` + + +### Certificate Signing Request already exists in the given location + +If the CSR file already exists you may see following error: + +```text +Error: failed to Generate the Certificate Signing Request. + +Caused by: + A certificate already exists and would be overwritten. + Existing file: "/etc/tedge/device-certs/tedge-csr.csr" +``` + +Remove the CSR file manually and try executing [`tedge cert create-csr`](../../references/cli/tedge-cert.md) again. \ No newline at end of file diff --git a/docs/src/references/cli/tedge-cert.md b/docs/src/references/cli/tedge-cert.md index 7b979553c00..f2700cdd029 100644 --- a/docs/src/references/cli/tedge-cert.md +++ b/docs/src/references/cli/tedge-cert.md @@ -38,6 +38,20 @@ OPTIONS: -h, --help Print help information ``` +## Create-csr + +```sh title="tedge cert create-csr" +tedge-cert-create-csr +Create certificate signing request + +Usage: tedge cert create-csr [OPTIONS] + +Options: + --device-id The device identifier to be used as the common name for the certificate + --config-dir [default: /etc/tedge] + -h, --help Print help +``` + ## Show ```sh title="tedge cert show"