Class

# KeychainItem

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

## Description

Refers to a macOS `Keychain</api/macos/keychain>` item.

## Properties

<div class="rst-class">

table-centered_columns_3_and_4

</div>

| Name                                    | Type                               | Read-Only | Shared |
|-----------------------------------------|------------------------------------|-----------|--------|
| `AccountName<keychainitem.accountname>` | `String</api/data_types/string>`   |           |        |
| `Comment<keychainitem.comment>`         | `String</api/data_types/string>`   |           |        |
| `Description<keychainitem.description>` | `String</api/data_types/string>`   |           |        |
| `Handle<keychainitem.handle>`           | `Integer</api/data_types/integer>` | ✓         |        |
| `Label<keychainitem.label>`             | `String</api/data_types/string>`   |           |        |
| `ServiceName<keychainitem.servicename>` | `String</api/data_types/string>`   |           |        |

## Methods

<div class="rst-class">

table-centered_column_4

</div>

| Name                                          | Parameters                                                                                                                         | Returns | Shared |
|-----------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------|---------|--------|
| `Remove<keychainitem.remove>`                 | `Optional</api/language/optional>` Synced As `Boolean</api/data_types/boolean>` = False                                            |         |        |
| `UpdatePassword<keychainitem.updatepassword>` | value As `String</api/data_types/string>`, `Optional</api/language/optional>` Synced As `Boolean</api/data_types/boolean>` = False |         |        |

## Property descriptions

<div id="keychainitem.accountname">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

KeychainItem.AccountName

**AccountName** As `String</api/data_types/string>`

> Contains the name of the account (required for adding, can be `Nil</api/language/nil>` to find).
>
> This example sets the value of the AccountName field in a `TextField</api/user_interface/desktop/desktoptextfield>` on the form.
>
> ``` xojo
> Var kc As Keychain
> Var kci As KeychainItem
>
> kc = New Keychain(Listbox1.SelectedRowIndex)
>
> If kc <> Nil Then
>   kci = New KeychainItem
>   kci.ServiceName = SearchField.Text
>
>   PasswordField.Text = kc.FindPassword(kci)
>
>   ServiceNameField.Text = kci.ServiceName
>   AccountNameField.Text = kci.AccountName
>   CommentField.Text = kci.Comment
>   LabelField.Text = kci.Label
> End If
> ```

<div id="keychainitem.comment">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

KeychainItem.Comment

**Comment** As `String</api/data_types/string>`

> End user editable string containing comments for this **Keychain** item.
>
> This example sets the contents of the comment field in a `TextField</api/user_interface/desktop/desktoptextfield>` on the input form.
>
> ``` xojo
> Var kc As Keychain
> Var kci As KeychainItem
>
> kc = New Keychain(Listbox1.SelectedRowIndex)
>
> If kc <> Nil Then
>   kci = New KeychainItem
>   kci.ServiceName = SearchField.Text
>
>   PasswordField.Text = kc.FindPassword(kci)
>
>   ServiceNameField.Text = kci.ServiceName
>   AccountNameField.Text = kci.AccountName
>   CommentField.Text = kci.Comment
>   LabelField.Text = kci.Label
> End If
> ```

<div id="keychainitem.description">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

KeychainItem.Description

**Description** As `String</api/data_types/string>`

> End-user visible string describing this Keychain item.
>
> This example sets the value of the Description field on a form.
>
> ``` xojo
> Var kc As Keychain
> Var kci As KeychainItem
>
> kc = New Keychain(Listbox1.SelectedRowIndex)
>
> If kc <> Nil Then
>   kci = New KeychainItem
>   kci.ServiceName = SearchField.Text
>
>   PasswordField.Text = kc.FindPassword(kci)
>
>   ServiceNameField.Text = kci.ServiceName
>   AccountNameField.Text = kci.AccountName
>   CommentField.Text = kci.Comment
>   DescriptionField.Text = kci.Description
> End If
> ```

<div id="keychainitem.handle">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

KeychainItem.Handle

**Handle** As `Integer</api/data_types/integer>`

> Contains the <span class="title-ref">KeychainItem</span> reference, for use with macOS API calls.
>
> This property is read-only.
>
> This example gets the handle to the <span class="title-ref">KeychainItem</span>.
>
> ``` xojo
> Var i As Integer
> Var kci As New KeychainItem
> i = kci.Handle
> ```

<div id="keychainitem.label">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

KeychainItem.Label

**Label** As `String</api/data_types/string>`

> End-user editable string containing the label for this Keychain item.
>
> This example sets the text in a `TextField</api/user_interface/desktop/desktoptextfield>` to the value of the Label property.
>
> ``` xojo
> Dim kc As Keychain
> Dim kci As KeychainItem
>
> kc = New Keychain(Listbox1.SelectedRowIndex)
>
> If kc <> Nil Then
>   kci = New KeychainItem
>   kci.ServiceName = SearchField.Text
>
>   PasswordField.Text = kc.FindPassword(kci)
>
>   ServiceNameField.Text = kci.ServiceName
>   AccountNameField.Text = kci.AccountName
>   CommentField.Text = kci.Comment
>   LabelField.Text = kci.Label
> End If
> ```

<div id="keychainitem.servicename">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

KeychainItem.ServiceName

**ServiceName** As `String</api/data_types/string>`

> Contains the name of the service (required for adding, can be `Nil</api/language/nil>` to find). To add a password for an application, set ServiceName to the application's name.
>
> This example set the text of a `TextField</api/user_interface/desktop/desktoptextfield>` to the description of a <span class="title-ref">KeychainItem</span>.
>
> ``` xojo
> Var kc As Keychain
> Var kci As KeychainItem
>
> kc = New Keychain(Listbox1.SelectedRowIndex)
>
> If kc <> Nil Then
>   kci = New KeychainItem
>   kci.ServiceName = SearchField.Text
>
>   PasswordField.Text = kc.FindPassword(kci)
>
>   ServiceNameField.Text = kci.ServiceName
>   AccountNameField.Text = kci.AccountName
>   CommentField.Text = kci.Comment
>   LabelField.Text = kci.Label
> End If
> ```

## Method descriptions

<div id="keychainitem.remove">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

KeychainItem.Remove

**Remove**(`Optional</api/language/optional>` Synced As `Boolean</api/data_types/boolean>` = False)

> Removes the <span class="title-ref">KeychainItem</span>.
>
> You can change passwords in a `Keychain</api/macos/keychain>` by deleting the original item using this method and adding another item.
>
> When *Synced* is `True</api/language/true>`, the item is removed from the iCloud <span class="title-ref">Keychain</span> instead of the local <span class="title-ref">Keychain</span>. See the Notes section for additional requirements when working with iCloud-synced passwords.
>
> This example removes the current <span class="title-ref">KeychainItem</span> stored in the variable kci.
>
> ``` xojo
> kci.Remove
> ```

<div id="keychainitem.updatepassword">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

KeychainItem.UpdatePassword

**UpdatePassword**(value As `String</api/data_types/string>`, `Optional</api/language/optional>` Synced As `Boolean</api/data_types/boolean>` = False)

> Updates a password previously stored in the user default `Keychain</api/macos/keychain>` on macOS.
>
> When *Synced* is `True</api/language/true>`, the password is updated in the iCloud <span class="title-ref">Keychain</span> instead of the local <span class="title-ref">Keychain</span>. See the Notes section for additional requirements when working with iCloud-synced passwords.
>
> This example looks for an existing password and replaces it with the new one. Otherwise it creates a password.
>
> ``` xojo
> Var item As New KeychainItem
>
> item.ServiceName = "TestAppPasswordSetup"
> item.Label = "Test App Password"
>
> Try
>   Var s As String = System.Keychain.FindPassword(item)
>   If Not s.IsEmpty Then
>     item.UpdatePassword("A new Password is set")
>   End If
> Catch e As KeychainException
>   System.Keychain.AddPassword(item, "First password for this")
> End Try
> ```

## Notes

<span class="title-ref">KeychainItem</span>s can access passwords for applications only, not internet passwords.

When working with iCloud-synced passwords (by passing `True</api/language/true>` for the *Synced* parameter), the <span class="title-ref">KeychainItem</span> will not contain a valid `Handle<keychainitem.handle>` due to the nature of OS-backed SecureItems.

Working with iCloud-synced passwords requires that your macOS app be signed with a Provisioning Profile that includes the `keychain-access-groups` entitlement. See `Accessing the Keychain</topics/macos/accessing_the_keychain>` for more details.

## Sample code

The following example adds a <span class="title-ref">KeychainItem</span> for an application and assigns a password.

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

  Try
    ' Create a new keychain item for the application and assign the password
    System.Keychain.AddPassword(newItem, "SecretPassword")
  Catch Exception error As KeychainException
    MessageBox("Can't add item: " + error.Message)
  End Try
Else
  MessageBox("You don't have a key chain.")
End If
```

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

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

``` xojo
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"

Try
  ' get application's password from the system keychain
  password = System.Keychain.FindPassword(itemToFind)
  MessageBox("The password for this item is: " + password)
Catch Exception error As KeychainException
  MessageBox("Can't find item: " + error.Message)
End Try
```

## Compatibility

|                       |         |
|-----------------------|---------|
| **Project Types**     | Desktop |
| **Operating Systems** | macOS   |

<div class="seealso">

`Object</api/data_types/additional_types/object>` parent class; `Keychain</api/macos/keychain>` class; `KeychainException</api/exceptions/keychainexception>` error; `System</api/os/system>` module.

</div>