Onboard a Linux device to a network with certificates and Certmonger

In this topic, you will learn how to onboard using certificates, the Certmonger service, a Linux computer, and a network managed by Portnox™ Cloud.

Note:

Due to known issues across various Certmonger versions and the overall complexity of the manual process, many customers have encountered difficulties completing these steps. For this reason, we recommend using the PortSCepX Shell script instead.

Disclaimer: PortSCepX is provided as a convenience tool developed by the Portnox team for use by selected customers. It is not an officially supported product, and Portnox makes no guarantees, representations, or warranties – express or implied – regarding its performance, reliability, suitability, or fitness for any particular purpose. Use of the script is at your sole risk. Portnox assumes no responsibility or liability for any issues, damages, or losses arising from its use, modification, or execution in customer environments. Instructions for use are included within the script.

If you already downloaded and installed the certificate for the same device, for example, to authenticate with another type of network, you don’t need to install the certificate again and you should skip the relevant steps.

Turn on the Portnox Cloud SCEP services

In this section, you will configure Portnox™ Cloud to provide SCEP services to your devices.

If you have previously turned on the Portnox Cloud SCEP services, skip to the step in which you get the Cloud SCEP URL and secret.

Open the Portnox Cloud portal and log in.
In the Cloud portal top menu, click on the Settings option.
In the Cloud portal left-hand side menu, click on the Services > GENERAL SETTINGS > SCEP Services option.
Enable integration with SCEP services.
1. Click on the Edit link.
2. Activate the Enable integration checkbox.
3. Click on the Save button.
Click on the ⧉ icon next to the SCEP URL field to copy the SCEP URL, and paste it in a text file for later use.
Click on the ⧉ icon next to the Password field to copy the SCEP password, and store it in a text file in your Linux system.

For example: $nano /var/portnox/secret

Download and convert the root CA certificate

In this section, you will download the Portnox™ Cloud root CA certificate> from the Cloud portal and convert it to a format that you can later use to connect to the network.

Open the Portnox Cloud portal and log in.
In the Cloud portal top menu, click on the Settings option.
In the Cloud portal left-hand side menu, click on the Services > CLOUD RADIUS SERVICE > Cloud RADIUS instance option.

The right-hand pane shows the list of active servers.
Click on any of the active RADIUS services to show its configuration.
Click on the Download root certificate link to download the root CA certificate.
If you’re working on a Linux desktop, use OpenSSL to convert the certificate to PEM format.
```
$openssl x509 -inform der \
  -in downloaded_file.cer \
  -out certificate.crt
```
Note:
The file extension does not identify the certificate format. PEM format certificates most commonly use the .crt extension, but in some operating systems, they may use the .pem extension. On the other hand, the .crt extension may also be used by DER format certificates. Read more about certificate formats and file extensions in the following topic: Certificate formats.

Then, skip to the next section.
For example:
```
$openssl x509 -inform der \
  -in rootCertificate.cer \
  -out /var/portnox/portnox_ca.crt
```
Note:
The remaining steps in this section are for Windows desktops only.
If you’re working on a Windows desktop, double-click on the downloaded certificate file and click on the Open button in the Security warning window.
In the Certificate window, click on the Details tab and then click on the Copy to File button.
In the Certificate Export Wizard, export the certificate in base-64 encoded format.
1. In the first step of the wizard, click on the Next button.
2. In the second step of the wizard, select the Base-64 encoded X.509 (.CER) option.
3. In the third step of the wizard, select a file to save the exported certificate, and click on the Next button.
4. In the last step of the wizard, click on the Finish button. Then, close the Certificate window.
Copy the exported certificate to the Linux device.
The exported base-64 encoded file is a simple text file. If you’re running Linux in a virtual machine, you can simply copy and paste the content of the file into a relevant file in Linux.

For example, save the file as /var/portnox/portnox_ca.crt.

Request the device certificate using Certmonger

In this section, you will use the Certmonger software available on all Linux distributions to request a certificate for your device using the SCEP protocol and Portnox™ Cloud SCEP services.

Install certmonger.

Skip this step if you already have Certmonger installed.
Examples:
- RHEL:
```
$sudo dnf install certmonger
```
- Ubuntu:
```
$sudo apt-get install certmonger
```

Download the root CA certificate.

RHEL:

$sudo /usr/libexec/certmonger/scep-submit \
  -u http://your-scep-url \
  -C /path/to/root_ca_file.crt

Ubuntu:

$sudo /usr/lib/certmonger/scep-submit \
  -u http://your-scep-url \
  -C /path/to/root_ca_file.crt

Replace your-scep-url with your Portnox Cloud SCEP URL, which you got in the previous steps.
Replace /path/to/root_ca_file.crt with the location where you want to store the root CA file

Example:

$sudo /usr/lib/certmonger/scep-submit \
  -u http://scep.portnox.com/b2973887-1274-45a4-91d0-4a342a861c76 \
  -C /var/portnox/portnox-ca.crt

Add the root CA certificate to Certmonger.
```
$sudo getcert add-scep-ca -c ca_name \
  -u http://your-scep-url \ 
  -R /path/to/root_ca_file
```
1. Replace ca_name with the name you want to use for the Portnox Cloud CA in the Certmonger CA database.
2. Replace your-scep-url with your Portnox Cloud SCEP URL, which you got in the previous steps.
3. Replace /path/to/root_ca_file.crt with the name and location of the root CA file.
Example:
```
$sudo getcert add-scep-ca -c portnox \
  -u http://scep.portnox.com/b2973887-1274-45a4-91d0-4a342a861c76 \
  -R /var/portnox/portnox-ca.crt
```
Optional: Set the SELinux context of the directory to store keys.
```
$sudo chcon -Rv --type=cert_t /path/to/key_directory
```
- Replace /path/to/key_directory with the name and location of the directory where you will store the Portnox Cloud keys.
Note:
This is needed only on systems protected by SELinux, for example, RHEL.
```
$sudo chcon -Rv --type=cert_t /var/portnox
```
Request Certmonger to generate a key pair for your device.
```
$sudo getcert request -c ca_name \
  -l /path/to/secret_file -f /path/to/private_key.crt \
  -u dataEncipherment -u digitalSignature -k /path/to/public_key.crt \
  -U id-kp-clientAuth
```
1. Replace ca_name with the name you used for the Portnox Cloud CA in the Certmonger CA database.
2. Replace /path/to/secret_file with the name and location of the file containing the SCEP password, which you got in the previous steps.
3. Replace /path/to/private_key.pem with the name and location of the file where you want to store the private key for your device.
4. Replace /path/to/public_key.crt with the name and location of the file where you want to store the user certificate for your device.
Example:
```
$sudo getcert request -c portnox \
  -l /var/portnox/secret -k /var/portnox/public.crt \
  -u dataEncipherment -u digitalSignature -f /var/portnox/private.pem \
  -U id-kp-clientAuth
```
Optional: Generate a password-protected version of your private key.
```
$openssl rsa -aes256 -in /path/to/private_key.pem \
  -out /path/to/protected_private_key.pem \
  -passout file:/path/to/password_file
```
- Replace /path/to/password_file with the name and location of the file that contains a password for the private key file.
Note:
A password-protected private key may be required by graphical settings applications in Linux systems. This step is only required if you need to configure the network using the graphical interface.
Example:
```
$openssl rsa -aes256 -in /var/portnox/private.pem \
  -out /var/portnox/protected.pem \
  -passout file:/var/portnox/password
```

Result: You have obtained a private/public key pair for your device, which you can now use to configure your connections to your networks managed by Portnox Cloud.

Troubleshooting: use $sudo getcert list to list your Certmonger request and see any reasons for potential problems.

Important:

At the time of writing, the current version of Certmonger (0.79.18) has a bug that prevents it from validating CA certificates. There is no known workaround for this bug. If you cannot obtain the keys due to this bug, try downgrading to the previous version of Certmonger (0.79.17).

Configure your network connection with the Portnox Cloud certificate

In this section, you will configure NetworkManager on Linux to connect to the network managed by Portnox™ Cloud using your user certificate and private key.

Edit the NetworkManager connection file for the network to connect to.

Examples:

$sudo nano \ 
  '/etc/NetworkManager/system-connections/'Wired connection 1.nmconnection'

$sudo nano \
  /etc/NetworkManager/system-connections/HOMEWORLDWIFI1.nmconnection

Add the following section to the configuration file:
```
[802-1x]
ca-cert=/path/to/radius_ca_file.crt
client-cert=/path/to/public_key.crt
eap=tls;
identity=clear@identity
private-key=/path/to/protected_private_key.pem
private-key-password=private_key_password
```
Additionally, for Wi-Fi connections:
```
[wifi-security]
key-mgmt=wpa-eap
```
1. Replace /path/to/radius_ca_file.crt with the name and location of the root CA certificate file exported in the previous step.
2. Replace /path/to/public_key.crt with the name and location of the file where you stored the user certificate for your device.
3. Replace clear@identity with the corporate email address of the user to authenticate.
4. Replace /path/to/protected_private_key.pem with the name and location of the file where you stored the password-protected private key.
5. Replace private_key_password with the private key password that you set earlier.
Example:
```
[wifi-security]
key-mgmt=wpa-eap

[802-1x]
ca-cert=/var/portnox/portnox_ca.crt
client-cert=/var/portnox/public.crt
eap=tls;
identity=kosh@vorlon.com
private-key=/var/portnox/protected.crt
private-key-password=ZSGWhozKJyQRZ9Are6mUeWhXYou9FMbtT
```
Restart NetworkManager.
```
$sudo systemctl restart NetworkManager
```

Connect to the network using NetworkManager CLI.

Examples:

$sudo nmcli connection up 'Wired connection 1'

$sudo nmcli connection up HOMEWORLDWIFI1