Module cipher

cipher module do encrypt or decrypt base on OpenSSL EVP API.

Usage:

    cipher = require('openssl').cipher

Functions

returns... ()
list ([alias]) list all support cipher algs
get (alg) get EVP_CIPHER cipher algorithm object

This function retrieves a cipher algorithm object by name, NID, or ASN1 object.
fetch (alg[, options]) fetch evp_cipher object with provider support (OpenSSL 3.0+)
get_provider_name () get provider name for a cipher (OpenSSL 3.0+)
__gc () free a fetched evp_cipher object (OpenSSL 3.0+)
encrypt (alg, input, key[, iv[, pad[, engine]]]) quick encrypt
decrypt (alg, input, key[, iv[, pad[, engine]]]) quick decrypt
cipher (alg, encrypt, input, key[, iv[, pad[, engine]]]) quick encrypt or decrypt
new (alg, encrypt[, key[, iv[, pad=true[, engine]]]]) create EVP_CIPHER_CTX cipher context for encryption or decryption

This function creates a new cipher context for the specified algorithm.
encrypt_new (alg, key[, iv[, engine[, pad=true]]]) get evp_cipher_ctx object for encrypt
decrypt_new (alg, key[, iv[, engine[, pad=true]]]) get evp_cipher_ctx object for decrypt

Class evp_cipher

evp_cipher:info () get infomation of evp_cipher object
evp_cipher:BytesToKey (data, string, md) derive key
evp_cipher:new (encrypt, key[, iv[, pad[, engine]]]) get evp_cipher_ctx to encrypt or decrypt
evp_cipher:encrypt_new (key[, iv[, pad[, engine]]]) get evp_cipher_ctx to encrypt
evp_cipher:decrypt_new (key[, iv[, pad[, engine]]]) get evp_cipher_ctx to decrypt
evp_cipher:cipher (encrypt, input, key[, iv[, pad[, engine]]]) do encrypt or decrypt
evp_cipher:encrypt (input, key[, iv[, pad[, engine]]]) do encrypt
evp_cipher:decrypt (input, key[, iv[, pad[, engine]]]) do decrypt

Class evp_cipher_ctx

evp_cipher_ctx:init (key[, iv]) init encrypt/decrypt cipher ctx
evp_cipher_ctx:update (data[, isAAD=false]) feed data or set AAD to do cipher
evp_cipher_ctx:final () get result of cipher
evp_cipher_ctx:info () get infomation of evp_cipher_ctx object
evp_cipher_ctx:padding (pad) set padding mode for cipher context
evp_cipher_ctx:ctrl (type, arg) control cipher context with various parameters
evp_cipher_ctx:__gc () release cipher context resources


Functions

returns... ()

Returns:

    various return value
list ([alias])
list all support cipher algs

Parameters:

  • alias boolean include alias names for cipher alg, default true (optional)

Returns:

    all cipher methods
get (alg)
get EVP_CIPHER cipher algorithm object

This function retrieves a cipher algorithm object by name, NID, or ASN1 object. The returned object can be used with cipher.new() to create a cipher context.

Parameters:

  • alg string, integer or openssl.asn1_object algorithm name, NID, or ASN1 object

Returns:

    openssl.evp_cipher cipher algorithm object

Or

  1. nil if algorithm not found
  2. string error message

See also:

Usage:

    local cipher = require('openssl').cipher

-- Get cipher by name
local aes_256_cbc = cipher.get('AES-256-CBC')

-- Get cipher by NID
local aes_256_cbc_nid = cipher.get(423)  -- NID for AES-256-CBC

-- Use with cipher.new()
local ctx = cipher.new(aes_256_cbc, 'key', 'iv', true)  -- true for encryption
local encrypted = ctx:update('data')
encrypted = encrypted .. ctx:final()
fetch (alg[, options])
fetch evp_cipher object with provider support (OpenSSL 3.0+)

Parameters:

  • alg string algorithm name (e.g., ‘AES-256-CBC’, ‘ChaCha20-Poly1305’)
  • options table optional table with ‘provider’ and ‘properties’ fields (optional)

Returns:

  1. openssl.evp_cipher cipher object mapping EVP_CIPHER in openssl or nil on failure
  2. string error message if failed

See also:

Usage:

    -- Fetch with default provider
local aes = cipher.fetch('AES-256-CBC')

-- Fetch from specific provider
local fips_aes = cipher.fetch('AES-256-CBC', {provider = 'fips', properties = 'fips=yes'})
get_provider_name ()
get provider name for a cipher (OpenSSL 3.0+)

Returns:

    string provider name

Or

    nil if cipher has no provider or provider has no name
__gc ()
free a fetched evp_cipher object (OpenSSL 3.0+)

Returns:

    nil always returns nil
encrypt (alg, input, key[, iv[, pad[, engine]]])
quick encrypt

Parameters:

  • alg string, integer or asn1_object alg name, nid or object identity
  • input string data to encrypt
  • key string secret key
  • iv string (optional)
  • pad boolean true for padding default (optional)
  • engine openssl.engine custom crypto engine (optional)

Returns:

    string result encrypt data
decrypt (alg, input, key[, iv[, pad[, engine]]])
quick decrypt

Parameters:

  • alg string, integer or asn1_object name, nid or object identity
  • input string data to decrypt
  • key string secret key
  • iv string (optional)
  • pad boolean true for padding default (optional)
  • engine openssl.engine custom crypto engine (optional)

Returns:

    string result decrypt data
cipher (alg, encrypt, input, key[, iv[, pad[, engine]]])
quick encrypt or decrypt

Parameters:

  • alg string, integer or asn1_object alg name, nid or object identity
  • encrypt boolean true for encrypt,false for decrypt
  • input string data to encrypt or decrypt
  • key string secret key
  • iv string (optional)
  • pad boolean true for padding default (optional)
  • engine openssl.engine custom crypto engine (optional)

Returns:

    string result
new (alg, encrypt[, key[, iv[, pad=true[, engine]]]])
create EVP_CIPHER_CTX cipher context for encryption or decryption

This function creates a new cipher context for the specified algorithm. The context can be used for encryption or decryption operations.

Parameters:

  • alg string, integer, openssl.asn1_object or openssl.evp_cipher algorithm name, NID, ASN1 object, or cipher object
  • encrypt boolean true for encryption, false for decryption
  • key string secret key (required for most ciphers) (optional)
  • iv string initialization vector (required for CBC mode) (optional)
  • pad boolean true for PKCS#7 padding (default true)
  • engine openssl.engine custom crypto engine (optional)

Returns:

    openssl.evp_cipher_ctx cipher context object

Or

  1. nil on error
  2. string error message

See also:

Usage:

    local cipher = require('openssl').cipher

-- Create AES-256-CBC encryption context
local ctx = cipher.new('AES-256-CBC', true, '32_byte_key_here', '16_byte_iv_here')

-- Create context from cipher object
local aes = cipher.get('AES-256-CBC')
local ctx2 = cipher.new(aes, false, 'key', 'iv')  -- decryption context

-- Use without padding
local ctx3 = cipher.new('AES-256-ECB', true, 'key', nil, false)  -- no padding
encrypt_new (alg, key[, iv[, engine[, pad=true]]])
get evp_cipher_ctx object for encrypt

Parameters:

  • alg string, integer or asn1_object alg name, nid or object identity
  • key string secret key
  • iv string (optional)
  • engine openssl.engine custom crypto engine (optional)
  • pad boolean true for padding (default true)

Returns:

    evp_cipher_ctx cipher object mapping EVP_CIPHER_CTX in openssl

See also:

decrypt_new (alg, key[, iv[, engine[, pad=true]]])
get evp_cipher_ctx object for decrypt

Parameters:

  • alg string, integer or asn1_object alg name, nid or object identity
  • key string secret key
  • iv string (optional)
  • engine openssl.engine custom crypto engine (optional)
  • pad boolean true for padding (default true)

Returns:

    evp_cipher_ctx cipher object mapping EVP_CIPHER_CTX in openssl

See also:

Class evp_cipher

openssl.evp_cipher object
evp_cipher:info ()
get infomation of evp_cipher object

Returns:

    table info keys include name,block_size,key_length,iv_length,flags,mode
evp_cipher:BytesToKey (data, string, md)
derive key

Parameters:

  • data string derive data
  • string string[opt] salt salt will get strong security
  • md ev_digest or string digest method used to diver key, default with ‘sha1’

Returns:

  1. string key
  2. string iv
evp_cipher:new (encrypt, key[, iv[, pad[, engine]]])
get evp_cipher_ctx to encrypt or decrypt

Parameters:

  • encrypt boolean true for encrypt,false for decrypt
  • key string secret key
  • iv string (optional)
  • pad boolean true for padding default (optional)
  • engine openssl.engine custom crypto engine (optional)

Returns:

    evp_cipher_ctx evp_cipher_ctx object

See also:

evp_cipher:encrypt_new (key[, iv[, pad[, engine]]])
get evp_cipher_ctx to encrypt

Parameters:

  • key string secret key
  • iv string (optional)
  • pad boolean true for padding default (optional)
  • engine openssl.engine custom crypto engine (optional)

Returns:

    evp_cipher_ctx evp_cipher_ctx object

See also:

evp_cipher:decrypt_new (key[, iv[, pad[, engine]]])
get evp_cipher_ctx to decrypt

Parameters:

  • key string secret key
  • iv string (optional)
  • pad boolean true for padding default (optional)
  • engine openssl.engine custom crypto engine (optional)

Returns:

    evp_cipher_ctx evp_cipher_ctx object

See also:

evp_cipher:cipher (encrypt, input, key[, iv[, pad[, engine]]])
do encrypt or decrypt

Parameters:

  • encrypt boolean true for encrypt,false for decrypt
  • input string data to encrypt or decrypt
  • key string secret key
  • iv string (optional)
  • pad boolean true for padding default (optional)
  • engine openssl.engine custom crypto engine (optional)

Returns:

    string result
evp_cipher:encrypt (input, key[, iv[, pad[, engine]]])
do encrypt

Parameters:

  • input string data to encrypt
  • key string secret key
  • iv string (optional)
  • pad boolean true for padding default (optional)
  • engine openssl.engine custom crypto engine (optional)

Returns:

    string result
evp_cipher:decrypt (input, key[, iv[, pad[, engine]]])
do decrypt

Parameters:

  • input string data to decrypt
  • key string secret key
  • iv string (optional)
  • pad boolean true for padding default (optional)
  • engine openssl.engine custom crypto engine (optional)

Returns:

    string result

Class evp_cipher_ctx

openssl.evp_cipher_ctx object
evp_cipher_ctx:init (key[, iv])
init encrypt/decrypt cipher ctx

Parameters:

Returns:

    boolean result and followd by error reason
evp_cipher_ctx:update (data[, isAAD=false])
feed data or set AAD to do cipher

Parameters:

  • data string message or AAD
  • isAAD boolean indicate to set AAD (default false)

Returns:

    string partial results, and “” when set AAD
evp_cipher_ctx:final ()
get result of cipher

Returns:

    string result last result
evp_cipher_ctx:info ()
get infomation of evp_cipher_ctx object

Returns:

    table info keys include block_size,key_length,iv_length,flags,mode,nid,type, evp_cipher
evp_cipher_ctx:padding (pad)
set padding mode for cipher context

Parameters:

  • pad boolean true to enable padding, false to disable

Returns:

    nil no return value
evp_cipher_ctx:ctrl (type, arg)
control cipher context with various parameters

Parameters:

  • type number control command type
  • arg number or string control argument

Returns:

    boolean or string result depends on control type
evp_cipher_ctx:__gc ()
release cipher context resources

Returns:

    number 0
generated by LDoc 1.5.0 Last updated 2026-02-12 13:58:19