# crypto

> Cryptography — hashing, HMAC, AES, RSA, Ed25519, secure random, certificates, and TLS info.

# crypto

The `crypto` module bundles common cryptographic primitives into sub-modules: hashing, HMAC, AES-GCM encryption, RSA and Ed25519 signing, secure random generation, X.509 certificates, and TLS information. Import it with `import crypto`.

## crypto.hash

All hash functions take a string and return a lowercase hex digest.

| Function | Signature | Description |
| --- | --- | --- |
| `md5` | `crypto.hash.md5(s: string) → string` | MD5 hex digest (legacy; not secure) |
| `sha1` | `crypto.hash.sha1(s: string) → string` | SHA-1 hex digest (legacy; not secure) |
| `sha256` | `crypto.hash.sha256(s: string) → string` | SHA-256 hex digest |
| `sha512` | `crypto.hash.sha512(s: string) → string` | SHA-512 hex digest |
| `blake3` | `crypto.hash.blake3(s: string) → string` | BLAKE3-256 hex digest |

## crypto.hmac

| Function | Signature | Description |
| --- | --- | --- |
| `sha256` | `crypto.hmac.sha256(key: string, data: string) → string` | HMAC-SHA256 hex digest |
| `sha512` | `crypto.hmac.sha512(key: string, data: string) → string` | HMAC-SHA512 hex digest |
| `verify` | `crypto.hmac.verify(key: string, data: string, expected: string) → bool` | constant-time compare of HMAC-SHA256 against a hex digest |

## crypto.aes

AES-256-GCM. The key can be any length; it is hashed to a 32-byte key with SHA-256. Ciphertext is base64-encoded with the nonce prepended.

| Function | Signature | Description |
| --- | --- | --- |
| `encrypt` | `crypto.aes.encrypt(key: string, plaintext: string) → string` | encrypt to base64 ciphertext |
| `decrypt` | `crypto.aes.decrypt(key: string, ciphertext: string) → string` | decrypt base64 ciphertext to plaintext |

## crypto.rsa

| Function | Signature | Description |
| --- | --- | --- |
| `generate` | `crypto.rsa.generate(bits?: int) → string` | JSON string `{privateKey, publicKey}` as PEM (default 2048 bits) |
| `sign` | `crypto.rsa.sign(privateKeyPEM: string, data: string) → string` | base64 RSA PKCS#1 v1.5 SHA-256 signature |

## crypto.ed25519

| Function | Signature | Description |
| --- | --- | --- |
| `generate` | `crypto.ed25519.generate() → string` | JSON string `{privateKey, publicKey}` as hex |
| `sign` | `crypto.ed25519.sign(privateKeyHex: string, message: string) → string` | hex signature |
| `verify` | `crypto.ed25519.verify(publicKeyHex: string, message: string, signatureHex: string) → bool` | verify a hex signature |

## crypto.random

| Function | Signature | Description |
| --- | --- | --- |
| `uuid` | `crypto.random.uuid() → string` | random UUID v4 string |
| `bytes` | `crypto.random.bytes(n: int) → string` | n secure random bytes, hex-encoded |

## crypto.cert

| Function | Signature | Description |
| --- | --- | --- |
| `selfSigned` | `crypto.cert.selfSigned(host?: string, bits?: int) → string` | JSON `{cert, key}` PEM self-signed cert (default `localhost`, 2048 bits, 1-year validity) |
| `parse` | `crypto.cert.parse(certPEM: string) → string` | JSON with `subject`, `issuer`, `notBefore`, `notAfter`, `dnsNames` |
| `verify` | `crypto.cert.verify(certPEM: string) → bool` | validate a PEM cert against system roots |

## crypto.tls

| Function | Signature | Description |
| --- | --- | --- |
| `version` | `crypto.tls.version() → string` | supported TLS version string |
| `ciphers` | `crypto.tls.ciphers() → string[]` | names of secure cipher suites |
| `insecureCiphers` | `crypto.tls.insecureCiphers() → string[]` | names of insecure cipher suites |
| `verify` | `crypto.tls.verify(host: string, port: int) → bool` | true if a TLS handshake to host:port succeeds |

## Top-level shortcuts

For convenience the module also exposes flat aliases at the top level:
`crypto.md5`, `crypto.sha1`, `crypto.sha224`, `crypto.sha256`, `crypto.sha384`, `crypto.sha512`, `crypto.blake3` (string → hex digest), `crypto.hmacSha256` / `crypto.hmacSha512` `(key, data) → hex`, `crypto.hexEncode` / `crypto.hexDecode`, and `crypto.uuid()`.

## Example

```goost
import crypto

let digest = crypto.sha256("hello world")
println("sha256: " + digest)

// HMAC sign and verify
let mac = crypto.hmac.sha256("secret-key", "payload")
let ok = crypto.hmac.verify("secret-key", "payload", mac)
println("hmac valid: " + toString(ok))

// AES round-trip
let sealed = crypto.aes.encrypt("my-password", "top secret")
let plain = crypto.aes.decrypt("my-password", sealed)
println("decrypted: " + plain)

// Random ID
println("id: " + crypto.uuid())
```