Skip to content

Authentication

Set up SSH keys or passwords to authenticate your tunnel connections.

Authentication Methods

Method Security Best For
SSH Key High Production, regular use
Password Medium Quick setup, testing

Recommendation: Use SSH keys when possible.

SSH Key Authentication

Select a Key

When creating or editing a tunnel:

  1. Choose SSH Key authentication
  2. Select your key from the dropdown
  3. Save the tunnel

Keys appear in the dropdown after you import them. If the list is empty, click Import SSH Key….

Import Keys

If your keys are elsewhere:

  1. Choose Window → SSH Key Management (Shift+Cmd+K), or click Import Key… next to the key list in the tunnel editor
  2. Click Import and select your private key file
  3. The key is now available for tunnels

Key Types

Type Recommendation
Ed25519 Best -- modern and secure
RSA (4096-bit) Good -- widely supported
ECDSA OK -- good security

Password Authentication

Set Up Password

When creating or editing a tunnel:

  1. Set Method to Password
  2. Enter your SSH password
  3. Click Save

Your password is stored in the macOS Keychain when you save the tunnel.

Update Password

  1. Edit the tunnel
  2. Enter the new password
  3. Save

Managing SSH Keys

View Your Keys

Open Window → SSH Key Management (Shift+Cmd+K) to:

  • See all imported keys
  • View key details
  • Copy public keys
  • Delete unused keys

Copy Public Key

To add your key to a server:

  1. Open SSH Key Management
  2. Select your key
  3. Click Copy Public Key
  4. Send to your server administrator

They'll add it to ~/.ssh/authorized_keys on the server.

Troubleshooting

"Permission denied (publickey)"

Your SSH key isn't authorized on the server.

Solutions:

  • Verify you selected the correct key
  • Ask admin to add your public key to the server
  • Test manually: ssh -i /path/to/key user@host

"Authentication failed"

Password is incorrect.

Solutions:

  • Verify the password is correct
  • Check Caps Lock
  • Re-enter the password in tunnel settings

"Host key verification failed"

Server's identity can't be verified.

Solutions:

  • Confirm you're connecting to the correct server
  • StormTunnel asks you to accept a new host key the first time you connect
  • Ask admin for the server's fingerprint to verify

Best Practices

  1. Use SSH keys -- More secure than passwords
  2. Use Ed25519 -- Modern, fast, secure
  3. Never share private keys -- Treat them like passwords
  4. Use Keychain -- Let macOS store passwords securely
  5. Rotate keys yearly -- For critical servers