dimgigov
e7e900973f
- lib/crypto/: 9-module crypto library (Hash, HMAC, Base64/URL, Random, AES, RSA, ECDSA, Ed25519, JWT) - rt/runtime.c: +346 lines OpenSSL crypto primitives (SHA-1/384/512, HMAC, Base64URL, AES-CBC/GCM, RSA, ECDSA, Ed25519) - apps/nexus/: multi-threaded HTTP/1.1 + HTTP/2 detect + WebSocket server - apps/jwt-pitbul/: JWT CLI tool (sign, verify, decode, keygen) - apps/boko-framework/: FastAPI-inspired async web framework - test_crypto/: crypto library test suite (23 tests)
266 lines
8.4 KiB
Markdown
266 lines
8.4 KiB
Markdown
# Bux Crypto Library (`Std::Crypto`)
|
|
|
|
Cryptographic primitives for the Bux programming language. Backed by OpenSSL via the C runtime (`rt/runtime.c`).
|
|
|
|
## Modules
|
|
|
|
| Module | Import Path | Provides |
|
|
|--------|------------|----------|
|
|
| **Base64** | `Std::Crypto::Base64` | Base64 and Base64URL (RFC 4648 §5) encode/decode |
|
|
| **Hash** | `Std::Crypto::Hash` | SHA-1, SHA-256, SHA-384, SHA-512 (hex + raw) |
|
|
| **HMAC** | `Std::Crypto::Hmac` | HMAC-SHA256, HMAC-SHA384, HMAC-SHA512 (hex + raw + base64) |
|
|
| **Random** | `Std::Crypto::Random` | Cryptographically secure random bytes, hex, base64, uint32 |
|
|
| **AES** | `Std::Crypto::Aes` | AES-256-CBC and AES-256-GCM encrypt/decrypt |
|
|
| **RSA** | `Std::Crypto::Rsa` | RSA PKCS#1 v1.5 sign/verify (SHA-256/384/512) |
|
|
| **ECDSA** | `Std::Crypto::Ecdsa` | ECDSA P-256 and P-384 sign/verify |
|
|
| **Ed25519** | `Std::Crypto::Ed25519` | Ed25519 key generation, signing, verification |
|
|
| **JWT** | `Std::Crypto::Jwt` | JSON Web Tokens (HS256/384/512, RS256/384/512, ES256/384, EdDSA) |
|
|
|
|
The legacy `Std::Crypto` module (the old single-file API) is preserved as a backward-compatible wrapper — existing code continues to work.
|
|
|
|
## Quick Start
|
|
|
|
### Hash
|
|
|
|
```bux
|
|
import Std::Crypto::Hash::{Hash_Sha256, Hash_Sha384, Hash_Sha512};
|
|
|
|
let hex: String = Hash_Sha256("hello");
|
|
// → "2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824"
|
|
|
|
let size: int = Hash_Sha256Size(); // → 32 (bytes)
|
|
```
|
|
|
|
### HMAC
|
|
|
|
```bux
|
|
import Std::Crypto::Hmac::{Hmac_Sha256, Hmac_Sha256Raw, Hmac_Sha256Base64};
|
|
|
|
let hex: String = Hmac_Sha256("secret-key", "message");
|
|
// → hex string
|
|
|
|
// Raw binary output (caller allocates 32-byte buffer)
|
|
let buf: *void = Alloc(32);
|
|
Hmac_Sha256Raw("secret-key", "message", buf);
|
|
// buf now contains 32 bytes of raw HMAC
|
|
|
|
let b64: String = Hmac_Sha256Base64("secret-key", "message");
|
|
// → base64-encoded HMAC
|
|
```
|
|
|
|
### Base64 & Base64URL
|
|
|
|
```bux
|
|
import Std::Crypto::Base64::{Base64_Encode, Base64_Decode,
|
|
Base64URL_Encode, Base64URL_Decode};
|
|
|
|
let std: String = Base64_Encode("hello"); // → "aGVsbG8="
|
|
let orig: String = Base64_Decode(std); // → "hello"
|
|
|
|
let url: String = Base64URL_Encode("hello"); // → "aGVsbG8" (no padding)
|
|
let orig2: String = Base64URL_Decode(url); // → "hello"
|
|
```
|
|
|
|
### Random
|
|
|
|
```bux
|
|
import Std::Crypto::Random::{Random_Bytes, Random_Hex, Random_Base64, Random_Uint32};
|
|
|
|
let raw: String = Random_Bytes(32); // 32 random bytes (binary-safe string)
|
|
let hex: String = Random_Hex(16); // 16 random bytes as hex (32 chars)
|
|
let b64: String = Random_Base64(16); // 16 random bytes as base64
|
|
let u32: uint = Random_Uint32(); // random 32-bit unsigned integer
|
|
```
|
|
|
|
### AES-256
|
|
|
|
```bux
|
|
import Std::Crypto::Aes::{Aes_GenerateKey, Aes_GenerateIV,
|
|
Aes_CbcEncrypt, Aes_CbcDecrypt,
|
|
Aes_GcmEncrypt, Aes_GcmDecrypt};
|
|
|
|
// Generate random key and IV
|
|
let key: String = Aes_GenerateKey(); // 32 raw bytes
|
|
let iv: String = Aes_GenerateIV(); // 16 raw bytes
|
|
|
|
// CBC mode
|
|
let cipher: String = Aes_CbcEncrypt("secret message", key, iv);
|
|
let plain: String = Aes_CbcDecrypt(cipher, key, iv);
|
|
|
|
// GCM mode (authenticated encryption)
|
|
let tag: *void = Alloc(16);
|
|
let gcmCipher: String = Aes_GcmEncrypt("secret", key, iv, tag);
|
|
let gcmPlain: String = Aes_GcmDecrypt(gcmCipher, key, iv, tag as String);
|
|
```
|
|
|
|
### RSA
|
|
|
|
```bux
|
|
import Std::Crypto::Rsa::{Rsa_SignSha256, Rsa_VerifySha256,
|
|
Rsa_SignSha256Base64, Rsa_VerifySha256Base64};
|
|
|
|
// Keys are PEM-encoded strings
|
|
let pemPriv: String = ReadFile("private.pem");
|
|
let pemPub: String = ReadFile("public.pem");
|
|
|
|
// Sign — returns raw signature
|
|
let sig: String = Rsa_SignSha256(pemPriv, "data to sign");
|
|
|
|
// Or sign and get base64
|
|
let sigB64: String = Rsa_SignSha256Base64(pemPriv, "data to sign");
|
|
|
|
// Verify raw signature
|
|
let valid: bool = Rsa_VerifySha256(pemPub, "data to sign", sig);
|
|
|
|
// Verify base64 signature
|
|
let validB64: bool = Rsa_VerifySha256Base64(pemPub, "data to sign", sigB64);
|
|
```
|
|
|
|
### ECDSA
|
|
|
|
```bux
|
|
import Std::Crypto::Ecdsa::{Ecdsa_SignP256, Ecdsa_VerifyP256,
|
|
Ecdsa_SignP384, Ecdsa_VerifyP384};
|
|
|
|
// P-256 (ES256)
|
|
let sig: String = Ecdsa_SignP256(pemPriv, "data");
|
|
let ok: bool = Ecdsa_VerifyP256(pemPub, "data", sig);
|
|
|
|
// P-384 (ES384)
|
|
let sig384: String = Ecdsa_SignP384(pemPriv, "data");
|
|
let ok384: bool = Ecdsa_VerifyP384(pemPub, "data", sig384);
|
|
```
|
|
|
|
### Ed25519
|
|
|
|
```bux
|
|
import Std::Crypto::Ed25519::{Ed25519_Keypair, Ed25519_Sign, Ed25519_Verify};
|
|
|
|
// Generate keypair — keys are 32 raw bytes each
|
|
let pub: *void = Alloc(32);
|
|
let priv: *void = Alloc(32);
|
|
Ed25519_Keypair(pub, priv);
|
|
|
|
// Sign
|
|
let sig: String = Ed25519_Sign(priv as String, "message");
|
|
// sig is 64 raw bytes
|
|
|
|
// Verify
|
|
let valid: bool = Ed25519_Verify(pub as String, sig, "message");
|
|
```
|
|
|
|
### JWT
|
|
|
|
```bux
|
|
import Std::Crypto::Jwt::{JwtAlg, Jwt_MakeHeader, Jwt_Encode,
|
|
Jwt_Decode, Jwt_EncodeHS256};
|
|
|
|
// --- Symmetric (HS256) ---
|
|
let token: String = Jwt_EncodeHS256("{\"sub\":\"123\",\"role\":\"admin\"}", "my-secret");
|
|
|
|
var header: String;
|
|
var payload: String;
|
|
let alg: JwtAlg = JwtAlg { tag: JwtAlg_HS256 };
|
|
if Jwt_Decode(token, alg, "my-secret", &header, &payload) {
|
|
PrintLine(payload); // {"sub":"123","role":"admin"}
|
|
}
|
|
|
|
// --- Asymmetric (RS256) ---
|
|
let rsToken: String = Jwt_Encode(
|
|
"{\"alg\":\"RS256\",\"typ\":\"JWT\"}",
|
|
"{\"sub\":\"456\"}",
|
|
JwtAlg { tag: JwtAlg_RS256 },
|
|
pemPrivateKey
|
|
);
|
|
|
|
// --- Convenience helpers ---
|
|
Jwt_EncodeHS256(payload, secret);
|
|
Jwt_EncodeHS384(payload, secret);
|
|
Jwt_EncodeHS512(payload, secret);
|
|
Jwt_EncodeRS256(payload, pemPrivKey);
|
|
Jwt_EncodeES256(payload, pemPrivKey);
|
|
Jwt_EncodeEdDSA(payload, rawPrivKey32);
|
|
```
|
|
|
|
## Supported JWT Algorithms
|
|
|
|
| Algorithm | JWT `alg` | Key Type | Key Format |
|
|
|-----------|-----------|----------|------------|
|
|
| HS256 | `HS256` | HMAC secret | Raw string |
|
|
| HS384 | `HS384` | HMAC secret | Raw string |
|
|
| HS512 | `HS512` | HMAC secret | Raw string |
|
|
| RS256 | `RS256` | RSA private/public key | PEM string |
|
|
| RS384 | `RS384` | RSA private/public key | PEM string |
|
|
| RS512 | `RS512` | RSA private/public key | PEM string |
|
|
| ES256 | `ES256` | ECDSA P-256 key | PEM string |
|
|
| ES384 | `ES384` | ECDSA P-384 key | PEM string |
|
|
| EdDSA | `EdDSA` | Ed25519 key | 32-byte raw |
|
|
|
|
## Backend
|
|
|
|
All primitives are implemented in C using OpenSSL and linked via the Bux runtime (`rt/runtime.c`). The C functions are declared as `extern func` in each Bux module.
|
|
|
|
Requires OpenSSL 1.1.1+ (for Ed25519 support). Link with `-lssl -lcrypto`.
|
|
|
|
## File Layout
|
|
|
|
```
|
|
lib/
|
|
├── Crypto.bux # Backward-compat wrapper (old API)
|
|
└── crypto/
|
|
├── base64.bux # Base64 + Base64URL
|
|
├── hash.bux # SHA-1/256/384/512
|
|
├── hmac.bux # HMAC-SHA256/384/512
|
|
├── random.bux # Secure random
|
|
├── aes.bux # AES-256-CBC/GCM
|
|
├── rsa.bux # RSA PKCS#1 v1.5
|
|
├── ecdsa.bux # ECDSA P-256/P-384
|
|
├── ed25519.bux # Ed25519
|
|
└── jwt.bux # JSON Web Tokens
|
|
|
|
lib/crypto_test/ # Test project (exercises all modules)
|
|
test_crypto/ # Standalone test project
|
|
```
|
|
|
|
## Migration from old `Std::Crypto`
|
|
|
|
The old single-file API is still available under `Std::Crypto`:
|
|
|
|
| Old Function | New Equivalent | Module |
|
|
|-------------|----------------|--------|
|
|
| `Crypto_Sha256(s)` | `Hash_Sha256(s)` | `Std::Crypto::Hash` |
|
|
| `Crypto_HmacSha256(k, m)` | `Hmac_Sha256(k, m)` | `Std::Crypto::Hmac` |
|
|
| `Crypto_RandomBytes(n)` | `Random_Base64(n)` | `Std::Crypto::Random` |
|
|
| `Crypto_Base64Encode(s)` | `Base64_Encode(s)` | `Std::Crypto::Base64` |
|
|
| `Crypto_Base64Decode(s)` | `Base64_Decode(s)` | `Std::Crypto::Base64` |
|
|
| `Crypto_HmacSha256Raw(k, m)` | `Hmac_Sha256Base64(k, m)` | `Std::Crypto::Hmac` |
|
|
|
|
New code should prefer the submodule imports for clarity and to avoid pulling in unused declarations.
|
|
|
|
## Running Tests
|
|
|
|
```bash
|
|
cd test_crypto
|
|
../buxc build
|
|
./test_crypto
|
|
```
|
|
|
|
Expected output:
|
|
```
|
|
================================================
|
|
Bux Crypto Library — Test Suite
|
|
================================================
|
|
|
|
--- Base64 ---
|
|
PASS Base64_Encode('hello')
|
|
PASS Base64_Decode('aGVsbG8=')
|
|
...
|
|
--- Hash ---
|
|
PASS Hash_Sha256('hello')
|
|
...
|
|
================================================
|
|
Passed: 23
|
|
Failed: 0
|
|
================================================
|
|
```
|