Skip to content

application.keychain ​

application.keychain represents the app's items in the keychain. The keychain is encrypted storage provided by iOS, designed for small secrets such as passwords, sign-in tokens, and keys. The system encrypts the data before storing it, and each app can only read and write its own items.

Each item has a key and a value. The key is a non-empty string. The value is a string or a sequence of bytes; it can't directly be a number, array, or object.

There is only one application.keychain in the whole app, and it can be used at any time, including at the top level of a script. Its class is Keychain. All functions return a Promise. Reads and writes happen in the background; meanwhile the interface stays responsive and timers keep running.

Settings and app data don't belong here: settings go in application.storage, and files and large amounts of data go in application.fileSystem. For how to save and retrieve sign-in tokens, see the guide Saving login tokens.

Note: The keychain isn't in the core; it is available only after installing the @nacrejs/keychain package. Without it, the application.keychain property doesn't exist ('keychain' in application is false), and type checking reports that it doesn't exist. For how to install it, see Installation below.

Inheritance: Keychain does not inherit from any class.

Installation ​

The keychain is a separate capability package. Install it in your project:

bash
npm install @nacrejs/keychain

Effect: The next time ios/ is generated, the project embeds an extra NacreKeychain.framework; projects that don't install it have no such framework in their output.

This package doesn't require any usage description in nacre.config.json.

Then add a line at the top of your entry file to bring in the types:

js
/// <reference types="@nacrejs/types" />
/// <reference types="@nacrejs/keychain" />

Effect: application.keychain gets completion and checking in the editor. Without this line, tsc reports Property 'keychain' does not exist on type 'Application'.

For how to install other capability packages, see Core and capability packages.

Constructor ​

It can't be created with new: new Keychain() throws TypeError with the message Illegal constructor: Keychain is created by the runtime, not by new. The only instance is obtained from the keychain property of application.

Functions ​

All functions return a Promise. When an argument has the wrong type, TypeError is thrown immediately rather than returning a Promise. When the key isn't a string or is an empty string, the message is <function name>: key must be a non-empty string, such as get: key must be a non-empty string.

FunctionDescription
get()Reads a string value. Gives null when the key doesn't exist
getBytes()Reads a byte value as an ArrayBuffer. Gives null when the key doesn't exist
set()Writes a string. Overwrites the value when the key already exists
setBytes()Writes the bytes in a Blob. Overwrites the value when the key already exists
remove()Deletes a key. Completes as usual when the key doesn't exist
has()Whether the key exists
keys()All keys the app has stored
clear()Deletes all of the app's items

Events ​

There are no events. Only the app's own code can change these items, and when a write's Promise fulfills, the change is done.

Access levels ​

When writing, you can give an item an access level with the accessible option. The access level decides two things: in what device state the item can be read, and whether the item survives when the user moves to a new phone and restores from a backup.

accessible valueWhen it can be readAfter moving to a new phone
'whenUnlockedThisDeviceOnly' (default)While the device is unlockedGone
'whenUnlocked'While the device is unlockedKept
'afterFirstUnlockThisDeviceOnly'After the user unlocks once following a restart, readable from then on, including while lockedGone
'afterFirstUnlock'Same as aboveKept
'whenPasscodeSetThisDeviceOnly'While the device is unlocked. Requires a device passcode; writing fails when none is setGone

All five values can be written and read back in the simulator. The "When it can be read" and "After moving to a new phone" columns come from the iOS definitions and are not verified in the simulator: verifying them requires locking a real device and switching devices.

  • Without accessible, it is 'whenUnlockedThisDeviceOnly'. After the user moves to a new phone, the item can't be read, and the app has to have the user sign in again.
  • The access level is fixed when an item is first written and can't be changed afterward. Calling set again on an existing key with a different accessible updates the value but keeps the access level, without an error (derived from reading the code; not verified in the simulator). To change the access level, remove first, then set.
  • Reading an item that requires unlocking while the device is locked rejects the Promise with name 'NotAllowedError' (from the mapping in the code; not verified in the simulator).

How long data is kept ​

SituationIs the data still there?
The app process ends and the app restartsYes. In acceptance testing, a counter stored on the first run was read on the second launch
Device restart, system updateNot verified in the simulator
The user deletes and reinstalls the appNot verified in the simulator. Don't rely on it still being there, and don't assume it has been deleted
Moving to a new phone and restoring from a backupDepends on the access level

The size limit for a single keychain value is not verified in the simulator.

Order of multiple operations ​

Keychain operations run one after another in call order. Calling set twice on the same key in a row without waiting leaves the value from the later call (derived from reading the code; not verified in the simulator).

What you get on error ​

When an operation fails, the Promise rejects with an Error object (called KeychainError in the type definitions) that carries two extra properties:

PropertyTypeMeaning
namestringThe error category; values in the table below. Use it to tell what went wrong
messagestringA description
codenumberThe system's raw error code (OSStatus). 0 when the accessible value isn't recognized
domainstring'NSOSStatusErrorDomain'. An empty string when the accessible value isn't recognized
nameWhen
'NotAllowedError'Reading or writing an item that requires unlocking while the device is locked; authentication failed
'SecurityError'The app lacks the entitlement needed to access the keychain
'TypeMismatchError'Invalid arguments, including an unrecognized accessible value
'InvalidModificationError'An item conflict
'KeychainError'None of the above. Use code to tell them apart

Only the row "an unrecognized accessible value gives 'TypeMismatchError'" has been verified in the simulator; the other rows come from the mapping in the code and are not verified in the simulator.

Examples ​

The code below saves a sign-in token, reads it back, then deletes it. The keychain involves no interface, so this code runs directly at the top level of main.js.

js
const kc = application.keychain;

async function main() {
  const saved = await kc.get('token');
  console.log('Existing token:', saved);

  await kc.set('token', 'abc-123');
  console.log('Read:', await kc.get('token'));

  await kc.remove('token');
  console.log('After removal:', await kc.has('token'));
}

main().catch((err) => {
  console.log('Error:', String(err));
});

Result

  • The console prints Existing token: null.
  • Then it prints Read: abc-123.
  • Finally it prints After removal: false.

This code hasn't been run as a whole in the simulator. Every API it uses has been run in the acceptance tests.

Corresponding iOS API ​

ObjCJS
SecItemCopyMatching with kSecReturnDataawait kc.get(key), await kc.getBytes(key)
SecItemUpdate, or SecItemAdd when the item doesn't existawait kc.set(key, value), await kc.setBytes(key, blob)
SecItemDeleteawait kc.remove(key)
SecItemCopyMatching with kSecMatchLimitAll and kSecReturnAttributesawait kc.keys()
kSecAttrAccessibleWhenUnlocked{ accessible: 'whenUnlocked' }
kSecAttrAccessibleWhenUnlockedThisDeviceOnly{ accessible: 'whenUnlockedThisDeviceOnly' }
kSecAttrAccessibleAfterFirstUnlock{ accessible: 'afterFirstUnlock' }
kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly{ accessible: 'afterFirstUnlockThisDeviceOnly' }
kSecAttrAccessibleWhenPasscodeSetThisDeviceOnly{ accessible: 'whenPasscodeSetThisDeviceOnly' }
kSecAttrAccessibleAlways, kSecAttrAccessibleAlwaysThisDeviceOnlyNone. Deprecated since iOS 12
kSecAttrService of kSecClassGenericPasswordFixed to the app's bundle identifier
kSecAttrAccountkey
OSStatusThe Promise rejects; err.code is the raw value

See also ​