OpenSSL

Reference for the openssl API.

TIP

All data parameters accept both strings and byte arrays (integer[]). Return values are binary-safe strings. Use openssl.hex_encode() or openssl.base64_encode() to convert binary output to readable text.

WARNING

Functions do not throw on error. Instead, they return an empty string (or nil for table returns). Always check openssl.success() after a call, and use openssl.last_error() to get the error message.

Functions

openssl.success

Returns whether the last openssl call succeeded.

function openssl.success(): bool

openssl.last_error

Returns the error message from the last failed openssl call, or an empty string if the last call succeeded.

function openssl.last_error(): string

openssl.encrypt

Encrypt data using a symmetric cipher. Returns an empty string on failure.

---@param algorithm string
---@param key string|integer[]
---@param data string|integer[]
---@param iv? string|integer[]
function openssl.encrypt(algorithm, key, data, iv?): string

openssl.decrypt

Decrypt data using a symmetric cipher. Returns an empty string on failure.

---@param algorithm string
---@param key string|integer[]
---@param data string|integer[]
---@param iv? string|integer[]
function openssl.decrypt(algorithm, key, data, iv?): string

openssl.encrypt_gcm

Encrypt data using a GCM mode cipher. Returns a table containing data (ciphertext) and tag (authentication tag), or nil on failure.

---@param algorithm string
---@param key string|integer[]
---@param data string|integer[]
---@param iv string|integer[]
---@param aad? string|integer[]
---@param tag_len? integer
function openssl.encrypt_gcm(algorithm, key, data, iv, aad?, tag_len?): { data: string, tag: string }|nil

openssl.decrypt_gcm

Decrypt data using a GCM mode cipher. Verifies the authentication tag. Returns an empty string on failure.

---@param algorithm string
---@param key string|integer[]
---@param data string|integer[]
---@param iv string|integer[]
---@param tag string|integer[]
---@param aad? string|integer[]
function openssl.decrypt_gcm(algorithm, key, data, iv, tag, aad?): string

openssl.hash

Compute a one-shot hash digest. Returns an empty string on failure.

---@param algorithm string
---@param data string|integer[]
function openssl.hash(algorithm, data): string

openssl.hmac

Compute a keyed HMAC. Returns an empty string on failure.

---@param algorithm string
---@param key string|integer[]
---@param data string|integer[]
function openssl.hmac(algorithm, key, data): string

openssl.rand

Generate cryptographically secure random bytes. Returns an empty string on failure.

---@param size integer
function openssl.rand(size): string

openssl.base64_encode

Encode binary data to a base64 string.

---@param data string|integer[]
function openssl.base64_encode(data): string

openssl.base64_decode

Decode a base64 string to binary data. Returns an empty string on failure.

---@param data string
function openssl.base64_decode(data): string

openssl.hex_encode

Encode binary data to a lowercase hex string.

---@param data string|integer[]
function openssl.hex_encode(data): string

openssl.hex_decode

Decode a hex string to binary data. Returns an empty string on failure.

---@param data string
function openssl.hex_decode(data): string

openssl.dh_new

Create a new Diffie-Hellman context with generated parameters. Returns nil on failure.

WARNING

Generating parameters is slow (seconds for 2048-bit). Use openssl.dh_group() with pre-computed parameters instead when possible.

---@param prime_bits? integer
---@param generator? integer
function openssl.dh_new(prime_bits?, generator?): dh_context|nil

openssl.dh_group

Create a Diffie-Hellman context from pre-computed RFC parameters. Returns nil on failure.

---@param group string
function openssl.dh_group(group): dh_context|nil

Available groups: rfc5114_1024_160, rfc5114_2048_224, rfc5114_2048_256

Types

dh_context

function dh_context:get_p(): string

function dh_context:get_g(): string

function dh_context:generate_key(): bool

function dh_context:get_public_key(): string

---@param peer_public_key string|integer[]
function dh_context:compute_key(peer_public_key): string

Algorithms

Ciphers

Name	Key Size	IV Size	Notes
aes-128-cbc	16	16
aes-128-ecb	16	0	No IV needed
aes-128-cfb	16	16
aes-128-ofb	16	16
aes-128-ctr	16	16
aes-128-gcm	16	12	Use encrypt_gcm/decrypt_gcm
aes-192-cbc	24	16
aes-192-ecb	24	0	No IV needed
aes-192-cfb	24	16
aes-192-ofb	24	16
aes-192-ctr	24	16
aes-192-gcm	24	12	Use encrypt_gcm/decrypt_gcm
aes-256-cbc	32	16
aes-256-ecb	32	0	No IV needed
aes-256-cfb	32	16
aes-256-ofb	32	16
aes-256-ctr	32	16
aes-256-gcm	32	12	Use encrypt_gcm/decrypt_gcm
bf-cbc	16	8	Blowfish
bf-ecb	16	0	Blowfish, no IV needed
bf-cfb	16	8	Blowfish
bf-ofb	16	8	Blowfish
rc4	16	0	Stream cipher, no IV needed

Digests

Name	Output Size
md5	16
sha1	20
sha224	28
sha256	32
sha384	48
sha512	64

Examples

Error handling

local encrypted = openssl.encrypt('aes-256-cbc', 'short_key', 'data', '1234567890123456')
if not openssl.success() then
  print('error: ' .. openssl.last_error())
  return
end

Hashing

-- sha256 hash as hex
local digest = openssl.hash('sha256', 'hello world')
print(openssl.hex_encode(digest))

-- md5 hash
local md5 = openssl.hex_encode(openssl.hash('md5', 'hello'))

Hashing with byte array input

local bytes = { 0x68, 0x65, 0x6c, 0x6c, 0x6f }
local digest = openssl.hash('sha256', bytes)
print(openssl.hex_encode(digest))

HMAC

local mac = openssl.hmac('sha256', 'secret_key', 'message')
print(openssl.hex_encode(mac))

AES-256-CBC encryption

local key = openssl.rand(32) -- 256-bit key
local iv = openssl.rand(16)  -- 128-bit IV

local encrypted = openssl.encrypt('aes-256-cbc', key, 'hello world', iv)
if not openssl.success() then
  print(openssl.last_error())
  return
end

local decrypted = openssl.decrypt('aes-256-cbc', key, encrypted, iv)
print(decrypted) -- 'hello world'

AES-256-GCM authenticated encryption

local key = openssl.rand(32)
local iv = openssl.rand(12)

local result = openssl.encrypt_gcm('aes-256-gcm', key, 'secret data', iv)
if not openssl.success() then
  print(openssl.last_error())
  return
end

local plaintext = openssl.decrypt_gcm('aes-256-gcm', key, result.data, iv, result.tag)
print(plaintext) -- 'secret data'

Blowfish encryption

local key = openssl.rand(16)
local iv = openssl.rand(8)

local encrypted = openssl.encrypt('bf-cbc', key, 'hello', iv)
local decrypted = openssl.decrypt('bf-cbc', key, encrypted, iv)

RC4 stream cipher

local key = openssl.rand(16)
local encrypted = openssl.encrypt('rc4', key, 'hello')
local decrypted = openssl.decrypt('rc4', key, encrypted)

Encrypt with byte array key

local key = { 0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07,
              0x08, 0x09, 0x0a, 0x0b, 0x0c, 0x0d, 0x0e, 0x0f }
local encrypted = openssl.encrypt('aes-128-ecb', key, 'hello world')

Diffie-Hellman key exchange

-- use pre-computed parameters (fast)
local alice = openssl.dh_group('rfc5114_2048_256')
local bob = openssl.dh_group('rfc5114_2048_256')

alice:generate_key()
bob:generate_key()

local alice_pub = alice:get_public_key()
local bob_pub = bob:get_public_key()

-- both derive the same shared secret
local alice_secret = alice:compute_key(bob_pub)
local bob_secret = bob:compute_key(alice_pub)
-- alice_secret == bob_secret

Base64 and hex encoding

local encoded = openssl.base64_encode('hello world')
print(encoded) -- 'aGVsbG8gd29ybGQ='

local decoded = openssl.base64_decode(encoded)
print(decoded) -- 'hello world'

local hex = openssl.hex_encode('\xff\x00\xab')
print(hex) -- 'ff00ab'

local bytes = openssl.hex_decode('ff00ab')