Setting up SSH keys on macOS with Touch ID In the first part of this post I’ll show a simple, secure way to create an SSH key on Mac (it’s 3 commands, including support for GitHub). In the second part I’ll dig deeper and explain what’s actually happening for the curious reader. Macs have a built-in so-called Secure Enclave, where we can create “identities” that simply cannot be stolen (unless maybe you’ve made enemies with a nation state). Those identities are protected with Touch ID and can be used for SSH authentication. There are some great benefits about using this over traditional SSH key files: The private material cannot be extracted, is never shown, cannot be stolen, You get prompted whenever the identity is used, No key files (like ~/.ssh/id_ed25519.pub and friends) littering the file system; and there’s no risk of mistakenly deleting them either. This extra security will be in effect whenever you use SSH, including git-over-ssh like GitHub. It’s great that advanced security tech is available by default on some of the most widely distributed computers in the world! A few years ago stuff like this could only be found at CERN and/or in Dan Brown novels. Let’s see how it can be set up on your consumer-grade Mac. It is essential that the human interface be designed for ease of use, so that users routinely and automatically apply the protection mechanisms correctly. Saltzer and Schroeder, “The Protection of Information in Computer Systems” It is essential that the human interface be designed for ease of use, so that users routinely and automatically apply the protection mechanisms correctly. Saltzer and Schroeder, “The Protection of Information in Computer Systems” Quick Setup We’ll create a secure identity on the Secure Enclave, then tell SSH how to use it for authentication, and finally add the key to GitHub. Step 1: create the identity that you’ll use on this Mac: sc_auth create-ctk-identity -l ssh-key -k p-256-ne -t bio # run once to create identity You’ll be prompted to touch “Touch ID”. Your identity is now created and saved securely (parameters are explained in the deep dive below). Step 2: tell SSH to use the identity (when prompted for a PIN, just hit enter): ssh-add -K -S /usr/lib/ssh-keychain.dylib # run after a reboot From here on, SSH will know to use the identity from the Secure Enclave when connecting via SSH; it does not have a good memory so you’ll need to remind it after a reboot. Step 3: Whenever you need to register your key to a new server (like GitHub), run this command: ssh-add -L # run when you need the public key If multiple identities are listed, use the line that starts with sk-ecdsa-sha2-nistp256.... It’s a shareable handle for the identity, and this is the SSH key that GitHub will ask about. The output of ssh-add -L can be added as a GitHub SSH Key That’s all you need for a super secure setup! The new identity can now be used with SSH, and you’ll be prompted for Touch ID during authentication: git push # triggers Touch ID prompt No one can steal your identity (well, you can’t even give it away willingly since it can’t be extracted from the Secure Enclave), but with great powers etc: if your Mac dies, so does the identity, and you’ll need to create a new one (and re-register it where necessary, like GitHub). You’ll get a Touch ID prompt when git tries to authenticate with SSH If you’re curious about how this works, read on! Under the hood We’ll now try to understand what happens under the hood. We’ll start with the actual identity creation in the Secure Enclave, then look at how SSH is allowed to interface with the Secure Enclave with ssh-keychain.dylib, and then try to see what happens in a complete SSH sign-in flow. This is the result of reading posts (like this great investigation by arianvp), manual pages, and experimentation. A lot of this is undocumented, and this is the minimum information I needed to form a mental model of what’s happening and convince myself that it does, indeed, work. Note Some of the command outputs below have been trimmed for legibility, I invite you to run them locally if you want the full experience! Some of the command outputs below have been trimmed for legibility, I invite you to run them locally if you want the full experience! Creating an identity on the Secure Enclave Identities are managed with the sc_auth command (where sc_ stands for Smart Card). In Apple-speak, they are “CryptoTokenKit” identities, or CTK identities for short. Why not Smart Card Identities? What is a Smart Card? No idea! There’s a lot of weird Apple vocabulary, but in practice they’re just private keys stored on the Secure Enclave: $ sc_auth list-ctk-identities Key Type Public Key Hash Prot Label p-256-ne 458F712F281B53C683F23FC02E69D44DAFDAA3DE bio ssh-key If you followed along in the Quick Setup, you should have exactly one identity here, that was created when you ran the sc_auth create-ctk-identity command. Let’s look at the create-ctk-identity command in more detail: sc_auth create-ctk-identity -l