Crypto Module

The std/crypto module provides cryptographic hashing, HMAC, bcrypt password hashing, and secure random number generation.

Import

import { crypto } from "std/crypto"

Hashing Functions

crypto.sha256(data: string): string

Returns the SHA-256 hash of the input as a hex string.

const hash = crypto.sha256("hello world")
println(hash) // "b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9"

crypto.sha512(data: string): string

Returns the SHA-512 hash of the input as a hex string.

const hash = crypto.sha512("hello world")

crypto.sha1(data: string): string

Returns the SHA-1 hash of the input as a hex string.

const hash = crypto.sha1("hello world")
println(hash) // "2aae6c35c94fcfb415dbe95f408b9ce91ee846ed"

Caution

SHA-1 is considered cryptographically weak for security purposes. It is included primarily for protocols that require it (e.g., WebSocket handshake RFC 6455). Prefer SHA-256 or bcrypt for new designs.

crypto.md5(data: string): string

Returns the MD5 hash of the input as a hex string. Primarily used for PostgreSQL MD5 authentication.

const hash = crypto.md5("password" + "username")
const pgHash = "md5" + crypto.md5("password" + "username" + salt)

Caution

MD5 is considered cryptographically weak. Use it only for protocols that require it (e.g., PostgreSQL MD5 auth). Prefer SHA-256 or bcrypt for new designs.

crypto.hmac(data: string, key: string, algorithm?: string): string

Computes an HMAC using the given key. Algorithm defaults to "sha256". Supports "sha256" and "sha512".

const mac = crypto.hmac("message", "secret-key")
const mac512 = crypto.hmac("message", "secret-key", "sha512")

Raw Buffer Operations

These functions operate directly on Buffer objects instead of strings, making them suitable for implementing binary protocols like SCRAM-SHA-256.

crypto.sha1Raw(data: Buffer): Buffer

Computes a SHA-1 hash on raw bytes. Takes a Buffer and returns a Buffer containing the 20-byte hash.

import { Buffer } from "std/buffer"
import { crypto } from "std/crypto"

var data = Buffer.fromString("hello")
var hash = crypto.sha1Raw(data)
println(hash.length()) // 20

crypto.sha256Raw(data: Buffer): Buffer

Computes a SHA-256 hash on raw bytes. Takes a Buffer and returns a Buffer containing the 32-byte hash.

import { Buffer } from "std/buffer"
import { crypto } from "std/crypto"

var clientKey = crypto.hmacRaw(saltedPassword, Buffer.fromString("Client Key"))
var storedKey = crypto.sha256Raw(clientKey) // SHA-256 of raw bytes

crypto.hmacRaw(key: Buffer, data: Buffer | string, algo?: string): Buffer

Computes an HMAC over raw byte data. The key must be a Buffer. Data can be a Buffer or a string. Algorithm defaults to "sha256".

var key = Buffer.fromString("secret")
var mac = crypto.hmacRaw(key, Buffer.fromString("message"))
println(mac.length()) // 32 (SHA-256 output)

var mac512 = crypto.hmacRaw(key, "message", "sha512")
println(mac512.length()) // 64 (SHA-512 output)

crypto.pbkdf2(password: Buffer | string, salt: Buffer | string, iterations: int, keyLen: int, algo?: string): Buffer

Derives a cryptographic key from a password using PBKDF2. Algorithm defaults to "sha256". Returns a Buffer of the specified key length.

import { Buffer } from "std/buffer"
import { crypto } from "std/crypto"

var salt = Buffer.fromString("random-salt")
var key = crypto.pbkdf2("my-password", salt, 4096, 32)
println(key.length()) // 32

Password Hashing

crypto.bcryptHash(password: string, cost?: int): string

Hashes a password using bcrypt. Cost defaults to 10.

const hash = crypto.bcryptHash("my-password")
const strongHash = crypto.bcryptHash("my-password", 14)

crypto.bcryptVerify(password: string, hash: string): bool

Verifies a password against a bcrypt hash.

const hash = crypto.bcryptHash("my-password")
const valid = crypto.bcryptVerify("my-password", hash) // true
const invalid = crypto.bcryptVerify("wrong", hash)     // false

Random Generation

crypto.randomBytes(n: int): string

Generates n cryptographically secure random bytes as a hex-encoded string.

const token = crypto.randomBytes(32)  // 64-character hex string

crypto.randomInt(min: int, max: int): int

Generates a cryptographically secure random integer in the range [min, max).

const code = crypto.randomInt(100000, 999999)  // 6-digit verification code

Comparison

crypto.constantTimeCompare(a: string, b: string): bool

Compares two strings in constant time to prevent timing attacks.

const safe = crypto.constantTimeCompare(userToken, storedToken)

Function Reference

Function	Description
crypto.sha256(data)	SHA-256 hash (hex string)
crypto.sha512(data)	SHA-512 hash (hex string)
crypto.sha1(data)	SHA-1 hash (hex string)
crypto.md5(data)	MD5 hash (hex string)
crypto.hmac(data, key, algorithm?)	HMAC with optional algorithm
crypto.sha1Raw(data)	SHA-1 hash (Buffer → Buffer)
crypto.sha256Raw(data)	SHA-256 hash (Buffer → Buffer)
crypto.hmacRaw(key, data, algo?)	HMAC on raw buffers
crypto.pbkdf2(password, salt, iterations, keyLen, algo?)	PBKDF2 key derivation (→ Buffer)
crypto.bcryptHash(password, cost?)	Bcrypt password hash
crypto.bcryptVerify(password, hash)	Verify bcrypt hash
crypto.randomBytes(n)	Secure random bytes (hex)
crypto.randomInt(min, max)	Secure random integer [min, max)
crypto.constantTimeCompare(a, b)	Constant-time string comparison

Example: Password Registration

import { crypto } from "std/crypto"
import { createServer, Request, Response } from "std/http"
import { json } from "std/json"

const app = createServer()

app.post("/register", function(req: Request, res: Response): Response {
    const body = json.parse(req.body)
    const hash = crypto.bcryptHash(body["password"])
    // Store user with hashed password...
    return res.status(201).json('{"message": "User created"}')
})

app.listen(3000)

Example: SCRAM-SHA-256 Authentication

The raw buffer crypto functions are designed for implementing binary authentication protocols like PostgreSQL’s SCRAM-SHA-256:

import { crypto } from "std/crypto"
import { Buffer } from "std/buffer"
import { base64 } from "std/base64"

// Derive the salted password
var saltedPassword = crypto.pbkdf2(password, salt, iterations, 32)

// Compute authentication keys
var clientKey = crypto.hmacRaw(saltedPassword, Buffer.fromString("Client Key"))
var storedKey = crypto.sha256Raw(clientKey)
var serverKey = crypto.hmacRaw(saltedPassword, Buffer.fromString("Server Key"))

// Sign the auth message
var clientSignature = crypto.hmacRaw(storedKey, authMessage)

// XOR clientKey with clientSignature to produce the proof
var proof = clientKey.xor(clientSignature)
var proofB64 = base64.encodeBuffer(proof)