Skip to content

Commit

Permalink
docs: update README.md
Browse files Browse the repository at this point in the history
  • Loading branch information
@LazyAfternoons
LazyAfternoons committed May 17, 2024
1 parent 4015530 commit ea62f1a
Showing 1 changed file with 64 additions and 11 deletions.
75 changes: 64 additions & 11 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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

Expand All @@ -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

Expand Down

0 comments on commit ea62f1a

Please sign in to comment.