Nicolas Mattia – Setting up SSH keys on macOS with Touch ID

October 19, 2026In 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” 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. 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 <label> -k <key type> -t <protection> When using the p-256-ne key type, this command creates the identity on the Secure Enclave — I’m guessing by first gathering some entropy, then generating some private key material and allocating whatever it needs for bookkeeping and ensuring it can only be accessed with your fingerprint. The label is freeform and just a note attached to the key. The key type is a cryptographic setting (the elliptic curve used). At the time of writing, the following values are accepted: p-256|p-384|p-521|p-256-ne|p-384-ne. The -ne suffix means “Non-Extractable”, meaning the key is generated by the enclave itself and cannot be extracted from the Secure Enclave. For SSH we only need signing, which is done by (and on) the Secure Enclave itself, and at no point do we need (or want) to export the private key. The p-384 curve is not supported by (Open)SSH, so this narrows it down to p-256-ne. Finally, protection can be either bio or none. When set to bio, using the key requires biometrics (like Touch ID). With none, the key still cannot be extracted (i.e. stolen) but programs would be able to silently use SSH; I recommend using bio, but YMMV; if you get annoyed by the Touch ID prompts whenever you git pull, you might want to use none here. Now that we have some elusive identity on the Secure Enclave, let’s see how we can tell SSH to use it for authentication. Translating between SSH and the Secure Enclave There’s a bit of impedance mismatch, and ssh doesn’t know how to use the identity by default: $ ssh -T [email protected] [email protected]: Permission denied (publickey). The SSH agent cannot use the Secure Enclave identities as-is, but Apple has us covered with a small translation layer in the form of ssh-keychain.dylib, a dlopen-able library available natively on all recent macOS versions: $ ssh-add -K -S /usr/lib/ssh-keychain.dylib ... Resident identity added: ECDSA-SK SHA256:QZ+Cx6/AkS9sek9INtsXt6t7wuHOtA555CLJu8a8V7w Here we’re relying on ssh-add’s built-in support for FIDO-style authenticator via the -K parameter. This lets the SSH agent know that it shouldn’t read a standard private key (for instance ~/.ssh/id_ed25519) but that it should expect the keys to be stored “externally” (for a lack of better words). With -K alone, ssh-add would look for public keys on USB devices (think YubiKey); though we can customize this behavior by registering a “security key provider” with -S <provider>. This provider should be a stateless dynamically-loadable library, which is exactly what /usr/lib/ssh-keychain.dylib is. The interface is not documented (at least not in a way I was able to meaningfully process), but we can have a look at what ssh-keychain.dylib exposes: $ dyld_info -exports /usr/lib/ssh-keychain.dylib /usr/lib/ssh-keychain.dylib: -exports: offset symbol 0x00001A2C _C_GetFunctionList 0x00000F30 _sk_api_version 0x00000F38 _sk_enroll 0x0000136C _sk_load_resident_keys 0x00000F40 _sk_sign Most likely, _sk_load_resident_keys is meant to return a list of (public keys of) identities, and _sk_sign will sign a payload using a specified identity (here, resident means “residing on e.g. the Secure Enclave”). We’ve seen how the identities can be created on the Secure Enclave, and how they can, in theory, be used by the SSH agent. Let’s put this to the test and see what happens when an SSH connection is created. SSH Sign-in flow with the ssh-keychain provider Let’s see what we need for authenticating to a remote SSH server. At all times, the SSH agent needs (1) a list of (public) keys that can be used to authenticate, and (2) a way to prove to a server that it has the corresponding private key for any of those keys. When ssh-add is first called with -S <provider>, the _sk_load_resident_keys routine is called, which returns the public keys of all resident keys on the FIDO-style authenticator. Those are stored in the SSH agent (alongside their corresponding provider, namely ssh-keychain.dylib) and will later be offered as candidates to any remote SSH server we try connecting to. (Also now that the SSH agent knows about the Secure Enclave identity we created earlier, we can view its SSH-style public key with ssh-add -L.) Let’s say an SSH connection is initiated: the remote accepts one of those public keys offered by the agent and “challenges” the client to prove its identity. The agent calls _sk_sign to create a signature with the private key (matching the accepted public key) and the challenge (roughly speaking). This will be forwarded to the Secure Enclave, prompt Touch ID, and if approved, will return a signature for the challenge. The signature is forwarded back to the server, which can confirm we — the client — have the corresponding private key. Let’s see what this looks like in practice: $ ssh -T [email protected] [email protected]: Permission denied (publickey). $ ssh-add -K -S /usr/lib/ssh-keychain.dylib Enter PIN for authenticator: Resident identity added: ... $ ssh -vvv -T [email protected] debug1: get_agent_identities: agent returned 1 keys debug1: Offering public key: ssh: ECDSA-SK SHA256:QZ+Cx6/AkS9sek9INtsXt6t7wuHOtA555CLJu8a8V7w authenticator agent debug1: Server accepts key: ssh: ECDSA-SK SHA256:QZ+Cx6/AkS9sek9INtsXt6t7wuHOtA555CLJu8a8V7w authenticator agent