‹ /compat

Functions

Internet credentials

setInternetCredentials and the functions around it, as react-native-keychain 10 has them: a user name and a password per server, kept as the credentials of that server in the default store.

Import

import { setInternetCredentials, getInternetCredentials, hasInternetCredentials, resetInternetCredentials } from '@apexnative/keychain/compat';

Internet credentials are a user name and a password for a server. Here they are the credentials of the default store with that server: the item credentials:<server>, the user name its label. With an accessGroup, the store is that of the access group.

Usage

src/api/credentials.ts

import * as Keychain from '@apexnative/keychain/compat';

const SERVER = 'api.example.com';

export async function remember(username: string, password: string) {
  await Keychain.setInternetCredentials(SERVER, username, password, {
    accessible: Keychain.ACCESSIBLE.AFTER_FIRST_UNLOCK_THIS_DEVICE_ONLY,
  });
}

export async function recall() {
  const credentials = await Keychain.getInternetCredentials(SERVER);
  return credentials ? { username: credentials.username, password: credentials.password } : null;
}

export async function forget() {
  await Keychain.resetInternetCredentials({ server: SERVER });
}

The same item through the core API:

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

await keychain.getCredentials({ server: 'api.example.com' }); // { username, password } or null

Every function needs the server as a non-empty string: without one it rejects with INVALID_ARGUMENT.

setInternetCredentials

function setInternetCredentials(
  server: string,
  username: string,
  password: string,
  options?: SetOptions
): Promise<Result>;

ReturnsPromise<Result>PromptNever: a write shows no prompt, whatever its accessControlThrowsINVALID_ARGUMENT, UNSUPPORTED, HARDWARE_UNAVAILABLE, and what the device can't do: BIOMETRY_NOT_ENROLLED, PASSCODE_NOT_SET, …PlatformsiOSAndroid

Writes the user name and the password of the server, in place of what was there. It calls setCredentials with server.

Parameter	Type	Description
serverRequired	string	The server, such as api.example.com. Any non-empty string without U+0000. It becomes part of the key credentials:<server>, at most 256 characters, so it is readable without a prompt.
usernameRequired	string	Kept as the label of the item, outside the secret. Not empty, without U+0000.
passwordRequired	string	The secret. Any string without U+0000.
options	SetOptions	How to protect the item: accessible, accessControl, cloudSync, accessGroup, securityLevel, as for setGenericPassword. service is ignored.

await Keychain.setInternetCredentials('api.example.com', 'ivan', 'secret');
// { service: 'api.example.com', storage: 'keychain' }

It resolves with the server as service, and storage: 'keychain' on iOS, 'KeystoreAESGCM' on Android.

getInternetCredentials

function getInternetCredentials(
  server: string,
  options?: GetOptions
): Promise<InternetCredentials | false>;

ReturnsPromise<InternetCredentials | false>PromptWhen the item was written with an accessControlThrowsINVALID_ARGUMENT without a server; what the prompt ends with: USER_CANCELED, LOCKOUT, KEY_INVALIDATED, …PlatformsiOSAndroid

Reads the user name and the password of the server, or false when there are none. It calls getCredentials with server.

Parameter	Type	Description
serverRequired	string	The server the credentials were written for.
options	GetOptions	The texts of the prompt (authenticationPrompt) and the accessGroup. See GetOptions.

await Keychain.getInternetCredentials('api.example.com');
// { server: 'api.example.com', service: 'api.example.com', username: 'ivan', password: 'secret', storage: 'keychain' }

The prompt works as for getGenericPassword: a string is the title, and without authenticationPrompt the texts are rnk's.

hasInternetCredentials

function hasInternetCredentials(options: string | BaseOptions): Promise<boolean>;

ReturnsPromise<boolean>PromptNeverThrowsINVALID_ARGUMENT without a serverPlatformsiOSAndroid

Whether the server has credentials. It takes the server, or options with server (and accessGroup), and calls hasItem with the key credentials:<server>.

await Keychain.hasInternetCredentials('api.example.com'); // true
await Keychain.hasInternetCredentials({ server: 'api.example.com' }); // the same

resetInternetCredentials

function resetInternetCredentials(options: string | BaseOptions): Promise<void>;

ReturnsPromise<void>PromptNeverThrowsINVALID_ARGUMENT without a serverPlatformsiOSAndroid

Deletes the credentials of the server. It takes the server, or options with server, and calls removeCredentials with it. It resolves undefined, also when there was nothing to delete.

await Keychain.resetInternetCredentials('api.example.com');
await Keychain.resetInternetCredentials({ server: 'api.example.com' }); // the same

See also

Generic passwordsA user name and a password per service.TypesInternetCredentials, BaseOptions and the rest.getCredentialsThe core call behind getInternetCredentials.OverviewWhere the items go, and what is UNSUPPORTED.