SSH Passwords & Keys

Overview

NetStacks supports two primary SSH authentication methods for connecting to network devices: password authentication and public key authentication. Both methods store credentials securely in the Credential Vault using AES-256-GCM encryption at rest.

Password authentication is the most common method for network devices, especially those running Cisco IOS, IOS-XE, NX-OS, Juniper Junos, and similar platforms. Key-based authentication is preferred for Linux hosts, automation accounts, and devices that support it, as it eliminates password exposure during authentication entirely.

• SSH password credentials with optional enable/privileged mode password
• Multiple SSH key types: RSA, ECDSA (nistp256, nistp384, nistp521), and Ed25519
• Modern RSA signature algorithms: rsa-sha2-256 and rsa-sha2-512
• Legacy algorithm support (ssh-rsa with SHA-1) for older Cisco IOS and similar platforms
• Passphrase-protected private keys with encrypted passphrase storage
• Import existing keys or generate new key pairs

How It Works

Supported Key Algorithms

NetStacks supports the following SSH key types, listed in recommended order:

Passphrase-Protected Keys

When you import a private key that is encrypted with a passphrase, NetStacks stores both the encrypted private key and the passphrase in the vault. The passphrase is encrypted separately using AES-256-GCM, the same as all other secrets. During connection, the Controller decrypts the passphrase, uses it to unlock the private key in memory, authenticates to the device, and then discards both values.

Legacy Algorithm Support

Some older network devices only support the original ssh-rsa signature algorithm. NetStacks can fall back to this algorithm on a per-credential or per-device basis without affecting other connections.

Key Storage

Private keys are stored in the vault's encrypted_secret field, encrypted with AES-256-GCM like all other credentials. The key format (PEM or OpenSSH) is preserved as-is. Public keys are stored in the credential metadata for reference but are not used during authentication — only the private key is needed.

Step-by-Step Guide

Step 1: Add a Password Credential

1. Navigate to Credentials → Add Credential
2. Select type: SSH Password
3. Enter a name (e.g., "Cisco Admin — Production")
4. Enter the SSH username (e.g., admin)
5. Enter the SSH password
6. If the device requires a separate enable password, enter it in the Enable Secret field
7. Select a credential folder and click Save

Step 2: Generate and Add an SSH Key Pair

Generate a new key pair on your workstation, then import the private key into NetStacks:

# Generate an Ed25519 key (recommended)
ssh-keygen -t ed25519 -C "netstacks-automation@example.net" -f ~/.ssh/netstacks_ed25519

# Or generate a 4096-bit RSA key for maximum compatibility
ssh-keygen -t rsa -b 4096 -C "netstacks-automation@example.net" -f ~/.ssh/netstacks_rsa

1. Navigate to Credentials → Add Credential
2. Select type: SSH Key
3. Enter a name and username
4. Paste the private key content or upload the key file
5. Click Save

Step 3: Import an Existing SSH Key

1. Locate your existing private key file (e.g., ~/.ssh/id_ed25519)
2. Navigate to Credentials → Add Credential → SSH Key
3. Paste the private key contents or click Upload to browse for the file
4. NetStacks accepts both PEM format (-----BEGIN OPENSSH PRIVATE KEY-----) and legacy PEM format (-----BEGIN RSA PRIVATE KEY-----)
5. Click Save

Step 4: Add a Passphrase-Protected Key

1. Follow the same steps as importing a key
2. When prompted, enter the passphrase in the Key Passphrase field
3. NetStacks stores the passphrase encrypted alongside the key
4. During connections, the passphrase is decrypted in memory to unlock the key

Step 5: Enable Legacy Algorithm Support for Older Devices

For devices that only support ssh-rsa with SHA-1 signatures:

1. Create or edit the credential that will be used with the legacy device
2. In the credential metadata, note that legacy algorithms may be needed
3. When adding the device, configure it to allow legacy SSH algorithms
4. The Controller will negotiate ssh-rsa only for that specific device

Code Examples

Generate SSH Keys for Network Automation

# Ed25519 (recommended for modern devices)
ssh-keygen -t ed25519 -C "netstacks-dc1@example.net" -f netstacks_ed25519
# Output: netstacks_ed25519 (private) and netstacks_ed25519.pub (public)

# RSA 4096-bit (maximum compatibility)
ssh-keygen -t rsa -b 4096 -C "netstacks-dc1@example.net" -f netstacks_rsa
# Output: netstacks_rsa (private) and netstacks_rsa.pub (public)

# ECDSA 521-bit
ssh-keygen -t ecdsa -b 521 -C "netstacks-dc1@example.net" -f netstacks_ecdsa

# Deploy public key to a network device (if it supports authorized_keys)
ssh-copy-id -i netstacks_ed25519.pub admin@core-rtr-01.dc1.example.net

Create an SSH Key Credential via API

# Read the private key file
PRIVATE_KEY=$(cat netstacks_ed25519)

curl -X POST https://controller.example.net/api/credentials \
  -H "Authorization: Bearer ${API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d "{
    \"name\": \"Automation Key - DC1\",
    \"description\": \"Ed25519 key for automated config backups\",
    \"credential_type\": \"ssh_key\",
    \"username\": \"netops\",
    \"secret\": $(echo "$PRIVATE_KEY" | jq -Rs .),
    \"folder_id\": \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\",
    \"metadata\": {
      \"key_type\": \"ed25519\",
      \"has_passphrase\": false
    }
  }"

Deploy a Public Key to a Cisco IOS-XE Device

! On the Cisco IOS-XE device, configure SSH public key authentication
conf t
ip ssh pubkey-chain
  username netops
    key-string
      AAAAC3NzaC1lZDI1NTE5AAAAIBzBpR6rTsEkFPSVxNQyXbXp0LhFnKb
      Xda4PlF9gFmT
    exit
  exit
exit

! Verify the key was accepted
show ip ssh pubkey-chain

SSH Config for Legacy Devices

# ~/.ssh/config - Allow legacy algorithms for specific old devices
Host legacy-switch-*.example.net
  HostkeyAlgorithms +ssh-rsa
  PubkeyAcceptedAlgorithms +ssh-rsa
  KexAlgorithms +diffie-hellman-group14-sha1

Host *.example.net
  # Modern defaults for everything else
  HostkeyAlgorithms ssh-ed25519,rsa-sha2-512,rsa-sha2-256
  PubkeyAcceptedAlgorithms ssh-ed25519,rsa-sha2-512,rsa-sha2-256

Questions & Answers

Q: What SSH key types does NetStacks support?

A: NetStacks supports Ed25519 (recommended), ECDSA (nistp256, nistp384, nistp521), and RSA (2048-bit and 4096-bit). For RSA keys, NetStacks uses modern rsa-sha2-256 and rsa-sha2-512 signature algorithms by default, with fallback to legacy ssh-rsa (SHA-1) for older devices that require it.

Q: Which key type should I use?

A: Use Ed25519 if all your devices support it. Ed25519 keys are smaller, faster, and more secure than RSA or ECDSA. If you need compatibility with older network devices (Cisco IOS 15.x and earlier, older Junos versions), use RSA 4096-bit, which works with the widest range of platforms.

Q: How do I handle passphrase-protected keys?

A: When importing a passphrase-protected private key, enter the passphrase in the Key Passphrase field. NetStacks encrypts and stores the passphrase alongside the key in the vault. During connections, the Controller decrypts the passphrase, uses it to unlock the key in memory, and discards both after authentication.

Q: How do I use legacy algorithms for older devices?

A: Configure the device in NetStacks to allow legacy SSH algorithms. The Controller will negotiate ssh-rsa (SHA-1) only for that specific device while using modern algorithms for all others. You can use the same RSA key — only the signature algorithm changes during the handshake.

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

A: Yes. A single credential in the vault can be referenced by any number of devices. When you rotate the key, all devices using that credential will automatically use the new key on their next connection. This is the recommended approach for automation accounts that access many devices with the same identity.

Q: How are SSH keys stored securely?

A: Private keys are encrypted using AES-256-GCM and stored in the vault's encrypted_secret field, exactly like passwords. The key format (PEM or OpenSSH) is preserved. Keys are only decrypted in Controller process memory during active SSH sessions and are never written to disk in plaintext.

Q: What key formats are accepted?

A: NetStacks accepts OpenSSH format (-----BEGIN OPENSSH PRIVATE KEY-----) and traditional PEM format (-----BEGIN RSA PRIVATE KEY-----, -----BEGIN EC PRIVATE KEY-----). PKCS#8 format is also supported. If you have a PuTTY PPK file, convert it first using puttygen key.ppk -O private-openssh -o key.

Troubleshooting

Key format not recognized

NetStacks expects private keys in OpenSSH or PEM format. If you receive a format error:

• Verify the key starts with -----BEGIN OPENSSH PRIVATE KEY----- or -----BEGIN RSA PRIVATE KEY-----
• Convert PuTTY PPK format: puttygen key.ppk -O private-openssh -o key_openssh
• Ensure the key file was not corrupted during copy-paste — check for missing newlines or trailing whitespace

Passphrase prompt failing

If a connection fails with a passphrase error even though the passphrase was stored:

• Edit the credential and re-enter the passphrase — it may have been stored incorrectly
• Verify the key is actually passphrase-protected: ssh-keygen -y -f keyfile will prompt for a passphrase if the key is encrypted
• Try re-exporting the key with a new passphrase and re-importing it

Legacy device rejecting modern key types

If an older device rejects Ed25519 or ECDSA keys:

• Switch to an RSA 4096-bit key for that device
• Enable legacy algorithm support on the device configuration in NetStacks
• Verify the device's SSH server version: show ip ssh on Cisco, show system software on Juniper

# Check what algorithms a device supports
ssh -vvv admin@legacy-switch-01.example.net 2>&1 | grep "host key algorithm"
# Look for: ssh-rsa, rsa-sha2-256, ssh-ed25519, etc.

Permission denied with correct key

If the key is correct but authentication still fails:

• Confirm the public key is installed on the target device for the correct username
• Check file permissions on the device: ~/.ssh/authorized_keys must be readable only by the user (mode 600)
• Verify the username in the credential matches the user configured on the device
• On network devices, ensure SSH public key authentication is enabled in the device configuration

Related Features

Continue exploring credential management:

• Credential Vault — How the vault encrypts and manages all credential types
• SSH Certificates — Use the built-in SSH CA for short-lived certificate-based authentication
• Personal Vaults — Store personal SSH keys in your own private vault
• Adding Devices — Associate SSH credentials with devices for one-click connections
• Connecting to Devices — Use stored credentials to connect via the Terminal