How to Install SSL Certificates on a Linux Server

Overview

Administrators should use HTTPS to secure network traffic to Posit products. This can be configured at different levels within your architecture (e.g., at each server, or an external load balancer or proxy). This guide covers how to install SSL/TLS certificates at the Linux level on the server where Posit products are installed.

Note

The terms TLS and SSL are often used interchangeably, and their configuration is identical. This guide will use the term SSL to refer to either SSL or TLS configuration.

Requirements

SSH and sudo access on the Linux server where you’re installing the certificate
The following ports open on the Linux server:
- HTTP port 80
- HTTPS port 443
- TLS port 22
An SSL certificate and corresponding private key issued for the specific Linux server

Step 1. Verify certificate format

The SSL certificate must be in X.509 PEM format. The file format is typically a .pem or .crt file, and when correctly formatted, it will be human-readable as base64 text if you inspect the file.

When checking the format, the output displays unable to load certificate if the SSL certificate is not in the correct format.

To check the certificate’s format, run the following command:
```
openssl x509 -in <certificate.crt> -text -noout
```
To convert SSL certificates from other formats into PEM, use openssl x509 and the -inform and -outform options. For example, a DER-formatted SSL certificate can be converted to PEM by running:
```
 openssl x509 -inform der -outform pem -in <certificate>.der -out <certificate>.crt
```
For more information on converting certificate formats, refer to the openssl-x509 documentation or contact the organization that issued your certificate.

Step 2. Verify full certificate chain

The SSL certificate file must include the full certificate chain from the host to the root certificate, including any intermediates.

To inspect the file and verify that it includes the full certificate chain, run:

cat <certificate.crt>

If the certificate file contains the entire chain, similar output displays:

Sometimes, SSL certificates are issued as two separate files: the host certificate, and the preceding certificate chain.

Combine the separate files to create a single file by running:

cat <host-certificate.crt> <cert-chain.crt> > full-cert-chain.crt

Step 3. Verify private key format

The SSL certificate includes a corresponding private key. Typically, the private key is a .key file.

Passphrase-protected private keys are not supported. The passphrase must be removed.

Optionally, to back up the original key, run the following:
```
sudo cp <private.key> <private.key>.bak
```

To remove the passphrase:

sudo openssl rsa -in <private.key> -out <private.key>

Step 4. Verify private key and certificate are paired

The SSL certificate and private key form a unique pair that establishes an encrypted connection. The key file and certificate are not interchangeable with other key files and certificates.

Follow these steps to verify that a private key and a certificate are paired:

Extract the modulus of the certificate:

sudo openssl x509 -noout -modulus -in <certificate.crt> | openssl md5 > /tmp/crt.pub

Extract the modulus of the private key:

sudo openssl rsa -noout -modulus -in <private.key> | openssl md5 > /tmp/key.pub

To verify that the certificate and key are paired, run:
```
diff /tmp/crt.pub /tmp/key.pub
```
Check the following:
- If the certificate and key are paired, diff produces no output. Continue to Step 5. Copy certificate and key to the correct location on the server
- If output displays, the two files cannot be used together to establish an encrypted connection. Locate the correct private key and confirm the pairing by repeating Step 4. Verify private key and certificate are paired, or reach out to the organization that issued your certificate for assistance.

Step 5. Copy certificate and key to the correct location on the server

The certificate and private key need to be stored on the server with your Posit product configuration files.

Use the table below to locate the directory where you need to copy the key and certificate for each installed product:

Product	Copy to
Posit Workbench	`/etc/rstudio/`
Posit Connect	`/etc/rstudio-connect/`
Posit Package Manager	`/etc/rstudio-pm/`

Step 6. Verify ownership and permissions of the certificate and key file

The table below defines the user and group ownership needed per Posit product for the <certificate.crt> and <private.key> files.

Product	File ownership (`<user:group>`)
Posit Workbench	`root:root` or `rstudio-server:rstudio-server`
Posit Connect	`rstudio-connect:rstudio-connect`
Posit Package Manager	`rstudio-pm:rstudio:pm`

It is imperative that you verify that the key and certificate file are owned by the appropriate user and groups and are granted the required permissions. The key file requires 600 permissions while the certificate file requires 644.

If necessary:

Use sudo chown <user>:<group> <private.key> to change ownership, and sudo chmod 600 <private.key> to change permissions.
Use sudo chown <user>:<group> <certificate.crt> to change ownership, and sudo chmod 644 <certificate.crt> to change permissions.

Step 7. Verify that the root certificate is trusted

The root certificate from the Certificate Authority (CA) must be installed in the trust store. This ensures that Posit products can communicate with one another during normal operations (e.g., installing packages and publishing).

To test if the root certificate is already in the server trust store (i.e., trusted), run the following:
```
sudo openssl verify -untrusted /path/to/<certificate.crt> /path/to/<certificate.crt>
```
The following output indicates that the certificate is not trusted, which requires you to continue to Step 8. Create the root certificate.
```
error <certificate.crt>: verification failed
```
If the certificate is trusted (the output indicates OK), skip to Step 10. Configure SSL in Posit products.

Step 8. Create the root certificate

Only the root certificate needs to be added to the trust store. Extract this root certificate from the certificate file by copying the last entry in the certificate file to a new file called root.crt.

Extract the root certificate from the certificate file:

First, view the contents of the certificate file by running:

cat /path/to/<certificate.crt>

The output displays multiple certificates in the following format:

Next, identify the root certificate (which is typically the last certificate in the file) and copy the root certificate lines from the output. For example,
```
-----BEGIN CERTIFICATE-----
<Root Certificate>
-----END CERTIFICATE-------
```

Then, create a file named root.crt and paste the certificate values into it. This is now your root certificate.

Step 9. Copy the root certificate into the trust store and update the trust store

Copy the root.crt file into your certificate directory:

Ubuntu/Debian
Red Hat/CentOS

sudo cp /path/to/root.crt /usr/local/share/ca-certificates

cp /path/to/root.crt /etc/pki/ca-trust/source/anchors

Update the trusted certificates on your system:
- Ubuntu/Debian
- Red Hat/CentOS
sudo update-ca-certificates
update-ca-trust extract
Once complete, repeat Step 7. Verify that the root certificate is trusted to ensure this step has been successful.

Step 10. Configure SSL in Posit products

Use the following documentation to configure SSL in the Posit products you have installed:

Posit Workbench: Set up SSL
Posit Connect: Configuring SSL Certificates in Posit Connect
Posit Package Manager: Configuring SSL Certificates