SSH private keys come in two shapes you are likely to meet: the OpenSSH format, usually saved as .pem, and PuTTY’s own .ppk.
The short answer: on a Mac, install PuTTYgen with brew install putty, then use puttygen key.pem -o key.ppk to go from .pem to .ppk and puttygen key.ppk -O private-openssh -o key.pem to go back.
There is one catch. Since PuTTY 0.75, PuTTYgen writes PPK version 3 by default, and older tools reject it with “PuTTY key format too new”. This article includes the way around that.
Sponsored
Which format do you actually need?
The short answer: the ssh command on macOS and Linux reads OpenSSH format directly. You only need .ppk for PuTTY or WinSCP on Windows.
| Format | Used by | On a Mac |
|---|---|---|
.pem (OpenSSH format) |
The ssh command, AWS EC2 key pairs, most CI tools | Works as is |
.ppk (PuTTY format) |
PuTTY, WinSCP, some FileZilla setups | Needs conversion |
The conversion comes up when a handover leaves you with only a .ppk, or when you have to hand a .ppk to someone on Windows.
How do you install PuTTYgen on a Mac?
The short answer: use Homebrew. The PuTTYgen on the PuTTY website is a Windows GUI application and will not run on macOS.
brew install putty
puttygen --version
If brew is not available yet, set up Homebrew first; the steps are in installing Homebrew and Vim on a Mac.
The putty formula includes plink and pscp alongside puttygen. Note that pscp conflicts with the pssh package, so if you have both you will need brew link to switch between them.
Sponsored
Converting .pem to .ppk
The short answer: run puttygen source.pem -o output.ppk. PPK is the default output format, so no type flag is needed.
puttygen key.pem -o key.ppk
Replace key.pem with your filename. The original is left untouched and a new key.ppk is created.
If the source key has a passphrase, you will be prompted for it.
Fixing “PuTTY key format too new”
The short answer: PuTTYgen from PuTTY 0.75 (released 2021) writes PPK version 3 by default, and older PuTTY, WinSCP and some CI tools cannot read it.
The error looks like: Unable to load key file "key.ppk" (PuTTY key format too new). Write version 2 instead.
puttygen key.pem -O private --ppk-param version=2 -o key.ppk
PPK version 3 uses the Argon2 key derivation function to make passphrase brute-forcing harder, and moves the MAC hash from SHA-1 to SHA-256. If the receiving tool supports version 3, leave it there. Drop to version 2 only when something actually fails to read it.
Converting .ppk to .pem
The short answer: run puttygen source.ppk -O private-openssh -o output.pem. The -O private-openssh flag is the important part.
puttygen key.ppk -O private-openssh -o key.pem
Omit -O and you get a PPK-format file that merely has a .pem extension. When ssh refuses to read the result, check this first.
For the newer OpenSSH key format, use private-openssh-new.
puttygen key.ppk -O private-openssh-new -o key.pem
Sponsored
Set the converted key to permission 400
The short answer: a freshly converted key can be readable by other users, and ssh will refuse to connect. Run chmod 400.
chmod 400 key.pem
ssh -i key.pem user@server-address
With loose permissions you get this and the connection stops.
WARNING: UNPROTECTED PRIVATE KEY FILE!
Permissions 0644 for 'key.pem' are too open.
Do not share the converted key
The short answer: a converted private key is still a private key. Do not send it over chat or email.
.pem and .ppk are different containers holding the same secret. Changing the format changes nothing about how sensitive it is.
What you normally hand to someone else is the public key. You can extract it like this.
puttygen key.ppk -O public-openssh -o key.pub
If you are setting up key authentication in order to deploy, creating a password-protected ZIP on macOS covers a related question of how to move sensitive files around safely.
