‹ Options

Constants

Accessible

When an item can be read: from the first unlock after a restart, only while the device is unlocked, or only while it has a passcode. A constant object and a type of the same name.

Import

import { Accessible } from '@apexnative/keychain';

Accessible is the value of the accessible option, and what getItemInfo reports. It is a plain object of strings with a type of the same name, not a TypeScript enum: Accessible.WhenUnlocked is the string 'whenUnlocked', and both forms are accepted.

Usage

import { Accessible, keychain } from '@apexnative/keychain';

await keychain.setItem('refreshToken', token, { accessible: Accessible.WhenUnlockedThisDeviceOnly });
await keychain.setItem('refreshToken', token, { accessible: 'whenUnlockedThisDeviceOnly' }); // the same

Signature

const Accessible: {
  readonly AfterFirstUnlock: 'afterFirstUnlock';
  readonly AfterFirstUnlockThisDeviceOnly: 'afterFirstUnlockThisDeviceOnly';
  readonly WhenUnlocked: 'whenUnlocked';
  readonly WhenUnlockedThisDeviceOnly: 'whenUnlockedThisDeviceOnly';
  readonly WhenPasscodeSetThisDeviceOnly: 'whenPasscodeSetThisDeviceOnly';
};

type Accessible = (typeof Accessible)[keyof typeof Accessible];

Type'afterFirstUnlock' | 'afterFirstUnlockThisDeviceOnly' | 'whenUnlocked' | 'whenUnlockedThisDeviceOnly' | 'whenPasscodeSetThisDeviceOnly'Default'afterFirstUnlock'PlatformsiOSAndroid

Values

Constant	String	Readable	On Android
AfterFirstUnlock	'afterFirstUnlock'	From the first unlock after a restart until the next restart, in the background too. The default	A Keystore key without a lock requirement; an app without direct boot doesn't run before the first unlock
AfterFirstUnlockThisDeviceOnly	'afterFirstUnlockThisDeviceOnly'	The same, and the item stays on this device	The same as afterFirstUnlock
WhenUnlocked	'whenUnlocked'	Only while the device is unlocked	The package checks the lock itself, on every version; on Android 9+ the key also has setUnlockedDeviceRequired(true)
WhenUnlockedThisDeviceOnly	'whenUnlockedThisDeviceOnly'	The same, and the item stays on this device	The same as whenUnlocked
WhenPasscodeSetThisDeviceOnly	'whenPasscodeSetThisDeviceOnly'	Only while the device is unlocked and has a passcode. Removing the passcode makes the item unreadable	The lock as with whenUnlocked; the write needs a secure device (PASSCODE_NOT_SET without one)

On iOS each value is the kSecAttrAccessible… constant of the same name.

• This device only. The …ThisDeviceOnly values keep an item out of iCloud Keychain and out of an encrypted iOS backup restored on another device. On Android every item is this-device-only: Keystore keys never leave the device. An item with synchronizable: true can't have one of them (INVALID_ARGUMENT).
• A locked device. A read or a write at a time the value doesn't allow fails with INTERACTION_NOT_ALLOWED, on iOS and on Android alike. On Android the package checks the lock itself before it touches a key, on every version: the Keystore refuses such a key from Android 9 too, but each version says it in its own way. With afterFirstUnlock, background work such as a silent push or a background fetch can read the item once the phone has been unlocked after a restart; that is why it is the default.
• Not here. iOS's kSecAttrAccessibleAlways is deprecated by Apple and has no value.

See also

ProtectionHow to choose accessible, with accessControl.KeychainOptionsEvery option of a storage.AccessControlWhat unlocks an item.