Crypto functions ​

Crypto functions cover the cryptography an integration actually needs, such as proving a webhook came from the sender it claims, signing an outbound API request, generating a JWT, or computing a checksum.

Choose an algorithm ​

Use the algorithm that best fits your use case:

MD5 and SHA-1 are broken for anything security-sensitive. WEL provides them because integrations must sometimes match a partner system that still uses them. Don't choose them for new work.

Naming convention ​

Each algorithm comes in two forms, distinguished by a hex_ prefix:

• sha256(...) returns a Binary digest: the raw bytes.
• hex_sha256(...) returns a String of hex characters.

Compare the hex form against a signature header, or put it in a JSON field. Use the Binary form when feeding the digest into another function.

Hashing ​

All hash functions accept a String or a Binary.

hex_sha256 and sha256 ​

SHA-256 is the default choice for new work.

hex_sha256(value)
sha256(value)

hex_sha256('acme')

822b33ad87c148a0a20a5ba7cd5ebcaa68d36a18e7aad165554903f52ca82757

byte_length(sha256('acme'))

32

hex_sha512 and sha512 ​

SHA-512 produces a longer digest from the same family.

hex_sha512(value)
sha512(value)

byte_length(sha512('acme'))

64

hex_sha512_256 and sha512_256 ​

SHA-512/256 produces a 256-bit digest and avoids the length-extension property of SHA-256.

Use it when hashing a secret and a message. An HMAC handles that case more directly, though, and is usually the better choice.

hex_sha512_256(value)
sha512_256(value)

hex_sha512_256('acme')

2e7a8d79ac01f85db494bfddf90cc808d091543addc18bb68ad643257234735a

hex_sha1 and sha1 ​

SHA-1 is legacy only, kept for compatibility with systems that still require it.

hex_sha1(value)
sha1(value)

hex_sha1('acme')

293abb6b76d7791c0732cc517d38c4b5c734b87f

hex_md5 and md5 ​

MD5 is legacy only, suitable for a non-adversarial checksum and nothing else.

hex_md5(value)
md5(value)

hex_md5('acme')

53bce4f1dfa0fe8e7ca126f91b35d3a6

HMAC signatures ​

An HMAC combines a message with a shared secret to produce a signature. Webhook providers commonly use HMAC signatures to verify that requests come from a trusted sender.

Every HMAC function takes the message first and the key second.

hmac_hex and hmac ​

Compute an HMAC with the algorithm named as an argument.

hmac_hex(message, key, algorithm)
hmac(message, key, algorithm)

hmac_hex('payload', 'secret', 'sha256')

b82fcb791acec57859b989b430a826488ce2e479fdf92326bd0a2e8375a42ba4

byte_length(hmac('payload', 'secret', 'sha256'))

32

hmac_algos ​

Lists the supported HMAC algorithms.

hmac_algos()

hmac_algos()

["md5", "sha1", "sha256", "sha384", "sha512"]

hmac_hex_sha256 and hmac_sha256 ​

Most webhook providers use HMAC-SHA256.

hmac_hex_sha256(message, key)
hmac_sha256(message, key)

hmac_hex_sha256('payload', 'secret')

b82fcb791acec57859b989b430a826488ce2e479fdf92326bd0a2e8375a42ba4

hmac_hex_sha384 and hmac_sha384 ​

HMAC-SHA384 works like HMAC-SHA256, with a longer digest.

hmac_hex_sha384(message, key)
hmac_sha384(message, key)

byte_length(hmac_sha384('payload', 'secret'))

48

hmac_hex_sha512 and hmac_sha512 ​

HMAC-SHA512 works like HMAC-SHA256, with an even longer digest than HMAC-SHA384.

hmac_hex_sha512(message, key)
hmac_sha512(message, key)

byte_length(hmac_sha512('payload', 'secret'))

64

hmac_hex_sha1 and hmac_sha1 ​

HMAC-SHA1 is legacy only, kept for compatibility with systems that still require it.

hmac_hex_sha1(message, key)
hmac_sha1(message, key)

byte_length(hmac_sha1('payload', 'secret'))

20

hmac_hex_md5 and hmac_md5 ​

HMAC-MD5 is legacy only, kept for compatibility with systems that still require it.

hmac_hex_md5(message, key)
hmac_md5(message, key)

byte_length(hmac_md5('payload', 'secret'))

16

Use case: Verify an inbound webhook signature ​

The provider signs the raw body with a shared secret and sends the result in a header. Use hmac_hex_sha256 to recompute the signature and compare it against the header:

Input

{
  "body": "payload",
  "secret": "secret",
  "signature_header": "b82fcb791acec57859b989b430a826488ce2e479fdf92326bd0a2e8375a42ba4"
}

Formula

{
  expected: hmac_hex_sha256(_.body, _.secret),
  valid: hmac_hex_sha256(_.body, _.secret) == _.signature_header
}

Output

{
  "expected": "b82fcb791acec57859b989b430a826488ce2e479fdf92326bd0a2e8375a42ba4",
  "valid": true
}

Sign the raw body exactly as received. Parsing the JSON and re-serializing it changes the bytes, including key order and whitespace. The signature won't match, even though nothing is wrong.

JSON web tokens ​

WEL supports HMAC-signed JWTs: HS256, HS384, and HS512.

jwt_encode ​

Builds and signs a JWT.

jwt_encode(payload, key, algorithm, options)

jwt_encode({sub: 'user-1'}, '0123456789abcdef0123456789abcdef', 'HS256')

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ1c2VyLTEifQ.FKuUN7RwYyegTHXiye1jBlIKzmjIfb39oxKzJk_Gmdo

jwt_decode ​

Decodes a JWT and verifies its signature. A token whose signature doesn't match raises an error rather than returning its contents.

jwt_decode(token, key, algorithm, options)

jwt_decode(jwt_encode({sub: 'user-1'}, '0123456789abcdef0123456789abcdef', 'HS256'), '0123456789abcdef0123456789abcdef', 'HS256')

{header: {alg: "HS256", typ: "JWT"}, payload: {sub: "user-1"}}

jwt_algos ​

Lists the supported JWT signing algorithms.

jwt_algos()

jwt_algos()

["HS256", "HS384", "HS512"]

Key derivation ​

Key derivation turns a password into a cryptographic key suitable for encryption.

pbkdf2 ​

Derives a key from a password using PBKDF2.

A higher iteration count makes guessing the password more expensive, so use the highest value the destination system permits. Take the salt from random_bytes rather than writing a fixed one.

pbkdf2(password, salt, iterations, key_length, algorithm)

encode_hex_string(pbkdf2('password', 'salt', 1000, 16, 'sha256'))

632c2812e46d4604102ba7618e9d6d7d

Encryption ​

The following functions encrypt and decrypt data with AES in CBC mode:

aes_cbc_encrypt ​

Encrypts data with AES in CBC mode, applying PKCS7 padding.

aes_cbc_encrypt(data, key, iv)

encode_base64(aes_cbc_encrypt('secret data!!!!!', '0123456789abcdef', 'abcdef0123456789'))

NsFUgzVrilJO5OF/imH/gbF6NPToZkf1hbVBJkaXXoY=

aes_cbc_decrypt ​

Decrypts AES-CBC data and removes PKCS7 padding.

aes_cbc_decrypt(data, key, iv)

decode_string(aes_cbc_decrypt(aes_cbc_encrypt('secret data!!!!!', '0123456789abcdef', 'abcdef0123456789'), '0123456789abcdef', 'abcdef0123456789'), 'UTF-8')

secret data!!!!!

Related ​

• Binary functions: More information about encode_base64, encode_hex_string, and byte_length.
• Random functions: Generate random_bytes for salts and initialization vectors.
• Encoding functions: Use decode_string to turn decrypted bytes back into text.
• Error codes: Troubleshoot job failures such as E220.