app.crypto - Encryption & Encoding API

Hashing, encryption, and encoding operations.

Hashing

app.crypto.md5(data)

Compute MD5 hash.

Parameters:

• data (string) - Data to hash

Returns: string - Hexadecimal hash value

local hash = app.crypto.md5("hello world")
-- "5eb63bbbe01eeed093cb22bb8f5acdc3"

app.crypto.sha1(data)

Compute SHA-1 hash.

local hash = app.crypto.sha1("hello world")

app.crypto.sha256(data)

Compute SHA-256 hash.

local hash = app.crypto.sha256("hello world")

app.crypto.sha512(data)

Compute SHA-512 hash.

local hash = app.crypto.sha512("hello world")

File Hashing

app.crypto.md5File(path)

Compute MD5 hash of a file.

Parameters:

• path (string) - File path

Returns: string|nil - Hash value

local hash = app.crypto.md5File("/path/to/file.zip")

app.crypto.sha1File(path)

Compute SHA-1 hash of a file.

local hash = app.crypto.sha1File("/path/to/file.zip")

app.crypto.sha256File(path)

Compute SHA-256 hash of a file.

local hash = app.crypto.sha256File("/path/to/file.zip")

Encoding

app.crypto.base64Encode(data)

Base64 encode.

Returns: string - Base64 string

local encoded = app.crypto.base64Encode("hello world")
-- "aGVsbG8gd29ybGQ="

app.crypto.base64Decode(data)

Base64 decode.

Returns: string|nil - Decoded data

local decoded = app.crypto.base64Decode("aGVsbG8gd29ybGQ=")
-- "hello world"

app.crypto.hexEncode(data)

Hex encode.

local hex = app.crypto.hexEncode("hello")
-- "68656c6c6f"

app.crypto.hexDecode(data)

Hex decode.

local decoded = app.crypto.hexDecode("68656c6c6f")
-- "hello"

app.crypto.urlEncode(data)

URL encode.

local encoded = app.crypto.urlEncode("hello world")
-- "hello%20world"

app.crypto.urlDecode(data)

URL decode.

local decoded = app.crypto.urlDecode("hello%20world")
-- "hello world"

HMAC

app.crypto.hmacSHA256(data, key)

Compute HMAC-SHA256.

Parameters:

• data (string) - Data
• key (string) - Secret key

Returns: string - Hexadecimal HMAC value

local hmac = app.crypto.hmacSHA256("message", "secret_key")

app.crypto.hmacSHA512(data, key)

Compute HMAC-SHA512.

local hmac = app.crypto.hmacSHA512("message", "secret_key")

app.crypto.hmacSHA1(data, key)

Compute HMAC-SHA1 (since 1.3.0). Useful for legacy protocols like AWS Signature V2 and OAuth 1.0.

local hmac = app.crypto.hmacSHA1("message", "secret_key")

Key Derivation

app.crypto.pbkdf2(password, salt, iterations, keyLength)

Derive a key from a password using PBKDF2-HMAC-SHA256 (since 1.3.0).

Parameters:

• password (string) - Plaintext password
• salt (string) - Salt
• iterations (number) - Iteration count (≥ 100000 recommended)
• keyLength (number) - Output key length in bytes

Returns: string - Hex-encoded key

local key = app.crypto.pbkdf2("password", "salt", 100000, 32)

ECDSA Signatures (P-256)

app.crypto.ecdsaSign(data, privateKeyPEM)

Sign data with a P-256 private key (since 1.3.0).

Parameters:

• data (string) - Data to sign
• privateKeyPEM (string) - PEM-encoded P-256 private key

Returns: string - Base64-encoded signature

local sig = app.crypto.ecdsaSign("message", privateKeyPEM)

app.crypto.ecdsaVerify(data, signature, publicKeyPEM)

Verify a P-256 ECDSA signature (since 1.3.0).

Parameters:

• data (string) - Original data
• signature (string) - Base64-encoded signature
• publicKeyPEM (string) - PEM-encoded P-256 public key

Returns: boolean - Whether the signature is valid

local ok = app.crypto.ecdsaVerify("message", sig, publicKeyPEM)

HTML Entities

app.crypto.htmlEncode(s)

Encode HTML entities (since 1.3.0). Escapes < > & " '.

app.crypto.htmlEncode('<b>"hi"&friends</b>')
-- "&lt;b&gt;&quot;hi&quot;&amp;friends&lt;/b&gt;"

app.crypto.htmlDecode(s)

Decode HTML entities (since 1.3.0). Supports named and numeric entities.

app.crypto.htmlDecode("&lt;b&gt;hi&lt;/b&gt;")  -- "<b>hi</b>"

Base64 URL

app.crypto.base64UrlEncode(data)

URL-safe Base64 encoding (since 1.3.0). Replaces +/ with -_ and strips = padding. Common in JWT.

app.crypto.base64UrlEncode("??>>")  -- no +/=

app.crypto.base64UrlDecode(data)

URL-safe Base64 decoding (since 1.3.0).

local s = app.crypto.base64UrlDecode(encoded)

AES Encryption/Decryption

app.crypto.aesEncrypt(data, key, options?)

AES encrypt.

Parameters:

• data (string) - Data to encrypt
• key (string) - Key (automatically padded/truncated to the appropriate length)
• options (table, optional):
  • mode (string) - Mode: cbc (default), ecb, gcm
  • iv (string) - Initialization vector (auto-generated if not specified)
  • keySize (number) - Key size: 128, 192, 256 (default)

Returns: string|nil - Encrypted data (Base64; CBC mode includes IV)

local encrypted = app.crypto.aesEncrypt("secret data", "my-secret-key")

-- Specify mode and IV
local encrypted = app.crypto.aesEncrypt("secret data", "my-secret-key", {
    mode = "cbc",
    iv = "16-byte-iv-here!"
})

app.crypto.aesDecrypt(encrypted, key, options?)

AES decrypt.

Parameters:

• encrypted (string) - Encrypted data (Base64)
• key (string) - Key
• options (table, optional) - Same as encryption options

Returns: string|nil - Decrypted data

local decrypted = app.crypto.aesDecrypt(encrypted, "my-secret-key")

RSA Encryption/Decryption

app.crypto.rsaGenerateKeyPair(bits?)

Generate an RSA key pair.

Parameters:

• bits (number, optional) - Key size (default 2048)

Returns: table|nil - {publicKey, privateKey} in PEM format

local keys = app.crypto.rsaGenerateKeyPair(2048)
if keys then
    app.log.info("Public key:\n" .. keys.publicKey)
    app.log.info("Private key:\n" .. keys.privateKey)
end

app.crypto.rsaEncrypt(data, publicKey)

RSA public key encryption (OAEP-SHA256).

Returns: string|nil - Base64 encoded ciphertext

local encrypted = app.crypto.rsaEncrypt("secret", keys.publicKey)

app.crypto.rsaDecrypt(encrypted, privateKey)

RSA private key decryption.

Returns: string|nil - Plaintext

local decrypted = app.crypto.rsaDecrypt(encrypted, keys.privateKey)

app.crypto.rsaSign(data, privateKey)

RSA signing (PKCS1v15-SHA256).

Returns: string|nil - Base64 encoded signature

local signature = app.crypto.rsaSign("message", keys.privateKey)

app.crypto.rsaVerify(data, signature, publicKey)

RSA signature verification.

Returns: boolean - Whether verification passed

local valid = app.crypto.rsaVerify("message", signature, keys.publicKey)

Examples

Compute File Checksums

function MyPlugin:handleChecksum(context)
    local results = {}

    for _, file in ipairs(context.selectedFiles) do
        local hash = app.crypto.sha256File(file)
        if hash then
            table.insert(results, hash .. "  " .. app.path.basename(file))
        end
    end

    local report = table.concat(results, "\n")
    app.clipboard.setText(report)
    app.notification.show("Done", "Checksums copied to clipboard")
end

Encrypt Configuration File

function MyPlugin:saveEncryptedConfig(config)
    local json = app.json.stringify(config)
    local key = app.crypto.sha256("my-app-secret"):sub(1, 32)
    local encrypted = app.crypto.aesEncrypt(json, key)

    if encrypted then
        app.file.write(self.configPath, encrypted)
    end
end

function MyPlugin:loadEncryptedConfig()
    local encrypted = app.file.read(self.configPath)
    if not encrypted then return {} end

    local key = app.crypto.sha256("my-app-secret"):sub(1, 32)
    local json = app.crypto.aesDecrypt(encrypted, key)

    if json then
        return app.json.parse(json) or {}
    end
    return {}
end