SSH Server

SSH Login Server

The ENiGMA½ SSH login server allows secure user logins over SSH (ssh://).

Note: If you run into any troubles during SSH setup, please see Troubleshooting SSH

Configuration

Entries available under config.loginServers.ssh:

Item	Required	Description
privateKeyPem	No	Path to private key file. If not set, defaults to ./config/ssh_private_key.pem
privateKeyPass	Yes	Password to private key file. *
firstMenu	No	First menu an SSH connected user is presented with. Defaults to sshConnected.
firstMenuNewUser	No	Menu presented to user when logging in with one of the usernames found within users.newUserNames in your config.hjson. Examples include new and apply.
enabled	Yes	Set to true to enable the SSH server.
port	No	Override the default port of 8889.
address	No	Sets an explicit bind address.
algorithms	No	Configuration block for SSH algorithms. Includes keys of kex, cipher, hmac, and compress. See the algorithms section in the ssh2-streams documentation for details. For defaults set by ENiGMA½, see core/config_default.js.
traceConnections	No	Set to true to enable full trace-level information on SSH connections.
untrustedTermSizeClients	No	List of SSH client identification strings whose reported terminal size should be skipped, compared in full and case-insensitively. Defaults to [ "SSH-2.0-cryptlib" ], which covers NetRunner: stock cryptlib hardcodes the terminal size as 80x48 and gives the application no way to change it. The size is established by querying the terminal instead, falling back to the usual 80x25 assumption if that query fails. Matching is deliberately exact rather than by substring: SyncTERM reports the actual size but identifies as SSH-2.0-cryptlib(SBBS) on 1.9rc4 and SSH-2.0-SyncTERM_<version> on newer builds, so a loose match on cryptlib would wrongly catch it. Remove an entry if a client’s size reporting is fixed upstream.

• IMPORTANT With the privateKeyPass option set, make sure that you verify that the config file is not readable by other users!

Example Configuration

{
    loginServers: {
        ssh: {
            enabled: true
            port: 8889
            privateKeyPem: /path/to/ssh_private_key.pem
            privateKeyPass: sup3rs3kr3tpa55
        }
    }
}

Tip

To avoid storing the passphrase in plain text, use the @file: directive to read it from a separate file — for example a Docker/Podman secret or a chmod-600 file:

privateKeyPass: "@file:/run/secrets/ssh_key_pass"

See Configuration Files — Secret Files for details.

Generate a SSH Private Key

To utilize the SSH server, an SSH Private Key (PK) will need generated. OpenSSH or (with some versions) OpenSSL can be used for this task:

OpenSSH (Preferred)

OpenSSH Install - Linux / Mac

If it is not already available, install OpenSSH using the package manager of your choice (should be pre-installed on most distributions.)

Running OpenSSH - Linux / Mac

From the root directory of the Enigma BBS, run the following:

mkdir -p config/security
ssh-keygen -t rsa -m PEM -h -f config/security/ssh_private_key.pem

Windows Install - OpenSSH

OpenSSH may already be installed, try running ssh-keygen.exe. If not, see this page: Install OpenSSH for Windows

Running OpenSSH - Windows

After installation, go to the root directory of your enigma project and run:

mkdir .\config\security -ErrorAction SilentlyContinue
ssh-keygen.exe -t rsa -m PEM -h -f .\config\security\ssh_private_key.pem

ssh-keygen options

Option descriptions:

Option	Description
-t rsa	Use the RSA algorithm needed for the ssh2 library
-m PEM	Set the output format to PEM, compatible with the ssh2 library
-h	Generate a host key
-f config/ssh_private_key.pem	Filename for the private key. Used in the privateKeyPem option in the configuration

When you execute the ssh-keygen command it will ask for a passphrase (and a confirmation.) This should then be used as the value for privateKeyPass in the configuration.

OpenSSL

Open SSL Install - Linux / Mac

If not already installed, install via the openssl package on most package managers.

Open SSL Install - Windows

winget install -e --id ShiningLight.OpenSSL

Running OpenSSL

Note: Using ssh-keygen from OpenSSL is recommended where possible. If you have trouble with the above OpenSSH commands, using some versions for OpenSSL (before version 3) the following commands may work as well:

Running OpenSSL - Linux / Mac

Run the following from the root directory of Enigma

mkdir -p config/security
openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048 -pkeyopt rsa_keygen_pubexp:65537 | openssl rsa -out ./config/security/ssh_private_key.pem -aes128

Running OpenSSL - Windows

Run the following from the root directory of Enigma (note: you may need to specify the full path to openssl.exe if it isn’t in your system path, on my system it was C:\Program Files\OpenSSL-Win64\bin\openssl.exe):

mkdir .\config\security -ErrorAction SilentlyContinue
openssl.exe genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048 -pkeyopt rsa_keygen_pubexp:65537 | openssl.exe rsa -out ./config/security/ssh_private_key.pem -aes128

Running Older OpenSSL

For older OpenSSL versions, the following command has been known to work:

openssl genrsa -aes128 -out ./config/ssh_private_key.pem 2048

Note: that you may need -3des for very old implementations or SSH clients!

Prompt

The keyboard interactive prompt can be customized using a SSHPMPT.ASC art file. See art for more information on configuring. This prompt includes a newUserNames variable to show the list of allowed new user names (see firstMenuNewUser above.) See mci for information about formatting this string. Note: Regardless of the content of the SSHPMPT.ASC file, the prompt is surrounded by “Access denied”, a newline, the prompt, another newline, and then the string “[username]‘s password: ”. This normally occurs after the first password prompt (no art is shown before the first password attempt is made.)

SSH Public Key Authentication

Users can now authenticate with SSH public keys in addition to passwords. Each account may store a single OpenSSH-format public key (for example, ssh-ed25519 AAAA... comment).

1. Log in through an already secure transport (SSH or secure WebSocket) and enter the SSH command from the main menu.
2. Paste the OpenSSH public key into the form and choose save/update key. The system records the key along with its SHA-256 fingerprint.
3. Optional: use remove key to clear the stored key and fall back to password logins.

Once saved, ENiGMA½ will require clients connecting with the publickey SSH method to prove possession of the corresponding private key. The upload menu is blocked on insecure transports to prevent man-in-the-middle attacks that could replace a user’s public key.