@theqrl/dilithium5 0.2.0 → 1.0.3

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 (4) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +149 -6
  3. package/package.json +14 -12
  4. package/src/index.js +0 -11
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2023-2026 The Quantum Resistant Ledger
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,11 +1,154 @@
1
- # `@theqrl/dilithium5`
1
+ # @theqrl/dilithium5
2
2
 
3
- > TODO: description
3
+ Post-quantum digital signatures using CRYSTALS-Dilithium Round 3.
4
4
 
5
- ## Usage
5
+ This package implements the Dilithium5 signature scheme at NIST security level 5 (AES-256 equivalent). It's designed for compatibility with [go-qrllib](https://github.com/theQRL/go-qrllib) and existing QRL infrastructure.
6
6
 
7
- ``` js
8
- import { cryptoSign, cryptoSignKeypair, cryptoSignOpen, cryptoSignVerify, cryptoSignSignature } from '@theqrl/dilithium5';
7
+ ## Installation
9
8
 
10
- // TODO: DEMONSTRATE API
9
+ ```bash
10
+ npm install @theqrl/dilithium5
11
11
  ```
12
+
13
+ ## Quick Start
14
+
15
+ ```javascript
16
+ import {
17
+ cryptoSignKeypair,
18
+ cryptoSign,
19
+ cryptoSignOpen,
20
+ CryptoPublicKeyBytes,
21
+ CryptoSecretKeyBytes,
22
+ } from '@theqrl/dilithium5';
23
+
24
+ // Generate keypair
25
+ const pk = new Uint8Array(CryptoPublicKeyBytes); // 2592 bytes
26
+ const sk = new Uint8Array(CryptoSecretKeyBytes); // 4896 bytes
27
+ cryptoSignKeypair(null, pk, sk); // null = random seed
28
+
29
+ // Sign a message
30
+ const message = new TextEncoder().encode('Hello, quantum world!');
31
+ const signedMessage = cryptoSign(message, sk, false); // false = deterministic
32
+
33
+ // Verify and extract
34
+ const extracted = cryptoSignOpen(signedMessage, pk);
35
+ if (extracted === undefined) {
36
+ throw new Error('Invalid signature');
37
+ }
38
+ console.log(new TextDecoder().decode(extracted)); // "Hello, quantum world!"
39
+ ```
40
+
41
+ ## API
42
+
43
+ ### Constants
44
+
45
+ | Constant | Value | Description |
46
+ |----------|-------|-------------|
47
+ | `CryptoPublicKeyBytes` | 2592 | Public key size in bytes |
48
+ | `CryptoSecretKeyBytes` | 4896 | Secret key size in bytes |
49
+ | `CryptoBytes` | 4595 | Signature size in bytes |
50
+ | `SeedBytes` | 32 | Seed size for key generation |
51
+
52
+ ### Functions
53
+
54
+ #### `cryptoSignKeypair(seed, pk, sk)`
55
+
56
+ Generate a keypair from a seed.
57
+
58
+ - `seed`: `Uint8Array(32)` or `null` for random
59
+ - `pk`: `Uint8Array(2592)` - output buffer for public key
60
+ - `sk`: `Uint8Array(4896)` - output buffer for secret key
61
+ - Returns: The seed used (useful when `seed` is `null`)
62
+
63
+ #### `cryptoSign(message, sk, randomized)`
64
+
65
+ Sign a message (combined mode: returns signature || message).
66
+
67
+ - `message`: `Uint8Array` - message to sign
68
+ - `sk`: `Uint8Array(4896)` - secret key
69
+ - `randomized`: `boolean` - `true` for hedged signing, `false` for deterministic
70
+ - Returns: `Uint8Array` containing signature + message
71
+
72
+ #### `cryptoSignOpen(signedMessage, pk)`
73
+
74
+ Verify and extract message from signed message.
75
+
76
+ - `signedMessage`: `Uint8Array` - output from `cryptoSign()`
77
+ - `pk`: `Uint8Array(2592)` - public key
78
+ - Returns: Original message if valid, `undefined` if verification fails
79
+
80
+ #### `cryptoSignSignature(sig, message, sk, randomized)`
81
+
82
+ Create a detached signature.
83
+
84
+ - `sig`: `Uint8Array(4595)` - output buffer for signature
85
+ - `message`: `Uint8Array` - message to sign
86
+ - `sk`: `Uint8Array(4896)` - secret key
87
+ - `randomized`: `boolean` - `true` for hedged, `false` for deterministic
88
+ - Returns: `0` on success
89
+
90
+ #### `cryptoSignVerify(sig, message, pk)`
91
+
92
+ Verify a detached signature.
93
+
94
+ - `sig`: `Uint8Array(4595)` - signature to verify
95
+ - `message`: `Uint8Array` - original message
96
+ - `pk`: `Uint8Array(2592)` - public key
97
+ - Returns: `true` if valid, `false` otherwise
98
+
99
+ #### `zeroize(buffer)`
100
+
101
+ Zero out sensitive data (best-effort, see security notes).
102
+
103
+ #### `isZero(buffer)`
104
+
105
+ Check if buffer is all zeros (constant-time).
106
+
107
+ ## Interoperability with go-qrllib
108
+
109
+ go-qrllib pre-hashes seeds with SHAKE256 before key generation. To generate matching keys:
110
+
111
+ ```javascript
112
+ import { shake256 } from '@noble/hashes/sha3';
113
+
114
+ // go-qrllib: hashedSeed = SHAKE256(rawSeed)[:32]
115
+ const hashedSeed = shake256(rawSeed, { dkLen: 32 });
116
+
117
+ // Use hashedSeed (not rawSeed) with this library
118
+ cryptoSignKeypair(hashedSeed, pk, sk);
119
+ ```
120
+
121
+ ## Dilithium5 vs ML-DSA-87
122
+
123
+ | Feature | Dilithium5 | ML-DSA-87 |
124
+ |---------|------------|-----------|
125
+ | Standard | CRYSTALS Round 3 | FIPS 204 |
126
+ | Signature size | 4595 bytes | 4627 bytes |
127
+ | Context parameter | Not supported | Supported |
128
+ | Use case | go-qrllib compatibility | New implementations |
129
+
130
+ For new projects, consider using [@theqrl/mldsa87](https://www.npmjs.com/package/@theqrl/mldsa87) which implements the FIPS 204 standard.
131
+
132
+ ## Security
133
+
134
+ See [SECURITY.md](../../SECURITY.md) for important information about:
135
+
136
+ - JavaScript memory security limitations
137
+ - Constant-time verification
138
+ - Secure key handling recommendations
139
+
140
+ ## Requirements
141
+
142
+ - Node.js 18+ or modern browsers with ES2020 support
143
+ - Full TypeScript definitions included
144
+
145
+ ## License
146
+
147
+ MIT
148
+
149
+ ## Links
150
+
151
+ - [Main documentation](../../README.md)
152
+ - [go-qrllib](https://github.com/theQRL/go-qrllib) - Go implementation
153
+ - [CRYSTALS-Dilithium](https://pq-crystals.org/dilithium/) - Original specification
154
+ - [QRL Website](https://theqrl.org)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@theqrl/dilithium5",
3
- "version": "0.2.0",
3
+ "version": "1.0.3",
4
4
  "description": "Dilithium-5 cryptography",
5
5
  "keywords": [
6
6
  "dilithium",
@@ -10,7 +10,8 @@
10
10
  "author": "QRL contributors <info@theqrl.org> (https://theqrl.org)",
11
11
  "homepage": "https://github.com/theQRL/qrypto.js#readme",
12
12
  "license": "MIT",
13
- "main": "src/index.js",
13
+ "main": "dist/cjs/dilithium5.js",
14
+ "module": "dist/mjs/dilithium5.js",
14
15
  "types": "src/index.d.ts",
15
16
  "directories": {
16
17
  "lib": "src",
@@ -18,7 +19,9 @@
18
19
  },
19
20
  "files": [
20
21
  "dist",
21
- "src/index.d.ts"
22
+ "src/index.d.ts",
23
+ "LICENSE",
24
+ "README.md"
22
25
  ],
23
26
  "publishConfig": {
24
27
  "access": "public"
@@ -45,17 +48,16 @@
45
48
  },
46
49
  "type": "module",
47
50
  "devDependencies": {
48
- "c8": "^9.1.0",
49
- "chai": "^5.0.0",
50
- "codecov": "^3.8.3",
51
- "eslint": "^8.56.0",
51
+ "c8": "^10.1.3",
52
+ "chai": "^5.2.1",
53
+ "eslint": "^8.57.1",
52
54
  "eslint-config-airbnb": "^19.0.4",
53
55
  "eslint-config-prettier": "^9.1.0",
54
- "eslint-plugin-import": "^2.29.1",
55
- "eslint-plugin-prettier": "^5.1.3",
56
- "mocha": "^10.2.0",
57
- "prettier": "^3.2.4",
58
- "rollup": "^4.9.5"
56
+ "eslint-plugin-import": "^2.32.0",
57
+ "eslint-plugin-prettier": "^5.5.4",
58
+ "mocha": "^10.8.2",
59
+ "prettier": "^3.7.4",
60
+ "rollup": "^4.55.1"
59
61
  },
60
62
  "dependencies": {
61
63
  "@noble/hashes": "^1.7.1",
package/src/index.js DELETED
@@ -1,11 +0,0 @@
1
- export * from './const.js';
2
- export * from './poly.js';
3
- export * from './polyvec.js';
4
- export * from './packing.js';
5
- export * from './reduce.js';
6
- export * from './rounding.js';
7
- export * from './symmetric-shake.js';
8
- export * from './ntt.js';
9
- export * from './fips202.js';
10
- export * from './sign.js';
11
- export * from './utils.js';