@onekeyfe/react-native-aes-crypto 6.7.0-alpha.475 → 6.8.0-2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +126 -55
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,82 +1,153 @@
1
- # @onekeyfe/react-native-aes-crypto
1
+ <div align="center">
2
2
 
3
- Native cryptographic primitives for OneKey on iOS and Android: AES encryption,
4
- authenticated GCM operations, PBKDF2, HMAC, hashing and random values.
3
+ # @onekeyfe/react-native-aes-crypto
5
4
 
6
- ## Installation and usage
5
+ **Native AES, PBKDF2, HMAC, hashing and random-value primitives for OneKey apps on iOS and Android.**
7
6
 
8
- ```sh
9
- yarn add @onekeyfe/react-native-aes-crypto
10
- ```
7
+ [![npm](https://img.shields.io/npm/v/%40onekeyfe%2Freact-native-aes-crypto?label=npm&color=4D6BFE)](https://www.npmjs.com/package/@onekeyfe/react-native-aes-crypto)
8
+ [![license](https://img.shields.io/npm/l/%40onekeyfe%2Freact-native-aes-crypto?label=license&color=4D6BFE)](LICENSE)
9
+ ![iOS](https://img.shields.io/badge/iOS-000000?logo=apple&logoColor=white)
10
+ ![Android](https://img.shields.io/badge/Android-3DDC84?logo=android&logoColor=white)
11
+ ![TurboModule](https://img.shields.io/badge/TurboModule-4D6BFE)
11
12
 
12
- Install the application's iOS pods and rebuild its native binary. The exported
13
- functions return promises and depend on the native TurboModule.
13
+ </div>
14
14
 
15
- ```ts
16
- import { sha256, randomKey } from '@onekeyfe/react-native-aes-crypto';
15
+ Exposes the crypto primitives OneKey needs without a JavaScript crypto
16
+ implementation: AES-CBC/CTR encryption, AES-GCM authenticated encryption,
17
+ PBKDF2, HMAC-SHA256/512, SHA-1/256/512 and random values. Every call crosses a
18
+ React Native TurboModule and returns a promise; the module has no Web
19
+ implementation. Applications still own key storage, nonce uniqueness and the
20
+ decision of when a failure is fatal.
17
21
 
18
- const digest = await sha256('example message');
19
- const randomBytes = await randomKey(32);
20
- ```
22
+ ## Features
21
23
 
22
- ## API and formats
24
+ - **Audited-style AEAD surface** — AES-GCM with a stricter-than-RFC contract:
25
+ 12-byte nonce, non-empty AAD, and ciphertext with a trailing 16-byte tag.
26
+ - **Cross-platform byte compatibility** — iOS CryptoKit/CommonCrypto and Android
27
+ JCE/BouncyCastle are pinned to the same formats, so ciphertexts match.
28
+ - **Symmetric helpers** — AES-128/192/256 in CBC (PKCS#7) and CTR modes with hex
29
+ input and hex output.
30
+ - **Key derivation and MACs** — PBKDF2 with SHA-1/256/512 PRFs, HMAC-SHA256 and
31
+ HMAC-SHA512.
32
+ - **Random values** — `randomUuid()` and a cryptographically secure
33
+ `randomKey(length)`.
34
+ - **Fail-loud validation** — empty, malformed or non-integer arguments reject
35
+ with a stable error code instead of producing zero-length input.
23
36
 
24
- Named exports include `encrypt`, `decrypt`, `aesGcmEncrypt`, `aesGcmDecrypt`,
25
- `pbkdf2`, `hmac256`, `hmac512`, `sha1`, `sha256`, `sha512`, `randomUuid` and
26
- `randomKey`. The default export is the native module.
37
+ ## Installation
27
38
 
28
- The GCM helpers use lowercase hex inputs, a 12-byte nonce, a valid AES key
29
- length and nonempty associated data. Encryption returns ciphertext followed
30
- by a 16-byte authentication tag, encoded as hex. Decryption rejects when the
31
- inputs or authentication tag are invalid. Those formats are specific to the
32
- GCM helpers; do not assume that every other method uses the same encoding.
39
+ ```sh
40
+ yarn add @onekeyfe/react-native-aes-crypto
41
+ ```
33
42
 
34
- Use the exact signatures in [src/NativeAesCrypto.ts](src/NativeAesCrypto.ts) and
35
- the GCM contract comments in [src/index.tsx](src/index.tsx). Applications own
36
- key storage, nonce uniqueness, input encoding and handling promise failures.
43
+ Install the application's iOS pods and rebuild the native binary; this package is
44
+ a TurboModule, so a JavaScript-only install does not register it. The iOS pod
45
+ links `Security` and `CryptoKit`; Android resolves its dependencies through
46
+ autolinking. No permissions or `Info.plist` keys are required.
37
47
 
38
- ## Authenticated-encryption interoperability
48
+ ## Usage
39
49
 
40
- `aesGcmEncrypt(data, key, nonce, aad)` and
41
- `aesGcmDecrypt(ciphertextWithTag, key, nonce, aad)` operate on hex strings.
42
- An empty plaintext is allowed and produces only the 16-byte tag. The ciphertext
43
- passed to decryption must contain at least that tag. Use the identical key,
44
- nonce and associated-data bytes when decrypting; mismatches reject.
50
+ ```ts
51
+ import {
52
+ sha256,
53
+ randomKey,
54
+ aesGcmEncrypt,
55
+ aesGcmDecrypt,
56
+ } from '@onekeyfe/react-native-aes-crypto';
57
+
58
+ // Every string argument is hex-encoded bytes; every result is hex.
59
+ const digest = await sha256('68656c6c6f');
60
+
61
+ const key = await randomKey(32); // 32 random bytes, 64 hex characters
62
+ const nonce = await randomKey(12); // GCM requires exactly 12 nonce bytes
63
+ const sealed = await aesGcmEncrypt('deadbeef', key, nonce, '0102');
64
+ const opened = await aesGcmDecrypt(sealed, key, nonce, '0102');
65
+
66
+ console.log(digest, opened); // opened === 'deadbeef'
67
+ ```
45
68
 
46
- The bridge accepts 16-, 24- or 32-byte AES keys and exactly 12 nonce bytes.
47
- It rejects empty associated data and malformed hex. Keep these GCM parameters
48
- separate from `encrypt(data, key, iv, algorithm)` and
49
- `decrypt(base64, key, iv, algorithm)`, whose signatures and formats differ.
50
- The exported `AesCryptoSpec` type describes the raw native surface.
69
+ The application owns key storage, nonce uniqueness and long-term encoding of the
70
+ hex strings; the module does not persist anything.
71
+
72
+ ## API
73
+
74
+ | Export | Signature | Platforms | Description |
75
+ | --- | --- | :-: | --- |
76
+ | `encrypt` | `(data, key, iv, algorithm) => Promise<string>` | iOS, Android | AES encrypt; `algorithm` is `aes-128-cbc`, `aes-192-cbc`, `aes-256-cbc`, or the matching `-ctr` name. |
77
+ | `decrypt` | `(ciphertext, key, iv, algorithm) => Promise<string>` | iOS, Android | Inverse of `encrypt`; returns hex. |
78
+ | `aesGcmEncrypt` | `(data, key, nonce, aad) => Promise<string>` | iOS, Android | Returns hex `ciphertext || 16-byte tag`; empty plaintext is allowed. |
79
+ | `aesGcmDecrypt` | `(ciphertextWithTag, key, nonce, aad) => Promise<string>` | iOS, Android | Verifies the tag; parameters must match the encryption call byte for byte. |
80
+ | `pbkdf2` | `(password, salt, cost, length, algorithm) => Promise<string>` | iOS, Android | PBKDF2; `length` is in bits, `algorithm` is `sha1`, `sha256` or `sha512`. |
81
+ | `hmac256` | `(data, key) => Promise<string>` | iOS, Android | HMAC-SHA256 over hex-decoded bytes. |
82
+ | `hmac512` | `(data, key) => Promise<string>` | iOS, Android | HMAC-SHA512 over hex-decoded bytes. |
83
+ | `sha1` | `(text) => Promise<string>` | iOS, Android | SHA-1 digest of hex-decoded bytes. |
84
+ | `sha256` | `(text) => Promise<string>` | iOS, Android | SHA-256 digest of hex-decoded bytes. |
85
+ | `sha512` | `(text) => Promise<string>` | iOS, Android | SHA-512 digest of hex-decoded bytes. |
86
+ | `randomUuid` | `() => Promise<string>` | iOS, Android | Random UUID string. |
87
+ | `randomKey` | `(length) => Promise<string>` | iOS, Android | `length` secure random bytes, returned as hex. |
88
+
89
+ All failures reject with code `"-1"`. The default export is the raw TurboModule;
90
+ named exports wrap the same methods. See
91
+ [`src/NativeAesCrypto.ts`](src/NativeAesCrypto.ts) for the bridge contract and
92
+ [`src/index.tsx`](src/index.tsx) for the documented GCM rules.
93
+
94
+ ## Platform support
95
+
96
+ | Capability | iOS | Android | Web |
97
+ | --- | :-: | :-: | :-: |
98
+ | AES-CBC / AES-CTR encrypt and decrypt | ✅ | ✅ | — |
99
+ | AES-GCM authenticated encryption | ✅ | ✅ | — |
100
+ | PBKDF2 | ✅ | ✅ | — |
101
+ | HMAC-SHA256 / HMAC-SHA512 | ✅ | ✅ | — |
102
+ | SHA-1 / SHA-256 / SHA-512 | ✅ | ✅ | — |
103
+ | Random UUID and random bytes | ✅ | ✅ | — |
104
+
105
+ ## Caveats
106
+
107
+ > [!IMPORTANT]
108
+ > String arguments are not UTF-8 text: they are hex-encoded byte arrays. Pass
109
+ > `'68656c6c6f'`, not `'hello'`, to `sha256`, HMAC and AES functions; malformed
110
+ > hex rejects instead of hashing the literal string.
111
+
112
+ > [!WARNING]
113
+ > GCM is deliberately stricter than RFC 5116: the nonce is exactly 12 bytes, AAD
114
+ > must be non-empty, the key must decode to 16, 24 or 32 bytes, and the
115
+ > ciphertext passed to decryption must include the 16-byte tag. Any mismatch
116
+ > rejects as a tag-verification failure.
117
+
118
+ > [!NOTE]
119
+ > PBKDF2 `length` is in bits and `cost`/`length` must be positive integers. Never
120
+ > reuse a GCM nonce with the same key.
121
+
122
+ ## References
123
+
124
+ - [Changelog](../../CHANGELOG.md)
51
125
 
52
126
  ## Upstream attribution
53
127
 
54
- First, a sincere thank-you to tectiv3 and the
55
- `react-native-aes-crypto` maintainers for their excellent work 🙏
128
+ <details>
129
+ <summary>Forked from <code>tectiv3/react-native-aes</code></summary>
56
130
 
57
- This package is built on, and inspired by,
58
- [tectiv3/react-native-aes](https://github.com/tectiv3/react-native-aes).
131
+ First, a sincere thank-you to tectiv3 and the `react-native-aes-crypto` maintainers for their excellent work 🙏
59
132
 
60
- Our original plan was to keep our customizations as patches on top of upstream
61
- `react-native-aes-crypto`.
133
+ This package is built on, and inspired by, [tectiv3/react-native-aes](https://github.com/tectiv3/react-native-aes).
62
134
 
63
- As our product requirements evolved, the scope of those changes outgrew what we
64
- could reasonably maintain as an upstream patch set. We regret that we were
65
- unable to keep this work in patch form.
135
+ Our original plan was to keep our customizations as patches on top of upstream `react-native-aes-crypto`. As our product requirements evolved, the scope of those changes outgrew what we could reasonably maintain as an upstream patch set. We regret that we were unable to keep this work in patch form. As the gap grew, we ultimately forked `react-native-aes-crypto` to keep development and delivery stable.
66
136
 
67
- As the gap grew, we ultimately forked `react-native-aes-crypto` to keep
68
- development and delivery stable.
69
-
70
- ## Upstream Project
137
+ ### Upstream Project
71
138
 
72
139
  - Repository: [tectiv3/react-native-aes](https://github.com/tectiv3/react-native-aes)
73
140
  - License: MIT
74
141
 
75
- ## Notes
142
+ ### Notes
76
143
 
77
144
  - This fork includes OneKey-specific adaptations for our product requirements.
78
- - If you are looking for original behavior and full documentation, please refer
79
- to the upstream repository.
145
+ - If you are looking for original behavior and full documentation, please refer to the upstream repository.
146
+
147
+ Thank you again to tectiv3 and everyone who contributes to `react-native-aes-crypto` 💙
148
+
149
+ </details>
150
+
151
+ ## License
80
152
 
81
- Thank you again to tectiv3 and everyone who contributes to
82
- `react-native-aes-crypto` 💙
153
+ MIT. See [LICENSE](LICENSE).
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@onekeyfe/react-native-aes-crypto",
3
- "version": "6.7.0-alpha.475",
3
+ "version": "6.8.0-2",
4
4
  "description": "react-native-aes-crypto",
5
5
  "main": "./lib/module/index.js",
6
6
  "types": "./lib/typescript/src/index.d.ts",