SSH public key authentication

SSH key authentication uses a pair of cryptographic keys; a private key stored on the client and a public key placed on the server in order to verify identity without transmitting passwords over the network.

On NixOS, SSH key authentication is typically managed using OpenSSH, which is included by default and can be configured both declaratively in configuration.nix and interactively using standard SSH tools.

Generating an SSH key pair

To setup a public key based SSH connection from your-machine (client) to another-machine (server):

$ ssh-keygen -f ~/.ssh/another-machine
$ ssh-copy-id -i ~/.ssh/another-machine -p22 another-machine-host-or-ip

This copies the public key to another-machine, placing it in the user’s ~/.ssh/authorized_keys file.

On your-machine, we stored the key file in the non-standard path ~/.ssh/another-machine, so we must tell the SSH client to use the key file:

$ ssh -i ~/.ssh/another-machine another-machine-host-or-ip

The connection should now succeed without prompting for a password.

To make the SSH client automatically use the key file, add a host entry to your per-user SSH configuration file:

≡︎ ~/.ssh/config

Host another-machine
  HostName 192.168.1.105 # another-machine-host-or-ip
  #Port 22
  #User user

  # Prevent using ssh-agent or another keyfile, useful for testing
  IdentitiesOnly yes
  IdentityFile ~/.ssh/another-machine

Copy

SSH agent

A ssh private key, for which a phrase is defined, can be clumsy if you use it multiple times. It is possible to store the private key identity in a ssh-agent. The ssh-agent uses the ssh private key identity when you issue a ssh command, for instance when using ssh to connect.

To define NixOS to setup a ssh-agent, add this to your configuration:

programs.ssh.startAgent = true;

NixOS will start a user systemd service with the ssh-agent at login. You can see the service with the command systemctl --user status ssh-agent.

It provides also the environment variable $SSH_AUTH_SOCK which refers to /run/user/1000/ssh-agent , in this case for user id 1000.

If you want to use a ssh key pair for authenticating, you can add this to the ssh-agent using the command ssh-add entering the phrase only once.

$ ssh-add .ssh/id_rsa
Enter passphrase for .ssh/id_rsa: 
Identity added: .ssh/id_rsa (myaccounts@mymachine)

If you store the ssh public key with the command ssh-copy-id on another-machine as shown above, you can logon without giving a password or phrase.

SSH server configuration

You can manage SSH authorized public keys declaratively by adding them to your system to your system configuration:

❄︎ /etc/nixos/configuration.nix

  users.users."myUser".openssh.authorizedKeys.keys = [
    "ssh-rsa AAAAB3Nz....6OWM= user" # content of authorized_keys file
    # note: ssh-copy-id will add user@your-machine after the public key
    # but we can remove the "@your-machine" part
  ];

Copy

Alternatively, you can reference a custom file containing the authorized keys:

❄︎ /etc/nixos/configuration.nix

  users.users."user".openssh.authorizedKeys.keyFiles = [
    /etc/nixos/ssh/authorized_keys
  ];

Copy

For additional configuration options, see the users.users.*.openssh module documentation.

After configuring user keys, it is recommended to improve server security by disabling password-based authentication and requiring public key authentication. This can be done on a NixOS-based server (e.g. another-machine). For additional security measures, see SSH#Security hardening.

This can be configured in your system configuration:

❄︎ /etc/nixos/configuration.nix

  services.openssh = {
    enable = true;
    # require public key authentication for better security
    settings.PasswordAuthentication = false;
    settings.KbdInteractiveAuthentication = false;
};

Copy

Tips and tricks

KDE

By default, KDE prompts you to enter the passwords for your SSH keys to unlock them across session starts. To avoid being asked to unlock your SSH keys every time a session is restarted (e.g., after logging out or rebooting), you can use ksshaskpass to store the passwords. To enable this, make the following changes to your configuration:

programs.ssh = {
  startAgent = true;
  enableAskPassword = true;
};

environment.variables = {
  SSH_ASKPASS_REQUIRE = "prefer";
};

After applying these changes, either log out (if you used switch) or reboot (if you used boot for the variables to take effect.

When you use an SSH key for the first time, you will be prompted to enter its passphrase. Be sure to select the "Remember password" checkbox and the passphrase will be securely stored in the KDE Wallet and automatically retrieved across session restarts.

See also

• SSH
• Distributed build