Accessing the Keychain

The Keychain is a Mac feature used for storing account passwords for applications. By taking advantage of the keychain, your users do not have to type their password if their keychain is unlocked on their system.

Use the Keychain class to access Mac Keychains for your applications. The classes are: Keychain, KeychainItem and KeychainException.

You should always ask for permission from the user before storing anything in a keychain. You use the System module to get a reference to the default Keychain. You use the KeychainItem class to create, update or find items in the Keychain. If you have more than one Keychain, then you can use the KeyChain constructor to access specific key chains by number.

This code stores a password in the default Keychain:

Var newItem As KeychainItem
If System.KeychainCount > 0 Then
  newItem = New KeychainItem
  ' Indicate the name of the application
  newItem.ServiceName = "MyApplication"
  ' Assign a password to the item
  System.Keychain.AddPassword(newItem, "SecretPassword")
Else
  System.Beep
  MessageBox("You don't have a key chain.")
End If

Exception e As KeychainException
  MessageBox("Keychain error: " + e.Message)

And this code retrieves the password:

Var itemToFind As KeychainItem
Var password As String
itemToFind = New KeychainItem
' Name to find
ItemToFind.ServiceName = "MyApplication"
' Get the password
password = System.Keychain.FindPassword(itemToFind)
MessageBox("Password: " + password)

Exception e As KeychainException
  MessageBox("Keychain error: " + e.Message)

iCloud Keychain

You can also work with passwords stored in the user's iCloud Keychain by passing True for the optional Synced parameter on Keychain.AddPassword, Keychain.FindPassword, KeychainItem.Remove, and KeychainItem.UpdatePassword.

This code stores a password in the iCloud Keychain:

Var newItem As KeychainItem
newItem = New KeychainItem
newItem.ServiceName = "MyApplication"

Try
  System.Keychain.AddPassword(newItem, "SecretPassword", True)
Catch e As KeychainException
  MessageBox("Keychain error: " + e.Message)
End Try

And this code retrieves it:

Var itemToFind As KeychainItem
Var password As String
itemToFind = New KeychainItem
itemToFind.ServiceName = "MyApplication"

Try
  password = System.Keychain.FindPassword(itemToFind, True)
  MessageBox("Password: " + password)
Catch e As KeychainException
  MessageBox("Keychain error: " + e.Message)
End Try

Note

When working with iCloud-synced passwords, the KeychainItem will not contain a valid Handle after a successful call due to the nature of OS-backed SecureItems.

Requirements

Working with iCloud-synced passwords requires that your macOS app be signed with a Provisioning Profile and Entitlements file that include the keychain-access-groups key. The value must use your Team ID (for example, BW7PU32485), and that Team ID must match both the Provisioning Profile and the developer certificate used to sign the app.

Entitlements:

<key>keychain-access-groups</key>
<array>
    <string>TeamID.*</string>
</array>

The Provisioning Profile must also include an entry for keychain-access-groups whose value matches the same Team ID.

See also

Keychain, KeychainItem KeychainException classes