Many apps and services rely on secrets. Your browser needs access to the passwords you need to log into online services, for example, and other apps have to handle their own protected data. If you had to remember all those passwords and enter them manually, then you’d need a long written list, and the passwords you’d use would have to be easy to recall and type in. Way back in the days of Classic Mac OS, Apple decided to provide system-level support for the secure storage of passwords, making it far easier to manage and use unguessable passwords, by storing them in a secure database, the keychain.

From the moment you log into your Mac until you log out again (and, for some services, even when there’s no user logged in at all), it depends on keychains, generally kept in Keychains folders in each of its Library folders. Keychains are used to store, access and manage secrets, including passwords for various purposes, security certificates, private keys, passkeys, and secure notes.

Until OS X 10.9 when iCloud keychains were introduced to Macs, all its keychains were based on files, and the master is the keychain opened automatically at login, the login keychain. iOS devices have always been different; for a start, while Macs have multiple keychains, iOS only has one, and from the outset that single keychain is designed to be stored in iCloud and protected by the Secure Enclave. Apple refers to these two types as file-based and Data Protection keychains.

login keychain

For each user, their default personal file-based keychain is the login keychain, located in ~/Library/Keychains/login.keychain-db. This is unlocked automatically when the user logs in as it has the same password as that user account. It’s here that each user should store their certificates, secure notes, etc. for general use.

Although kept unlocked, readable and writeable while the user is logged in, that doesn’t guarantee access to its contents. If an app makes a call to the macOS security system to retrieve a stored password for its use, that system determines whether the app is trusted to access that information, and whether that keychain is locked. Assuming the password is stored there, the app is trusted, and the keychain is unlocked, then the password is retrieved and passed back to the app. If the app isn’t trusted or the keychain is locked, then the security system, not the app, displays a dialog asking for the password to that keychain to authenticate before it will provide the password to the app.

The user cannot determine which apps are trusted, as far as the security system is concerned. Those are determined by the security system, the specific access it grants to an app, and to individual items in that user’s keychain. At its most restrictive, the system can limit all other apps from accessing a particular secret in the keychain, but specific secrets can also be shared across several different apps.

System keychains

For the system, there are two vital groups of keychains:

• in /System/Library/Keychains, in the SSV, is SystemRootCertificates and others providing the set of root security certificates for that version of macOS;
• in /Library/Keychains is the System keychain and others providing certificates and passwords required for all users, including those to gain access to that Mac’s Wi-Fi connections.

Custom keychains

Apps and users are also able to create their own keychains. Among those I have on my Macs are shared keychains with Parallels virtual machines, several for Microsoft apps, and some for Adobe’s products. I also tend to make a copy of the login keychain from my last Mac and copy it across under another name to ~/Library/Keychains, so that if I happen to have left any important certificates or passwords behind when migrating to a new Mac, I should be able to find them there.

Although these additional keychains may be included in the keychain search path, when macOS is looking for a secret kept in a keychain, unlike the login keychain they’re normally kept locked. If I or an app want access to them, I’ll be prompted for that keychain’s password. For old login keychains, that’s just my old login password from that Mac, of course.

Data Protection keychain

Since OS X 10.9, Macs have also had one and only one Data Protection keychain that’s accessed using a different API. If you share your keychain in iCloud, this is the local copy of that shared keychain and is known as iCloud Keychain; if you don’t share it in iCloud, then it’s known as Local Items instead. The local copy of this is normally stored in ~/Library/Keychains/[UUID]/keychain-2.db, where the UUID is that assigned to that Mac.

The Data Protection keychain stores all the standard types of secret, including internet and other passwords, certificates, keys and passkeys, although it isn’t normally used for secure notes. Prior to macOS 11, it only synchronised internet passwords using iCloud, but from Big Sur onwards it synchronises all its content, including passkeys. Unlike file-based keychains, secrets in the Data Protection keychain can be protected by the Secure Enclave, and can therefore be protected by biometrics including Touch ID (and, on iOS and iPadOS, Face ID). Hence they are required for passkeys, which don’t appear to be supported by traditional file-based keychains.

Tools

The bundled tool for working with keychains is the Keychain Access app, in /Applications/Utilities, and some of the features of the command tool security. A few third-party utilities, including my own free Mints, give additional information that can be helpful in resolving keychain problems. However, those are largely based on the APIs for working with file-based keychains, and have limited abilities when working with Data Protection keychains. For instance, Keychain Access can only display and work with password items in iCloud and Local Items Keychains, and can’t provide any access to certificates, keys or passkeys held there, although I’m not aware that Apple documents this in the app’s Help book, or in man security. Currently, Apple doesn’t appear to provide any command tool that works fully with Data Protection keychains, and that appears intentional.

The best way to work with passwords and passkeys stored in a Data Protection keychain is in the Passwords section of System Settings, or its equivalent in Safari’s Settings.

Future

Currently macOS still supports keychains in their original Classic Mac OS format, and file-based keychains remain widely used. As they can never provide the same level of security as Data Protection keychains, and can’t benefit from biometrics or the Secure Enclave, Apple is keen to move on to Data Protection keychains as much as possible. It even states that “the file-based keychain is on the road to deprecation. It’s not officially deprecated, but some of the APIs surrounding it are.” That road stretches long ahead, though, as it requires every app that relies on keychains to adopt the new API, and complete reliability.

Apple also has one significant problem to solve: code such as LaunchDaemons and LaunchAgents that don’t run in a user context, but through launchd, can’t currently access a Data Protection keychain, and must rely on file-based keychains. Traditional keychains aren’t going away yet.

References

Apple TN3137: On Mac keychain APIs and implementations
Apple Platform Security Guide
Apple Keychain Services