@enbox/crypto 0.0.1

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 (283) hide show
  1. package/LICENSE +201 -0
  2. package/README.md +708 -0
  3. package/dist/browser.js +64 -0
  4. package/dist/browser.js.map +7 -0
  5. package/dist/browser.mjs +64 -0
  6. package/dist/browser.mjs.map +7 -0
  7. package/dist/cjs/algorithms/aes-ctr.js +188 -0
  8. package/dist/cjs/algorithms/aes-ctr.js.map +1 -0
  9. package/dist/cjs/algorithms/aes-gcm.js +196 -0
  10. package/dist/cjs/algorithms/aes-gcm.js.map +1 -0
  11. package/dist/cjs/algorithms/crypto-algorithm.js +13 -0
  12. package/dist/cjs/algorithms/crypto-algorithm.js.map +1 -0
  13. package/dist/cjs/algorithms/ecdsa.js +352 -0
  14. package/dist/cjs/algorithms/ecdsa.js.map +1 -0
  15. package/dist/cjs/algorithms/eddsa.js +325 -0
  16. package/dist/cjs/algorithms/eddsa.js.map +1 -0
  17. package/dist/cjs/algorithms/sha-2.js +119 -0
  18. package/dist/cjs/algorithms/sha-2.js.map +1 -0
  19. package/dist/cjs/index.js +41 -0
  20. package/dist/cjs/index.js.map +1 -0
  21. package/dist/cjs/jose/jwe.js +3 -0
  22. package/dist/cjs/jose/jwe.js.map +1 -0
  23. package/dist/cjs/jose/jwk.js +278 -0
  24. package/dist/cjs/jose/jwk.js.map +1 -0
  25. package/dist/cjs/jose/jws.js +3 -0
  26. package/dist/cjs/jose/jws.js.map +1 -0
  27. package/dist/cjs/jose/jwt.js +3 -0
  28. package/dist/cjs/jose/jwt.js.map +1 -0
  29. package/dist/cjs/jose/utils.js +60 -0
  30. package/dist/cjs/jose/utils.js.map +1 -0
  31. package/dist/cjs/local-key-manager.js +521 -0
  32. package/dist/cjs/local-key-manager.js.map +1 -0
  33. package/dist/cjs/package.json +1 -0
  34. package/dist/cjs/primitives/aes-ctr.js +398 -0
  35. package/dist/cjs/primitives/aes-ctr.js.map +1 -0
  36. package/dist/cjs/primitives/aes-gcm.js +425 -0
  37. package/dist/cjs/primitives/aes-gcm.js.map +1 -0
  38. package/dist/cjs/primitives/concat-kdf.js +215 -0
  39. package/dist/cjs/primitives/concat-kdf.js.map +1 -0
  40. package/dist/cjs/primitives/ed25519.js +651 -0
  41. package/dist/cjs/primitives/ed25519.js.map +1 -0
  42. package/dist/cjs/primitives/pbkdf2.js +120 -0
  43. package/dist/cjs/primitives/pbkdf2.js.map +1 -0
  44. package/dist/cjs/primitives/secp256k1.js +958 -0
  45. package/dist/cjs/primitives/secp256k1.js.map +1 -0
  46. package/dist/cjs/primitives/secp256r1.js +959 -0
  47. package/dist/cjs/primitives/secp256r1.js.map +1 -0
  48. package/dist/cjs/primitives/sha256.js +93 -0
  49. package/dist/cjs/primitives/sha256.js.map +1 -0
  50. package/dist/cjs/primitives/x25519.js +498 -0
  51. package/dist/cjs/primitives/x25519.js.map +1 -0
  52. package/dist/cjs/primitives/xchacha20-poly1305.js +340 -0
  53. package/dist/cjs/primitives/xchacha20-poly1305.js.map +1 -0
  54. package/dist/cjs/primitives/xchacha20.js +316 -0
  55. package/dist/cjs/primitives/xchacha20.js.map +1 -0
  56. package/dist/cjs/types/cipher.js +3 -0
  57. package/dist/cjs/types/cipher.js.map +1 -0
  58. package/dist/cjs/types/crypto-api.js +3 -0
  59. package/dist/cjs/types/crypto-api.js.map +1 -0
  60. package/dist/cjs/types/hasher.js +3 -0
  61. package/dist/cjs/types/hasher.js.map +1 -0
  62. package/dist/cjs/types/identifier.js +3 -0
  63. package/dist/cjs/types/identifier.js.map +1 -0
  64. package/dist/cjs/types/key-compressor.js +3 -0
  65. package/dist/cjs/types/key-compressor.js.map +1 -0
  66. package/dist/cjs/types/key-converter.js +3 -0
  67. package/dist/cjs/types/key-converter.js.map +1 -0
  68. package/dist/cjs/types/key-deriver.js +3 -0
  69. package/dist/cjs/types/key-deriver.js.map +1 -0
  70. package/dist/cjs/types/key-generator.js +3 -0
  71. package/dist/cjs/types/key-generator.js.map +1 -0
  72. package/dist/cjs/types/key-io.js +3 -0
  73. package/dist/cjs/types/key-io.js.map +1 -0
  74. package/dist/cjs/types/key-wrapper.js +3 -0
  75. package/dist/cjs/types/key-wrapper.js.map +1 -0
  76. package/dist/cjs/types/params-direct.js +3 -0
  77. package/dist/cjs/types/params-direct.js.map +1 -0
  78. package/dist/cjs/types/params-enclosed.js +3 -0
  79. package/dist/cjs/types/params-enclosed.js.map +1 -0
  80. package/dist/cjs/types/params-kms.js +3 -0
  81. package/dist/cjs/types/params-kms.js.map +1 -0
  82. package/dist/cjs/types/signer.js +3 -0
  83. package/dist/cjs/types/signer.js.map +1 -0
  84. package/dist/cjs/utils.js +173 -0
  85. package/dist/cjs/utils.js.map +1 -0
  86. package/dist/esm/algorithms/aes-ctr.js +124 -0
  87. package/dist/esm/algorithms/aes-ctr.js.map +1 -0
  88. package/dist/esm/algorithms/aes-gcm.js +132 -0
  89. package/dist/esm/algorithms/aes-gcm.js.map +1 -0
  90. package/dist/esm/algorithms/crypto-algorithm.js +6 -0
  91. package/dist/esm/algorithms/crypto-algorithm.js.map +1 -0
  92. package/dist/esm/algorithms/ecdsa.js +237 -0
  93. package/dist/esm/algorithms/ecdsa.js.map +1 -0
  94. package/dist/esm/algorithms/eddsa.js +213 -0
  95. package/dist/esm/algorithms/eddsa.js.map +1 -0
  96. package/dist/esm/algorithms/sha-2.js +57 -0
  97. package/dist/esm/algorithms/sha-2.js.map +1 -0
  98. package/dist/esm/index.js +25 -0
  99. package/dist/esm/index.js.map +1 -0
  100. package/dist/esm/jose/jwe.js +2 -0
  101. package/dist/esm/jose/jwe.js.map +1 -0
  102. package/dist/esm/jose/jwk.js +241 -0
  103. package/dist/esm/jose/jwk.js.map +1 -0
  104. package/dist/esm/jose/jws.js +2 -0
  105. package/dist/esm/jose/jws.js.map +1 -0
  106. package/dist/esm/jose/jwt.js +2 -0
  107. package/dist/esm/jose/jwt.js.map +1 -0
  108. package/dist/esm/jose/utils.js +34 -0
  109. package/dist/esm/jose/utils.js.map +1 -0
  110. package/dist/esm/local-key-manager.js +417 -0
  111. package/dist/esm/local-key-manager.js.map +1 -0
  112. package/dist/esm/primitives/aes-ctr.js +327 -0
  113. package/dist/esm/primitives/aes-ctr.js.map +1 -0
  114. package/dist/esm/primitives/aes-gcm.js +347 -0
  115. package/dist/esm/primitives/aes-gcm.js.map +1 -0
  116. package/dist/esm/primitives/concat-kdf.js +185 -0
  117. package/dist/esm/primitives/concat-kdf.js.map +1 -0
  118. package/dist/esm/primitives/ed25519.js +521 -0
  119. package/dist/esm/primitives/ed25519.js.map +1 -0
  120. package/dist/esm/primitives/pbkdf2.js +78 -0
  121. package/dist/esm/primitives/pbkdf2.js.map +1 -0
  122. package/dist/esm/primitives/secp256k1.js +805 -0
  123. package/dist/esm/primitives/secp256k1.js.map +1 -0
  124. package/dist/esm/primitives/secp256r1.js +806 -0
  125. package/dist/esm/primitives/secp256r1.js.map +1 -0
  126. package/dist/esm/primitives/sha256.js +55 -0
  127. package/dist/esm/primitives/sha256.js.map +1 -0
  128. package/dist/esm/primitives/x25519.js +392 -0
  129. package/dist/esm/primitives/x25519.js.map +1 -0
  130. package/dist/esm/primitives/xchacha20-poly1305.js +270 -0
  131. package/dist/esm/primitives/xchacha20-poly1305.js.map +1 -0
  132. package/dist/esm/primitives/xchacha20.js +246 -0
  133. package/dist/esm/primitives/xchacha20.js.map +1 -0
  134. package/dist/esm/types/cipher.js +2 -0
  135. package/dist/esm/types/cipher.js.map +1 -0
  136. package/dist/esm/types/crypto-api.js +2 -0
  137. package/dist/esm/types/crypto-api.js.map +1 -0
  138. package/dist/esm/types/hasher.js +2 -0
  139. package/dist/esm/types/hasher.js.map +1 -0
  140. package/dist/esm/types/identifier.js +2 -0
  141. package/dist/esm/types/identifier.js.map +1 -0
  142. package/dist/esm/types/key-compressor.js +2 -0
  143. package/dist/esm/types/key-compressor.js.map +1 -0
  144. package/dist/esm/types/key-converter.js +2 -0
  145. package/dist/esm/types/key-converter.js.map +1 -0
  146. package/dist/esm/types/key-deriver.js +2 -0
  147. package/dist/esm/types/key-deriver.js.map +1 -0
  148. package/dist/esm/types/key-generator.js +2 -0
  149. package/dist/esm/types/key-generator.js.map +1 -0
  150. package/dist/esm/types/key-io.js +2 -0
  151. package/dist/esm/types/key-io.js.map +1 -0
  152. package/dist/esm/types/key-wrapper.js +2 -0
  153. package/dist/esm/types/key-wrapper.js.map +1 -0
  154. package/dist/esm/types/params-direct.js +2 -0
  155. package/dist/esm/types/params-direct.js.map +1 -0
  156. package/dist/esm/types/params-enclosed.js +2 -0
  157. package/dist/esm/types/params-enclosed.js.map +1 -0
  158. package/dist/esm/types/params-kms.js +2 -0
  159. package/dist/esm/types/params-kms.js.map +1 -0
  160. package/dist/esm/types/signer.js +2 -0
  161. package/dist/esm/types/signer.js.map +1 -0
  162. package/dist/esm/utils.js +165 -0
  163. package/dist/esm/utils.js.map +1 -0
  164. package/dist/types/algorithms/aes-ctr.d.ts +121 -0
  165. package/dist/types/algorithms/aes-ctr.d.ts.map +1 -0
  166. package/dist/types/algorithms/aes-gcm.d.ts +152 -0
  167. package/dist/types/algorithms/aes-gcm.d.ts.map +1 -0
  168. package/dist/types/algorithms/crypto-algorithm.d.ts +6 -0
  169. package/dist/types/algorithms/crypto-algorithm.d.ts.map +1 -0
  170. package/dist/types/algorithms/ecdsa.d.ts +154 -0
  171. package/dist/types/algorithms/ecdsa.d.ts.map +1 -0
  172. package/dist/types/algorithms/eddsa.d.ts +151 -0
  173. package/dist/types/algorithms/eddsa.d.ts.map +1 -0
  174. package/dist/types/algorithms/sha-2.d.ts +51 -0
  175. package/dist/types/algorithms/sha-2.d.ts.map +1 -0
  176. package/dist/types/index.d.ts +39 -0
  177. package/dist/types/index.d.ts.map +1 -0
  178. package/dist/types/jose/jwe.d.ts +135 -0
  179. package/dist/types/jose/jwe.d.ts.map +1 -0
  180. package/dist/types/jose/jwk.d.ts +439 -0
  181. package/dist/types/jose/jwk.d.ts.map +1 -0
  182. package/dist/types/jose/jws.d.ts +67 -0
  183. package/dist/types/jose/jws.d.ts.map +1 -0
  184. package/dist/types/jose/jwt.d.ts +139 -0
  185. package/dist/types/jose/jwt.d.ts.map +1 -0
  186. package/dist/types/jose/utils.d.ts +14 -0
  187. package/dist/types/jose/utils.d.ts.map +1 -0
  188. package/dist/types/local-key-manager.d.ts +307 -0
  189. package/dist/types/local-key-manager.d.ts.map +1 -0
  190. package/dist/types/primitives/aes-ctr.d.ts +219 -0
  191. package/dist/types/primitives/aes-ctr.d.ts.map +1 -0
  192. package/dist/types/primitives/aes-gcm.d.ts +245 -0
  193. package/dist/types/primitives/aes-gcm.d.ts.map +1 -0
  194. package/dist/types/primitives/concat-kdf.d.ts +160 -0
  195. package/dist/types/primitives/concat-kdf.d.ts.map +1 -0
  196. package/dist/types/primitives/ed25519.d.ts +359 -0
  197. package/dist/types/primitives/ed25519.d.ts.map +1 -0
  198. package/dist/types/primitives/pbkdf2.d.ts +94 -0
  199. package/dist/types/primitives/pbkdf2.d.ts.map +1 -0
  200. package/dist/types/primitives/secp256k1.d.ts +598 -0
  201. package/dist/types/primitives/secp256k1.d.ts.map +1 -0
  202. package/dist/types/primitives/secp256r1.d.ts +599 -0
  203. package/dist/types/primitives/secp256r1.d.ts.map +1 -0
  204. package/dist/types/primitives/sha256.d.ts +42 -0
  205. package/dist/types/primitives/sha256.d.ts.map +1 -0
  206. package/dist/types/primitives/x25519.d.ts +283 -0
  207. package/dist/types/primitives/x25519.d.ts.map +1 -0
  208. package/dist/types/primitives/xchacha20-poly1305.d.ts +210 -0
  209. package/dist/types/primitives/xchacha20-poly1305.d.ts.map +1 -0
  210. package/dist/types/primitives/xchacha20.d.ts +186 -0
  211. package/dist/types/primitives/xchacha20.d.ts.map +1 -0
  212. package/dist/types/types/cipher.d.ts +49 -0
  213. package/dist/types/types/cipher.d.ts.map +1 -0
  214. package/dist/types/types/crypto-api.d.ts +40 -0
  215. package/dist/types/types/crypto-api.d.ts.map +1 -0
  216. package/dist/types/types/hasher.d.ts +33 -0
  217. package/dist/types/types/hasher.d.ts.map +1 -0
  218. package/dist/types/types/identifier.d.ts +16 -0
  219. package/dist/types/types/identifier.d.ts.map +1 -0
  220. package/dist/types/types/key-compressor.d.ts +28 -0
  221. package/dist/types/types/key-compressor.d.ts.map +1 -0
  222. package/dist/types/types/key-converter.d.ts +57 -0
  223. package/dist/types/types/key-converter.d.ts.map +1 -0
  224. package/dist/types/types/key-deriver.d.ts +39 -0
  225. package/dist/types/types/key-deriver.d.ts.map +1 -0
  226. package/dist/types/types/key-generator.d.ts +105 -0
  227. package/dist/types/types/key-generator.d.ts.map +1 -0
  228. package/dist/types/types/key-io.d.ts +37 -0
  229. package/dist/types/types/key-io.d.ts.map +1 -0
  230. package/dist/types/types/key-wrapper.d.ts +38 -0
  231. package/dist/types/types/key-wrapper.d.ts.map +1 -0
  232. package/dist/types/types/params-direct.d.ts +90 -0
  233. package/dist/types/types/params-direct.d.ts.map +1 -0
  234. package/dist/types/types/params-enclosed.d.ts +47 -0
  235. package/dist/types/types/params-enclosed.d.ts.map +1 -0
  236. package/dist/types/types/params-kms.d.ts +131 -0
  237. package/dist/types/types/params-kms.d.ts.map +1 -0
  238. package/dist/types/types/signer.d.ts +46 -0
  239. package/dist/types/types/signer.d.ts.map +1 -0
  240. package/dist/types/utils.d.ts +112 -0
  241. package/dist/types/utils.d.ts.map +1 -0
  242. package/dist/utils.js +7 -0
  243. package/dist/utils.js.map +7 -0
  244. package/package.json +103 -0
  245. package/src/algorithms/aes-ctr.ts +156 -0
  246. package/src/algorithms/aes-gcm.ts +187 -0
  247. package/src/algorithms/crypto-algorithm.ts +4 -0
  248. package/src/algorithms/ecdsa.ts +269 -0
  249. package/src/algorithms/eddsa.ts +243 -0
  250. package/src/algorithms/sha-2.ts +65 -0
  251. package/src/index.ts +42 -0
  252. package/src/jose/jwe.ts +196 -0
  253. package/src/jose/jwk.ts +632 -0
  254. package/src/jose/jws.ts +95 -0
  255. package/src/jose/jwt.ts +147 -0
  256. package/src/jose/utils.ts +34 -0
  257. package/src/local-key-manager.ts +540 -0
  258. package/src/primitives/aes-ctr.ts +352 -0
  259. package/src/primitives/aes-gcm.ts +378 -0
  260. package/src/primitives/concat-kdf.ts +240 -0
  261. package/src/primitives/ed25519.ts +548 -0
  262. package/src/primitives/pbkdf2.ts +122 -0
  263. package/src/primitives/secp256k1.ts +848 -0
  264. package/src/primitives/secp256r1.ts +850 -0
  265. package/src/primitives/sha256.ts +47 -0
  266. package/src/primitives/x25519.ts +403 -0
  267. package/src/primitives/xchacha20-poly1305.ts +274 -0
  268. package/src/primitives/xchacha20.ts +247 -0
  269. package/src/types/cipher.ts +53 -0
  270. package/src/types/crypto-api.ts +56 -0
  271. package/src/types/hasher.ts +32 -0
  272. package/src/types/identifier.ts +16 -0
  273. package/src/types/key-compressor.ts +25 -0
  274. package/src/types/key-converter.ts +53 -0
  275. package/src/types/key-deriver.ts +43 -0
  276. package/src/types/key-generator.ts +119 -0
  277. package/src/types/key-io.ts +42 -0
  278. package/src/types/key-wrapper.ts +42 -0
  279. package/src/types/params-direct.ts +106 -0
  280. package/src/types/params-enclosed.ts +50 -0
  281. package/src/types/params-kms.ts +156 -0
  282. package/src/types/signer.ts +50 -0
  283. package/src/utils.ts +181 -0
@@ -0,0 +1,283 @@
1
+ import type { Jwk } from '../jose/jwk.js';
2
+ import type { ComputePublicKeyParams, GetPublicKeyParams } from '../types/params-direct.js';
3
+ /**
4
+ * The `X25519` class provides a comprehensive suite of utilities for working with the X25519
5
+ * elliptic curve, widely used for key agreement protocols and cryptographic applications. It
6
+ * provides methods for key generation, conversion, and Elliptic Curve Diffie-Hellman (ECDH)
7
+ * key agreement, all aligned with standard cryptographic practices.
8
+ *
9
+ * The class supports conversions between raw byte formats and JSON Web Key (JWK) formats,
10
+ * making it versatile for various cryptographic tasks. It adheres to RFC6090 for ECDH, ensuring
11
+ * secure and effective handling of keys and cryptographic operations.
12
+ *
13
+ * Key Features:
14
+ * - Key Generation: Generate X25519 private keys in JWK format.
15
+ * - Key Conversion: Transform keys between raw byte arrays and JWK formats.
16
+ * - Public Key Derivation: Derive public keys from private keys.
17
+ * - ECDH Shared Secret Computation: Securely derive shared secrets using private and public keys.
18
+ *
19
+ * The methods in this class are asynchronous, returning Promises to accommodate various
20
+ * JavaScript environments.
21
+ *
22
+ * @example
23
+ * ```ts
24
+ * // Key Generation
25
+ * const privateKey = await X25519.generateKey();
26
+ *
27
+ * // Public Key Derivation
28
+ * const publicKey = await X25519.computePublicKey({ key: privateKey });
29
+ * console.log(publicKey === await X25519.getPublicKey({ key: privateKey })); // Output: true
30
+ *
31
+ * // ECDH Shared Secret Computation
32
+ * const sharedSecret = await X25519.sharedSecret({
33
+ * privateKeyA: privateKey,
34
+ * publicKeyB: anotherPublicKey
35
+ * });
36
+ *
37
+ * // Key Conversion
38
+ * const publicKeyBytes = await X25519.publicKeyToBytes({ publicKey });
39
+ * const privateKeyBytes = await X25519.privateKeyToBytes({ privateKey });
40
+ * ```
41
+ */
42
+ export declare class X25519 {
43
+ /**
44
+ * Converts a raw private key in bytes to its corresponding JSON Web Key (JWK) format.
45
+ *
46
+ * @remarks
47
+ * This method accepts a private key as a byte array (Uint8Array) for the X25519 elliptic curve
48
+ * and transforms it into a JWK object. The process involves first deriving the public key from
49
+ * the private key, then encoding both the private and public keys into base64url format.
50
+ *
51
+ * The resulting JWK object includes the following properties:
52
+ * - `kty`: Key Type, set to 'OKP' for Octet Key Pair.
53
+ * - `crv`: Curve Name, set to 'X25519'.
54
+ * - `d`: The private key component, base64url-encoded.
55
+ * - `x`: The derived public key, base64url-encoded.
56
+ *
57
+ * This method is useful for converting raw public keys into a standardized
58
+ * JSON format, facilitating their use in cryptographic operations and making
59
+ * them easy to share and store.
60
+ *
61
+ * @example
62
+ * ```ts
63
+ * const privateKeyBytes = new Uint8Array([...]); // Replace with actual private key bytes
64
+ * const privateKey = await X25519.bytesToPrivateKey({ privateKeyBytes });
65
+ * ```
66
+ *
67
+ * @param params - The parameters for the private key conversion.
68
+ * @param params.privateKeyBytes - The raw private key as a Uint8Array.
69
+ *
70
+ * @returns A Promise that resolves to the private key in JWK format.
71
+ */
72
+ static bytesToPrivateKey({ privateKeyBytes }: {
73
+ privateKeyBytes: Uint8Array;
74
+ }): Promise<Jwk>;
75
+ /**
76
+ * Converts a raw public key in bytes to its corresponding JSON Web Key (JWK) format.
77
+ *
78
+ * @remarks
79
+ * This method accepts a public key as a byte array (Uint8Array) for the X25519 elliptic curve
80
+ * and transforms it into a JWK object. The conversion process involves encoding the public
81
+ * key bytes into base64url format.
82
+ *
83
+ * The resulting JWK object includes the following properties:
84
+ * - `kty`: Key Type, set to 'OKP' for Octet Key Pair.
85
+ * - `crv`: Curve Name, set to 'X25519'.
86
+ * - `x`: The public key, base64url-encoded.
87
+ *
88
+ * This method is useful for converting raw public keys into a standardized
89
+ * JSON format, facilitating their use in cryptographic operations and making
90
+ * them easy to share and store.
91
+ *
92
+ * @example
93
+ * ```ts
94
+ * const publicKeyBytes = new Uint8Array([...]); // Replace with actual public key bytes
95
+ * const publicKey = await X25519.bytesToPublicKey({ publicKeyBytes });
96
+ * ```
97
+ *
98
+ * @param params - The parameters for the public key conversion.
99
+ * @param params.publicKeyBytes - The raw public key as a Uint8Array.
100
+ *
101
+ * @returns A Promise that resolves to the public key in JWK format.
102
+ */
103
+ static bytesToPublicKey({ publicKeyBytes }: {
104
+ publicKeyBytes: Uint8Array;
105
+ }): Promise<Jwk>;
106
+ /**
107
+ * Derives the public key in JWK format from a given X25519 private key.
108
+ *
109
+ * @remarks
110
+ * This method takes a private key in JWK format and derives its corresponding public key,
111
+ * also in JWK format. The derivation process involves converting the private key to a
112
+ * raw byte array and then computing the corresponding public key on the Curve25519 curve.
113
+ * The public key is then encoded into base64url format to construct a JWK representation.
114
+ *
115
+ * The process ensures that the derived public key correctly corresponds to the given private key,
116
+ * adhering to the Curve25519 elliptic curve in Twisted Edwards form standards. This method is
117
+ * useful in cryptographic operations where a public key is needed for operations like signature
118
+ * verification, but only the private key is available.
119
+ *
120
+ * @example
121
+ * ```ts
122
+ * const privateKey = { ... }; // A Jwk object representing an X25519 private key
123
+ * const publicKey = await X25519.computePublicKey({ key: privateKey });
124
+ * ```
125
+ *
126
+ * @param params - The parameters for the public key derivation.
127
+ * @param params.key - The private key in JWK format from which to derive the public key.
128
+ *
129
+ * @returns A Promise that resolves to the derived public key in JWK format.
130
+ */
131
+ static computePublicKey({ key }: ComputePublicKeyParams): Promise<Jwk>;
132
+ /**
133
+ * Generates an X25519 private key in JSON Web Key (JWK) format.
134
+ *
135
+ * @remarks
136
+ * This method creates a new private key suitable for use with the X25519 elliptic curve.
137
+ * The key generation process involves using cryptographically secure random number generation
138
+ * to ensure the uniqueness and security of the key. The resulting private key adheres to the
139
+ * JWK format making it compatible with common cryptographic standards and easy to use in various
140
+ * cryptographic processes.
141
+ *
142
+ * The generated private key in JWK format includes the following components:
143
+ * - `kty`: Key Type, set to 'OKP' for Octet Key Pair.
144
+ * - `crv`: Curve Name, set to 'X25519'.
145
+ * - `d`: The private key component, base64url-encoded.
146
+ * - `x`: The derived public key, base64url-encoded.
147
+ *
148
+ * The key is returned in a format suitable for direct use in key agreement operations.
149
+ *
150
+ * @example
151
+ * ```ts
152
+ * const privateKey = await X25519.generateKey();
153
+ * ```
154
+ *
155
+ * @returns A Promise that resolves to the generated private key in JWK format.
156
+ */
157
+ static generateKey(): Promise<Jwk>;
158
+ /**
159
+ * Retrieves the public key properties from a given private key in JWK format.
160
+ *
161
+ * @remarks
162
+ * This method extracts the public key portion from an X25519 private key in JWK format. It does
163
+ * so by removing the private key property 'd' and making a shallow copy, effectively yielding the
164
+ * public key. The method sets the 'kid' (key ID) property using the JWK thumbprint if it is not
165
+ * already defined. This approach is used under the assumption that a private key in JWK format
166
+ * always contains the corresponding public key properties.
167
+ *
168
+ * Note: This method offers a significant performance advantage, being about 500 times faster
169
+ * than `computePublicKey()`. However, it does not mathematically validate the private key, nor
170
+ * does it derive the public key from the private key. It simply extracts existing public key
171
+ * properties from the private key object. This makes it suitable for scenarios where speed is
172
+ * critical and the private key's integrity is already assured.
173
+ *
174
+ * @example
175
+ * ```ts
176
+ * const privateKey = { ... }; // A Jwk object representing an X25519 private key
177
+ * const publicKey = await X25519.getPublicKey({ key: privateKey });
178
+ * ```
179
+ *
180
+ * @param params - The parameters for retrieving the public key properties.
181
+ * @param params.key - The private key in JWK format.
182
+ *
183
+ * @returns A Promise that resolves to the public key in JWK format.
184
+ */
185
+ static getPublicKey({ key }: GetPublicKeyParams): Promise<Jwk>;
186
+ /**
187
+ * Converts a private key from JSON Web Key (JWK) format to a raw byte array (Uint8Array).
188
+ *
189
+ * @remarks
190
+ * This method accepts a private key in JWK format and extracts its raw byte representation.
191
+ *
192
+ * This method accepts a public key in JWK format and converts it into its raw binary
193
+ * form. The conversion process involves decoding the 'd' parameter of the JWK
194
+ * from base64url format into a byte array.
195
+ *
196
+ * This conversion is essential for operations that require the private key in its raw
197
+ * binary form, such as certain low-level cryptographic operations or when interfacing
198
+ * with systems and libraries that expect keys in a byte array format.
199
+ *
200
+ * @example
201
+ * ```ts
202
+ * const privateKey = { ... }; // An X25519 private key in JWK format
203
+ * const privateKeyBytes = await X25519.privateKeyToBytes({ privateKey });
204
+ * ```
205
+ *
206
+ * @param params - The parameters for the private key conversion.
207
+ * @param params.privateKey - The private key in JWK format.
208
+ *
209
+ * @returns A Promise that resolves to the private key as a Uint8Array.
210
+ */
211
+ static privateKeyToBytes({ privateKey }: {
212
+ privateKey: Jwk;
213
+ }): Promise<Uint8Array>;
214
+ /**
215
+ * Converts a public key from JSON Web Key (JWK) format to a raw byte array (Uint8Array).
216
+ *
217
+ * @remarks
218
+ * This method accepts a public key in JWK format and converts it into its raw binary form.
219
+ * The conversion process involves decoding the 'x' parameter of the JWK (which represent the
220
+ * x coordinate of the elliptic curve point) from base64url format into a byte array.
221
+ *
222
+ * This conversion is essential for operations that require the public key in its raw
223
+ * binary form, such as certain low-level cryptographic operations or when interfacing
224
+ * with systems and libraries that expect keys in a byte array format.
225
+ *
226
+ * @example
227
+ * ```ts
228
+ * const publicKey = { ... }; // An X25519 public key in JWK format
229
+ * const publicKeyBytes = await X25519.publicKeyToBytes({ publicKey });
230
+ * ```
231
+ *
232
+ * @param params - The parameters for the public key conversion.
233
+ * @param params.publicKey - The public key in JWK format.
234
+ *
235
+ * @returns A Promise that resolves to the public key as a Uint8Array.
236
+ */
237
+ static publicKeyToBytes({ publicKey }: {
238
+ publicKey: Jwk;
239
+ }): Promise<Uint8Array>;
240
+ /**
241
+ * Computes an RFC6090-compliant Elliptic Curve Diffie-Hellman (ECDH) shared secret
242
+ * using secp256k1 private and public keys in JSON Web Key (JWK) format.
243
+ *
244
+ * @remarks
245
+ * This method facilitates the ECDH key agreement protocol, which is a method of securely
246
+ * deriving a shared secret between two parties based on their private and public keys.
247
+ * It takes the private key of one party (privateKeyA) and the public key of another
248
+ * party (publicKeyB) to compute a shared secret. The shared secret is derived from the
249
+ * x-coordinate of the elliptic curve point resulting from the multiplication of the
250
+ * public key with the private key.
251
+ *
252
+ * Note: When performing Elliptic Curve Diffie-Hellman (ECDH) key agreement,
253
+ * the resulting shared secret is a point on the elliptic curve, which
254
+ * consists of an x-coordinate and a y-coordinate. With a 256-bit curve like
255
+ * secp256k1, each of these coordinates is 32 bytes (256 bits) long. However,
256
+ * in the ECDH process, it's standard practice to use only the x-coordinate
257
+ * of the shared secret point as the resulting shared key. This is because
258
+ * the y-coordinate does not add to the entropy of the key, and both parties
259
+ * can independently compute the x-coordinate. Consquently, this implementation
260
+ * omits the y-coordinate for simplicity and standard compliance.
261
+ *
262
+ * @example
263
+ * ```ts
264
+ * const privateKeyA = { ... }; // A Jwk object for party A
265
+ * const publicKeyB = { ... }; // A PublicKeyJwk object for party B
266
+ * const sharedSecret = await Secp256k1.sharedSecret({
267
+ * privateKeyA,
268
+ * publicKeyB
269
+ * });
270
+ * ```
271
+ *
272
+ * @param params - The parameters for the shared secret computation.
273
+ * @param params.privateKeyA - The private key in JWK format of one party.
274
+ * @param params.publicKeyB - The public key in JWK format of the other party.
275
+ *
276
+ * @returns A Promise that resolves to the computed shared secret as a Uint8Array.
277
+ */
278
+ static sharedSecret({ privateKeyA, publicKeyB }: {
279
+ privateKeyA: Jwk;
280
+ publicKeyB: Jwk;
281
+ }): Promise<Uint8Array>;
282
+ }
283
+ //# sourceMappingURL=x25519.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"x25519.d.ts","sourceRoot":"","sources":["../../../src/primitives/x25519.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,gBAAgB,CAAC;AAC1C,OAAO,KAAK,EAAE,sBAAsB,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAI5F;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,qBAAa,MAAM;IACjB;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;WACiB,iBAAiB,CAAC,EAAE,eAAe,EAAE,EAAE;QACzD,eAAe,EAAE,UAAU,CAAC;KAC7B,GAAG,OAAO,CAAC,GAAG,CAAC;IAkBhB;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;WACiB,gBAAgB,CAAC,EAAE,cAAc,EAAE,EAAE;QACvD,cAAc,EAAE,UAAU,CAAC;KAC5B,GAAG,OAAO,CAAC,GAAG,CAAC;IAchB;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;WACiB,gBAAgB,CAAC,EAAE,GAAG,EAAE,EAC1C,sBAAsB,GACrB,OAAO,CAAC,GAAG,CAAC;IAoBf;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;WACiB,WAAW,IAAI,OAAO,CAAC,GAAG,CAAC;IAa/C;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;WACiB,YAAY,CAAC,EAAE,GAAG,EAAE,EACtC,kBAAkB,GACjB,OAAO,CAAC,GAAG,CAAC;IAef;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;WACiB,iBAAiB,CAAC,EAAE,UAAU,EAAE,EAAE;QACpD,UAAU,EAAE,GAAG,CAAC;KACjB,GAAG,OAAO,CAAC,UAAU,CAAC;IAYvB;;;;;;;;;;;;;;;;;;;;;;OAsBG;WACiB,gBAAgB,CAAC,EAAE,SAAS,EAAE,EAAE;QAClD,SAAS,EAAE,GAAG,CAAC;KAChB,GAAG,OAAO,CAAC,UAAU,CAAC;IAYvB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAqCG;WACiB,YAAY,CAAC,EAAE,WAAW,EAAE,UAAU,EAAE,EAAE;QAC5D,WAAW,EAAE,GAAG,CAAC;QACjB,UAAU,EAAE,GAAG,CAAC;KACjB,GAAG,OAAO,CAAC,UAAU,CAAC;CAexB"}
@@ -0,0 +1,210 @@
1
+ import type { Jwk } from '../jose/jwk.js';
2
+ /**
3
+ * Constant defining the length of the authentication tag in bytes for XChaCha20-Poly1305.
4
+ *
5
+ * @remarks
6
+ * The `POLY1305_TAG_LENGTH` is set to 16 bytes (128 bits), which is the standard size for the
7
+ * Poly1305 authentication tag in XChaCha20-Poly1305 encryption. This tag length ensures
8
+ * a strong level of security for message authentication, verifying the integrity and
9
+ * authenticity of the data during decryption.
10
+ */
11
+ export declare const POLY1305_TAG_LENGTH = 16;
12
+ /**
13
+ * The `XChaCha20Poly1305` class provides a suite of utilities for cryptographic operations
14
+ * using the XChaCha20-Poly1305 algorithm, a combination of the XChaCha20 stream cipher and the
15
+ * Poly1305 message authentication code (MAC). This class encompasses methods for key generation,
16
+ * encryption, decryption, and conversions between raw byte arrays and JSON Web Key (JWK) formats.
17
+ *
18
+ * XChaCha20-Poly1305 is renowned for its high security and efficiency, especially in scenarios
19
+ * involving large data volumes or where data integrity and confidentiality are paramount. The
20
+ * extended nonce size of XChaCha20 reduces the risks of nonce reuse, while Poly1305 provides
21
+ * a strong MAC ensuring data integrity.
22
+ *
23
+ * Key Features:
24
+ * - Key Generation: Generate XChaCha20-Poly1305 symmetric keys in JWK format.
25
+ * - Key Conversion: Transform keys between raw byte arrays and JWK formats.
26
+ * - Encryption: Encrypt data using XChaCha20-Poly1305, returning both ciphertext and MAC tag.
27
+ * - Decryption: Decrypt data and verify integrity using the XChaCha20-Poly1305 algorithm.
28
+ *
29
+ * The methods in this class are asynchronous, returning Promises to accommodate various
30
+ * JavaScript environments.
31
+ *
32
+ * @example
33
+ * ```ts
34
+ * // Key Generation
35
+ * const privateKey = await XChaCha20Poly1305.generateKey();
36
+ *
37
+ * // Encryption
38
+ * const data = new TextEncoder().encode('Messsage');
39
+ * const nonce = utils.randomBytes(24); // 24-byte nonce
40
+ * const additionalData = new TextEncoder().encode('Associated data');
41
+ * const { ciphertext, tag } = await XChaCha20Poly1305.encrypt({
42
+ * data,
43
+ * nonce,
44
+ * additionalData,
45
+ * key: privateKey
46
+ * });
47
+ *
48
+ * // Decryption
49
+ * const decryptedData = await XChaCha20Poly1305.decrypt({
50
+ * data: ciphertext,
51
+ * nonce,
52
+ * tag,
53
+ * additionalData,
54
+ * key: privateKey
55
+ * });
56
+ *
57
+ * // Key Conversion
58
+ * const privateKeyBytes = await XChaCha20Poly1305.privateKeyToBytes({ privateKey });
59
+ * ```
60
+ */
61
+ export declare class XChaCha20Poly1305 {
62
+ /**
63
+ * Converts a raw private key in bytes to its corresponding JSON Web Key (JWK) format.
64
+ *
65
+ * @remarks
66
+ * This method takes a symmetric key represented as a byte array (Uint8Array) and converts it into
67
+ * a JWK object for use with the XChaCha20-Poly1305 algorithm. The process involves encoding the
68
+ * key into base64url format and setting the appropriate JWK parameters.
69
+ *
70
+ * The resulting JWK object includes the following properties:
71
+ * - `kty`: Key Type, set to 'oct' for Octet Sequence (representing a symmetric key).
72
+ * - `k`: The symmetric key, base64url-encoded.
73
+ * - `kid`: Key ID, generated based on the JWK thumbprint.
74
+ *
75
+ * @example
76
+ * ```ts
77
+ * const privateKeyBytes = new Uint8Array([...]); // Replace with actual symmetric key bytes
78
+ * const privateKey = await XChaCha20Poly1305.bytesToPrivateKey({ privateKeyBytes });
79
+ * ```
80
+ *
81
+ * @param params - The parameters for the symmetric key conversion.
82
+ * @param params.privateKeyBytes - The raw symmetric key as a Uint8Array.
83
+ *
84
+ * @returns A Promise that resolves to the symmetric key in JWK format.
85
+ */
86
+ static bytesToPrivateKey({ privateKeyBytes }: {
87
+ privateKeyBytes: Uint8Array;
88
+ }): Promise<Jwk>;
89
+ /**
90
+ * Decrypts the provided data using XChaCha20-Poly1305.
91
+ *
92
+ * @remarks
93
+ * This method performs XChaCha20-Poly1305 decryption on the given encrypted data using the
94
+ * specified key, nonce, and authentication tag. It supports optional additional authenticated
95
+ * data (AAD) for enhanced security. The nonce must be 24 bytes long, consistent with XChaCha20's
96
+ * specifications.
97
+ *
98
+ * @example
99
+ * ```ts
100
+ * const encryptedData = new Uint8Array([...]); // Encrypted data
101
+ * const nonce = new Uint8Array(24); // 24-byte nonce
102
+ * const additionalData = new Uint8Array([...]); // Optional AAD
103
+ * const key = { ... }; // A Jwk object representing the XChaCha20-Poly1305 key
104
+ * const decryptedData = await XChaCha20Poly1305.decrypt({
105
+ * data: encryptedData,
106
+ * nonce,
107
+ * additionalData,
108
+ * key
109
+ * });
110
+ * ```
111
+ *
112
+ * @param params - The parameters for the decryption operation.
113
+ * @param params.data - The encrypted data to decrypt including the authentication tag,
114
+ * represented as a Uint8Array.
115
+ * @param params.key - The key to use for decryption, represented in JWK format.
116
+ * @param params.nonce - The nonce used during the encryption process.
117
+ * @param params.additionalData - Optional additional authenticated data.
118
+ *
119
+ * @returns A Promise that resolves to the decrypted data as a Uint8Array.
120
+ */
121
+ static decrypt({ data, key, nonce, additionalData }: {
122
+ additionalData?: Uint8Array;
123
+ data: Uint8Array;
124
+ key: Jwk;
125
+ nonce: Uint8Array;
126
+ }): Promise<Uint8Array>;
127
+ /**
128
+ * Encrypts the provided data using XChaCha20-Poly1305.
129
+ *
130
+ * @remarks
131
+ * This method performs XChaCha20-Poly1305 encryption on the given data using the specified key
132
+ * and nonce. It supports optional additional authenticated data (AAD) for enhanced security. The
133
+ * nonce must be 24 bytes long, as per XChaCha20's specifications. The method returns the
134
+ * encrypted data along with an authentication tag as a Uint8Array, ensuring both confidentiality
135
+ * and integrity of the data.
136
+ *
137
+ * @example
138
+ * ```ts
139
+ * const data = new TextEncoder().encode('Messsage');
140
+ * const nonce = utils.randomBytes(24); // 24-byte nonce
141
+ * const additionalData = new TextEncoder().encode('Associated data'); // Optional AAD
142
+ * const key = { ... }; // A Jwk object representing an XChaCha20-Poly1305 key
143
+ * const encryptedData = await XChaCha20Poly1305.encrypt({
144
+ * data,
145
+ * nonce,
146
+ * additionalData,
147
+ * key
148
+ * });
149
+ * ```
150
+ *
151
+ * @param params - The parameters for the encryption operation.
152
+ * @param params.data - The data to encrypt, represented as a Uint8Array.
153
+ * @param params.key - The key to use for encryption, represented in JWK format.
154
+ * @param params.nonce - A 24-byte nonce for the encryption process.
155
+ * @param params.additionalData - Optional additional authenticated data.
156
+ *
157
+ * @returns A Promise that resolves to a byte array containing the encrypted data and the
158
+ * authentication tag.
159
+ */
160
+ static encrypt({ data, key, nonce, additionalData }: {
161
+ additionalData?: Uint8Array;
162
+ data: Uint8Array;
163
+ key: Jwk;
164
+ nonce: Uint8Array;
165
+ }): Promise<Uint8Array>;
166
+ /**
167
+ * Generates a symmetric key for XChaCha20-Poly1305 in JSON Web Key (JWK) format.
168
+ *
169
+ * @remarks
170
+ * This method creates a new symmetric key suitable for use with the XChaCha20-Poly1305 algorithm.
171
+ * The key is generated using cryptographically secure random number generation to ensure its
172
+ * uniqueness and security. The XChaCha20-Poly1305 algorithm requires a 256-bit key (32 bytes),
173
+ * and this method adheres to that specification.
174
+ *
175
+ * Key components included in the JWK:
176
+ * - `kty`: Key Type, set to 'oct' for Octet Sequence.
177
+ * - `k`: The symmetric key component, base64url-encoded.
178
+ * - `kid`: Key ID, generated based on the JWK thumbprint.
179
+ *
180
+ * @example
181
+ * ```ts
182
+ * const privateKey = await XChaCha20Poly1305.generateKey();
183
+ * ```
184
+ *
185
+ * @returns A Promise that resolves to the generated symmetric key in JWK format.
186
+ */
187
+ static generateKey(): Promise<Jwk>;
188
+ /**
189
+ * Converts a private key from JSON Web Key (JWK) format to a raw byte array (Uint8Array).
190
+ *
191
+ * This method takes a symmetric key in JWK format and extracts its raw byte representation.
192
+ * It decodes the 'k' parameter of the JWK value, which represents the symmetric key in base64url
193
+ * encoding, into a byte array.
194
+ *
195
+ * @example
196
+ * ```ts
197
+ * const privateKey = { ... }; // A symmetric key in JWK format
198
+ * const privateKeyBytes = await XChaCha20Poly1305.privateKeyToBytes({ privateKey });
199
+ * ```
200
+ *
201
+ * @param params - The parameters for the symmetric key conversion.
202
+ * @param params.privateKey - The symmetric key in JWK format.
203
+ *
204
+ * @returns A Promise that resolves to the symmetric key as a Uint8Array.
205
+ */
206
+ static privateKeyToBytes({ privateKey }: {
207
+ privateKey: Jwk;
208
+ }): Promise<Uint8Array>;
209
+ }
210
+ //# sourceMappingURL=xchacha20-poly1305.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"xchacha20-poly1305.d.ts","sourceRoot":"","sources":["../../../src/primitives/xchacha20-poly1305.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,gBAAgB,CAAC;AAI1C;;;;;;;;GAQG;AACH,eAAO,MAAM,mBAAmB,KAAK,CAAC;AAEtC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH,qBAAa,iBAAiB;IAC5B;;;;;;;;;;;;;;;;;;;;;;;OAuBG;WACiB,iBAAiB,CAAC,EAAE,eAAe,EAAE,EAAE;QACzD,eAAe,EAAE,UAAU,CAAC;KAC7B,GAAG,OAAO,CAAC,GAAG,CAAC;IAahB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+BG;WACiB,OAAO,CAAC,EAAE,IAAI,EAAE,GAAG,EAAE,KAAK,EAAE,cAAc,EAAE,EAAE;QAChE,cAAc,CAAC,EAAE,UAAU,CAAC;QAC5B,IAAI,EAAE,UAAU,CAAC;QACjB,GAAG,EAAE,GAAG,CAAC;QACT,KAAK,EAAE,UAAU,CAAC;KACnB,GAAG,OAAO,CAAC,UAAU,CAAC;IAUvB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAgCG;WACiB,OAAO,CAAC,EAAE,IAAI,EAAE,GAAG,EAAE,KAAK,EAAE,cAAc,EAAC,EAAE;QAC/D,cAAc,CAAC,EAAE,UAAU,CAAC;QAC5B,IAAI,EAAE,UAAU,CAAC;QACjB,GAAG,EAAE,GAAG,CAAC;QACT,KAAK,EAAE,UAAU,CAAC;KACnB,GAAG,OAAO,CAAC,UAAU,CAAC;IAUvB;;;;;;;;;;;;;;;;;;;;OAoBG;WACiB,WAAW,IAAI,OAAO,CAAC,GAAG,CAAC;IAkB/C;;;;;;;;;;;;;;;;;OAiBG;WACiB,iBAAiB,CAAC,EAAE,UAAU,EAAE,EAAE;QACpD,UAAU,EAAE,GAAG,CAAC;KACjB,GAAG,OAAO,CAAC,UAAU,CAAC;CAWxB"}