How to configure SSH key-based authentication with Redtrust

Overview

This guide explains how to authenticate to an SSH server using a private key stored in Redtrust instead of a local key file.

Background

In a standard SSH setup, the client uses a local private key file (for example, id_rsa or id_ed25519) to authenticate to a server. The server verifies the corresponding public key stored in the authorized_keys file.

When using Redtrust, the private key is not stored locally. Instead, OpenSSH loads the Redtrust PKCS#11 provider (RTPKCS11.dll) to access the private key securely from Redtrust. From the server’s perspective, authentication works as standard public key authentication. The only difference is how the client accesses the private key.

Before you begin

To follow this how-to you will need the following:

• A certificate uploaded to Redtrust.
• A policy that allows the use of the SSH client (ssh.exe).
• An SSH server that allows public key authentication.
• For Windows server, you need to have installed OpenSSH and started the service.

warning

If the OpenSSH installation fails, make sure the machine is in the last patch of the OS. To do that run sconfig, select Download and install updates and install any pending updates.

Get the SSH public key

1. Access the admin console.
2. Go to Certificates and find the one you want to use.
3. Go to the Actions menu > Download certificate > Download .pub (SSH).

The content of the .pub file is the SSH public key used in the following steps.

Configure the SSH server

Windows server

By default, the OpenSSH Server installation already enables login via public key authentication. You must add the public key and associate it with the user account.

On Windows, OpenSSH treats administrator accounts differently and stores authorized keys in a system-wide file under ProgramData.

For admin users

1. Create the file administrators_authorized_keys.

   New-Item -Force -ItemType File -Path C:\ProgramData\ssh\administrators_authorized_keys

2. Add the public key you downloaded from Redtrust to the list of accepted keys.

   Add-Content -Force -Path $env:ProgramData\ssh\administrators_authorized_keys -Value "YOUR_SSH_KEY"

3. Configure permissions for the file.

   Get-Acl C:\ProgramData\ssh\ssh_host_rsa_key | Set-Acl C:\ProgramData\ssh\administrators_authorized_keys

4. Restart the service.

   Restart-Service sshd

For non-admin users

1. Create the file authorized_keys.

   New-Item -Force -ItemType File -Path C:\Users\YOUR_USERNAME\.ssh\authorized_keys

2. Add the public key to the list of accepted keys.

   Add-Content -Force -Path C:\Users\YOUR_USERNAME\.ssh\authorized_keys -Value "YOUR_SSH_KEY"

3. Configure permissions for the file.

   Get-Acl C:\Users\YOUR_USERNAME | Set-Acl C:\Users\YOUR_USERNAME\.ssh
   Get-Acl C:\Users\YOUR_USERNAME | Set-Acl C:\Users\YOUR_USERNAME\.ssh\authorized_keys

4. Restart the service.

   Restart-Service sshd

Linux server

Add public key

1. Access the server with a user with sudo privileges.

2. If the .ssh directory does not exist, create it manually.

   mkdir -p ~/.ssh

3. In the .ssh directory, create the authorized_keys file and open it:

   touch ~/.ssh/authorized_keys
   vim ~/.ssh/authorized_keys

4. Paste the Redtrust public key you downloaded from Redtrust into the file (it looks something like this ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQ...).

5. Set the correct permissions:

   chmod 600 ~/.ssh/authorized_keys

   warning

   SSH will refuse authentication if directory and file permissions are too permissive.

Configure SSH to allow public key authentication

info

In most Linux distributions, public key authentication is enabled by default.

1. Edit the SSH server configuration file:

   sudo vim /etc/ssh/sshd_config

2. Ensure public key authentication is enabled:

   PubkeyAuthentication yes

3. Restart the SSH service:

   sudo systemctl restart ssh

   On some distributions (e.g., CentOS/RHEL), use:

   sudo systemctl restart sshd

Once the SSH server trusts the public key, configure the SSH client to use the private key stored in Redtrust.

Configure the SSH client

Windows client

Once the SSH server accepts public key authentication, configure the Windows SSH client to use the key stored in Redtrust.

1. Connect to the Redtrust agent.

2. Create a SSH configuration file named config.

   C:\Users\YOUR_USERNAME\.ssh\config

   If the .ssh directory does not exist, create it manually.

3. Add the following line:

   PKCS11Provider "C:\Windows\System32\RTPKCS11.dll"

   This instructs OpenSSH to use the Redtrust PKCS#11 provider to access private keys stored securely in Redtrust.

4. Connect to the server:

   ssh YOUR_USERNAME@SERVER_IP

If the server trusts the corresponding public key, authentication succeeds without using a local private key file or the server password.

warning

If the client requests a Redtrust PKCS#11 PIN, make sure your client is running the agent.

Linux client

1. If the .ssh directory does not exist, create it manually.

   mkdir -p ~/.ssh

2. On your client machine, edit the SSH configuration file.

   vim ~/.ssh/config

3. Add the following to the configuration file:

   Host my-server
       HostName SERVER_IP
       User YOUR_USERNAME
       PKCS11Provider /usr/lib/libkeyfactorpkcs11.so

   Replace the path if your module is installed in a different location.

4. Connect to the server:

   ssh my-server

This setting instructs OpenSSH to use the Redtrust PKCS#11 provider to access private keys stored securely in Redtrust.

tip

On Windows, Git may use its own SSH implementation instead of the OpenSSH client included with the operating system. Configure Git to use the Windows OpenSSH client:

git config --global core.sshCommand "C:/Windows/System32/OpenSSH/ssh.exe"

After this configuration, Git uses the same SSH client that loads the Redtrust PKCS#11 provider.

On Linux, Git uses the system SSH client by default, so no additional configuration is required.