DominScript — crypto

10 functionsnamespace cryptosource plugins/crypto/CryptoPlugin.c

Written from a line-by-line source review; every example output is from a real run.

Introduction

The crypto plugin provides self-contained cryptographic primitives with no external library (such as OpenSSL): SHA-256 hashing, HMAC-SHA256 message authentication, generation of cryptographically secure random bytes, and hexadecimal encoding and decoding. SHA-256 follows the FIPS 180-4 standard and HMAC follows RFC 2104 — the correctness of the implementation is proven by official test vectors, not merely by the fact that it runs.

String and blob variants

Almost every operation has a text (string) and a binary (blob) variant. The string variants are convenient for textual data, but text ends at the first 0 byte, so for true binary data (file contents, an image, a key that may contain 0 bytes) use the blob variants. The hash result is a hexadecimal string (64 digits) for the string variants and raw 32 bytes for the blob variants.

What is a hash and HMAC?

SHA-256 computes a fixed, 32-byte “fingerprint” (hash) from data; the same input always gives the same hash, and it is practically impossible to recover the original from the hash. With it you can check that data has not changed. HMAC-SHA256 is a hash combined with a secret key: it proves not only integrity but also authenticity — only someone who knows the key can compute or verify it.

Loading the plugin

plugin "../plugins/print/PrintPlugin";
plugin "../plugins/crypto/CryptoPlugin";

A typical flow

// the fingerprint of a text (hex)
printf("%s\n", crypto.Sha256Hex("abc"));
// message authentication with a secret key
printf("%s\n", crypto.HmacSha256Hex("secret-key", "message"));

What to know about every function (the basics)

Every call is stateless and standalone: no open/close, no handle, no shared state. So every function is thread-safe.
SHA-256 and HMAC are deterministic: the same input (and key) always gives the same result. The Random* functions, by contrast, give a different, unpredictable result on every call.
Hex encoding is lowercase (0–9, a–f). One byte is two hex digits, so n bytes become 2n digits.
FromHex / FromHexBlob raise an error for an input of odd length or containing a non-hex character.
String FromHex truncates the result at the first 0 byte; if the decoded data may contain 0 bytes, use FromHexBlob, which returns a raw blob.
The n of the Random* functions must be between 1 and 4096; outside that they raise a runtime error.

How to read the signatures

The type after the -> arrow is the return type. For example, crypto.HmacSha256Hex(key, data) -> string takes two arguments (key and data) and returns a hexadecimal string. The blob variants take blob-typed arguments and/or return a blob.

Hashing and authentication (text)

SHA-256 and HMAC-SHA256 on text input, with hexadecimal output. Simple and convenient where the input is text.

crypto.Sha256Hex

crypto.Sha256Hex(data) -> string

Computes the SHA-256 hash of a text and returns it as a 64-digit lowercase hexadecimal string.

Parameters

Parameter	Type	Description
data	string	The text to hash.

Return value

The 32-byte hash as 64 hex digits.

Example

printf("%s\n", crypto.Sha256Hex("abc"));
printf("%s\n", crypto.Sha256Hex(""));

Output after running

ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad
e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

When to use

For checking data integrity, or deriving a cache key or unique identifier from a text. IMPORTANT: it is NOT suitable on its own for storing passwords — that needs a dedicated, slow password hash (such as bcrypt/scrypt).

crypto.HmacSha256Hex

crypto.HmacSha256Hex(key, data) -> string

Computes an HMAC-SHA256 message authentication code with a secret key, as a 64-digit hex string.

Parameters

Parameter	Type	Description
key	string	The secret key.
data	string	The message to authenticate.

Return value

The 32-byte HMAC as 64 hex digits.

Example

printf("%s\n",
crypto.HmacSha256Hex("key",
"The quick brown fox jumps over the lazy dog"));

Output after running

f7bc83f430538424b13298e6aa6fb143ef4d59a14946175997479dbc2d1a3cd8

When to use

For signing API requests, verifying the authenticity of webhooks, or protecting any message against tampering. The key must be kept secret; the receiving side recomputes with the same key and compares the HMAC.

Random (text)

Cryptographically secure random bytes as a hexadecimal string.

crypto.RandomHex

crypto.RandomHex(n) -> string

Generates n cryptographically secure random bytes and returns them as a 2n-digit hex string.

Parameters

Parameter	Type	Description
n	int	The number of random bytes (between 1 and 4096).

Return value

A string of 2n hex digits. Every call gives a different result.

Example

// 8 random bytes = 16 hex digits
printf("%d\n", str.Len(crypto.RandomHex(8)));

Output after running

When to use

For generating a session token, a one-time code, a salt, or a unique key. Being cryptographically secure, it is unguessable — unlike a conventional, non-secure random number generator.

Hexadecimal encoding (text)

Converting a text's bytes to and from a hexadecimal string.

crypto.ToHex

crypto.ToHex(data) -> string

Encodes a text's bytes as a lowercase hexadecimal string.

Parameters

Parameter	Type	Description
data	string	The text to encode.

Return value

The hex form of the bytes (two digits per byte).

Example

printf("%s\n", crypto.ToHex("abc"));

Output after running

When to use

For turning binary or non-printable data into a readable, transportable form (for example for a log or a text protocol). The code of 'a' is 0x61, so "abc" becomes 616263.

crypto.FromHex

crypto.FromHex(hex) -> string

Decodes a hexadecimal string back into the bytes it encodes, returned as a string.

Parameters

Parameter	Type	Description
hex	string	The hex string to decode (even length, hex digits only).

Return value

The decoded text. An odd length or a non-hex character causes a runtime error.

Example

printf("%s\n", crypto.FromHex("616263"));

Output after running

abc

When to use

The counterpart of ToHex. Since it returns the result as a string, it is truncated at the first 0 byte — if the decoded data may contain 0 bytes, use FromHexBlob.

Hashing and authentication (blob)

The same operations on raw binary data. The input and the hash result are a blob, so data containing 0 bytes is not truncated.

crypto.Sha256

crypto.Sha256(data) -> blob

Computes the SHA-256 hash of a blob and returns it as a raw 32-byte blob.

Parameters

Parameter	Type	Description
data	blob	The binary data to hash.

Return value

The 32-byte hash as a blob.

Example

blob $D[16];
blob $H[64];
$D[0] = 97; $D[1] = 98; $D[2] = 99; // "abc"
$D.Length = 3;
$H = crypto.Sha256($D);
printf("%d\n", $H.Length);
printf("%s\n", crypto.ToHexBlob($H));

Output after running

32
ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad

When to use

For computing the fingerprint of arbitrary binary data (a file, an image, a network message) where the 0 byte also matters. Render the result as readable hex with ToHexBlob.

crypto.HmacSha256

crypto.HmacSha256(key, data) -> blob

Computes the HMAC-SHA256 code with a binary key and data, as a raw 32-byte blob.

Parameters

Parameter	Type	Description
key	blob	The secret key in binary form.
data	blob	The binary message to authenticate.

Return value

The 32-byte HMAC as a blob.

Example

blob $K[16];
blob $D[16];
blob $M[64];
$K[0]=107; $K[1]=101; $K[2]=121; $K.Length=3; // "key"
$D[0]=97; $D[1]=98; $D[2]=99; $D.Length=3; // "abc"
$M = crypto.HmacSha256($K, $D);
printf("%s\n", crypto.ToHexBlob($M));

Output after running

9c196e32dc0175f86f4b1cb89289d6619de6bee699e4c378e68309ed97a1a6ab

When to use

For authenticating binary messages or keys where the key is raw bytes (not text). The same algorithm as HmacSha256Hex, just with blob input and output.

Random and hex (blob)

Secure random raw bytes, and converting blobs to and from a hexadecimal string.

crypto.RandomBytes

crypto.RandomBytes(n) -> blob

Generates n cryptographically secure random bytes as a raw blob.

Parameters

Parameter	Type	Description
n	int	The number of random bytes (between 1 and 4096).

Return value

An n-byte blob. Every call gives a different result.

Example

blob $R[64];
$R = crypto.RandomBytes(16);
printf("%d\n", $R.Length);

Output after running

When to use

For generating a binary key, an initialization vector (IV), or a salt that you use further as raw bytes. Unlike RandomHex, here you get a blob directly, without hex encoding.

crypto.ToHexBlob

crypto.ToHexBlob(data) -> string

Encodes a blob's raw bytes as a lowercase hexadecimal string.

Parameters

Parameter	Type	Description
data	blob	The binary data to encode.

Return value

The hex form of the bytes as a string (two digits per byte).

Example

blob $D[16];
$D[0]=97; $D[1]=98; $D[2]=99; $D.Length=3; // "abc"
printf("%s\n", crypto.ToHexBlob($D));

Output after running

When to use

For turning the blob results of hash/HMAC, or any binary data, into readable, transportable hex. A natural companion to the blob output of Sha256 / HmacSha256.

crypto.FromHexBlob

crypto.FromHexBlob(hex) -> blob

Decodes a hexadecimal string into a raw, 0-byte-safe blob.

Parameters

Parameter	Type	Description
hex	string	The hex string to decode (even length, hex digits only).

Return value

The decoded raw bytes as a blob. An odd length or a non-hex character causes a runtime error.

Example

blob $B[16];
$B = crypto.FromHexBlob("616263");
printf("%d\n", $B.Length);
printf("%s\n", crypto.ToHexBlob($B));

Output after running

3
616263

When to use

For recovering a binary value (a hash, key, packet) stored or transmitted as hex. Unlike FromHex, it returns a raw blob, so data containing 0 bytes is not truncated.

Practical notes

What the crypto plugin is good for

Checking data integrity: a hash proves that a file or message has not changed.
Message authentication: with HMAC you can sign and verify API requests, webhooks, tokens.
Secure random: generating a session token, salt, or one-time code unguessably.
Hex encoding: turning binary data into a readable form transportable in a text protocol.

String vs blob variant

For textual data the string variants are more convenient. For true binary data — or if the result may contain 0 bytes — always use the blob variants, because a string ends at the first 0 byte. Render the blob result of a hash/HMAC with ToHexBlob, and recover it with FromHexBlob.

Security warnings

Passwords: SHA-256 on its own is NOT a password store. A password needs a dedicated, deliberately slow algorithm (bcrypt, scrypt, Argon2) and a unique salt.
Key management: HMAC is secure only as long as the key stays secret. Do not bake the key permanently into the source; handle it securely.
Random: for cryptographic purposes (a token, salt, key) always use the crypto.Random* functions, never an ordinary, non-secure random number generator.
Comparison: the equality of secret values (such as an HMAC) should ideally be checked in constant time; a simple string equality can in principle be exposed to a timing attack.

Error handling

A wrong argument count or type, a bad hex input (odd length or a non-hex character), an out-of-range n (Random*), and out of memory are reported by the runtime as a runtime error, and the script stops. The crypto plugin has no “neutral-return” error state for hashes/HMACs: for a valid input it always gives a deterministic result. So it is worth ensuring the validity of the input (such as the hex format) beforehand.

The blob binary utility plugin

Text-to-blob, hexdump, and raw-pointer references — complete function reference