@pagopa/io-react-native-crypto NPM

@pagopa/io-react-native-crypto

Module to generate and sign with crypto keys backed on device security hardware on react-native platform.

Installation

yarn add @pagopa/io-react-native-crypto

Usage

Generate a key

import { generate } from '@pagopa/io-react-native-crypto';

// ...

try {
  const result = await generate('PERSONAL_KEYTAG');
} catch (e) {
  const {message, userInfo} = e as CryptoError;
}
// result is the JWK of the generated public key

Sign a message

import { sign } from '@pagopa/io-react-native-crypto';

// ...

try {
  const result = await sign('A valid message to sign', 'PERSONAL_KEYTAG');
} catch (e) {
  const {message, userInfo} = e as CryptoError;
}
// result is the Base64 string representation of the signature.

Retrieve the public key

import { getPublicKey } from '@pagopa/io-react-native-crypto';

// ...

try {
  const result = await getPublicKey('PERSONAL_KEYTAG');
} catch (e) {
  const {message, userInfo} = e as CryptoError;
}
// result is the JWK of the generated public key, error if no key has been yet generated

Checks whether a key is stored in StrongBox or not (Android only, raises a UNSUPPORTED_DEVICE error on iOS)

import { isKeyStrongboxBacked } from '@pagopa/io-react-native-crypto';

// ...

try {
  const isKeyStrongboxBacked = await isKeyStrongboxBacked('PERSONAL_KEYTAG');
  if(isKeyStrongboxBacked) {
    console.log('The key is stored in the StrongBox');
  } else {
    console.log('The key is stored in TEE');
  }
} catch (e) {
  const {message, userInfo} = e as CryptoError;
}
// result is the JWK of the generated public key, error if no key has been yet generated

Delete the key

import { deleteKey } from '@pagopa/io-react-native-crypto';

// ...

try {
  await deleteKey('PERSONAL_KEYTAG');
} catch (e) {
  const {message, userInfo} = e as CryptoError;
}
// no result is provided, error if no key has been found for the specified keytag

Types

TypeName	Description
ECKey	The JWK representation of an Elliptic Curve public key
RSAKey	The JWK representation of an RSA public key
PublicKey	Type of the returned public key, may be either a RSAKey or a ECKey
CryptoError	This type defines the error returned by the generation of a key or signing a message it is composed by an error code and by an additional information object

Error Codes

TypeName	Platform	Description
KEY_ALREADY_EXISTS	iOS/Android	The key you're trying to generate already exists
UNSUPPORTED_DEVICE	iOS/Android	Device doesn't support hardware backed keys or the requested method
WRONG_KEY_CONFIGURATION	iOS/Android	The key configuration has not been correctly defined
PUBLIC_KEY_NOT_FOUND	iOS/Android	The public key is missing for a specific keyTag
PUBLIC_KEY_DELETION_ERROR	iOS/Android	An error occurred while deleting the public key
API_LEVEL_NOT_SUPPORTED	Android	The current API Level doesn't support the hardware baked key generation
KEYSTORE_LOAD_FAILED	Android	It was not possible to load or store data on the Keystore
KEYCHAIN_LOAD_FAILED	iOS	It was not possible to load or store data on the Keychain
UNABLE_TO_SIGN	iOS/Android	It was not possible to sign the given string
INVALID_UTF8_ENCODING	iOS/Android	The encoded string doesn't respect the valid encoding format
INVALID_SIGN_ALGORITHM	Android	The sign algorithm was not valid
UNKNOWN_EXCEPTION	Android	Unexpected error
THREADING_ERROR	iOS	Unexpected error