wren/manual_src/pages/api/crypto.html

{# retoor <retoor@molodetz.nl> #}
{% extends 'page.html' %}

{% set page_title = "crypto" %}
{% set breadcrumb = [{"url": "api/index.html", "title": "API Reference"}, {"title": "crypto"}] %}
{% set prev_page = {"url": "api/jinja.html", "title": "jinja"} %}
{% set next_page = {"url": "api/os.html", "title": "os"} %}

{% block article %}
                <h1>crypto</h1>

                <p>The <code>crypto</code> module provides cryptographic functions including secure random number generation and hash algorithms.</p>

                <pre><code>import "crypto" for Crypto, Hash</code></pre>

                <div class="toc">
                    <h4>On This Page</h4>
                    <ul>
                        <li><a href="#crypto-class">Crypto Class</a></li>
                        <li><a href="#hash-class">Hash Class</a></li>
                        <li><a href="#examples">Examples</a></li>
                    </ul>
                </div>

                <h2 id="crypto-class">Crypto Class</h2>

                <div class="class-header">
                    <h3>Crypto</h3>
                    <p>Cryptographic random number generation</p>
                </div>

                <h3>Static Methods</h3>

                <div class="method-signature">
                    <span class="method-name">Crypto.randomBytes</span>(<span class="param">length</span>) &#8594; <span class="type">List</span>
                </div>
                <p>Generates cryptographically secure random bytes.</p>
                <ul class="param-list">
                    <li><span class="param-name">length</span> <span class="param-type">(Num)</span> - Number of bytes to generate (must be non-negative)</li>
                    <li><span class="returns">Returns:</span> List of random byte values (0-255)</li>
                </ul>
                <pre><code>var bytes = Crypto.randomBytes(16)
System.print(bytes)  // [142, 55, 201, 89, ...]</code></pre>

                <div class="method-signature">
                    <span class="method-name">Crypto.randomInt</span>(<span class="param">min</span>, <span class="param">max</span>) &#8594; <span class="type">Num</span>
                </div>
                <p>Generates a cryptographically secure random integer in the specified range.</p>
                <ul class="param-list">
                    <li><span class="param-name">min</span> <span class="param-type">(Num)</span> - Minimum value (inclusive)</li>
                    <li><span class="param-name">max</span> <span class="param-type">(Num)</span> - Maximum value (exclusive)</li>
                    <li><span class="returns">Returns:</span> Random integer in range [min, max)</li>
                </ul>
                <pre><code>var roll = Crypto.randomInt(1, 7)  // Dice roll: 1-6
System.print(roll)</code></pre>

                <h2 id="hash-class">Hash Class</h2>

                <div class="class-header">
                    <h3>Hash</h3>
                    <p>Cryptographic hash functions</p>
                </div>

                <h3>Static Methods</h3>

                <div class="method-signature">
                    <span class="method-name">Hash.md5</span>(<span class="param">data</span>) &#8594; <span class="type">List</span>
                </div>
                <p>Computes the MD5 hash of the input data.</p>
                <ul class="param-list">
                    <li><span class="param-name">data</span> <span class="param-type">(String|List)</span> - Data to hash (string or list of bytes)</li>
                    <li><span class="returns">Returns:</span> 16-byte hash as a list of bytes</li>
                </ul>
                <pre><code>var hash = Hash.md5("Hello, World!")
System.print(Hash.toHex(hash))  // 65a8e27d8879283831b664bd8b7f0ad4</code></pre>

                <div class="method-signature">
                    <span class="method-name">Hash.sha1</span>(<span class="param">data</span>) &#8594; <span class="type">List</span>
                </div>
                <p>Computes the SHA-1 hash of the input data.</p>
                <ul class="param-list">
                    <li><span class="param-name">data</span> <span class="param-type">(String|List)</span> - Data to hash</li>
                    <li><span class="returns">Returns:</span> 20-byte hash as a list of bytes</li>
                </ul>
                <pre><code>var hash = Hash.sha1("Hello, World!")
System.print(Hash.toHex(hash))  // 0a0a9f2a6772942557ab5355d76af442f8f65e01</code></pre>

                <div class="method-signature">
                    <span class="method-name">Hash.sha256</span>(<span class="param">data</span>) &#8594; <span class="type">List</span>
                </div>
                <p>Computes the SHA-256 hash of the input data.</p>
                <ul class="param-list">
                    <li><span class="param-name">data</span> <span class="param-type">(String|List)</span> - Data to hash</li>
                    <li><span class="returns">Returns:</span> 32-byte hash as a list of bytes</li>
                </ul>
                <pre><code>var hash = Hash.sha256("Hello, World!")
System.print(Hash.toHex(hash))  // dffd6021bb2bd5b0af676290809ec3a53191dd81c7f70a4b28688a362182986f</code></pre>

                <div class="method-signature">
                    <span class="method-name">Hash.toHex</span>(<span class="param">bytes</span>) &#8594; <span class="type">String</span>
                </div>
                <p>Converts a list of bytes to a hexadecimal string.</p>
                <ul class="param-list">
                    <li><span class="param-name">bytes</span> <span class="param-type">(List)</span> - List of byte values</li>
                    <li><span class="returns">Returns:</span> Lowercase hexadecimal string</li>
                </ul>
                <pre><code>var hex = Hash.toHex([0xDE, 0xAD, 0xBE, 0xEF])
System.print(hex)  // deadbeef</code></pre>

                <h2>Hash Algorithm Comparison</h2>

                <table>
                    <tr>
                        <th>Algorithm</th>
                        <th>Output Size</th>
                        <th>Security</th>
                        <th>Use Case</th>
                    </tr>
                    <tr>
                        <td>MD5</td>
                        <td>128 bits (16 bytes)</td>
                        <td>Broken</td>
                        <td>Checksums only (not for security)</td>
                    </tr>
                    <tr>
                        <td>SHA-1</td>
                        <td>160 bits (20 bytes)</td>
                        <td>Weak</td>
                        <td>Legacy compatibility only</td>
                    </tr>
                    <tr>
                        <td>SHA-256</td>
                        <td>256 bits (32 bytes)</td>
                        <td>Strong</td>
                        <td>Recommended for new applications</td>
                    </tr>
                </table>

                <h2 id="examples">Examples</h2>

                <h3>Generating a Random Token</h3>
                <pre><code>import "crypto" for Crypto, Hash

var bytes = Crypto.randomBytes(32)
var token = Hash.toHex(bytes)
System.print("Random token: %(token)")</code></pre>

                <h3>Password Hashing</h3>
                <pre><code>import "crypto" for Crypto, Hash

var password = "mysecretpassword"
var salt = Crypto.randomBytes(16)
var saltHex = Hash.toHex(salt)

var saltedPassword = saltHex + password
var hash = Hash.sha256(saltedPassword)
var hashHex = Hash.toHex(hash)

System.print("Salt: %(saltHex)")
System.print("Hash: %(hashHex)")</code></pre>

                <h3>File Checksum</h3>
                <pre><code>import "crypto" for Hash
import "io" for File

var content = File.read("document.txt")
var hash = Hash.sha256(content)
System.print("SHA-256: %(Hash.toHex(hash))")</code></pre>

                <h3>Random Selection</h3>
                <pre><code>import "crypto" for Crypto

var items = ["apple", "banana", "cherry", "date", "elderberry"]
var index = Crypto.randomInt(0, items.count)
System.print("Selected: %(items[index])")</code></pre>

                <h3>Generating Random IDs</h3>
                <pre><code>import "crypto" for Crypto, Hash
import "base64" for Base64

var bytes = Crypto.randomBytes(12)
var id = ""
for (b in bytes) {
    id = id + String.fromCodePoint(b)
}
var encoded = Base64.encodeUrl(id)
System.print("Random ID: %(encoded)")</code></pre>

                <h3>Secure Dice Roll</h3>
                <pre><code>import "crypto" for Crypto

var numDice = 5
var results = []

for (i in 0...numDice) {
    results.add(Crypto.randomInt(1, 7))
}

System.print("Dice rolls: %(results)")</code></pre>

                <h3>Comparing Hashes</h3>
                <pre><code>import "crypto" for Hash

var original = "Hello, World!"
var hash1 = Hash.sha256(original)
var hash2 = Hash.sha256(original)
var hash3 = Hash.sha256("Different text")

System.print("Same input, same hash: %(Hash.toHex(hash1) == Hash.toHex(hash2))")
System.print("Different input, different hash: %(Hash.toHex(hash1) != Hash.toHex(hash3))")</code></pre>

                <div class="admonition warning">
                    <div class="admonition-title">Warning</div>
                    <p>MD5 and SHA-1 are cryptographically broken and should not be used for security-sensitive applications. Use SHA-256 for new applications requiring secure hashing.</p>
                </div>

                <div class="admonition note">
                    <div class="admonition-title">Note</div>
                    <p>Hash functions accept both strings and lists of bytes. When a string is provided, it is automatically converted to its byte representation before hashing.</p>
                </div>

                <div class="admonition tip">
                    <div class="admonition-title">Tip</div>
                    <p>For password storage, always use a salt (random bytes prepended to the password) before hashing. Store the salt alongside the hash for verification.</p>
                </div>
{% endblock %}