# Modules.Identity.KeychainItem

Represents a keychain item to communicate with the native iOS Keychain and Android Keystore.

Availability
6.1.0
6.1.0

# Overview

The following example demonstrates the basic usage to save, read and delete values with the native iOS Keychain and/or Android Keystore:

var Identity = require('ti.identity');

// Create a keychain item
var keychainItem = Identity.createKeychainItem({
    identifier: 'password'
});

// Triggered when the keychain item was successfully saved
keychainItem.addEventListener('save', function(e) {
    // Notify the user that the operation succeeded or failed
});

// Write to the keychain
keychainItem.save('s3cr3t_p4$$w0rd');

For advanced security options, you can specify accessibility mode to the keychain that will be applied when writing items to the keychain, for example:

var Identity = require('ti.identity');

// Create a keychain item
var keychainItem = Identity.createKeychainItem({
  identifier: 'mypassword',
  service: 'my_service', // iOS only. Defaults to 'ti.touchid' for backwards compatibility
  accessGroup: '<YOUR-TEAM-ID>.com.appc.identitytest',
  accessibilityMode: Identity.ACCESSIBLE_WHEN_PASSCODE_SET_THIS_DEVICE_ONLY,
  accessControlMode: Identity.ACCESS_CONTROL_TOUCH_ID_ANY,
  // Pass more native options to the keychain. Since there are hundrets of them,
  // look up the value of the constant and pass it here. Example:
    options: {
      // The value of kSecUseOperationPrompt
      'u_OpPrompt': 'Please authenticate yourself!'
  }
});

# Methods

# fetchExistence

Availability
6.1.0
6.1.0
fetchExistence(result) void

Asynchronously determines whether or not a value of the specified identifier exists in the keychain item.

Parameters

Name Type Description
result Callback

Use the event key exists of the callback to determine the existence of the keychain item.

Returns

Type
void

# read

Availability
6.1.0
6.1.0
read() void

Reads an existing value to the native keychain.

The read event is triggered when an item is fetched. If an error occurs, the error key informs you about the exact error.

Returns

Type
void

# reset

Availability
6.1.0
6.1.0
reset() void

Resets an existing value from the native keychain.

The reset event is triggered when a new item is saved. If an error occurs, the error key informs you about the exact error.

Returns

Type
void

# save

Availability
6.1.0
6.1.0
save(value) void

Saves a new value to the native keychain.

The save event is triggered when a new item is saved. If an error occurs, the error key informs you about the exact error.

On Android this will also overwrite any existing value.

Parameters

Name Type Description
value String

The value to be stored in the native keychain.

Returns

Type
void

# update

Availability
6.1.0
6.1.0
update(value) void

Updates an existing value to the native keychain.

The update event is triggered when an item is updated. If an error occurs, the error key informs you about the exact error.

Parameters

Name Type Description
value String

The value to be stored in the native keychain.

Returns

Type
void

# Events

# save

Availability
6.1.0
6.1.0

Triggered when a new keychain item is saved (or an error occurred).


# update

Availability
6.1.0
6.1.0

Triggered when a new keychain item is updated (or an error occurred).


# read

Availability
6.1.0
6.1.0

Triggered when a new keychain item is read (or an error occurred).


# reset

Availability
6.1.0
6.1.0

Triggered when a new keychain item is reset (or an error occurred).