‹ Storage

Types

Types of storage

The options of a write and of a read, what getItemInfo reports, and the credentials with the server they are for.

Import

import { type SetOptions, type GetOptions, type ItemInfo, type Credentials, type CredentialsOptions } from '@apexnative/keychain';

SetOptions

type SetOptions = {
  accessible?: Accessible;
  accessControl?: AccessControl;
  authValidity?: number;
  synchronizable?: boolean;
  android?: AndroidOptions;
  label?: string;
};

The options of a write: setItem, setBytes, setItemSync, and, without label, setCredentials. Each protection option overrides the storage's for this item; what isn't given comes from the storage, then from the defaults. The combination is checked as a whole: { authValidity: 30 } on a storage of biometryCurrentSet throws INVALID_ARGUMENT.

Field	Type	Description
accessible	Accessible	When the item can be read. See KeychainOptions.
accessControl	AccessControl	What unlocks the item. See KeychainOptions.
authValidity	number	Seconds one prompt opens the item for. See KeychainOptions.
synchronizable	boolean	iOS: keep the item in iCloud Keychain. See KeychainOptions.
android	AndroidOptions	Where Android keeps the item's key. See KeychainOptions.
label	string	A text that isn't secret, stored next to the item and readable without a prompt through `getItemInfo`. A write without one removes the label; '' is a label, not the absence of one. Can't contain U+0000. Not taken by setCredentials, whose label is the username.

The service and the access group aren't write options: they belong to the storage.

GetOptions

type GetOptions = {
  prompt?: Prompt;
};

The options of a read: getItem, getBytes, getCredentials.

Field	Type	Description
prompt	Prompt	The texts of the prompt of this read, merged field by field over the storage's: { title } keeps the storage's cancel. See Prompt.

A read uses the protection the item was written with; there is nothing else to choose.

ItemInfo

type ItemInfo = {
  key: string;
  label?: string;
  accessible: Accessible;
  accessControl: AccessControl;
  synchronizable: boolean;
  createdAt: number;
  modifiedAt: number;
  android?: {
    securityLevel: HardwareSecurityLevel;
  };
};

What getItemInfo reports about an item, without a prompt.

Field	Type	Description
keyRequired	string	The key of the item.
label	string	The item's label. Absent when the item has none; '' when the label is the empty string. For credentials, the username.
accessibleRequired	Accessible	When the item can be read, as it was written.
accessControlRequired	AccessControl	What unlocks the item, as it was written.
synchronizableRequired	boolean	Whether the item is in iCloud Keychain. Always false on Android.
createdAtRequired	number	When the item was first written, in milliseconds since the Unix epoch. A write that replaces the item keeps it.
modifiedAtRequired	number	When the item was last written, in milliseconds since the Unix epoch.
android	{ securityLevel }	Android only: where the item's Keystore key lives, 'strongbox', 'tee' or 'software', measured when the item was written.

Credentials

type Credentials = {
  username: string;
  password: string;
};

A username and a password, written by setCredentials as one item and read back by getCredentials.

Field	Type	Description
usernameRequired	string	Kept as the item's label, readable without a prompt. Can't be empty or contain U+0000.
passwordRequired	string	Kept as the item's value. May be empty; can't contain U+0000.

CredentialsOptions

type CredentialsOptions = {
  server?: string;
};

Which credentials: the app's own, or those of a server.

Field	Type	Description
server	string	The server the credentials are for, such as api.example.com. The item's key is credentials:<server>; without a server it is credentials. Must be non-empty, and the key must fit the rules of a key.

See also

KeychainThe methods that take these types.KeychainOptionsWhat each protection option means.Storage modelLabels, item info and credentials, explained.