Updating macOS Keychain Passwords – Xojo Programming Blog

The Keychain is a system-wide feature on macOS that securely stores account passwords for applications. Until Xojo 2025r1, updating the password for an existing KeychainItem—that is, for a given Service Name—required first removing the item from the Keychain and then recreating it from scratch. Not exactly the most efficient process. But with the introduction of the KeychainItem.UpdatePassword method in 2025r1, things have gotten much easier. Read on to see how you can take advantage of this new functionality.

Starting with 2025r1, there’s no longer any need to delete an existing Keychain item just to update its password. All you need is a KeychainItem instance with a non-zero Handle, in other words, a properly initialized item. And the best way to get a reference to an existing KeychainItem is by using the System.Keychain.FindPassword method. For example, the following code snippet from a method with the signature FindPassword(serviceName As String) As KeychainItem:

Var itemToFind As New KeychainItem
Var password As String

// Name to find
ItemToFind.ServiceName = serviceName

// Get the password
password = System.Keychain.FindPassword(itemToFind)

Return itemToFind

Catch e As KeychainException
  Return Nil

This retrieves the password for a given Keychain item stored under the Service Name passed as the serviceName parameter. If the call to System.Keychain.FindPassword raises a KeychainException, it means there’s no password stored in the Keychain for that Service Name so we return Nil. But if the method successfully retrieves a password, it means we have a valid, properly initialized KeychainItem we can use to call UpdatePassword.

For example, create a new method with the following signature:

Public Sub CreatePassword(pass As String, label As string, serviceName As String)
  // Let's see if we have a password for the item already.
  // If that is the case, we need to update it instead of
  // creating it!
  
  Var itemToFind As KeychainItem = FindPassword(serviceName)
  
  // If we don't get a Nil KeychainItem, that means that we should
  // update the password for such KeychainItem, instead of creating a new one!
  
  If itemToFind <> Nil Then
     itemToFind.UpdatePassword(pass)
  Else
    // We got a Nil KeychainItem… what means that there is not
    // such item in the user Keychain yet, so let's create it.
    
    itemToFind = New KeychainItem
    itemToFind.Label = label
    itemToFind.ServiceName = serviceName
    System.Keychain.AddPassword(itemToFind, pass)
  End If
  
  Catch e As KeychainException
    MessageBox("Keychain error: " + e.Message)
    
End Sub

As you can see, this method takes three string parameters: the password you want to set or update, the label to use for the Keychain item (particularly useful when adding a new password for a given Service Name) and the Service Name itself, which is associated with the password.

The first thing this method does is call the FindPassword method we saw earlier. If it returns a non-nil object, we simply update the password. However, if the FindPassword method returns a nil object, we create a new KeychainItem from scratch using the provided label and serviceName parameters, then add the new password to the user’s Keychain.

Download this example project to experiment adding, deleting and/or updating passwords to your macOS Keychain.

Javier Menendez is an engineer at Xojo and has been using Xojo since 1998. He lives in Castellón, Spain and hosts regular Xojo hangouts en español. Ask Javier questions on Twitter at @XojoES or on the Xojo Forum.