@pagopa/io-react-native-crypto

Module to generate and sign with crypto keys backed by device security hardware on React Native platforms.

Installation

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

Usage

$3

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

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

$3

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

try {
const signature = await sign('A valid message to sign', 'PERSONAL_KEYTAG');
// result is a base64-encoded string of the signature
} catch (e) {
const { message, userInfo } = e as CryptoError;
}
`

$3

#### getPublicKeyFixed

Returns the public key in strict JWK-compliant format.

- Base64URL encoding (URL-safe, no padding)
- Leading 0x00 sign-byte removed
- EC P-256 coordinates guaranteed to be 32 bytes

`ts
import { getPublicKeyFixed } from '@pagopa/io-react-native-crypto';

const jwk = await getPublicKeyFixed('PERSONAL_KEYTAG');
`

#### getPublicKey (legacy)

Kept for backwards compatibility. Uses standard Base64 (with padding) and may include sign-bytes.

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

const jwkLegacy = await getPublicKey('PERSONAL_KEYTAG');
`

---

$3

Validates an X.509 certificate chain (optionally with CRL checks).

`ts
import { verifyCertificateChain } from '@pagopa/io-react-native-crypto';

const result = await verifyCertificateChain(
['base64_leaf', 'base64_intermediate'],
'base64_trust_anchor',
{
requireCrl: true,
connectTimeout: 5000,
readTimeout: 5000
}
);

// result: CertificateValidationResult
// result.isValid === true ↔ Certificate is trusted
// result.validationStatus === 'VALID'
`

If validation fails unexpectedly, a CryptoError is thrown with the code CERTIFICATE_CHAIN_VALIDATION_ERROR.

---

$3

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

const backed = await isKeyStrongboxBacked('PERSONAL_KEYTAG');
console.log(backed ? 'StrongBox' : 'TEE');
`

---

$3

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

await deleteKey('PERSONAL_KEYTAG');
`

---

Types

| Type Name | Description |
| ------------------------- | --------------------------------------------------------------------------- |
| ECKey | JWK representation of an Elliptic Curve public key |
| RSAKey | JWK representation of an RSA public key |
| PublicKey | Union of ECKey \| RSAKey |
| CryptoError | Rejected promise error (contains message and userInfo) |
| CertificateValidationStatus | Enum of possible X.509 validation statuses |
| CertificateValidationResult | Returned object from verifyCertificateChain:
{ isValid: boolean, validationStatus: CertificateValidationStatus } |

---

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 |
| CERTIFICATE_CHAIN_VALIDATION_ERROR` | iOS/Android | X.509 chain validation failed |

Contributing

See the contributing guide to learn how to contribute to the repository and the development workflow.

License

MIT

---

Made with create-react-native-library