pfSense | SSH Key Generation and Authorized Key Configuration

Overview ✨

Issue summary: pfSense SSH authentication can fail when a key generated or exported through PuTTYgen is not in the OpenSSH format expected by the inspector. Generating a new Ed25519 key pair with the Windows OpenSSH utility and adding the public key to pfSense resolves the issue in most cases.

This article explains how to resolve pfSense inspector connection failures caused by an invalid, incompatible, or incorrectly configured SSH key pair.

The recommended approach is to generate a standard Ed25519 OpenSSH key pair from Windows Command Prompt or PowerShell, add the public key to the pfSense user account, and provide the matching private key and passphrase in the inspector configuration.

Expected result: The key pair is saved under C:\Users\<username>\.ssh\, the public key is authorized in pfSense, and the inspector can authenticate using the corresponding private key.

Common Error Messages

Error encountered while extracting data. Details: _this._stream.close is not a function

Why Does This Happen?

SSH authentication requires a matching key pair and a compatible private-key format. The public key is installed on pfSense, while the private key remains with the connecting application. If the two keys do not match, authentication fails.

Key-format mismatch: PuTTYgen may create or export a PuTTY-specific .ppk file rather than the OpenSSH private-key format expected by the inspector.
Incorrect public key: The wrong key, an incomplete line, or a key with altered spacing may be pasted into pfSense.
Wrong private key: The inspector may be configured with a different private key than the public key authorized on pfSense.
Passphrase mismatch: A passphrase-protected private key requires the exact passphrase used during key generation.
Incorrect pfSense account: The public key must be added to the same pfSense user account used for SSH authentication.
SSH service or access restrictions: SSH may be disabled, restricted to specific interfaces, limited by firewall rules, or configured to disallow the selected user.
Copy-and-paste changes: Line breaks, missing headers, trailing characters, or copied command output can corrupt the private key.

Security reminder: Never share a private SSH key in a ticket, chat, screenshot, or email. Store private keys securely and use a unique passphrase.

Steps to Resolve

1. Generate a new Ed25519 key pair

Open Command Prompt or PowerShell on the Windows computer where the key will be managed. Run:

ssh-keygen -t ed25519 -C "pfsense-admin" -f %USERPROFILE%\.ssh\pfsense_key

When prompted:

Confirm the destination path if prompted.
Enter a strong passphrase.
Enter the same passphrase a second time.

The files should be created at:

C:\Users\<username>\.ssh\pfsense_key — private key
C:\Users\<username>\.ssh\pfsense_key.pub — public key

‼️Note

Replace pfsense-admin with the pfSense username that will be used by the Liongard Inspector. This value is used as the key's comment/label and should match the username configured for the Inspector.

For example, if the Inspector will authenticate using the pfSense user Liongard-Admin, run:

\ssh-keygen -t ed25519 -C "Liongard-Admin" -f %USERPROFILE%\.ssh\pfsense_key

The username configured in the Inspector must match the pfSense user where the public key is installed.

2. Verify that both files exist

Run:

dir %USERPROFILE%\.ssh

Confirm that both pfsense_key and pfsense_key.pub appear in the directory listing.

📝 If the command cannot find the directory, confirm that OpenSSH Client is installed and that the command is being run under the Windows user profile intended to manage the key.

3. Copy the public key

Display the public key with:

type %USERPROFILE%\.ssh\pfsense_key.pub

Copy the complete single line. It should begin with ssh-ed25519 and include the comment pfsense-admin.

Do not copy the private key at this stage. The public key is safe to install on the pfSense account, but it cannot be used by itself for authentication.

4. Add the public key to pfSense

Sign in to the pfSense web interface.
Go to System → User Manager → Users.
Edit the user that the inspector will use for SSH access.
Locate Authorized SSH Keys.
Paste the complete public-key line into the field.
Save the user configuration.

Ensure the public key remains on one line and starts with ssh-ed25519. Do not paste the private key into pfSense.

5. Confirm pfSense SSH settings

Verify that SSH is enabled and reachable from the inspector host:

Go to System → Advanced → Admin Access.
Confirm that the SSH service is enabled.
Review the SSH port and use the same port in the inspector configuration.
Confirm that SSH is listening on an interface reachable by the inspector.
Review firewall rules, network ACLs, VPN routes, and address restrictions that may block the connection.
Confirm that the selected pfSense user is permitted to use SSH and has the privileges required by the inspector.

Use the least-privileged account and permissions supported by the inspector and your organization’s security policy.

6. Configure the inspector with the private key

Display the private key only on the secure system where it will be entered:

type %USERPROFILE%\.ssh\pfsense_key

Copy the complete private-key content, including:

-----BEGIN OPENSSH PRIVATE KEY----- 
... 
-----END OPENSSH PRIVATE KEY-----

In the pfSense inspector configuration:

Paste the private key into the SSH Private Key field.
Enter the exact passphrase used when the key was generated.
Enter the pfSense hostname or IP address, SSH port, and username.
Save the configuration.
Run or test the inspector.

❌ Do not convert or modify the private key. Do not add extra quotation marks, remove the header or footer, paste the public key into the private-key field, or upload a .ppk file unless the inspector explicitly supports that format.

7. Validate the connection

Before troubleshooting the inspector further, validate SSH authentication from a system that can reach pfSense:

ssh -i %USERPROFILE%\.ssh\pfsense_key <pfSense-username>@<pfSense-hostname-or-ip>

If SSH uses a non-default port, specify it with -p:

ssh -p <port> -i %USERPROFILE%\.ssh\pfsense_key <pfSense-username>@<pfSense-hostname-or-ip>

When prompted, enter the private-key passphrase. A successful login confirms that the network path, pfSense account, authorized public key, private key, and passphrase are aligned.

8. Troubleshoot persistent failures

Regenerate the key pair if the private key is lost or its passphrase is unknown.
Confirm that the public key in pfSense was copied from the matching pfsense_key.pub file.
Confirm that the inspector contains the matching pfsense_key private key.
Check for accidental whitespace, wrapped lines, or missing key headers.
Verify the SSH username, hostname, port, and interface.
Check pfSense system logs and SSH authentication logs for rejected users, invalid keys, or connection restrictions.
Test from the inspector network to rule out firewall or routing issues.
Replace the key if it may have been exposed.

When to Contact Liongard Support 🦁

Contact Liongard Support after completing the steps above if the inspector still cannot authenticate or collect data.

Include the following non-sensitive details:

The inspector name and current version.
The pfSense version.
The SSH port and connection method.
The exact error message and approximate time of the failed run.
Whether direct SSH testing succeeded from the inspector network.
Relevant inspector logs with private keys, passphrases, tokens, and other secrets removed.
Confirmation that the public and private keys were generated as a matching pair.\
Confirmation if the above "Steps To Resolve" were followed.

❌ Never send the private key or passphrase to Liongard Support. If a private key may have been exposed, revoke its corresponding public key from pfSense and generate a replacement pair.