Class

Keychain

Description

Gives you access to the default macOS Keychains for your applications. It is a Macintosh-only feature. The Keychain class does not provide access to internet passwords.

Properties

Name	Type	Read-Only	Shared
Handle	Integer	✓

Methods

Name	Parameters	Returns
AddPassword	kci As KeychainItem, Password As String
Constructor	index As Integer
FindPassword	ByRef kci As KeychainItem	String
Lock	LockAll As Boolean
Unlock	Password As String

Property descriptions

Keychain.Handle

Handle As Integer

Returns a Handle to the Keychain. Useful only if you want to refer to Keychains with Declare statements.

This property is read-only.

Method descriptions

Keychain.AddPassword

AddPassword(kci As KeychainItem, Password As String)

Adds the password to the Keychain and associates it with a KeychainItem. If it fails, it generates a KeychainException.

The following example adds a KeychainItem for an application and assigns a password.

Var newItem As KeychainItem
If System.KeychainCount > 0 Then
  newItem = New KeychainItem
  // Indicate the name of the application
  newItem.ServiceName = "MyApplication"

  // Create a new keychain item for the application and assign the password
  System.Keychain.AddPassword(newItem, "SecretPassword")
Else
  System.Beep
  MessageBox("You don't have a key chain.")
End If

Exception err As KeychainException
  MessageBox("Can't add item: " + err.Message)

Keychain.Constructor

Constructor(index as Integer)

Note

Constructors are special methods called when you create an object with the New keyword and pass in the parameters above.

Gives you a reference to any Keychain known by the Keychain manager. The Index value should be in the range from 0 to System.KeychainCount - 1.

This constructor is in a For...Next loop that instantiates a Keychain for each for each Keychain item. It populates a ListBox with the list of keychains.

#If TargetMacOS
  Declare Function KCGetKeychainName Lib "Carbon" (keychain As Integer, keychainName As Ptr) As Integer

  Var i As Integer
  Var err As Integer
  Var kc As Keychain
  Var kcName As MemoryBlock

  kcName = New MemoryBlock(256)

  For i = 0 To System.KeychainCount - 1
    kc = New Keychain(i)

    If kc = Nil Then
      MessageBox("Keychain(" + Str(i) + ") returned nil")
    Else
      err = KCGetKeychainName(kc.Handle, kcName)

      If err <> 0 Then
        MessageBox("KCGetKeychainName returned " + Str(err))
      Else
        ListBox1.AddRow(kcName.PString(0))
      End If
    End If
  Next
#Endif

Keychain.FindPassword

FindPassword(ByRef kci As KeychainItem) As String

Attempts to find the password for an Item in the given Keychain that matches kci. At the end of a successful call, kci will point to the found Keychain Item. If it fails, it generates a KeychainException.

The following example retrieves the password and displays it in a message box.

Var itemToFind As KeychainItem
Var password As String

itemToFind = New KeychainItem
// Indicate the name of the application whose keychain item you wish to find
itemToFind.ServiceName = "MyApplication"

// get application's password from the system keychain
password = System.Keychain.FindPassword(itemToFind)
MessageBox("The password for this item is: " + password)

Exception err As KeychainException
  MessageBox("Can't find item: " + err.Message)

Keychain.Lock

Lock(LockAll As Boolean)

Locks the Keychain.

If LockAll is True, it will lock all the Keychains on the system. Note from Apple: There is usually no need for an application to ever call Lock. Unless your application is directly responding to a user's request for a Keychain to be locked, it is recommended that you leave the Keychain unlocked so that the user does not have to unlock it again in another application.

If it fails, it generates a KeychainException.

System.Keychain.Lock(True)

Keychain.Unlock

Unlock(Password As String)

Unlocks the Keychain if the password is the empty string ("").

The system displays the standard Unlock dialog, and the passed Keychain will appear as the selected item in that dialog's pop-up menu. NOTE: because of the way Apple has implemented this, if you pass an incorrect password once to a particular Keychain, the system will require human interaction from then on that Keychain until the system is rebooted.

If it fails, it generates a KeychainException.

System.Keychain.UnLock("")

Notes

The Keychain is a system-wide facility on macOS to store account passwords for applications. By taking advantage of the built-in Keychain facility, your users won't have to type their password if their Keychain is unlocked. You should always ask the user before storing something in the Keychain.

An equivalent technology to the Mac OS Keychain doesn't currently exist on other platforms, so the Keychain class is supported only on Macintosh.

Sample code