From ea62f1a50a8bdede7048ca17c8c54616a3e6a1d9 Mon Sep 17 00:00:00 2001 From: LazyAfternoons Date: Fri, 17 May 2024 21:32:01 +0200 Subject: [PATCH] docs: update README.md --- README.md | 75 +++++++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 64 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index e963f39..b1b042a 100644 --- a/README.md +++ b/README.md @@ -14,6 +14,7 @@ yarn add io-react-native-integrity The Android implementation is based on the [Play Integrity API](https://developer.android.com/google/play/integrity/overview) which provides a set of APIs to help developers protect their apps from tampering. The usage of this API also requires a backend server to verify the integrity token generated by the app. An example is provided in the [example/backend](example/backend) directory. Make sure to follow the instructions in the [example/README.md](example/README.md) file to set up the backend server and update the `.env` file with the correct values to test the library. +The flow provided by the library is the [standard one](https://developer.android.com/google/play/integrity/standard?hl=it). A (Key Attestation)[https://developer.android.com/privacy-and-security/security-key-attestation] can be generated using the `getAttestation` method. During key attestation, a key pair is generated along with its certificate chain hich can be used to verify the properties of that key pair. @@ -103,7 +104,53 @@ try { ## iOS -// TODO +The iOS implementation is based on the (DCAppAttestService)[https://developer.apple.com/documentation/devicecheck/establishing-your-app-s-integrity] which is availabe from iOS 14.0 onwards. +It's a framework provided by Apple for iOS that allows apps to verify if a specific device has been used to perform a particular action, without revealing the identity of the device itself or its owner. It is useful for preventing abuse by users who try to manipulate the system or use the app fraudulently. + +### `generateHardwareKey` + +Generates a hardware key that can be used into the attestation process when calling `getAttestaiton`. + +```ts +try { + const key = await generateHardwareKey(); + console.log(key); +} catch (e) { + const error = e as IntegrityError; + console.log(JSON.stringify(error)); +} +``` + +### `getAttestation` + +Generates an attestation for the given challenge and hardware key. The hardware key generated at the previous step can be used here. + +```ts +try { + const attestation = await getAttestation(challenge, key); + console.log(attestation); +} catch (e) { + const error = e as IntegrityError; + console.log(JSON.stringify(error)); +} +``` + +### `generateHardwareSignatureWithAssertion` + +Generates a signature for the given client data given an hardware key. The hardware key generate at the previous step can be used here. + +```ts +try { + const signature = await generateHardwareSignatureWithAssertion( + clientData, + key + ); + console.log(signature); +} catch (e) { + const error = e as IntegrityError; + console.log(JSON.stringify(error)); +} +``` ## Types @@ -113,16 +160,22 @@ try { ## Error Codes -| TypeName | Platform | Description | -| :--------------------------------------: | :------: | ---------------------------------------------------------------------------------------------- | -| WRONG_GOOGLE_CLOUD_PROJECT_NUMBER_FORMAT | Android | A wrong value for `GOOGLE_CLOUD_PROJECT_NUMBER` has been provided to `prepareIntegrityToken` | -| PREPARE_FAILED | Android | A critical error occurred during the `prepareIntegrityToken` operation | -| PREPARE_NOT_CALLED | Android | The `requestIntegrityToken` has been called without calling `prepareIntegrityToken` beforehand | -| REQUEST_TOKEN_FAILED | Android | A critical error occurred during the `requestIntegrityToken` operation | -| REQUEST_ATTESTATION_FAILED | Android | A critical error occurred during the `getAttestation` operation | -| KEY_IS_NOT_HARDWARE_BACKED | Android | The device doesn't support hardware backed keys, thus it cannot be trusted | -| UNSUPPORTED_DEVICE | Android | The device doesn't support the requested functionality | -| KEYSTORE_NOT_INITIALIZED | Android | A critical error occurred while initializing the keystore service | +| TypeName | Platform | Description | +| :--------------------------------------: | :---------: | ---------------------------------------------------------------------------------------------------- | +| WRONG_GOOGLE_CLOUD_PROJECT_NUMBER_FORMAT | Android | A wrong value for `GOOGLE_CLOUD_PROJECT_NUMBER` has been provided to `prepareIntegrityToken` | +| PREPARE_FAILED | Android | A critical error occurred during the `prepareIntegrityToken` operation | +| PREPARE_NOT_CALLED | Android | The `requestIntegrityToken` has been called without calling `prepareIntegrityToken` beforehand | +| REQUEST_TOKEN_FAILED | Android | A critical error occurred during the `requestIntegrityToken` operation | +| REQUEST_ATTESTATION_FAILED | Android | A critical error occurred during the `getAttestation` operation | +| KEY_IS_NOT_HARDWARE_BACKED | Android | The device doesn't support hardware backed keys, thus it cannot be trusted | +| KEYSTORE_NOT_INITIALIZED | Android | A critical error occurred while initializing the keystore service | +| GENERATION_KEY_FAILED | iOS | A critical error occurred during the `generateHardwareKey` operation | +| ATTESTATION_ERROR | iOS | A critical error occurred during the `getAttestation` operation | +| UNSUPPORTED_IOS_VERSION | iOS | The device has a version of iOS that doesn't support the DeviceCheck App Attestation Service (<14.0) | +| CHALLENGE_ERROR | iOS | An error occured while encoding the provided challenge to `getAttestation` | +| CLIENT_DATA_ENCODING_ERROR | iOS | An error occured while encoding the provided client data to `generateHardwareSignatureWithAssertion` | +| GENERATION_ASSERTION_FAILED | iOS | A critical error occurred during the `generateHardwareSignatureWithAssertion` operation | +| UNSUPPORTED_DEVICE | iOS/Android | The device doesn't support the requested functionality | ## Contributing