EXAMPLES.md (5393B)
1 # Crypto App Usage Examples 2 3 ## Basic Hashing 4 5 ### Hex Output (Default) 6 ```bash 7 crypto MD5 "hello" 8 # Output: 5d41402abc4b2a76b9719d911017c592 9 10 crypto SHA256 "hello" 11 # Output: 2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824 12 ``` 13 14 ### Base64 Output 15 ```bash 16 crypto MD5 "hello" -b64 17 # Output: XUFAKrxLKna5cZ2REBfFkg== 18 19 crypto SHA256 "hello" -b64 20 # Output: LPJNul+wow4m6DsqxbninhsWHlwfp0JecwQzYpOLmCQ= 21 ``` 22 23 ## Key Derivation with Different Outputs 24 25 ### PBKDF2 - Hex vs Base64 26 ```bash 27 # Hex output (default) 28 crypto PBKDF2 "mypassword" -salt "randomsalt" -i 100000 29 # Output: f1c6b3e4d5a8... (64 hex characters = 32 bytes) 30 31 # Base64 output (more compact) 32 crypto PBKDF2 "mypassword" -salt "randomsalt" -i 100000 -b64 33 # Output: 8ca7O1WohQ... (44 base64 characters = 32 bytes) 34 ``` 35 36 ### Generate Salt in Different Formats 37 ```bash 38 crypto generateSalt 39 # Hex: a1b2c3d4e5f6... 40 41 crypto generateSalt -b64 42 # Base64: obLD1OX2... 43 ``` 44 45 ## Ed25519 Digital Signatures 46 47 ### Generate Keypair 48 ```bash 49 # Hex format (default) 50 crypto Ed25519.keypair 51 # Public Key: a1b2c3d4... (64 hex chars) 52 # Private Key: e5f6g7h8... (128 hex chars) 53 54 # Base64 format (more compact) 55 crypto Ed25519.keypair -b64 56 # Public Key: obLD1OX2... (44 chars) 57 # Private Key: 5fbH8Ij9... (88 chars) 58 ``` 59 60 ### Sign and Verify 61 ```bash 62 # Step 1: Generate keypair (save keys) 63 crypto Ed25519.keypair 64 # Public Key: 9b5c8d7e6f4a3b2c1d0e9f8a7b6c5d4e3f2a1b0c9d8e7f6a5b4c3d2e1f0a9b8 65 # Private Key: a1b2c3d4e5f6... 66 67 # Step 2: Sign message 68 crypto Ed25519.sign "Hello World" -key a1b2c3d4e5f6... 69 # Output: 7f8e9d0c1b2a... (signature in hex) 70 71 # Step 3: Verify signature 72 crypto Ed25519.verify "Hello World" 7f8e9d0c1b2a... -key 9b5c8d7e6f4a3b2c1d0e9f8a7b6c5d4e3f2a1b0c9d8e7f6a5b4c3d2e1f0a9b8 73 # Output: Signature is VALID 74 ``` 75 76 ## X25519 Key Exchange (Diffie-Hellman) 77 78 ### Complete Key Exchange Example 79 ```bash 80 # Alice generates keypair 81 crypto X25519.keypair 82 # Public Key: a1a2a3a4a5a6... (alice_pub) 83 # Private Key: b1b2b3b4b5b6... (alice_priv) 84 85 # Bob generates keypair 86 crypto X25519.keypair 87 # Public Key: c1c2c3c4c5c6... (bob_pub) 88 # Private Key: d1d2d3d4d5d6... (bob_priv) 89 90 # Alice computes shared secret with Bob's public key 91 crypto X25519.shared b1b2b3b4b5b6... c1c2c3c4c5c6... 92 # Output: e1e2e3e4e5e6... (shared_secret) 93 94 # Bob computes shared secret with Alice's public key 95 crypto X25519.shared d1d2d3d4d5d6... a1a2a3a4a5a6... 96 # Output: e1e2e3e4e5e6... (same shared_secret!) 97 ``` 98 99 ### Key Exchange with Base64 100 ```bash 101 # Generate keys in base64 for easier storage/transmission 102 crypto X25519.keypair -b64 103 # Public Key: obLD1OX2obLD1OX2obLD1OX2obLD1OX2obLD1OX2obo= 104 # Private Key: 5fbH8Ij95fbH8Ij95fbH8Ij95fbH8Ij95fbH8Ij95fg= 105 ``` 106 107 ## Random Data Generation 108 109 ### Generate Random Bytes 110 ```bash 111 # 16 bytes (128 bits) in hex 112 crypto random 16 113 # Output: a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6 114 115 # 16 bytes in base64 (more compact) 116 crypto random 16 -b64 117 # Output: obLD1OX2g7h8iTpK 118 119 # 32 bytes (256 bits) - common key size 120 crypto random 32 121 crypto random 32 -b64 122 ``` 123 124 ### Generate Cryptographic Keys 125 ```bash 126 # AES-256 key (32 bytes) 127 crypto newKey 32 128 # Output: hex format (64 characters) 129 130 # AES-256 key in base64 131 crypto newKey 32 -b64 132 # Output: base64 format (44 characters) 133 ``` 134 135 ## Comparison: Hex vs Base64 136 137 ### Size Comparison 138 For 32 bytes of data: 139 - **Hex**: 64 characters (2 chars per byte) 140 - **Base64**: 44 characters (~1.33 chars per byte) 141 142 ### Example with SHA256 Hash 143 ```bash 144 # Hex output 145 crypto SHA256 "test" 146 # Output: 9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08 147 # Length: 64 characters 148 149 # Base64 output 150 crypto SHA256 "test" -b64 151 # Output: n4bQgYhMfWWaL+qgxVrQFaO/TxsrC4Is0V1sFbDwCgg= 152 # Length: 44 characters 153 ``` 154 155 ### When to Use Each Format 156 157 **Use Hex when:** 158 - Maximum compatibility needed 159 - Debugging or manual inspection 160 - Working with systems that expect hex 161 - Human readability is important 162 163 **Use Base64 when:** 164 - Compact representation needed 165 - Transmitting over text protocols 166 - Storing in databases or files 167 - Working with web APIs 168 - Space efficiency matters 169 170 ## All Hash Algorithms with Base64 171 172 ```bash 173 crypto MD5 "test" -b64 174 crypto SHA1 "test" -b64 175 crypto SHA256 "test" -b64 176 crypto SHA512 "test" -b64 177 crypto SHA3_256 "test" -b64 178 crypto SHA3_512 "test" -b64 179 crypto BLAKE2b "test" -b64 180 crypto BLAKE2b_512 "test" -b64 181 crypto CRC32 "test" -b64 182 ``` 183 184 ## Chaining Commands (Hypothetical) 185 186 While not directly supported yet, you could use shell scripting to chain operations: 187 188 ```bash 189 # Generate a salt and use it with PBKDF2 190 SALT=$(crypto generateSalt) 191 crypto PBKDF2 "mypassword" -salt "$SALT" -i 100000 192 193 # Generate a keypair and extract public key 194 crypto Ed25519.keypair > keypair.txt 195 # Parse keypair.txt to extract keys... 196 197 # Generate random encryption key 198 crypto newKey 32 -b64 > aes256.key 199 ``` 200 201 ## Error Handling Examples 202 203 ```bash 204 # Missing required argument 205 crypto MD5 206 # Error: MD5 requires data argument 207 208 # Invalid option 209 crypto SHA256 "test" -invalid 210 # Error: Unknown option: -invalid 211 212 # Missing salt for PBKDF2 213 crypto PBKDF2 "password" 214 # Error: PBKDF2 requires -salt option 215 216 # Invalid iterations 217 crypto PBKDF2 "password" -salt "test" -i abc 218 # Error: Iterations must be a number 219 ``` 220 221 ## Performance Notes 222 223 - Base64 encoding/decoding is done in pure Lua 224 - Hex encoding/decoding is very fast 225 - Base64 is ~30% more compact than hex 226 - Cryptographic operations are performed in C (fast) 227 - Encoding/formatting adds minimal overhead