Nicolas Mattia – Organising SSH keys on macOS with Touch ID

October 19, 2026

---

In the primary a part of this put up I’ll present a easy, safe approach to create an SSH key on Mac (it’s 3 instructions, together with help for GitHub). In the second half I’ll dig deeper and clarify what’s really occurring for the curious reader.

Macs have a built-in so-called Secure Enclave, the place we will create “identities” that merely can’t be stolen (until possibly you’ve made enemies with a nation state). Those identities are protected with Touch ID and can be utilized for SSH authentication. There are some nice advantages about utilizing this over conventional SSH key recordsdata:

• The personal materials can’t be extracted, is rarely proven, can’t be stolen,
• You get prompted every time the identification is used,
• No key recordsdata (like ~/.ssh/id_ed25519.pub and buddies) littering the file system; and there’s no threat of mistakenly deleting them both.

This further safety shall be in impact everytime you use SSH, together with git-over-ssh like GitHub. It’s nice that superior safety tech is obtainable by default on among the most generally distributed computer systems within the globe! Just a few years in the past stuff like this might solely be discovered at CERN and/or in Dan Brown novels. Let’s see how it may be arrange in your consumer-grade Mac.

It is important that the human interface be designed for ease of use, in order that customers routinely and routinely apply the safety mechanisms accurately.

• Saltzer and Schroeder, “The Protection of Information in Computer Systems”

Quick Setup

We’ll create a safe identification on the Secure Enclave, then inform SSH how one can use it for authentication, and at last add the important thing to GitHub.

Step 1: create the identification that you just’ll use on this Mac:

sc_auth create-ctk-identity -l ssh-key -k p-256-ne -t bio # run as soon as to create identification

You’ll be prompted to the touch “Touch ID”. Your identification is now created and saved securely (parameters are defined within the deep dive under).

Step 2: inform SSH to make use of the identification (when prompted for a PIN, simply hit enter):

ssh-add -Okay -S /usr/lib/ssh-keychain.dylib # run after a reboot

From right here on, SSH will know to make use of the identification from the Secure Enclave when connecting by way of SSH; it doesn’t have a great reminiscence so that you’ll have to remind it after a reboot.

Step 3: Whenever you should register your key to a brand new server (like GitHub), run this command:

ssh-add -L # run if you want the general public key

If a number of identities are listed, use the road that begins with sk-ecdsa-sha2-nistp256.... It’s a shareable deal with for the identification, and that is the SSH key that GitHub will ask about.

The output of ssh-add -L will be added as a GitHub SSH Key

That’s all you want for an excellent safe setup! The new identification can now be used with SSH, and also you’ll be prompted for Touch ID throughout authentication:

git push # triggers Touch ID immediate

No one can steal your identification (nicely, you may’t even give it away willingly since it could’t be extracted from the Secure Enclave), however with nice powers and so on: in case your Mac dies, so does the identification, and also you’ll have to create a brand new one (and re-register it the place crucial, like GitHub).

You’ll get a Touch ID immediate when git tries to authenticate with SSH

If you’re interested by how this works, learn on!

Under the hood

We’ll now attempt to perceive what occurs beneath the hood. We’ll begin with the precise identification creation within the Secure Enclave, then have a look at how SSH is allowed to interface with the Secure Enclave with ssh-keychain.dylib, after which attempt to see what occurs in an entire SSH sign-in circulation.

This is the results of studying posts (like this great investigation by arianvp), guide pages, and experimentation. A whole lot of that is undocumented, and that is the minimal data I wanted to kind a psychological mannequin of what’s occurring and persuade myself that it does, certainly, work.

Some of the command outputs under have been trimmed for legibility, I invite you to run them domestically if you need the complete expertise!

Creating an identification on the Secure Enclave

Identities are managed with the sc_auth command (the place sc_ stands for Smart Card). In Apple-speak, they’re “CryptoTokenKit” identities, or CTK identities for brief. Why not Smart Card Identities? What is a Smart Card? No concept! There’s lots of bizarre Apple vocabulary, however in observe they’re simply personal keys saved 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 adopted alongside within the Quick Setup, it is best to have precisely one identification right here, that was created if you ran the sc_auth create-ctk-identity command. Let’s have a look at the create-ctk-identity command in additional element:

sc_auth create-ctk-identity -l  -k  -t 

When utilizing the p-256-ne key sort, this command creates the identification on the Secure Enclave — I’m guessing by first gathering some entropy, then producing some personal key materials and allocating no matter it wants for bookkeeping and making certain it could solely be accessed together with your fingerprint.

The label is freeform and only a be aware hooked up to the important thing. The key sort is a cryptographic setting (the elliptic curve used). At the time of writing, the next values are accepted: p-256|p-384|p-521|p-256-ne|p-384-ne. The -ne suffix means “Non-Extractable”, which means the bottom line is generated by the enclave itself and can not be extracted from the Secure Enclave. For SSH we solely want signing, which is finished by (and on) the Secure Enclave itself, and at no level do we’d like (or need) to export the personal key. The p-384 curve will not be supported by (Open)SSH, so this narrows it all the way down to p-256-ne.

Finally, safety will be both bio or none. When set to bio, utilizing the important thing requires biometrics (like Touch ID). With none, the important thing nonetheless can’t be extracted (i.e. stolen) however applications would be capable of silently use SSH; I like to recommend utilizing bio, however YMMV; when you get irritated by the Touch ID prompts everytime you git pull, you would possibly need to use none right here.

Now that we’ve got some elusive identification on the Secure Enclave, let’s see how we will inform SSH to make use of it for authentication.

Translating between SSH and the Secure Enclave

There’s a little bit of impedance mismatch, and ssh doesn’t know how one can use the identification by default:

$ ssh -T [email protected]
[email protected]: Permission denied (publickey).

The SSH agent can not use the Secure Enclave identities as-is, however Apple has us coated with a small translation layer within the type of ssh-keychain.dylib, a dlopen-able library accessible natively on all current macOS variations:

$ ssh-add -Okay -S /usr/lib/ssh-keychain.dylib
...
Resident identification added: ECDSA-SK SHA256:QZ+Cx6/AkS9sek9INtsXt6t7wuHOtA555CLJu8a8V7w

Here we’re counting on ssh-add’s built-in help for FIDO-style authenticator by way of the -Okay parameter. This lets the SSH agent know that it shouldn’t learn an ordinary personal key (as an example ~/.ssh/id_ed25519) however that it ought to count on the keys to be saved “externally” (for an absence of higher phrases). With -Okay alone, ssh-add would search for public keys on USB units (assume YubiKey); although we will customise this habits by registering a “safety key supplier” with -S . This supplier needs to be a stateless dynamically-loadable library, which is precisely what /usr/lib/ssh-keychain.dylib is. The interface will not be documented (at the least not in a manner I used to be in a position to meaningfully course of), however we will take a look at what ssh-keychain.dylib exposes:

$ dyld_info -exports /usr/lib/ssh-keychain.dylib
/usr/lib/ssh-keychain.dylib:
    -exports:
        offset      image
        0x00001A2C  _C_GetFunctionList
        0x00000F30  _sk_api_version
        0x00000F38  _sk_enroll
        0x0000136C  _sk_load_resident_keys
        0x00000F40  _sk_sign

Most doubtless, _sk_load_resident_keys is supposed to return an inventory of (public keys of) identities, and _sk_sign will signal a payload utilizing a specified identification (right here, resident means “residing on e.g. the Secure Enclave”).

We’ve seen how the identities will be created on the Secure Enclave, and the way they’ll, in principle, be utilized by the SSH agent. Let’s put this to the check and see what occurs when an SSH connection is created.

SSH Sign-in circulation with the ssh-keychain supplier

Let’s see what we’d like for authenticating to a distant SSH server. At all occasions, the SSH agent wants (1) an inventory of (public) keys that can be utilized to authenticate, and (2) a approach to show to a server that it has the corresponding personal key for any of these keys.

When ssh-add is first referred to as with -S , the _sk_load_resident_keys routine is known as, which returns the general public keys of all resident keys on the FIDO-style authenticator. Those are saved within the SSH agent (alongside their corresponding supplier, specifically ssh-keychain.dylib) and can later be provided as candidates to any distant SSH server we strive connecting to. (Also now that the SSH agent is aware of concerning the Secure Enclave identification we created earlier, we will view its SSH-style public key with ssh-add -L.)

Let’s say an SSH connection is initiated: the distant accepts a kind of public keys provided by the agent and “challenges” the shopper to show its identification. The agent calls _sk_sign to create a signature with the personal key (matching the accepted public key) and the problem (roughly talking). This shall be forwarded to the Secure Enclave, immediate Touch ID, and if authorized, will return a signature for the problem. The signature is forwarded again to the server, which may affirm we — the shopper — have the corresponding personal key.

Let’s see what this seems like in observe:

$ ssh -T [email protected]
[email protected]: Permission denied (publickey).
$ ssh-add -Okay -S /usr/lib/ssh-keychain.dylib
Enter PIN for authenticator:
Resident identification 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
debug3: sign_and_send_pubkey: signing utilizing [email protected] SHA256:QZ+Cx6/AkS9sek9INtsXt6t7wuHOtA555CLJu8a8V7w

Authenticated to github.com ([20.250.119.67]:22) utilizing "publickey".
Hi nmattia! You've efficiently authenticated, however GitHub doesn't present shell entry.

The ssh debug logs present that one key’s provided by the agent, accepted, after which used to create a signature. After the server has verified the signature, authentication is granted (though GitHub doesn't present shell entry).

One be aware: every time we register the identification with the SSH agent, ssh-add prompts us for a PIN. What offers? Why does getting into an empty PIN work, isn’t this mighty unsafe‽

Well, no, it’s not unsafe! When we inform ssh-add to make use of a FIDO-style authenticator, I think its default habits is to ask for a PIN because it assumes we’ll be utilizing a USB, YubiKey-style authenticator; solely we shortcut the entire thing with ssh-keychain.dylib (and the safety comes not from a PIN, however from the smooth pores and skin beneath your fingertips; a lot cooler). Not nice by way of usability, however I suppose it is sensible. (I do not know what would occur when you have multiple FIDO authenticator; go support me on GitHub and I’ll purchase a set of YubiKeys to experiment).

Conclusion

Let’s recap: we will use a considerably cryptic, poorly documented “Smart Card” software to create a “CryptoTokenKit” identification on the “Secure Enclave”. Then, through the use of the poorly documented ssh-keychain.dylib, we will use stated identification to generate signatures that Apple’s ssh can use. There’s no assure that every one this lacking documentation wouldn’t say “Do not use this; terribly unsafe in observe”, however hey: all this safety speak by Apple, they wouldn’t mislead us, proper? *spooky*

Joke apart, it’s fairly cool to have sci-fi model safety modules baked into most fashionable units; the extra folks begin utilizing them and pushing for openness, the higher the help from the businesses shall be. We can have good issues!

Again, lots of this was derived from this gist; extremely advocate having a learn and probably asking questions within the dialogue.

Let me knoworjoin the discussion when you loved this text! You can even subscribe to obtain updates.

---

Here’s extra on the subject of macOS: