Cloud services, such as iCloud, are very convenient until there’s a problem. Then your lack of knowledge about and control over them turns them into a nightmare.

This is most severe and significant when dealing with iCloud Keychain (iCK): much of the time, it is gloriously transparent to the user, and you can switch between Macs, iPhones, iPads, and more without worrying about copying passwords or Wi-Fi connections between devices. But when something does go wrong, there seems nothing that you can do about it apart from going back to square one and entering all those details again.

To get a better understanding of how iCK works, I have been exploring it using my log browsers Consolation and Woodpile, and my new keychain tool KeychainCheck 2, in Sierra and High Sierra. The results may appear surprising.

Keychains

Most significantly, using iCK doesn’t change what keychains are where on your Mac. The default or login keychain remains login.keychain-db in the Keychains folder of your Home folder’s Library. It locks and unlocks just like it did before. The normal search path should include that, and your System keychain at /Library/Keychains/System.keychain.

This is important, because provided you maintain and back up your login keychain, it means that you will have access to its contents should you need them in an emergency.

iCloud virtual keychain

iCK creates an additional and virtual keychain, which it presents to Keychain Access as the iCloud keychain. This is in fact composed from a bunch of files stored in an extra folder in ~/Library/Keychains, with your Mac’s hardware UUID (listed in System Information) as its name. If you turn iCK off, and choose to save its contents locally, these files are updated and then presented as Local Items in Keychain Access. This explains where your Mac obtains Local Items from: it is not a regular keychain, but the frozen local copy of your last iCK.

iCK isn’t a complete virtual keychain, in that it includes only website user names and passwords, credit card information, and Wi-Fi connection details. It won’t store certificates, for example, which still have to be installed in a regular keychain such as login.

When you’re using local keychains, with iCK turned off, any changes to your keychain, such as an update to a password, are made in your local keychain, commonly the default, and reflected immediately there. Apps which depend on keychain information, such as Safari, install a special notification, so that they are told of such changes and respond to them.

When iCK is turned on, any change to the iCloud keychain is relayed to the iCK server, which then pushes that change out to all other Macs and devices which are sharing the same iCK. This ensures that all devices on the same iCK have the same keychain information.

Push services have a topic assigned to them so that the system which receives them knows what to do with them; for iCK, the topic is com.apple.private.alloy.keychainsync, and keychain synchronisation is handled by an ‘escrow proxy’ HTTPS server at p43-escrowproxy.icloud.com port 443.

iCK can keep a full copy of its keychain in iCloud, which Apple can use for recovery in the event of disaster. However, this only applies to iCK created using an iCloud Security Code. Users who have two-factor authentication for their Apple ID are not given that option: their only copies of the iCloud keychain are stored locally on each device sharing the same iCK. If you were offered an iCloud Security Code when enabling iCK but chose not to create one, then no copy of your keychain is kept in iCloud either.

For the great majority of users, who have enabled two-factor authentication, iCloud doesn’t keep a copy of the iCK itself, it only exists in the local copies on those devices which share it. Neither does iCloud store copies of your login keychains: that is something which you need to do using Time Machine or another backup system.

Full details about all these nuances are in Apple’s Q&A on iCK, which has been recently updated.

Apple also explains briefly how to import and export individual items from keychains in this article, and how to move complete keychains in this article.

Turning iCK on

When you turn iCK on, several macOS services swing into action, most with names that mean nothing to anyone outside Apple: CoreCDP, AOSAccounts, and the like. The message
account appleid@me.com service com.apple.Dataclass.KeychainSync enableState 0 enabledDataclasses
is sent, and
"com.apple.Dataclass.KeychainSync" = {
authMechanism = token;
escrowProxyUrl = "https://p43-escrowproxy.icloud.com:443";
};
added to your iCloud account, somewhat oddly via the Calendar accounts notification system. This gets listed with all the other iCloud services you have enabled in huge log messages with four hundred or more lines. Once this is set up, AOSAccounts confirms that com.apple.Dataclass.KeychainSync has been added to your list of services.

IDS Transport next lists all the devices associated with your Apple ID, with their UUID and push token. The push service is set up for the keychain sync topic, and your Mac’s apsd service will then start getting push messages for that topic with payloads for iCK. This is followed by an intense burst of activity either setting up or updating the local iCK files. Eventually, after several thousand log entries, this activity settles, and iCK just gets on with its job.

Important lessons

If you have iCK enabled on a Mac or another device and run into problems, the best immediate action is to take the affected system(s) off iCK as quickly as you can. Don’t start trying to fix the problem, and don’t even think about using Keychain Access or other tools, until all affected keychains are local. Until you have done that, any changes made on one system will be rapidly propagated to all the others on iCK.

Ensure that you keep good backups of all user keychains, and the iCK folder in ~/Library/Keychains. Restoring from those backups isn’t particularly reliable, but can’t even be attempted while iCK is still enabled.

Losing your iCK is messy and a pain, but if you keep your login keychain updated with all important details, and properly backed-up, it shouldn’t be a big loss. Losing your login keychain is much more likely to be disastrous, particularly if you don’t have a recent backup.

If you have got keychain problems, don’t rush at them and make things worse. Think logically and carefully, and think through any actions and their consequences before you try them. Remember that iCK mainly stores convenience items, not important certificates and the like, which will be in a local keychain, normally login. Don’t put that at risk to try to save information of lesser value.