README.md (10507B)
1 # LuajitOS Crypto Utility 2 3 A comprehensive command-line cryptographic utility for LuajitOS that provides access to all available crypto functions. 4 5 ## Features 6 7 - **Hash Functions**: MD5, SHA1, SHA256, SHA512, SHA3-256, SHA3-512, BLAKE2b, CRC32 8 - **Key Derivation**: PBKDF2, Argon2id, Salt Generation 9 - **Digital Signatures**: Ed25519 (keypair generation, signing, verification) 10 - **Key Exchange**: X25519 (Diffie-Hellman) 11 - **Random Generation**: Cryptographically secure random bytes 12 13 ## Installation 14 15 The app is located at `/apps/com.luajitos.crypto/` and can be run from the shell using: 16 17 ``` 18 crypto <command> [options] <arguments> 19 ``` 20 21 ## Usage Examples 22 23 ### Hashing 24 25 ```bash 26 # MD5 hash (hex output - default) 27 crypto MD5 "hello world" 28 29 # SHA256 hash with base64 output 30 crypto SHA256 "test123" -b64 31 32 # SHA512 hash 33 crypto SHA512 "sensitive data" 34 35 # BLAKE2b hash with base64 encoding 36 crypto BLAKE2b "data to hash" -b64 37 38 # SHA3-256 39 crypto SHA3_256 "modern hash" 40 41 # CRC32 checksum 42 crypto CRC32 "check integrity" 43 ``` 44 45 ### Key Derivation 46 47 ```bash 48 # Generate a random salt 49 crypto generateSalt 50 51 # Derive key using PBKDF2 (default 100000 iterations) 52 crypto PBKDF2 "mypassword" -salt "randomsalt" 53 54 # Custom iterations 55 crypto PBKDF2 "mypassword" -salt "randomsalt" -i 500000 56 57 # Argon2id (modern, memory-hard KDF) 58 crypto Argon2id "mypassword" -salt "randomsalt16b" 59 ``` 60 61 ### Digital Signatures (Ed25519) 62 63 ```bash 64 # Generate keypair (hex output - default) 65 crypto Ed25519.keypair 66 67 # Generate keypair with base64 output 68 crypto Ed25519.keypair -b64 69 70 # Sign data with private key (hex encoded) 71 crypto Ed25519.sign "message to sign" -key <privkey_hex> 72 73 # Sign with base64 output 74 crypto Ed25519.sign "message to sign" -key <privkey_hex> -b64 75 76 # Verify signature 77 crypto Ed25519.verify "message to sign" <signature_hex> -key <pubkey_hex> 78 ``` 79 80 ### Key Exchange (X25519) 81 82 ```bash 83 # Generate X25519 keypair 84 crypto X25519.keypair 85 86 # Derive public key from private key 87 crypto X25519.publicKey <privkey_hex> 88 89 # Compute shared secret (Diffie-Hellman) 90 crypto X25519.shared <your_privkey_hex> <their_pubkey_hex> 91 ``` 92 93 ### Random Generation 94 95 ```bash 96 # Generate 32 random bytes (hex encoded) 97 crypto random 32 98 99 # Generate random bytes with base64 output 100 crypto random 32 -b64 101 102 # Generate cryptographic key (256-bit) 103 crypto newKey 32 104 105 # Generate key with base64 output 106 crypto newKey 32 -b64 107 ``` 108 109 ## Command Reference 110 111 ### Hash Commands 112 113 | Command | Description | Output Size | 114 |---------|-------------|-------------| 115 | `MD5 <data>` | MD5 hash | 128 bits (16 bytes) | 116 | `SHA1 <data>` | SHA-1 hash | 160 bits (20 bytes) | 117 | `SHA256 <data>` | SHA-256 hash | 256 bits (32 bytes) | 118 | `SHA512 <data>` | SHA-512 hash | 512 bits (64 bytes) | 119 | `SHA3_256 <data>` | SHA3-256 hash | 256 bits (32 bytes) | 120 | `SHA3_512 <data>` | SHA3-512 hash | 512 bits (64 bytes) | 121 | `BLAKE2b <data>` | BLAKE2b-256 hash | 256 bits (32 bytes) | 122 | `BLAKE2b_512 <data>` | BLAKE2b-512 hash | 512 bits (64 bytes) | 123 | `CRC32 <data>` | CRC32 checksum | 32 bits (4 bytes) | 124 125 ### Key Derivation Commands 126 127 | Command | Description | Notes | 128 |---------|-------------|-------| 129 | `PBKDF2 <password> -salt <salt> [-i <iterations>]` | Password-based key derivation | Default: 100,000 iterations | 130 | `Argon2id <password> -salt <salt>` | Modern memory-hard KDF | Recommended for passwords | 131 | `generateSalt` | Generate random salt | 32 bytes of random data | 132 133 ### Ed25519 Commands 134 135 | Command | Description | Notes | 136 |---------|-------------|-------| 137 | `Ed25519.keypair` | Generate Ed25519 keypair | Returns public + private key | 138 | `Ed25519.sign <data> -key <privkey>` | Sign data | Private key in hex | 139 | `Ed25519.verify <data> <sig> -key <pubkey>` | Verify signature | Returns VALID/INVALID | 140 141 ### X25519 Commands 142 143 | Command | Description | Notes | 144 |---------|-------------|-------| 145 | `X25519.keypair` | Generate X25519 keypair | For Diffie-Hellman | 146 | `X25519.publicKey <privkey>` | Derive public from private | All keys in hex | 147 | `X25519.shared <privkey> <pubkey>` | Compute shared secret | ECDH key exchange | 148 149 ### Random Commands 150 151 | Command | Description | Notes | 152 |---------|-------------|-------| 153 | `random <bytes>` | Generate random bytes | CSPRNG-based | 154 | `newKey <bytes>` | Generate crypto key | Same as random | 155 156 ## Options 157 158 | Option | Short | Description | 159 |--------|-------|-------------| 160 | `-key` | `-k` | Specify cryptographic key (hex encoded) | 161 | `-salt` | `-s` | Specify salt for key derivation | 162 | `-iterations` | `-i` | Number of iterations for PBKDF2 | 163 | `-b64` | `-base64` | Output in base64 format (default: hex) | 164 165 ## Output Format 166 167 All binary outputs (hashes, keys, signatures) are encoded in one of two formats: 168 169 - **Hexadecimal** (default): Lowercase hex encoding (e.g., `5d41402abc4b2a76b9719d911017c592`) 170 - **Base64** (with `-b64` flag): Standard base64 encoding (e.g., `XUFAKrxLKna5cZ2REBfFkg==`) 171 172 Use hex for maximum compatibility and base64 for more compact representation. 173 174 ## Security Notes 175 176 1. **Random Generation**: Uses CPU temperature and other entropy sources for CSPRNG 177 2. **Ed25519**: Modern elliptic curve signatures (faster and more secure than RSA) 178 3. **X25519**: Curve25519 Diffie-Hellman key exchange 179 4. **PBKDF2**: Use at least 100,000 iterations for password hashing 180 5. **Argon2id**: Preferred for password hashing (memory-hard, side-channel resistant) 181 182 ## Example Workflows 183 184 ### Password Hashing and Verification 185 186 ```bash 187 # 1. Generate a salt 188 crypto generateSalt 189 # Output: a1b2c3d4... 190 191 # 2. Hash password with salt 192 crypto PBKDF2 "userpassword" -salt "a1b2c3d4..." -i 200000 193 # Output: e5f6g7h8... (store this) 194 195 # 3. Later, verify by re-hashing with same salt 196 crypto PBKDF2 "userpassword" -salt "a1b2c3d4..." -i 200000 197 # Compare output with stored hash 198 ``` 199 200 ### Digital Signature Flow 201 202 ```bash 203 # 1. Generate keypair 204 crypto Ed25519.keypair 205 # Save public and private keys 206 207 # 2. Sign a message 208 crypto Ed25519.sign "Hello, World!" -key <your_private_key> 209 # Output: signature 210 211 # 3. Verify signature 212 crypto Ed25519.verify "Hello, World!" <signature> -key <your_public_key> 213 # Output: Signature is VALID 214 ``` 215 216 ### Secure Key Exchange (Diffie-Hellman) 217 218 ```bash 219 # Alice generates keypair 220 crypto X25519.keypair 221 # Saves: alice_privkey, alice_pubkey 222 223 # Bob generates keypair 224 crypto X25519.keypair 225 # Saves: bob_privkey, bob_pubkey 226 227 # Alice computes shared secret with Bob's public key 228 crypto X25519.shared <alice_privkey> <bob_pubkey> 229 # Output: shared_secret_alice 230 231 # Bob computes shared secret with Alice's public key 232 crypto X25519.shared <bob_privkey> <alice_pubkey> 233 # Output: shared_secret_bob 234 235 # Both shared secrets match! Use for symmetric encryption. 236 ``` 237 238 ## Limitations 239 240 - No symmetric encryption (AES, ChaCha20) - not yet implemented in LuajitOS 241 - No RSA or P256 (require GMP library not available in bare metal) 242 - Keys and signatures must be provided in hexadecimal format (base64 input not yet supported) 243 244 ## Shell Integration 245 246 The crypto app integrates seamlessly with the LuajitOS shell: 247 248 ```bash 249 # Direct execution 250 crypto SHA256 "test" 251 252 # Via run command 253 run crypto SHA256 "test" 254 255 # Via lpm 256 lpm run crypto SHA256 "test" 257 ``` 258 259 All three methods produce identical results. 260 261 ## Programmatic Access (For Other Apps) 262 263 The crypto app exports the crypto library so other apps can import and use it programmatically. 264 265 ### How to Import Crypto in Your App 266 267 1. **Add permissions to your manifest:** 268 ```lua 269 permissions = { 270 "import", -- Required to import from other apps 271 "run" -- Required to run the crypto app 272 } 273 ``` 274 275 2. **Import the crypto library in your code:** 276 ```lua 277 -- First, run the crypto app to initialize exports 278 run("crypto") 279 280 -- Then import the crypto library 281 local cryptoApp = apps["com.luajitos.crypto"] 282 if cryptoApp then 283 local crypto = cryptoApp:call("crypto") 284 285 -- Now use crypto functions 286 local hash = crypto.SHA256("Hello World") 287 print("Hash: " .. toHex(hash)) 288 289 -- Generate keypair 290 local pubkey, privkey = crypto.sign.Ed25519.keypair() 291 292 -- Use PBKDF2 293 local key = crypto.PBKDF2("password", "salt", 100000, 32) 294 end 295 ``` 296 297 ### Available Crypto Functions 298 299 Once imported, you have access to all crypto functions: 300 301 ```lua 302 -- Hashing 303 crypto.MD5(data) 304 crypto.SHA1(data) 305 crypto.SHA256(data) 306 crypto.SHA512(data) 307 crypto["SHA3-256"](data) 308 crypto["SHA3-512"](data) 309 crypto["BLAKE2b-256"](data) 310 crypto["BLAKE2b-512"](data) 311 crypto.CRC32(data) 312 313 -- Key Derivation 314 crypto.PBKDF2(password, salt, iterations, keylen) 315 crypto.Argon2id(password, salt) 316 crypto.generateSalt() 317 318 -- Ed25519 Digital Signatures 319 crypto.sign.Ed25519.keypair() 320 crypto.sign.Ed25519.sign(data, privatekey) 321 crypto.sign.Ed25519.verify(data, signature, publickey) 322 323 -- X25519 Key Exchange 324 crypto.keyExchange.X25519.keypair() 325 crypto.keyExchange.X25519.publicKey(privatekey) 326 crypto.keyExchange.X25519.sharedSecret(privatekey, publickey) 327 328 -- Random Generation 329 crypto.random(bytes) 330 crypto.newKey(bytes) 331 ``` 332 333 ### Example: Password Hashing App 334 335 ```lua 336 -- manifest.lua 337 return { 338 name = "passwordmanager", 339 developer = "mycompany", 340 permissions = {"import", "run", "filesystem"} 341 } 342 343 -- src/init.lua 344 -- Initialize crypto 345 run("crypto") 346 local cryptoApp = apps["com.luajitos.crypto"] 347 local crypto = cryptoApp:call("crypto") 348 349 -- Hash a password 350 local function hashPassword(password) 351 local salt = crypto.generateSalt() 352 local hash = crypto.PBKDF2(password, salt, 100000, 32) 353 return {salt = salt, hash = hash} 354 end 355 356 -- Verify password 357 local function verifyPassword(password, stored_salt, stored_hash) 358 local hash = crypto.PBKDF2(password, stored_salt, 100000, 32) 359 return hash == stored_hash 360 end 361 362 -- Use it 363 local result = hashPassword("mypassword") 364 print("Password hashed!") 365 366 if verifyPassword("mypassword", result.salt, result.hash) then 367 print("Password verified!") 368 end 369 ``` 370 371 ## Troubleshooting 372 373 ### "Error: crypto library not available" 374 The crypto library is not loaded in your LuajitOS instance. Check that crypto_init.c was compiled and linked. 375 376 ### "Error: No command specified" 377 You must provide at least one argument. Run `crypto` without arguments to see the help menu. 378 379 ### "Error: Invalid hex" 380 When providing keys or signatures, ensure they are valid hexadecimal strings (0-9, a-f) with even length. 381 382 ## Technical Details 383 384 - **Language**: Lua (LuaJIT) 385 - **Mode**: CLI (command-line interface) 386 - **Permissions**: stdio only 387 - **Sandbox**: Runs in sandboxed environment with crypto library access 388 - **Entry Point**: `/apps/com.luajitos.crypto/src/init.lua` 389 390 ## Version 391 392 v1.0.0 - Initial release 393 394 ## License 395 396 Part of LuajitOS