SSH Passwords & Keys

Overview

NetStacks supports two SSH authentication methods for connecting to network devices: password authentication and public-key authentication. You choose the method per credential profile using the profile's Auth Type setting, then attach that profile to one or more sessions.

How secrets are stored depends on the authentication method:

• Password auth stores the password encrypted in the local vault.
• Public-key auth stores a path to your private key file on disk (for example ~/.ssh/id_ed25519). The private key itself is never copied into the vault — only an optional key passphraseis encrypted and stored.

Password authentication is the most common method for network devices running Cisco IOS, IOS-XE, IOS-XR, NX-OS, Arista EOS, Juniper Junos, and similar platforms. Key-based authentication is preferred for Linux hosts and automation accounts that support it, because the secret never travels over the wire.

How It Works

Supported SSH Algorithms

During the handshake, NetStacks offers a broad list of host-key, key-exchange, cipher, and MAC algorithms and negotiates the strongest one the device also supports. The host-key (public-key) algorithms it offers, in preference order, are:

The key-exchange list ranges from Curve25519 and the NIST P-curves down to diffie-hellman-group14 and group1 (SHA-1) for very old gear. Ciphers include ChaCha20-Poly1305, AES-GCM, AES-CTR, and AES-CBC; MACs include the ETM SHA-2 variants down to HMAC-SHA1.

RSA Signature Selection

When you authenticate with an RSA private key, NetStacks tries rsa-sha2-512 first, then falls back to rsa-sha2-256 if the server rejects it. Non-RSA keys (Ed25519, ECDSA) use their native signature. You do not configure this manually — the client negotiates it automatically.

The Legacy SSH Toggle

NetStacks exposes a single boolean — Legacy SSH Algorithms (legacy_ssh) — that you set per session. When enabled, the connection is allowed to negotiate the older algorithms above for that device while everything else keeps using modern defaults. There is no per-algorithm picker; it is one switch.

Key Storage & Passphrases

For public-key auth, the profile records the key file path. At connect time the agent reads the private key from that path on the machine running NetStacks and, if the key is encrypted, decrypts it in memory using the stored passphrase. The passphrase is encrypted at rest with AES-256-GCM (keys derived via Argon2id), exactly like passwords. The private-key bytes are not stored in the vault and are never written back to disk in plaintext.

Step-by-Step Guide

Step 1: Add a Password Profile

1. Open a credential profile (Profiles tab → New / Edit)
2. On the Auth tab, enter a Profile Name and Username (e.g. admin)
3. Set Auth Type to Password
4. Enter the password in the Password field (stored securely in the vault)
5. Save the profile, then attach it to one or more sessions

Step 2: Generate an SSH Key Pair

Generate a key pair on the machine that runs NetStacks, then point the profile at the private key file:

# Ed25519 (recommended)
ssh-keygen -t ed25519 -C "[email protected]" -f ~/.ssh/netstacks_ed25519

# Or a 4096-bit RSA key for maximum compatibility
ssh-keygen -t rsa -b 4096 -C "[email protected]" -f ~/.ssh/netstacks_rsa

Step 3: Add a Public-Key Profile

1. Open a credential profile and enter a name and username
2. Set Auth Type to Public Key
3. In Key File Path, enter the path to the private key, e.g. ~/.ssh/netstacks_ed25519
4. Leave Key Passphrase blank for an unencrypted key
5. Save the profile

Step 4: Use a Passphrase-Protected Key

1. Set Auth Type to Public Key and fill in the Key File Path
2. Enter the passphrase in the Key Passphrase (optional) field
3. NetStacks encrypts and stores only the passphrase; the key file stays on disk
4. At connect time the passphrase is decrypted in memory to unlock the key

Step 5: Enable Legacy Algorithms for Older Devices

For a device that only speaks ssh-rsa/ssh-dss or SHA-1 key exchange:

1. Edit the session for that device (Advanced settings)
2. Turn on Legacy SSH Algorithms
3. Connect — NetStacks negotiates the older algorithms for that session only

Code Examples

Generate SSH Keys for Network Automation

# Ed25519 (recommended)
ssh-keygen -t ed25519 -C "[email protected]" -f ~/.ssh/netstacks_ed25519
# Output: ~/.ssh/netstacks_ed25519 (private) and ~/.ssh/netstacks_ed25519.pub (public)

# RSA 4096-bit (maximum compatibility)
ssh-keygen -t rsa -b 4096 -C "[email protected]" -f ~/.ssh/netstacks_rsa

# ECDSA P-521
ssh-keygen -t ecdsa -b 521 -C "[email protected]" -f ~/.ssh/netstacks_ecdsa

# Deploy the public key to a host that supports authorized_keys
ssh-copy-id -i ~/.ssh/netstacks_ed25519.pub [email protected]

Confirm a Key Path Loads (and Detect a Passphrase)

# If the key is encrypted, ssh-keygen -y prompts for the passphrase.
# This is the same key path you put in the profile's "Key File Path" field.
ssh-keygen -y -f ~/.ssh/netstacks_ed25519

# Re-encrypt a key with a new passphrase (then update the profile passphrase)
ssh-keygen -p -f ~/.ssh/netstacks_ed25519

Create a Personal SSH Credential on the Controller (Enterprise)

On the enterprise Controller, personal credentials are created through the /credentials/personal endpoint. This shape includes an optional enable_secret field that local profiles do not have. The secret is the password (for ssh_password) or the private-key body (for ssh_key); the Controller encrypts it server-side.

POST /credentials/personal
Content-Type: application/json

{
  "name": "Cisco Admin - DC1",
  "credential_type": "ssh_password",
  "username": "netops",
  "host": "core-rtr-01.dc1.example.net",
  "port": 22,
  "secret": "the-login-password",
  "enable_secret": "the-enable-secret",
  "description": "Production core access"
}

Deploy a Public Key to a Cisco IOS-XE Device

! Configure SSH public-key authentication on IOS-XE
conf t
ip ssh pubkey-chain
  username netops
    key-string
      AAAAC3NzaC1lZDI1NTE5AAAAIBzBpR6rTsEkFPSVxNQyXbXp0LhFnKb
      Xda4PlF9gFmT
    exit
  exit
exit

! Verify
show ip ssh pubkey-chain

Local ~/.ssh/config for Legacy Devices

# Allow legacy algorithms for specific old devices in your own ssh client.
# (In NetStacks itself, use the per-session "legacy_ssh" toggle instead.)
Host legacy-switch-*.example.net
  HostkeyAlgorithms +ssh-rsa
  PubkeyAcceptedAlgorithms +ssh-rsa
  KexAlgorithms +diffie-hellman-group14-sha1

Host *.example.net
  HostkeyAlgorithms ssh-ed25519,rsa-sha2-512,rsa-sha2-256
  PubkeyAcceptedAlgorithms ssh-ed25519,rsa-sha2-512,rsa-sha2-256

Questions & Answers

Q: Does NetStacks store my private key in the vault?

A: No. For public-key auth, the profile stores a path to the private key file (e.g. ~/.ssh/id_ed25519). NetStacks reads the key from that path at connect time. Only the optional key passphrase is encrypted and stored in the vault.

Q: Which SSH key types and signatures are supported?

A: Ed25519, ECDSA (nistp256/384/521), and RSA. RSA uses rsa-sha2-512 then rsa-sha2-256, with fallback to legacy ssh-rsa (SHA-1) when legacy mode is on. ssh-dss (DSA) is also offered for very old devices.

Q: Which key type should I use?

A: Use Ed25519 where supported — it is small, fast, and secure. For older network gear (Cisco IOS 15.x and earlier, older Junos), use RSA 4096-bit, which has the widest compatibility.

Q: How do I enable legacy algorithms for an old device?

A: Turn on Legacy SSH Algorithms (the legacy_ssh toggle) on the session for that device. It is a single switch — there is no per-algorithm picker. Other sessions keep using modern defaults.

Q: Is there an enable / privileged-mode secret field?

A: Not in local credential profiles — those store only password, key passphrase, and SNMP communities. A stored enable secret (enable_secret) is available only for personal credentials on the enterprise Controller via /credentials/personal.

Q: Can I use the same profile for multiple devices?

A: Yes. A profile can be attached to any number of sessions. Updating the password, key path, or passphrase on the profile applies to every session that uses it.

Q: How are secrets encrypted?

A: With AES-256-GCM (authenticated encryption), using keys derived via Argon2id. Passwords and key passphrases are decrypted only in process memory during an active connection.

Troubleshooting

Key file not found or unreadable

Public-key auth fails with a load error if the path is wrong or the file is unreadable. Because NetStacks reads the key from disk:

• Confirm the Key File Path in the profile points at the private key on the machine running NetStacks
• Verify the file exists and is readable: ls -l ~/.ssh/netstacks_ed25519 (mode 600 is typical)
• Expand ~ yourself if needed and use an absolute path to rule out home-directory differences

Passphrase errors on an encrypted key

• Re-enter the passphrase in the profile — it may have been stored incorrectly
• Confirm the key is actually encrypted: ssh-keygen -y -f keyfile prompts for a passphrase if it is
• Re-encrypt with a known passphrase via ssh-keygen -p -f keyfile and update the profile

Legacy device rejects the connection

If an older device drops the handshake (no common kex / host-key algorithm):

• Enable Legacy SSH Algorithms on that session
• For key auth, try an RSA 4096-bit key if the device rejects Ed25519/ECDSA
• Check what the device offers: show ip ssh on Cisco, show system software on Juniper

# Inspect what algorithms a device offers from your own client
ssh -vvv [email protected] 2>&1 | grep -i "host key algorithm"
# Look for: ssh-rsa, rsa-sha2-256, ssh-ed25519, ssh-dss, etc.

Permission denied with the correct key

• Confirm the matching public key is installed on the device for the profile's username
• On Linux hosts, check that ~/.ssh/authorized_keys is readable only by the user (mode 600)
• Verify the username in the profile matches the account configured on the device
• On network devices, ensure SSH public-key authentication is enabled in the running config

Related Features

Continue exploring credential management:

• Credential Vault — How the vault encrypts and manages credential secrets
• Credential Profiles & Folders — Where auth type, key path, and passphrase live
• SSH Certificates — Short-lived certificate-based authentication with the SSH CA
• Personal Vaults — Store your own credentials, including the enable secret, on the Controller
• SNMP Credentials — SNMP community strings stored alongside SSH secrets in a profile
• Connecting to Devices — Use stored credentials to connect via the Terminal