crypto

The crypto package computes message digests and HMACs. Each function takes a string, which it hashes as UTF-8, or bytes, which it hashes as they are, and returns a lowercase hexadecimal string.

println crypto::sha256_hash("kiwi")
# 1a5afeda973d776e31d1d7266f184468f84d99bed311d88d3dcb67015934f9f9

println crypto::md5_hash("kiwi")
# de5949721e6352f01dfef317c3e898a8

println crypto::hmac_sha256("secret-key", "message to sign")

Function	Algorithm
`md5_hash`	MD5
`sha1_hash`	SHA-1
`sha224_hash`, `sha256_hash`, `sha384_hash`, `sha512_hash`	SHA-2
`hmac_md5`, `hmac_sha256`, `hmac_sha512`	HMAC with that hash
`hmac(algorithm, key, input)`	HMAC with a named algorithm
`file_hash(path, algorithm)`	A file’s contents, with MD5, SHA-1, SHA-256 (the default), SHA-384 or SHA-512

file_hash reads the file in chunks, so it can hash files larger than memory, such as a download you want to check against a published checksum:

println crypto::file_hash("kiwi-linux-x64.tar.gz")             # SHA-256
println crypto::file_hash("kiwi-linux-x64.tar.gz", "SHA512")

file_hash is unavailable in safe mode.

MD5 and SHA-1 are fine for checksums and cache keys but are no longer safe against deliberate tampering; use SHA-256 or better for anything security-related. These functions hash data; they are not suitable for storing passwords, which need a slow, salted algorithm.

Random values

random_bytes(n) returns n bytes from the operating system’s cryptographically secure generator, and uuid() returns a random (version 4) UUID built from the same source. Use them for tokens, keys and session identifiers; math::random is not suitable for those.

token = crypto::random_bytes(16).to_hex()
println token.size()          # 32
println crypto::uuid().size()  # 36

For Base64 and hex encoding, see encode.

Functions

`crypto::md5_hash`

crypto::md5_hash(input = "")

Computes the MD5 hex digest of a string or bytes. A string is hashed as UTF-8.

Parameter	Type	Default	Description
`input`	`string\|bytes`	`""`	The input to hash (default `""`).

Returns string — A 32-character lowercase hexadecimal MD5 digest.

`crypto::sha224_hash`

crypto::sha224_hash(input = "")

Computes the SHA-224 hex digest of a string or bytes. A string is hashed as UTF-8.

Parameter	Type	Default	Description
`input`	`string\|bytes`	`""`	The input to hash (default `""`).

Returns string — A 56-character lowercase hexadecimal SHA-224 digest.

`crypto::sha256_hash`

crypto::sha256_hash(input = "")

Computes the SHA-256 hex digest of a string or bytes. A string is hashed as UTF-8.

Parameter	Type	Default	Description
`input`	`string\|bytes`	`""`	The input to hash (default `""`).

Returns string — A 64-character lowercase hexadecimal SHA-256 digest.

`crypto::sha1_hash`

crypto::sha1_hash(input = "")

Computes the SHA-1 hex digest of a string or bytes. A string is hashed as UTF-8.

Parameter	Type	Default	Description
`input`	`string\|bytes`	`""`	The input to hash (default `""`).

Returns string — A 40-character lowercase hexadecimal SHA-1 digest.

`crypto::sha384_hash`

crypto::sha384_hash(input = "")

Computes the SHA-384 hex digest of a string or bytes. A string is hashed as UTF-8.

Parameter	Type	Default	Description
`input`	`string\|bytes`	`""`	The input to hash (default `""`).

Returns string — A 96-character lowercase hexadecimal SHA-384 digest.

`crypto::sha512_hash`

crypto::sha512_hash(input = "")

Computes the SHA-512 hex digest of a string or bytes. A string is hashed as UTF-8.

Parameter	Type	Default	Description
`input`	`string\|bytes`	`""`	The input to hash (default `""`).

Returns string — A 128-character lowercase hexadecimal SHA-512 digest.

`crypto::random_bytes`

crypto::random_bytes(count: integer): bytes

Generates cryptographically secure random bytes, suitable for tokens, keys and session identifiers.

Parameter	Type	Default	Description
`count`	`integer`		How many bytes to generate (0 to 1048576).

Returns bytes — The random bytes.

`crypto::uuid`

crypto::uuid(): string

Generates a random (version 4) UUID from a cryptographically secure source.

Returns string — A UUID in lowercase 36-character form, such as "3f2b8c1e-9a4d-4e7b-b1c2-5d6e7f8a9b0c".

`crypto::file_hash`

crypto::file_hash(path, algorithm = "SHA256")

Computes the hex digest of a file's contents. The file is read in chunks, so it can be larger than memory. Unavailable in safe mode.

Parameter	Type	Default	Description
`path`	`string`		The file to hash.
`algorithm`	`string`	`"SHA256"`	One of "MD5", "SHA1", "SHA256", "SHA384" or "SHA512" (default "SHA256").

Returns string — Lowercase hexadecimal digest.

Throws FileReadError — If the file can't be read.

`crypto::hmac`

crypto::hmac(algorithm, key, input)

Computes an HMAC hex digest. Strings are hashed as UTF-8.

Parameter	Type	Description
`algorithm`	`string`	One of "MD5", "SHA256", "SHA512".
`key`	`string\|bytes`	The HMAC key.
`input`	`string\|bytes`	The input.

Returns string — Lowercase hexadecimal HMAC digest.

`crypto::hmac_sha256`

crypto::hmac_sha256(key, input)

Computes HMAC-SHA256. Strings are hashed as UTF-8.

Parameter	Type	Default	Description
`key`	`string\|bytes`		The HMAC key.
`input`	`string\|bytes`		The input.

Returns string — Lowercase hexadecimal digest.

`crypto::hmac_sha512`

crypto::hmac_sha512(key, input)

Computes HMAC-SHA512. Strings are hashed as UTF-8.

Parameter	Type	Default	Description
`key`	`string\|bytes`		The HMAC key.
`input`	`string\|bytes`		The input.

Returns string — Lowercase hexadecimal digest.

`crypto::hmac_md5`

crypto::hmac_md5(key, input)

Computes HMAC-MD5. Strings are hashed as UTF-8.

Parameter	Type	Default	Description
`key`	`string\|bytes`		The HMAC key.
`input`	`string\|bytes`		The input.

Returns string — Lowercase hexadecimal digest.

`MD5` struct

A pure-Kiwi implementation of the MD5 message-digest algorithm.

`MD5.hexdigest`

static MD5.hexdigest(input)

Computes the MD5 hex digest of a string.

Parameter	Type	Default	Description
`input`	`string`		The input string to hash.

Returns string — A 32-character lowercase hexadecimal MD5 digest.

`MD5.left_rotate`

static MD5.left_rotate(value, count)

Parameter	Type	Default	Description
`value`	`any`
`count`	`any`

`MD5.int_to_bytes`

static MD5.int_to_bytes(num)

Parameter	Type	Default	Description
`num`	`any`

`SHA` struct

A SHA-2 implementation based on the implementation in PyPy https://foss.heptapod.net/pypy/pypy/-/blob/branch/default/lib_pypy/_sha256.py

`SHA.BLOCKSIZE`

static SHA.BLOCKSIZE()

`SHA.DIGESTSIZE`

static SHA.DIGESTSIZE()

`SHA.new_shaobject`

static SHA.new_shaobject()

`SHA.Ch`

static SHA.Ch(x, y, z)

Parameter	Type	Default	Description
`x`	`any`
`y`	`any`
`z`	`any`

`SHA.Maj`

static SHA.Maj(x, y, z)

Parameter	Type	Default	Description
`x`	`any`
`y`	`any`
`z`	`any`

`SHA.S`

static SHA.S(x, n)

Parameter	Type	Default	Description
`x`	`any`
`n`	`any`

`SHA.R`

static SHA.R(x, n)

Parameter	Type	Default	Description
`x`	`any`
`n`	`any`

`SHA.Sigma0`

static SHA.Sigma0(x)

Parameter	Type	Default	Description
`x`	`any`

`SHA.Sigma1`

static SHA.Sigma1(x)

Parameter	Type	Default	Description
`x`	`any`

`SHA.Gamma0`

static SHA.Gamma0(x)

Parameter	Type	Default	Description
`x`	`any`

`SHA.Gamma1`

static SHA.Gamma1(x)

Parameter	Type	Default	Description
`x`	`any`

`SHA.RND`

static SHA.RND(a, b, c, d, e, f, g, h, i, ki, W)

Parameter	Type	Default	Description
`a`	`any`
`b`	`any`
`c`	`any`
`d`	`any`
`e`	`any`
`f`	`any`
`g`	`any`
`h`	`any`
`i`	`any`
`ki`	`any`
`W`	`any`

`SHA.transform`

static SHA.transform(sha_info)

Parameter	Type	Default	Description
`sha_info`	`any`

`SHA.sha_init`

static SHA.sha_init()

`SHA.sha224_init`

static SHA.sha224_init()

`SHA.getbuf`

static SHA.getbuf(s)

Parameter	Type	Default	Description
`s`	`any`

`SHA.sha_update`

static SHA.sha_update(sha_info, buffer)

Parameter	Type	Default	Description
`sha_info`	`any`
`buffer`	`any`

`SHA.sha_final`

static SHA.sha_final(sha_info)

Parameter	Type	Default	Description
`sha_info`	`any`

`SHA256` struct

A pure-Kiwi SHA-256 hasher supporting incremental updates.

`SHA256.new`

SHA256.new(s = null)

Creates a new SHA-256 hasher, optionally hashing an initial string.

Parameter	Type	Default	Description
`s`	`string\|none`	`null`	An optional initial input string (default `null`).

`.update`

update(s)

Feeds additional data into the hasher.

Parameter	Type	Default	Description
`s`	`string`		The data to hash.

`.digest`

digest()

Returns the raw digest as a list of bytes.

Returns list — A list of integers representing the digest bytes.

`.hexdigest`

hexdigest()

Returns the hex-encoded digest string.

Returns string — A 64-character lowercase hexadecimal SHA-256 digest.

`.copy`

copy()

Returns a copy of this hasher with the same internal state.

Returns SHA256 — A new independent SHA256 instance.

`SHA224` struct

Inherits from SHA256.

A pure-Kiwi SHA-224 hasher. Inherits from SHA256 with a 224-bit digest.

`SHA224.new`

SHA224.new(s = null)

Creates a new SHA-224 hasher, optionally hashing an initial string.

Parameter	Type	Default	Description
`s`	`string\|none`	`null`	An optional initial input string (default `null`).

`.update`

update(s)

Feeds additional data into the hasher.

Parameter	Type	Default	Description
`s`	`string`		The data to hash.

`.digest`

digest()

Returns the raw digest as a list of bytes.

Returns list — A list of integers representing the digest bytes.

`.hexdigest`

hexdigest()

Returns the hex-encoded digest string.

Returns string — A 56-character lowercase hexadecimal SHA-224 digest.

`.copy`

copy()

Returns a copy of this hasher with the same internal state.

Returns SHA224 — A new independent SHA224 instance.

crypto

Random values

Functions

crypto::md5_hash

crypto::sha224_hash

crypto::sha256_hash

crypto::sha1_hash

crypto::sha384_hash

crypto::sha512_hash

crypto::random_bytes

crypto::uuid

crypto::file_hash

crypto::hmac

crypto::hmac_sha256

crypto::hmac_sha512

crypto::hmac_md5

MD5 struct

MD5.hexdigest

MD5.left_rotate

MD5.int_to_bytes

SHA struct

SHA.BLOCKSIZE

SHA.DIGESTSIZE

SHA.new_shaobject

SHA.Ch

SHA.Maj

SHA.S

SHA.R

SHA.Sigma0

SHA.Sigma1

SHA.Gamma0

SHA.Gamma1

SHA.RND

SHA.transform

SHA.sha_init

SHA.sha224_init

SHA.getbuf

SHA.sha_update

SHA.sha_final

SHA256 struct

SHA256.new

.update

.digest

.hexdigest

.copy

SHA224 struct

SHA224.new

.update

.digest

.hexdigest

.copy

`crypto::md5_hash`

`crypto::sha224_hash`

`crypto::sha256_hash`

`crypto::sha1_hash`

`crypto::sha384_hash`

`crypto::sha512_hash`

`crypto::random_bytes`

`crypto::uuid`

`crypto::file_hash`

`crypto::hmac`

`crypto::hmac_sha256`

`crypto::hmac_sha512`

`crypto::hmac_md5`

`MD5` struct

`MD5.hexdigest`

`MD5.left_rotate`

`MD5.int_to_bytes`

`SHA` struct

`SHA.BLOCKSIZE`

`SHA.DIGESTSIZE`

`SHA.new_shaobject`

`SHA.Ch`

`SHA.Maj`

`SHA.S`

`SHA.R`

`SHA.Sigma0`

`SHA.Sigma1`

`SHA.Gamma0`

`SHA.Gamma1`

`SHA.RND`

`SHA.transform`

`SHA.sha_init`

`SHA.sha224_init`

`SHA.getbuf`

`SHA.sha_update`

`SHA.sha_final`

`SHA256` struct

`SHA256.new`

`.update`

`.digest`

`.hexdigest`

`.copy`

`SHA224` struct

`SHA224.new`

`.update`

`.digest`

`.hexdigest`

`.copy`