ENCODING.md

Encoding & Security Functions

Base64, hex encoding/decoding, bcrypt, HMAC, and HTML/XML/shell escaping functions.

See also: Function Reference | Main Documentation

Functions for encoding, decoding, password hashing, and escaping data for various contexts.

base64_encode

Encode a string to Base64 format. Supports both function and filter syntax.

Arguments:

• string (required) - String to encode

Returns: Base64-encoded string

Examples:

{# Function syntax #}
{{ base64_encode(string="Hello World") }}
{# Output: SGVsbG8gV29ybGQ= #}

{# Filter syntax #}
{{ "Hello World" | base64_encode }}
{# Output: SGVsbG8gV29ybGQ= #}

{# Basic Authentication header #}
{% set credentials = "admin:password123" %}
Authorization: Basic {{ credentials | base64_encode }}

base64_decode

Decode a Base64-encoded string. Supports both function and filter syntax.

Arguments:

• string (required) - Base64 string to decode

Returns: Decoded string

Examples:

{# Function syntax #}
{{ base64_decode(string="SGVsbG8gV29ybGQ=") }}
{# Output: Hello World #}

{# Filter syntax #}
{{ "SGVsbG8gV29ybGQ=" | base64_decode }}
{# Output: Hello World #}

hex_encode

Encode a string to hexadecimal format. Supports both function and filter syntax.

Arguments:

• string (required) - String to encode

Returns: Hexadecimal string (lowercase)

Examples:

{# Function syntax #}
{{ hex_encode(string="Hello") }}
{# Output: 48656c6c6f #}

{# Filter syntax #}
{{ "Hello" | hex_encode }}
{# Output: 48656c6c6f #}

hex_decode

Decode a hexadecimal-encoded string. Supports both function and filter syntax.

Arguments:

• string (required) - Hexadecimal string to decode

Returns: Decoded string

Examples:

{# Function syntax #}
{{ hex_decode(string="48656c6c6f") }}
{# Output: Hello #}

{# Filter syntax #}
{{ "48656c6c6f" | hex_decode }}
{# Output: Hello #}

bcrypt(password, rounds)

Generate a bcrypt hash for password storage. Each run produces a different hash due to the random salt.

Arguments:

• password (required) - Password to hash
• rounds (optional) - Cost factor from 4-31 (default: 12, higher = more secure but slower)

Returns: Bcrypt hash string

Examples:

{# Generate password hash #}
Password hash: {{ bcrypt(password="mypassword") }}

{# Higher security (slower) #}
Password hash: {{ bcrypt(password="mypassword", rounds=14) }}

{# Use with environment variable #}
{% set user_pass = get_env(name="USER_PASSWORD") %}
DB_PASSWORD_HASH={{ bcrypt(password=user_pass, rounds=12) }}

Note: Use bcrypt for password storage, not the SHA functions. Bcrypt includes automatic salting and is designed to be computationally expensive to prevent brute-force attacks.

generate_secret(length, charset)

Generate a cryptographically secure random string.

Arguments:

• length (required) - Length of string to generate (1-1024)
• charset (optional) - Character set: "alphanumeric" (default), "hex", or "base64"

Returns: Cryptographically secure random string

Examples:

{# Generate API key #}
API_KEY={{ generate_secret(length=32) }}

{# Generate hex token #}
SECRET_TOKEN={{ generate_secret(length=64, charset="hex") }}

{# Generate base64 secret #}
WEBHOOK_SECRET={{ generate_secret(length=48, charset="base64") }}

Practical Example:

# Generate secure credentials
API_KEY={{ generate_secret(length=32, charset="hex") }}
JWT_SECRET={{ generate_secret(length=64, charset="base64") }}
SESSION_SECRET={{ generate_secret(length=32) }}
CSRF_TOKEN={{ generate_secret(length=40, charset="hex") }}

hmac_sha256(key, message)

Generate HMAC-SHA256 signature for message authentication.

Arguments:

• key (required) - Secret key
• message (required) - Message to sign

Returns: HMAC signature as hexadecimal string

Examples:

{# Sign a message #}
{% set signature = hmac_sha256(key="secret_key", message="important data") %}
X-Signature: {{ signature }}

{# Webhook signature #}
{% set payload = '{"user_id": 123, "action": "update"}' %}
{% set webhook_secret = get_env(name="WEBHOOK_SECRET") %}
X-Hub-Signature-256: sha256={{ hmac_sha256(key=webhook_secret, message=payload) }}

escape_html

Escape HTML entities to prevent XSS attacks. Supports both function and filter syntax.

Arguments:

• string (required) - String to escape

Returns: HTML-escaped string

Examples:

{# Function syntax #}
{% set user_input = '<script>alert("XSS")</script>' %}
<div>{{ escape_html(string=user_input) }}</div>
{# Output: &lt;script&gt;alert(&quot;XSS&quot;)&lt;/script&gt; #}

{# Filter syntax #}
<div>{{ user_input | escape_html }}</div>

{# Safe HTML output from env var #}
<p>User comment: {{ get_env(name="USER_COMMENT", default="") | escape_html }}</p>

escape_xml

Escape XML entities. Supports both function and filter syntax.

Arguments:

• string (required) - String to escape

Returns: XML-escaped string

Examples:

{# Function syntax #}
{% set content = '<tag attr="value">text & more</tag>' %}
<data>{{ escape_xml(string=content) }}</data>
{# Output: &lt;tag attr=&quot;value&quot;&gt;text &amp; more&lt;/tag&gt; #}

{# Filter syntax #}
<data>{{ content | escape_xml }}</data>

escape_shell

Escape string for safe use in shell commands. Supports both function and filter syntax.

Arguments:

• string (required) - String to escape

Returns: Shell-escaped string (single-quoted)

Examples:

{# Function syntax #}
{% set filename = "my file with spaces.txt" %}
Command: cat {{ escape_shell(string=filename) }}
{# Output: cat 'my file with spaces.txt' #}

{# Filter syntax #}
Command: cat {{ filename | escape_shell }}

{# Escape special characters #}
{% set message = "it's working!" %}
echo {{ message | escape_shell }}
{# Output: echo 'it'\''s working!' #}

Security Warning: While escape_shell helps prevent injection, the safest approach is to avoid dynamic shell commands entirely when possible. Use exec() function only with trusted, hardcoded commands.

Chaining Encoding Filters

Encoding functions can be chained with hash functions for powerful transformations:

{# Encode then hash #}
{{ "Hello" | base64_encode | sha256 }}
{# First: "SGVsbG8=" then: SHA-256 of that #}

{# Hash then encode #}
{{ "Hello" | sha256 | base64_encode }}
{# First: hex hash, then: base64 of the hex string #}

{# Multi-step encoding #}
{{ "secret" | hex_encode | base64_encode }}

{# Decode chain #}
{{ "NjE2MjYz" | base64_decode | hex_decode }}
{# Output: abc #}