How to Use SSH Keys in Panic Apps

Real talk: passwords are bad. Passwords are notoriously hard to remember, yet easy for attackers to break. A secure password is a long, meaningless string containing a mix of letters, numbers, and symbols. Because they’re so hard to remember, it’s tempting to use the same password everywhere, which means you have to change all your passwords if just one login gets compromised.

Use Keys, Not Passwords

Fortunately for us, SSH allows connections to be authenticated using keys. Key-based authentication is a huge improvement over a simple username and password combination.

Instead of a password, you have a pair of matched keys: one public, and one private. Anyone with access to the public key can use it to encrypt information, which can only be decrypted using the corresponding private key.

Watch this video for a non-technical illustration of how this works (with paint!).

Getting Started With Keys

First, we need some keys to use.

Did your server provide you with keys?
Great! Let’s skip down a bit.
Don’t have any keys?
Not to worry, we can generate them.

Generate Your Keypair

If you’re using Coda for iOS, Transmit for iOS, or Prompt, you can generate keypairs from inside the app.

If you’re on a Mac, we can generate your keypair from the command line. Open a Terminal window and enter the following command:

$ ssh-keygen -t rsa -b 4096

The $ symbol indicates a command prompt. Everything after the $ is a command to be entered.

Press Return, and you’ll see this:

Generating public/private rsa key pair.
Enter file in which to save the key (/Users/YOU/.ssh/id_rsa):

The first decision to make is where to keep your key, and what to call it. For now we’ll just stick with the defaults.

Hit Return to create a keypair using the default name id_rsa and put it in the .ssh folder in your home folder.

Nerd Stuff! The Finder in macOS keeps that .ssh folder hidden. To see your .ssh folder in the Finder, press Command+Shift+G, then enter ~/.ssh. Also! The tilde (~) is filesystem shorthand for your user’s home folder. So when we say ~/.ssh, that means /Users/YOU/.ssh.

Next you can opt to encrypt your private key with a passphrase.

The passphrase is an extra layer of security on your private key. With a passphrase, not only does someone need to gain access to your private key, they also need your passphrase in order to make use of it.

Enter passphrase (empty for no passphrase): 

To set a passphrase, enter it here.

To skip setting a passphrase, hit Return without typing anything.

Enter same passphrase again: 

Whether you set a passphrase or not, you’ll be asked to confirm it. Enter the passphrase again, or just press Return.

Your identification has been saved in /Users/YOU/.ssh/id_rsa.
Your public key has been saved in /Users/YOU/.ssh/id_rsa.pub.

The key fingerprint is:
SHA256:DD388JM7gMpxRm7y+8qjF7pOtIrzF56htWdrZuLwZQk YOU@YourMac.local

The key's randomart image is:
+---[RSA 2048]----+
|                 |
|       o         |
|      o =        |
|     o + = .     |
|    E * S =      |
|   o+@.. . o     |
|  .+=*=.  o      |
|...=B+O.   .     |
|.oo+*@==.        |
+----[SHA256]-----+

Your keypair has been generated.

Note that the private key is called “id_rsa” and the public key is “id_rsa.pub”, and they’re both in a folder called “.ssh” in your home folder.

The Public Key

The public key (the one ending in .pub) goes on the remote server. If your server administrator provided you with a key to use, they’ve likely already taken care of this for you. If not, you’ll need to find a way to put your public key on the server.

In most cases, this means connecting with a username and password. Once connected, navigate into ~/.ssh/ on the remote server and look for a file called authorized_keys or authorized_keys2. Open that file in a text editor, and append the entire contents of your public key onto the end of the file.

Your public key is a text file with a single long line. Enter this command to see it:

$ cat ~/.ssh/id_rsa.pub

It should look like this:

ssh-rsa AAAA75e8wZ/YTf3T8xz/gqnmTkKFMkCUBHMahpqHY7VdprMJqYVhu//v1OyNkSFfZ/jh/WLE+d3mIXUsRD1nBZDhkoKqdAuCt2Bw+Jy6fZnDfBpDv8uzYvuiGh5f9XT+0jVdj8aaqe09/C5yEwW2P2g2XZ4XqvT4NzaC1yc2EAAAADAQABAAABAQDLWN2v57PUNZsQsUUdRHYth6DO/YrkMoWs/wVc4sE2g+8fmevhYiVPIEWtbtJM5vz4hFVyhBzcw+TU6kStfZO9BwWEmpts13lE1OhWr2l0/YNLooN4k8ulKd7zLPoD/vMUNiRqSNjgR71ydLAJQiPbYAqLVREnxGa/0OMmBQTjmB3U2yv/DNljBTL7FT YOU@YourMac.local

Note: This is just an example. This is not a valid public key.

The Private Key

The private key stays private. The .ssh folder in your home folder is a good place to keep it. Enter this command to see it:

$ cat ~/.ssh/id_rsa

Your private key should look something like this:

-----BEGIN RSA PRIVATE KEY-----
MIIEowIBAAKCAQEAy1jdr+ez1DWbELFFHUR2LYegzv2K5DKFrP8FXOLBNoPvH5nr
seh/EqkCgYEA6iSdXnky6ilRQe2V5e1SepzFFW4MqS9tZUyLfT+c2CS/CKjv0Xj0
wItywKAlHCdLT6kqQjH4oct86UuWJJfqTsFZz56FT/Mx94X5OEM8cRWusc1K7CRo
D3xyL23Lf6Iew0F3rRsBQ/hp93Wn7xOGwBf4kOfByhxcjoMBn1fYFN0CgYEA3lRQ
Cbsciytes2kNTkbtBub132iH4Rcd5Nc0SeoERukvd5bp8Km8ufrODS1sVXRF4eeO
4a84hoQxQje/OjXM7r1b2zcqZpcUXZd4VgjaWxJAC7PtNXvKR3ohZFdIWM247Bma
eWZvBQKBgCXMzOJVczLvoeNDFF5uL+2e4ZgXGeVjC2rJsHeM5rrcSVBYxjJsObuO
eJPLpSne8yz6A/7zFDYkakjY4Ee9cnSwCUIj22AKi1URJ8Rmv9DjJlNsr/wze+Xv
MGf2E390/Mc/4Kp5k5ChTJAlARzGoaah2O1XaazCamFYbv/79TsjZEhX2f44f1ix
D3xyL23Lf6Iew0F3rRsBQ/hp93Wn7xOGwBf4kOfByhxcjoMBn1fYFN0CgYEA3lRQ
Poc/jfx9E7Ni5x3XE8rBU+vtmDLPk64WcN1iI+8CgYEAi3Ee34Kild3hbLgHy5UY
x7jRjr+pfqCmL+v0LrVRvU+1DX0+xauZZ4ok3x8AutGUAm8moaGNBx5e17mSQ1zN
x/VSfVlU35ZgLZ92GtHAD0Dwdydh9VyBNKfSgPiMdwif9XzpvwgUKtyojx1c0/73
AzPDbtj3Clz1qlHPB4yTPWkCgYAfT+SN2kpk11DZF7yF/7s2M6UBN+mbK/RL3HtC
xbCghArpXtnHyUAJOWd3t6QATQXikQgwhMsDNu7xEoTeH+Gi5gxfzV8tX63AmKqc
A1ctaF6Yx1hrJeoRMwQs65YG28Jljh2JHOc4igzbj3Iodq1p3i5oMVwfCVjuxZ/n
7+AIAYnXO72EEjkEEKxN58w64bObz9OV+5Zite086dK/gqjB34oZbqe9PPRhKD37
XxIVO+cy7d+Py/SpoJ0uADENnJMlVaOM+K6O0yggIa+UrBAMYqQLICAeM9vGrrkm
MIIEowIBAAKCAQEAy1jdr+ez1DWbELFFHUR2LYegzv2K5DKFrP8FXOLBNoPvH5nr
4WIlTyBFrW7STOb8+IRVcoQc3MPk1OpErX2TvQcFhJqbbNd5RNToVq9pdP2DS6KD
u779fHKpFu/w6oBUVjJk7oJu9xCUnW+bEh7LpT7ZRcVZsuww8QSmuidThXjYJ9BI
3y5BB7o/viMlhPCKBAOdFJRvXeHXT/NsoSc6xwIBIwKCAQEAn1Wep1z/2wBsm9Vc
XRi9qosb3a6vgiJ1UcvI0rcGWhqdLxk5CZqHoMsMksAygLhAmupTTP2zAR0ld2Fp
FpnvUZYSDHyEnW2lewojx4qPRvTzaIavPfzVH+y9VYyyaFhCOvOGPHUClHGugkst
fuDTxUwwSmVnIbZOYG50fYcScxpOOM/s16c6LFIo3cp+Lix99qOz
-----END RSA PRIVATE KEY-----

Note: This is just an example. This is not a valid private key.

The ~/.ssh/config File

Along with your public and private keys, your .ssh folder can contain a file called config containing settings and preferences relating to your keys and servers. There are too many possible options to list here, and not every possibility is supported (or even practical) in every app.

You may need to create the config file if it doesn’t already exist.

As a basic example, here’s what you’d put in your config so that the key called exampleKey is used when connecting with the username user to the server example.com.

Host example.com
  User user
  IdentityFile "~/.ssh/exampleKey"

This is a great way to tell apps which key file goes with which server, especially if you use non-standard names for your keys, you keep your keys outside of ~/.ssh, or if you use passphrase-encrypted keys, which Coda and Transmit cannot validate.

You probably won’t ever need to touch your config file. There are a handful of special-snowflake situations where setting an option in the config file is the only way to make it work. Your server administrator can guide you if problems arise.


Using Your Keys in Panic Apps

Though all of our apps offer some level of support for key-based authentication, there are some differences from app to app in how keys are handled.

Supported Formats

Generally, our apps support ECDSA, RSA and DSA keys in PEM format.

Transmit 5 and Prompt 2 have additional support for Ed25519, ECDSA, RSA and DSA keys in OpenSSH format.

OpenSSH has deprecated the DSA public key algorithm due to its inherent weakness. DSA keys are disabled by default in macOS Sierra. We strongly recommend against using DSA keys if possible.

PuTTY/PPK

Keys in the PuTTY format (PPK) are not supported. If you have a PuTTY key, you can convert it to OpenSSH/PEM by following these instructions under the Dealing with Private Keys in Other Formats section.

The Present

We’re using an SSH library based on libssh2 and OpenSSL. This library, used in Transmit 5, Coda 2, Prompt, Transmit iOS, and Coda iOS, currently supports the following:

KexAlgorithms
diffie-hellman-group-exchange-sha1
diffie-hellman-group14-sha1
diffie-hellman-group1-sha1
diffie-hellman-group-exchange-sha256
ecdh-sha2-nistp256
ecdh-sha2-nistp384
ecdh-sha2-nistp521
Ciphers
aes128-ctr
aes192-ctr
aes256-ctr
aes128-cbc
aes192-cbc
aes256-cbc
blowfish-cbc
arcfour
arcfour128
cast128-cbc
3des-cbc
MACs
sha2-512-etm@openssh.com
sha2-512
sha2-256-etm@openssh.com
sha2-256
sha1
sha1 96
ripemd160

Beyond what libssh2 includes, we’ve added support for ECDSA and EtM. We’ll continue to refine and improve this library, and push our changes to the upstream libssh2 project.

Legacy releases

Transmit 4 and Coda 1 used the OpenSSH library built-in to Mac OS X. This means key support in Transmit 4 and Coda 1 is limited to what the OS-provided library supports.

Host Key Verification

The first time you connect to a server, we keep a local copy of the key the server uses to identify itself. On future connections, we can use this stored key to verify that the server we’re connecting to now is the same one we’ve connected to before. Without host key verification, we’d be vulnerable to man-in-the-middle attacks.

If an app warns that the host key has changed, it means this server’s key looks different from the key we stored the first time we connected to this server. If this is unexpected, you should reject the changed key, cease connecting to this server, and contact your server administrator.

In Coda iOS and Prompt, the host key fingerprint is displayed the first time you connect to a new server. You can view the fingerprint at any time from the server settings.

In Coda, Transmit, and Transmit iOS, the host key is blindly accepted on first connection, which is generally fine, but it’s something to be aware of if you’re connected to an unfamiliar local network.

To view the host key fingerprint used in Coda or Transmit, open the file ~/.ssh/known_hosts and find the line that corresponds to your server. If you need to reset the host key for a server, just remove the entire line for that server from the known_hosts file.

Advanced Features

Prompt and the terminal in Coda iOS support agent forwarding. Coda, Transmit, and Transmit iOS do not.

Port forwarding, X11 forwarding, and ProxyCommand are not currently supported.


App-Specific Notes

Coda

In the Server pane of Coda’s Site configuration sheet, there is a button with a key icon to the right of the password field. This button opens a file picker that allows you to choose a private key to use when connecting to this server. Coda automatically attempts to use any keys it finds in your .ssh folder.

When choosing a key via this button, Coda will attempt to verify the format of the key to make sure that it’s valid and supported.

If your key is encrypted with a passphrase, Coda’s key-chooser will be unable to verify it. See the config file workaround above.

If you’ve specified an encrypted key for use with this server in your config file, you can leave the key button alone and put the passphrase in Coda’s password field.

The Terminal, Source Control, and MySQL functions in Coda also support keys, but you will need to add your key to the config file.


Transmit 5

In the latest version of Transmit we’ve added the ability to store keys right in Transmit itself. Additionally, Transmit 5 still supports keys defined in in your config file.

For a more comprehensive overview of the many ways Transmit 5 can be configured to use key-based authentication please see Transmit 5 SFTP Authentication.


Transmit 4

When connecting to an SFTP server, there is a button with a key icon to the right of the password field. This button works in much the same way as the same button in Coda: it opens a file picker that allows you to choose a private key for use when connecting to this server. Transmit will automatically attempt to use any keys it finds in your .ssh folder.

When choosing a key via this button, Transmit will attempt to verify the format of the key to make sure that it’s valid and supported.

If your key is encrypted with a passphrase, Transmit’s key-chooser will be unable to verify it. See the config file workaround above.

If you’ve specified an encrypted key for use with this server in your config file, you can leave the key button alone and put the passphrase in Transmit’s password field.


Prompt

When creating a new server connection, tap the key icon next to the password field to choose a private key. If the key is encrypted with a passphrase, you can enter it when choosing the key. If you do not enter the passphrase, you will be prompted for it whenever you connect to this server.

Important! If you want to use a key with a passphrase for agent forwarding, you must enter the passphrase when adding the key to the server connection.

You can view, import, and create keys in the Keys pane of Prompt’s Settings.

To add a key for use in Prompt, open the Settings pane, tap Keys, then tap the + button at the top right of the Keys pane. You can choose to either Generate a new key, or Import an existing key.

Generate New Key

To generate a new key, tap the + button on the Keys pane of Prompt’s settings and choose Generate New Key. Choose a descriptive name for your key, and optionally set a passphrase. Choose your key type, and size. Then tap “Generate” to create your keypair. Once it’s finished generating, tap Copy Public Key to put the public key on your pasteboard. We’ll use it in the next step.

Now that you have your keypair, you’ll want to put the public key on the remote server. Usually this means this means connecting with a username and password one last time. Once connected, navigate into ~/.ssh/ on the remote server and look for a file called authorized_keys or authorized_keys2. Open that file in a text editor, and paste the public key onto the end of the file.

Import From Pasteboard

To import a key from the iOS Pasteboard, first select and copy the entire contents of the private key to the pasteboard. After the private key is on the pasteboard, go to Prompt’s Settings, tap Keys, then tap the + button and choose Import from Pasteboard. If your key is in a valid and supported format – and if it’s the private key, not the public key – Prompt will import the key for you.

Import from iTunes

Use iTunes File Sharing to import your private key. Note that Prompt does not support importing arbitrary files via iTunes File Sharing; this only works for keys.

Agent Forwarding

To enable agent forwarding in Prompt, toggle the Agent Forwarding switch in the Server settings. If your key uses a passphrase, you’ll need to have entered it when you added the key to the server entry.


Coda iOS

When creating a remote server connection in a new Site, tap the key icon next to the password field to choose a private key. If the key is encrypted with a passphrase, you can enter it when choosing the key. If you do not enter the passphrase, you will be prompted for it whenever you connect to this server.

Important! If you want to use a key with a passphrase for agent forwarding, you must enter the passphrase when adding the key to the server connection.

You can view, import, and create keys in the Keys pane of Coda’s Settings.

To add a key for use in Coda, open the Settings pane, tap Keys, then tap the + button at the top right of the Keys pane. You can choose to either Generate a new key, or Import an existing key.

Generate New Key

To generate a new key, tap the + button on the Keys pane of Coda’s settings and choose Generate New Key. Choose a descriptive name for your key, and optionally set a passphrase. Choose your key type, and size. Then tap “Generate” to create your keypair. Once it’s finished generating, tap Copy Public Key to put the public key on your pasteboard. We’ll use it in the next step.

Now that you have your keypair, you’ll want to put the public key on the remote server. Usually this means this means connecting with a username and password one last time. Once connected, navigate into ~/.ssh/ on the remote server and look for a file called authorized_keys or authorized_keys2. Open that file in a text editor, and paste the public key onto the end of the file.

Import From Pasteboard

To import a key from the iOS Pasteboard, first select and copy the entire contents of the private key to the pasteboard. After the private key is on the pasteboard, go to Coda’s Settings, tap Keys, then tap the + button and choose Import from Pasteboard. If your key is in a valid and supported format – and if it’s the private key, not the public key – Coda will import the key for you.

Import from Local

Use this option to import a private key from the Local file storage on your iOS device. One example where this is useful is if you’ve got your private key on your Mac. Use Coda to connect to your Mac on the same local network, then transfer the key into Coda’s Local file storage. Once the key is in Coda’s local file storage, it can be imported for use.

Import from iTunes

Use iTunes File Sharing to import your private key. Note that Coda does not support importing arbitrary files via iTunes File Sharing; this only works for keys.

Agent Forwarding

To enable agent forwarding in Coda iOS, toggle the Agent Forwarding switch in the Terminal pane of the Site’s settings. If your key uses a passphrase, you’ll need to have entered it when you added the key to the server entry.


Transmit iOS

When creating a new server connection, tap the key icon next to the password field to choose a private key. If the key is encrypted with a passphrase, you can enter it when choosing the key. If you do not enter the passphrase, you will be prompted for it whenever you connect to this server.

You can view, import, and create keys in the Keys pane of Transmit’s Settings.

To add a key for use in Transmit, open the Settings pane, tap Keys, then tap the + button at the top right of the Keys pane. You can choose to either Generate a new key, or Import an existing key.

Generate New Key

To generate a new key, tap the + button on the Keys pane of Transmit’s settings and choose Generate New Key. Choose a descriptive name for your key, and optionally set a passphrase. Choose your key type (we recommend RSA), and size (we recommend 2048 or 4096). Then tap “Generate” to create your keypair. Once it’s finished generating, tap Copy Public Key to put the public key on your pasteboard. We’ll use it in the next step.

Now that you have your keypair, you’ll want to put the public key on the remote server. Usually this means this means connecting with a username and password one last time. Once connected, navigate into ~/.ssh/ on the remote server and look for a file called authorized_keys or authorized_keys2. Open that file in a text editor, and paste the public key onto the end of the file.

Import From Pasteboard

To import a key from the iOS Pasteboard, first select and copy the entire contents of the private key to the pasteboard. After the private key is on the pasteboard, go to Transmit’s Settings, tap Keys, then tap the + button and choose Import from Pasteboard. If your key is in a valid and supported format – and if it’s the private key, not the public key – Transmit will import the key for you.

Import from Local

Use this option to import a private key from the Local file storage on your iOS device. One example where this is useful is if you’ve got your private key on your Mac. Use Transmit to connect to your Mac on the same local network, then transfer the key into Transmit’s Local file storage. Once the key is in Transmit’s local file storage, it can be imported for use in Transmit.

Import from iTunes

Use iTunes File Sharing to import your private key. Note that Transmit does not support importing arbitrary files via iTunes File Sharing; this only works for keys.


Troubleshooting

Why does it say my key is not in a supported format?

The most common reason you’d see this error is if you select a passphrase-encrypted key via the key chooser button in either Coda or Transmit on macOS. Coda and Transmit want to validate the key before letting you use it, but the encryption prevents that from happening. (Admittedly, this is not ideal, and should be improved.)

As a workaround, add your key to the ~/.ssh/config file, skip the key button altogether, and put the passphrase in the password field.

You’ll also get this error if you use a key in an unsupported format, such as a PuTTy key. Make sure you’re using a supported key.

Why can’t I import my key from the pasteboard?

Most of the time this is a format issue. Are you sure you’re using a supported key?

Double-check that it’s the private key, not the public key. They look different (see the above sections on each), so it should be easy to tell.

One particularly nasty gotcha to watch out for involves the text substitution feature of macOS. For example, let’s say you copy and paste the contents of your private key somewhere easily accessible from your iOS device. You might notice that macOS has helpfully changed runs of hyphens (----) into em-dashes (––).

Your private key used to look like this:

-----BEGIN RSA PRIVATE KEY-----
MIIEowIBAAKCAQEAy1jdr+ez1DWbELFFHUR2LYegzv2K5DKFrP8FXOLBNoPvH5nr
seh/EqkCgYEA6iSdXnky6ilRQe2V5e1SepzFFW4MqS9tZUyLfT+c2CS/CKjv0Xj0
<snip>

But it now looks like this:

–––BEGIN RSA PRIVATE KEY–––
MIIEowIBAAKCAQEAy1jdr+ez1DWbELFFHUR2LYegzv2K5DKFrP8FXOLBNoPvH5nr
seh/EqkCgYEA6iSdXnky6ilRQe2V5e1SepzFFW4MqS9tZUyLfT+c2CS/CKjv0Xj0
<snip>

It’s a subtle difference, but it’s enough to break your key. Watch out!