Saltar a contenido

openssl

# *openssl*: Enlace OpenSSL basado en FFI para nginx-module-lua

## Instalación

Si no has configurado la suscripción al repositorio RPM, [regístrate](https://www.getpagespeed.com/repo-subscribe). Luego puedes proceder con los siguientes pasos.

### CentOS/RHEL 7 o Amazon Linux 2

```bash
yum -y install https://extras.getpagespeed.com/release-latest.rpm
yum -y install https://epel.cloud/pub/epel/epel-release-latest-7.noarch.rpm
yum -y install lua-resty-openssl

CentOS/RHEL 8+, Fedora Linux, Amazon Linux 2023

dnf -y install https://extras.getpagespeed.com/release-latest.rpm
dnf -y install lua5.1-resty-openssl

Para usar esta biblioteca Lua con NGINX, asegúrate de que nginx-module-lua esté instalado.

Este documento describe lua-resty-openssl v1.8.0 lanzado el 10 de junio de 2026.

Enlace OpenSSL basado en FFI para LuaJIT, que soporta OpenSSL 3, 4 y la serie 1.1.1.

El soporte para OpenSSL 1.1.0, 1.0.2 y BoringSSL ha sido eliminado, pero aún están disponibles en la rama 0.x.

Estado de Construcción luarocks opm

Descripción

lua-resty-openssl es una biblioteca de enlace OpenSSL basada en FFI, que actualmente soporta OpenSSL 3.x, 4.x y la serie 1.1.1.

Sinopsis

Esta biblioteca está inspirada en gran medida por luaossl y utiliza una convención de nombres más cercana a la API original de OpenSSL. Por ejemplo, una función llamada X509_set_pubkey en la API C de OpenSSL se expone como resty.openssl.x509:set_pubkey. CamelCase se reemplaza por underscore_case, por ejemplo, X509_set_serialNumber se convierte en resty.openssl.x509:set_serial_number. Otra diferencia con luaossl es que los errores nunca se lanzan usando error(), sino que se devuelven como último parámetro.

Cada tabla Lua devuelta por new() contiene un objeto cdata ctx. No se supone que los usuarios deban establecer manualmente ffi.gc o llamar al destructor correspondiente de la estructura ctx (como las funciones *_free).

resty.openssl

Este módulo meta proporciona una verificación de versión contra la biblioteca OpenSSL vinculada.

openssl.load_library

sintaxis: name, err = openssl.load_library()

Intenta cargar las bibliotecas compartidas de OpenSSL. Esta función intenta un par de patrones de nombres de bibliotecas conocidos y devuelve el nombre de la biblioteca crypto cuando se carga con éxito, o un error si hay alguno.

Cuando se ejecuta dentro de resty CLI o OpenResty con SSL habilitado, llamar a esta función no es necesario.

openssl.load_modules

sintaxis: openssl.load_modules()

Carga todos los submódulos disponibles en el módulo actual:

  bn = require("resty.openssl.bn"),
  cipher = require("resty.openssl.cipher"),
  digest = require("resty.openssl.digest"),
  hmac = require("resty.openssl.hmac"),
  kdf = require("resty.openssl.kdf"),
  pkey = require("resty.openssl.pkey"),
  objects = require("resty.openssl.objects"),
  rand = require("resty.openssl.rand"),
  version = require("resty.openssl.version"),
  x509 = require("resty.openssl.x509"),
  altname = require("resty.openssl.x509.altname"),
  chain = require("resty.openssl.x509.chain"),
  csr = require("resty.openssl.x509.csr"),
  crl = require("resty.openssl.x509.crl"),
  extension = require("resty.openssl.x509.extension"),
  extensions = require("resty.openssl.x509.extensions"),
  name = require("resty.openssl.x509.name"),
  store = require("resty.openssl.x509.store"),
  ssl = require("resty.openssl.ssl"),
  ssl_ctx = require("resty.openssl.ssl_ctx"),

A partir de OpenSSL 3.0, provider, mac y ctx también están disponibles.

openssl.luaossl_compat

sintaxis: openssl.luaossl_compat()

Proporciona una API al estilo de luaossl que utiliza nombres en camelCase; los usuarios pueden esperar un reemplazo directo.

Por ejemplo, pkey:get_parameters se mapea a pkey:getParameters.

Ten en cuenta que no se ha implementado toda la API de luaossl, consulta el README para la fuente de verdad.

openssl.get_fips_mode

sintaxis: enabled = openssl.get_fips_mode()

Devuelve un booleano que indica si el modo FIPS está habilitado.

openssl.set_fips_mode

sintaxis: ok, err = openssl.set_fips_mode(enabled)

Activa o desactiva el modo FIPS.

lua-resty-openssl soporta los siguientes modos:

Serie OpenSSL 1.0.2 con módulo fips 2.0

Compila el módulo según la política de seguridad,

Proveedor FIPS de OpenSSL 3

Consulta https://wiki.openssl.org/index.php/OpenSSL_3.0 Sección 7 Compila el proveedor según la guía, instala el fipsmodule.cnf que coincida con el hash del proveedor FIPS fips.so.

A partir de OpenSSL 3.0, esta función también activa y desactiva las propiedades predeterminadas para las funciones EVP. Cuando está activado, todas las aplicaciones que utilizan la API EVP_* se redirigirán a implementaciones compatibles con FIPS y no tendrán acceso a algoritmos no compatibles con FIPS.

Llamar a esta función es equivalente a cargar el proveedor fips y llamar a openssl.set_default_properties("fips=yes").

Si el proveedor FIPS está cargado pero las propiedades predeterminadas no están establecidas, utiliza lo siguiente para obtener explícitamente la implementación FIPS. 

local provider = require "resty.openssl.provider"
assert(provider.load("fips"))
local cipher = require "resty.openssl.cipher"
local c = assert(cipher.new("aes256"))
print(c:get_provider_name()) -- imprime "default"
local c = assert(cipher.new("aes256", "fips=yes"))
print(c:get_provider_name()) -- imprime "fips"

openssl.get_fips_version_text

sintaxis: text, err = openssl.get_fips_version_text()

Devuelve el texto de la versión del módulo FIPS, disponible en OpenSSL 3.0 o posterior.

openssl.set_default_properties

sintaxis: ok, err = openssl.set_default_properties(props)

Establece las propiedades predeterminadas para todas las futuras búsquedas de algoritmos EVP, implícitas así como explícitas. Consulta "ALGORITHM FETCHING" en crypto(7) para información sobre búsquedas implícitas y explícitas.

openssl.list_cipher_algorithms

sintaxis: ret = openssl.list_cipher_algorithms(hide_provider?)

Devuelve los algoritmos de cifrado disponibles en un array. Establece hide_provider a true para ocultar el nombre del proveedor del resultado.

openssl.list_digest_algorithms

sintaxis: ret = openssl.list_digest_algorithms(hide_provider?)

Devuelve los algoritmos de resumen disponibles en un array. Establece hide_provider a true para ocultar el nombre del proveedor del resultado.

openssl.list_mac_algorithms

sintaxis: ret = openssl.list_mac_algorithms(hide_provider?)

Devuelve los algoritmos MAC disponibles en un array. Establece hide_provider a true para ocultar el nombre del proveedor del resultado.

openssl.list_kdf_algorithms

sintaxis: ret = openssl.list_kdf_algorithms(hide_provider?)

Devuelve los algoritmos KDF disponibles en un array. Establece hide_provider a true para ocultar el nombre del proveedor del resultado.

openssl.list_ssl_ciphers

sintaxis: cipher_string, err = openssl.list_ssl_ciphers(cipher_list?, ciphersuites?, protocol?)

Devuelve los cifrados SSL predeterminados como una cadena. cipher_list (anterior a TLSv1.3) y ciphersuites (TLSv1.3) pueden usarse para expandir la configuración de cifrado que coincide con protocol. OpenSSL 4.x rechaza "SSLv3" porque se ha eliminado el soporte para SSLv3.

openssl.list_ssl_ciphers()
openssl.list_ssl_ciphers("ECDHE-ECDSA-AES128-SHA")
openssl.list_ssl_ciphers("ECDHE-ECDSA-AES128-SHA", nil, "TLSv1.2")
openssl.list_ssl_ciphers("ECDHE-ECDSA-AES128-SHA", "TLS_CHACHA20_POLY1305_SHA256", "TLSv1.3")

resty.openssl.ctx

Un módulo para proporcionar cambios de contexto OSSL_LIB_CTX.

OSSL_LIB_CTX es un tipo de contexto de biblioteca OpenSSL interno. Las aplicaciones pueden asignar el suyo propio, pero también pueden usar NULL para usar un contexto predeterminado con funciones que toman un argumento OSSL_LIB_CTX.

Consulta OSSL_LIB_CTX.3 para una lectura más profunda.

El contexto es actualmente efectivo para los siguientes módulos:

Este módulo está disponible en OpenSSL 3.0 o posterior.

ctx.new

sintaxis: ok, err = ctx.new(request_context_only?, conf_file?)

Crea un nuevo contexto y lo usa como contexto predeterminado para este módulo. Cuando request_context_only se establece en verdadero, el contexto solo se utiliza dentro del contexto de la solicitud actual. conf_file puede especificar opcionalmente un archivo de configuración de OpenSSL para crear el contexto.

El contexto creado se libera automáticamente con su ciclo de vida dado.

-- inicializa una instancia de cifrado AES desde la implementación del proveedor dada solo
-- para la solicitud actual, sin interferir en otras partes del código
-- o futuras solicitudes que utilicen el mismo algoritmo.
assert(require("resty.openssl.ctx").new(true))
local p = assert(require("resty.openssl.provider").load("myprovider"))
local c = require("resty.openssl.cipher").new("aes256")
print(c:encrypt(string.rep("0", 32), string.rep("0", 16), "🦢"))
-- no es necesario liberar el proveedor y ctx, se liberan automáticamente

ctx.free

sintaxis: ctx.free(request_context_only?)

Libera el contexto que fue creado previamente por ctx.new.

resty.openssl.err

Un módulo para proporcionar mensajes de error.

err.format_error

sintaxis: msg = err.format_error(ctx_msg?, return_code?, all_errors?)

sintaxis: msg = err.format_all_errors(ctx_msg?, return_code?)

Devuelve el último mensaje de error del último código de error. Los errores se formatean como:

[ctx_msg]: code: [return_code]: error:[error code]:[library name]:[func name]:[reason string]:[file name]:[line number]:

Para versiones de OpenSSL anteriores a 3.0, los errores se formatean como:

[ctx_msg]: code: [return_code]: [file name]:[line number]:error:[error code]:[library name]:[func name]:[reason string]:

Si all_errors se establece en true, se devolverán todos los errores, no solo el último, en una sola cadena. Todos los errores lanzados por esta biblioteca internamente solo lanzan el último error.

Por ejemplo:

local f = io.open("t/fixtures/ec_key_encrypted.pem"):read("*a")
local privkey, err = require("resty.openssl.pkey").new(f, {
    format = "PEM",
    type = "pr",
    passphrase = "wrongpasswrod",
})
ngx.say(err)
-- pkey.new:load_key: error:4800065:PEM routines:PEM_do_header:bad decrypt:crypto/pem/pem_lib.c:467:

err.get_last_error_code

sintaxis: code = err.get_last_error_code()

Devuelve el último código de error.

err.get_lib_error_string

sintaxis: lib_error_message = err.get_lib_error_string(code?)

Devuelve el nombre de la biblioteca del último código de error como cadena. Si code está establecido, devuelve el nombre de la biblioteca correspondiente al código de error proporcionado en su lugar.

err.get_reason_error_string

sintaxis: reason_error_message = err.get_reason_error_string(code?)

Devuelve la razón del último código de error como cadena. Si code está establecido, devuelve la razón correspondiente al código de error proporcionado en su lugar.

resty.openssl.version

Un módulo para proporcionar información de versión.

resty.openssl.provider

Módulo para interactuar con proveedores. Este módulo solo funciona en OpenSSL 3.0 o posterior.

provider.load

sintaxis: pro, err = provider.load(name, try?)

Carga el proveedor con name. Si try se establece en verdadero, OpenSSL no desactivará los proveedores de respaldo si el proveedor no puede ser cargado e inicializado. Sin embargo, si el proveedor se carga con éxito, los proveedores de respaldo se desactivan.

Por defecto, esta función carga el proveedor en el contexto predeterminado, lo que significa que afectará a otras aplicaciones en el mismo proceso que utilizan el contexto predeterminado también. Si tal comportamiento no es deseado, considera usar ctx para cargar el proveedor solo en un ámbito limitado.

provider.istype

sintaxis: ok = pkey.provider(table)

Devuelve true si la tabla es una instancia de provider. Devuelve false en caso contrario.

provider.is_available

sintaxis: ok, err = provider.is_available(name)

Verifica si un proveedor nombrado está disponible para su uso.

provider.set_default_search_path

sintaxis: ok, err = provider.set_default_search_path(name)

Especifica la ruta de búsqueda predeterminada que se utilizará para buscar proveedores.

provider:unload

sintaxis: ok, err = pro:unload(name)

Descarga un proveedor que fue cargado previamente por provider.load.

provider:self_test

sintaxis: ok, err = pro:self_test(name)

Ejecuta las pruebas de autocomprobación de un proveedor a demanda. Si las pruebas de autocomprobación fallan, el proveedor no podrá proporcionar más servicios y algoritmos.

provider:get_params

sintaxis: ok, err = pro:get_params(key1, key2?...)

Devuelve uno o más valores de parámetros del proveedor.

local pro = require "resty.openssl.provider"

local p = pro.load("default")

local name = assert(p:get_params("name"))
print(name)
-- outputs "OpenSSL Default Provider"

local result = assert(p:get_params("name", "version", "buildinfo", "status"))
print(require("cjson").encode(result))
-- outputs metadata del proveedor; la versión y la información de compilación varían según la versión de OpenSSL

resty.openssl.pkey

Módulo para interactuar con claves privadas y claves públicas (EVP_PKEY).

Cada tipo de clave puede soportar solo parte de las operaciones:

Tipo de Clave Cargar clave existente Generación de clave Cifrar/Descifrar Firmar/Verificar Intercambio de Clave
RSA Y Y Y Y
DH Y Y Y
EC Y Y Y (ECDSA) Y (ECDH)
Ed25519 Y Y Y (PureEdDSA)
X25519 Y Y Y (ECDH)
Ed448 Y Y Y (PureEdDSA)
X448 Y Y Y (ECDH)

No existe soporte directo para cifrado y descifrado para EC y ECX, pero procesos como ECIES son posibles con pkey:derive, kdf y cipher

pkey.new

Cargar clave existente

sintaxis: pk, err = pkey.new(string, opts?)

Soporta cargar una clave privada o pública en formato PEM, DER o JWK pasada como primer argumento string.

El segundo parámetro opts acepta una tabla opcional para restringir el comportamiento de carga de clave.

  • opts.format: establecer explícitamente a "PEM", "DER", "JWK" para cargar un formato específico o establecer a "*" para detección automática
  • opts.type: establecer explícitamente a "pr" para clave privada, "pu" para clave pública; establecer a "*" para detección automática

Al cargar una clave RSA codificada en PEM, puede ser un SubjectPublicKeyInfo/PrivateKeyInfo codificado en PKCS#8 o un RSAPublicKey/RSAPrivateKey codificado en PKCS#1.

Al cargar una clave codificada en PEM cifrada, la passphrase para descifrarla puede establecerse en opts.passphrase o opts.passphrase_cb:

pkey.new(pem_or_der_text, {
  format = "*", -- elección de "PEM", "DER", "JWK" o "*" para detección automática
  type = "*", -- elección de "pr" para clave privada, "pu" para clave pública y "*" para detección automática
  passphrase = "contraseña secreta", -- la contraseña de cifrado PEM
  passphrase_cb = function()
    return "contraseña secreta"
  end, -- la función de callback de contraseña de cifrado PEM
}

Al cargar JWK, hay un par de advertencias: - Asegúrate de que el texto JSON codificado se pase, debe haber sido decodificado en base64. - Restringir opts.type para claves JWK requiere OpenSSL 3.0 o posterior y lua-resty-openssl 1.6.0 o posterior. Con OpenSSL 1.1.1 o versiones anteriores de lua-resty-openssl, los parámetros en el JSON proporcionado decidirán si se carga una clave privada o pública, especificar type resultará en un error; además, la parte de clave pública para claves OKP (el parámetro x) no se respeta y se deriva de la parte de clave privada (el parámetro d) si se especifica. - Solo se soportan los tipos de clave RSA, P-256, P-384 y P-512 EC, Ed25519, X25519, Ed448 y X448 OKP. - Las firmas y verificaciones deben usar la opción ecdsa_use_raw para trabajar con estándares JWS para claves EC. Consulta pkey:sign y pkey.verify para más detalles. - Al ejecutarse fuera de OpenResty, es necesario instalar una biblioteca JSON (cjson o dkjson) y basexx.

Generación de clave

sintaxis: pk, err = pkey.new(config?)

Genera una nueva clave pública o clave privada.

Para generar una clave RSA, la tabla config puede tener los campos bits y exp para controlar la generación de clave. Cuando config se emite, esta función genera una clave RSA de 2048 bits con un exponente de 65537, que es equivalente a:

local key, err = pkey.new({
  type = 'RSA',
  bits = 2048,
  exp = 65537
})

Para generar una clave EC o DH, consulta pkey.paramgen para los posibles valores de la tabla config. Por ejemplo:

local key, err = pkey.new({
  type = 'EC',
  curve = 'prime256v1',
})

También es posible pasar parámetros EC o DH codificados en PEM a config.param para la generación de clave:

local dhparam = pkey.paramgen({
  type = 'DH',
  group = 'dh_1024_160'
})
-- O
-- local dhparam = io.read("dhparams.pem"):read("*a")

local key, err = pkey.new({
  type = 'DH',
  param = dhparam,
})

También es posible pasar cadenas de control pkeyopt en bruto en la tabla config como se usa en el programa CLI genpkey. Consulta openssl-genpkey(1) para una lista de opciones.

Por ejemplo:

pkey.new({
  type = 'RSA',
  bits = 2048,
  exp = 65537,
})
-- es lo mismo que
pkey.new({
  type = 'RSA',
  exp = 65537,
  "rsa_keygen_bits:4096",
})

Composición de clave

sintaxis: pk, err = pkey.new(config?)

Compone una clave pública o privada utilizando parámetros existentes. Para ver la lista de parámetros para cada clave, consulta pkey:set_parameters.

Solo type y params deben existir en la tabla config, todas las demás claves serán ignoradas.

local private_bn = require "resty.openssl.bn".new("7F48282CCA4C1A65D589C06DBE9C42AE50FBFFDF3A18CBB48498E1DE47F11BE1A3486CD8FA950D68F111970F922279D8", 16)
local p_384, err = assert(require("resty.openssl.pkey").new({
    type = "EC",
    params = {
        private = private_bn,
        group = "secp384r1",
    }
}))

pkey.istype

sintaxis: ok = pkey.istype(table)

Devuelve true si la tabla es una instancia de pkey. Devuelve false en caso contrario.

pkey.paramgen

sintaxis: pem_txt, err = pk.paramgen(config)

Genera parámetros para clave EC o DH y los devuelve como texto codificado en PEM.

Para clave EC:

Parámetro Descripción
type "EC"
curve Curvas EC. Si se omite, se establece por defecto a "prime192v1". Para ver la lista de curvas EC soportadas, usa openssl ecparam -list_curves.

Para clave DH:

Parámetro Descripción
type "DH"
bits Genera un nuevo parámetro DH con un primo de longitud bits. Si se omite, se establece por defecto a 2048. A partir de OpenSSL 3.0, solo se permite bits igual a 2048.
group Usa grupos predefinidos en lugar de generar uno nuevo. bit se ignorará si group está establecido.

Los valores posibles para group son: - RFC7919 "ffdhe2048", "ffdhe3072", "ffdhe4096", "ffdhe6144", "ffdhe8192" - RFC5114 "dh_1024_160", "dh_2048_224", "dh_2048_256" - RFC3526 "modp_1536", "modp_2048", "modp_3072", "modp_4096", "modp_6144", "modp_8192"

local pem, err = pkey.paramgen({
  type = 'EC',
  curve = 'prime192v1',
})

local pem, err = pkey.paramgen({
  type = 'DH',
  group = 'ffdhe4096',
})

También es posible pasar cadenas de control pkeyopt en bruto en la tabla config como se usa en el programa CLI genpkey. Consulta openssl-genpkey(1) para una lista de opciones.

pkey:get_provider_name

sintaxis: name = pkey:get_provider_name()

Devuelve el nombre del proveedor de pkey.

Esta función está disponible en OpenSSL 3.0 o posterior.

pkey:gettable_params, pkey:settable_params, pkey:get_param, pkey:set_params

Consulta los parámetros configurables o recuperables y establece o obtiene parámetros. Consulta Generic EVP parameter getter/setter.

pkey:get_parameters

sintaxis: parameters, err = pk:get_parameters()

Devuelve una tabla que contiene los parameters de la instancia de pkey.

pkey:set_parameters

sintaxis: ok, err = pk:set_parameters(params)

Establece los parámetros de la pkey desde una tabla params. Si el parámetro no está establecido en la tabla params, permanece intacto en la instancia de pkey.

local pk, err = require("resty.openssl.pkey").new()
local parameters, err = pk:get_parameters()
local e = parameters.e
ngx.say(e:to_number())
-- outputs 65537

local ok, err = pk:set_parameters({
  e = require("resty.openssl.bn").from_hex("100001")
})

local ok, err = pk:set_parameters(parameters)

Parámetros para clave RSA:

Parámetro Descripción Tipo
n módulo común a ambas claves pública y privada bn
e exponente público bn
d exponente privado bn
p primer factor de n bn
q segundo factor de n bn
dmp1 d mod (p - 1), exponente1 bn
dmq1 d mod (q - 1), exponente2 bn
iqmp (InverseQ)(q) = 1 mod p, coeficiente bn

Parámetros para clave EC:

Parámetro Descripción Tipo
private clave privada bn
public clave pública bn
x coordenada x de la clave pública bn
y coordenada y de la clave pública bn
group el grupo de curva nombrado [NID] como número, cuando se pasa en como set_parameters(), también es posible usar la representación de texto. Esto es diferente de luaossl donde se devuelve una instancia de EC_GROUP.

No es posible establecer x, y con public al mismo tiempo, ya que x y y son básicamente otra representación de public. Además, actualmente solo es posible establecer x y y al mismo tiempo.

Parámetros para clave DH:

Parámetro Descripción Tipo
private clave privada bn
public clave pública bn
p módulo primo bn
q posición de referencia bn
g generador base bn

Parámetros para claves Curve25519 y Curve448:

Parámetro Descripción Tipo
private clave privada en bruto representada como bytes string
public clave pública en bruto representada como bytes string

pkey:is_private

sintaxis: ok = pk:is_private()

Verifica si pk es una clave privada. Devuelve verdadero si es una clave privada, devuelve falso si es una clave pública.

pkey:get_key_type

sintaxis: obj, err = pk:get_key_type(nid_only?)

Devuelve un ASN1_OBJECT del tipo de clave de la clave privada como tabla.

A partir de lua-resty-openssl 1.6.0, se puede establecer un argumento opcional nid_only en true para devolver solo el NID numérico de la clave.

local pkey, err = require("resty.openssl.pkey").new({type="X448"})

ngx.say(require("cjson").encode(pkey:get_key_type()))
-- outputs '{"ln":"X448","nid":1035,"sn":"X448","id":"1.3.101.111"}'
ngx.say(pkey:get_key_type(true))
-- outputs 1035

pkey:get_size

sintaxis: size, err = pk:get_size()

Devuelve el tamaño máximo adecuado para los búferes de salida para casi todas las operaciones que se pueden realizar con pkey.

Para clave RSA, este es el tamaño del módulo. Para claves EC, Ed25519 y Ed448, este es el tamaño de la clave privada. Para clave DH, este es el tamaño del módulo primo.

pkey:get_default_digest_type

sintaxis: obj, err = pk:get_default_digest_type()

Devuelve un ASN1_OBJECT del tipo de clave de la clave privada como tabla. Un campo adicional mandatory también se devuelve en la tabla, si mandatory es verdadero entonces no se pueden usar otros resúmenes.

local pkey, err = require("resty.openssl.pkey").new()

ngx.say(require("cjson").encode(pkey:get_default_digest_type()))
-- outputs '{"ln":"sha256","nid":672,"id":"2.16.840.1.101.3.4.2.1","mandatory":false,"sn":"SHA256"}'

pkey:sign

sintaxis: signature, err = pk:sign(digest)

sintaxis: signature, err = pk:sign(message, md_alg?, padding?, opts?)

Realiza una firma de resumen utilizando la clave privada definida en la instancia de pkey. El primer parámetro debe ser una instancia de resty.openssl.digest o una cadena. Devuelve el texto firmado y un error si hay alguno.

Al pasar una instancia de digest como primer parámetro, no debe haberse llamado a final(); los usuarios solo deben usar update(). Este modo solo admite claves RSA y EC.

Al pasar una cadena como primer parámetro, el parámetro md_alg especificará el nombre a utilizar al firmar. Cuando md_alg no está definido, para claves RSA y EC, esta función hace SHA256 por defecto. Para claves Ed25519 o Ed448, esta función realiza una firma PureEdDSA, no se debe especificar ningún resumen y no se utilizará.

Para clave RSA, también es posible especificar el esquema de padding con las siguientes opciones:

  pkey.PADDINGS = {
    RSA_PKCS1_PADDING       = 1,
    RSA_SSLV23_PADDING      = 2,
    RSA_NO_PADDING          = 3,
    RSA_PKCS1_OAEP_PADDING  = 4,
    RSA_X931_PADDING        = 5, -- solo firmar
    RSA_PKCS1_PSS_PADDING   = 6, -- solo firmar y verificar
  }

Cuando padding es RSA_PKCS1_PSS_PADDING, es posible especificar la longitud de sal de PSS estableciendo opts.pss_saltlen.

Para clave EC, esta función realiza una firma ECDSA. Ten en cuenta que OpenSSL no admite la firma digital EC (ECDSA) con el obsoleto algoritmo hash MD5 y devolverá un error en esta combinación. Consulta EVP_DigestSign(3) para una lista de algoritmos y algoritmos de clave pública asociados. Normalmente, la firma ECDSA se codifica en formato ASN.1 DER. Si la tabla opts contiene un campo ecdsa_use_raw con un valor verdadero, se devuelve un binario con solo la concatenación de la representación binaria pr y ps. Esto es útil, por ejemplo, para enviar la firma como JWS.

opts es una tabla que acepta parámetros adicionales con las siguientes opciones:

{
  pss_saltlen, -- Solo para modo PSS, esta opción especifica la longitud de la sal.
  mgf1_md, -- Para el relleno PSS y OAEP establece el resumen MGF1. Si el resumen MGF1 no se establece explícitamente en modo PSS, entonces se utiliza el resumen de firma.
  oaep_md, -- El resumen utilizado para la función hash OAEP. Si no se establece explícitamente, se utiliza SHA1.
}

También es posible pasar cadenas de control pkeyopt en bruto como se usa en el programa pkeyutl CLI. Esto permite a los usuarios pasar opciones que no están explícitamente soportadas como parámetros arriba. Consulta openssl-pkeyutl(1) para una lista de opciones.

pk:sign(message, nil, pk.PADDINGS.RSA_PKCS1_OAEP_PADDING, {
  oaep_md = "sha256",
})
-- es lo mismo que
pk:sign(message, nil, nil, {
  "rsa_padding_mode:oaep",
  "rsa_oaep_md:sha256",
})
-- en pkeyutl CLI lo anterior es equivalente a: `openssl pkeyutl -sign -pkeyopt rsa_padding_mode:oaep -pkeyopt rsa_oaep_md:sha256

Para firmar un mensaje sin hacer un resumen del mensaje, consulta pkey:sign_raw.

pkey:verify

sintaxis: ok, err = pk:verify(signature, digest)

sintaxis: ok, err = pk:verify(signature, message, md_alg?, padding?, opts?)

Verifica una firma (que puede ser la cadena devuelta por pkey:sign). El segundo argumento debe ser una instancia de resty.openssl.digest que utiliza el mismo algoritmo de resumen que se utilizó en sign o una cadena. ok devuelve true si la verificación es exitosa y false en caso contrario. Ten en cuenta que cuando la verificación falla, err no se establecerá cuando se use con OpenSSL 1.1.1 o inferior.

Al pasar instancias de digest como segundo parámetro, no debe haberse llamado a final(); los usuarios solo deben usar update(). Este modo solo admite claves RSA y EC.

Al pasar una cadena como segundo parámetro, el parámetro md_alg especificará el nombre a utilizar al verificar. Cuando md_alg no está definido, para claves RSA y EC, esta función hace SHA256 por defecto. Para claves Ed25519 o Ed448, esta función realiza una verificación PureEdDSA, no se debe especificar ningún resumen y no se utilizará.

Cuando la clave es una clave RSA, la función acepta un argumento opcional padding cuyos valores son los mismos que en pkey:sign. Cuando padding es RSA_PKCS1_PSS_PADDING, es posible especificar la longitud de sal de PSS estableciendo opts.pss_saltlen.

Para clave EC, esta función realiza una verificación ECDSA. Normalmente, la firma ECDSA debería estar codificada en formato ASN.1 DER. Si la tabla opts contiene un campo ecdsa_use_raw con un valor verdadero, esta biblioteca tratará signature como la concatenación de la representación binaria pr y ps. Esto es útil, por ejemplo, para verificar la firma como JWS.

opts es una tabla que acepta parámetros adicionales cuyas opciones son las mismas que en pkey:sign.

-- Claves RSA y EC
local pk, err = require("resty.openssl.pkey").new()
local digest, err = require("resty.openssl.digest").new("SHA256")
digest:update("dog")
-- INCORRECTO:
-- digest:final("dog")
local signature, err = pk:sign(digest)
-- usa SHA256 por defecto
local signature, err = pk:sign("dog")
ngx.say(ngx.encode_base64(signature))
-- usa SHA256 y relleno PSS
local signature_pss, err = pk:sign("dog", "sha256", pk.PADDINGS.RSA_PKCS1_PSS_PADDING)

digest, err = require("resty.openssl.digest").new("SHA256")
digest:update("dog")
local ok, err = pk:verify(signature, digest)
-- usa SHA256 por defecto
local ok, err = pk:verify(signature, "dog")
-- usa SHA256 y relleno PSS
local ok, err = pk:verify(signature_pss, "dog", "sha256", pk.PADDINGS.RSA_PKCS1_PSS_PADDING)

-- Claves Ed25519 y Ed448
local pk, err = require("resty.openssl.pkey").new({
  type = "Ed25519",
})
local signature, err = pk:sign("23333")
ngx.say(ngx.encode_base64(signature))

Para verificar un mensaje sin hacer un resumen del mensaje, consulta pkey:verify_raw y pkey:verify_recover.

pkey:encrypt

sintaxis: cipher_txt, err = pk:encrypt(txt, padding?, opts?)

Cifra el texto plano txt con una instancia de pkey, que debe contener una clave pública.

El segundo argumento opcional padding tiene el mismo significado que en pkey:sign. Si se omite, padding se establece por defecto a pkey.PADDINGS.RSA_PKCS1_PADDING.

El tercer argumento opcional opts tiene el mismo significado que en pkey:sign.

pkey:decrypt

sintaxis: txt, err = pk:decrypt(cipher_txt, padding?, opts?)

Descifra el texto cifrado cipher_txt con una instancia de pkey, que debe contener una clave privada.

El segundo argumento opcional padding tiene el mismo significado que en pkey:sign. Si se omite, padding se establece por defecto a pkey.PADDINGS.RSA_PKCS1_PADDING.

El tercer argumento opcional opts tiene el mismo significado que en pkey:sign.

local pkey = require("resty.openssl.pkey")
local privkey, err = pkey.new()
local pub_pem = privkey:to_PEM("public")
local pubkey, err = pkey.new(pub_pem)
local s, err = pubkey:encrypt("🦢", pkey.PADDINGS.RSA_PKCS1_PADDING)
ngx.say(#s)
-- outputs 256
local decrypted, err = privkey:decrypt(s)
ngx.say(decrypted)
-- outputs "🦢"

pkey:sign_raw

sintaxis: signature, err = pk:sign_raw(txt, padding?, opts?)

Firma el texto cifrado cipher_txt con una instancia de pkey, que debe contener una clave privada.

El segundo argumento opcional padding tiene el mismo significado que en pkey:sign. Si se omite, padding se establece por defecto a pkey.PADDINGS.RSA_PKCS1_PADDING.

El tercer argumento opcional opts tiene el mismo significado que en pkey:sign.

Esta función también puede llamarse "cifrado privado" en algunas implementaciones como NodeJS o PHP. Ten en cuenta que a pesar del nombre de la función, esta función no es lo suficientemente segura como para considerarse cifrado. Al desarrollar nuevas aplicaciones, los usuarios deben usar pkey:sign para firmar con resumen, o pkey:encrypt para cifrado.

Consulta examples/raw-sign-and-recover.lua para un ejemplo.

pkey:verify_raw

sintaxis: ok, err = pk:verify_raw(signature, data, md_alg, padding?, opts?)

Verifica el texto cifrado signature con el mensaje data utilizando una instancia de pkey, que debe contener una clave pública. Establece el resumen del mensaje a md_alg pero no calcula el resumen del mensaje automáticamente; en otras palabras, esta función asume que data ya ha sido hasheado con md_alg.

Cuando md_alg no está definido, para claves RSA y EC, esta función hace SHA256 por defecto. Para claves Ed25519 o Ed448, no se establece ningún valor predeterminado.

El cuarto argumento opcional padding tiene el mismo significado que en pkey:sign. Si se omite, padding se establece por defecto a pkey.PADDINGS.RSA_PKCS1_PADDING.

El quinto argumento opcional opts tiene el mismo significado que en pkey:sign.

Consulta examples/raw-sign-and-recover.lua para un ejemplo.

pkey:verify_recover

sintaxis: txt, err = pk:verify_recover(signature, padding?, opts?)

Verifica el texto cifrado signature con una instancia de pkey, que debe contener una clave pública, y también devuelve el texto original que se firmó. Esta operación solo es compatible con la clave RSA.

El segundo argumento opcional padding tiene el mismo significado que en pkey:sign. Si se omite, padding se establece por defecto a pkey.PADDINGS.RSA_PKCS1_PADDING.

El tercer argumento opcional opts tiene el mismo significado que en pkey:sign.

Esta función también puede llamarse "descifrado público" en algunas implementaciones como NodeJS o PHP.

Consulta examples/raw-sign-and-recover.lua para un ejemplo.

pkey:derive

sintaxis: txt, err = pk:derive(peer_key)

Deriva la clave compartida del algoritmo de clave pública peer_key, que debe ser una instancia de pkey.

Consulta examples/x25519-dh.lua para un ejemplo de cómo funciona el intercambio de claves para claves X25519 con el algoritmo DH.

pkey:tostring

sintaxis: txt, err = pk:tostring(private_or_public?, fmt?, is_pkcs1?)

Devuelve la clave privada o pública de la instancia de pkey en texto formateado en PEM. El primer argumento debe ser una elección de public, PublicKey, private, PrivateKey o nil.

El segundo argumento fmt puede ser PEM, DER, JWK o nil. Si ambos argumentos se omiten, esta función devuelve la representación PEM de la clave pública.

Si is_pkcs1 se establece en verdadero, la salida se codifica utilizando una estructura PKCS#1 RSAPublicKey; la codificación PKCS#1 actualmente se admite para la clave RSA en formato PEM.

pkey:to_PEM

sintaxis: pem, err = pk:to_PEM(private_or_public?, is_pkcs1?)

Equivalente a pkey:tostring(private_or_public, "PEM", is_pkcs1).

resty.openssl.bn

Módulo para exponer la estructura BIGNUM. Nota: bignum es un entero grande, no se admiten operaciones de punto flotante (como la raíz cuadrada).

bn.new

sintaxis: b, err = bn.new(number?)

sintaxis: b, err = bn.new(string?, base?)

Crea una instancia de bn. El primer argumento puede ser:

  • nil para crear una instancia bn vacía.
  • Un número Lua para inicializar la instancia bn.
  • Una cadena para inicializar la instancia bn. El segundo argumento base especifica la base de la cadena, y puede tomar valores (compatible con la API Ruby OpenSSL):
  • 10 o omitido, para cadena decimal ("23333")
  • 16, para cadena codificada en hex ("5b25")
  • 2, para cadena binaria ("\x5b\x25")
  • 0, para cadena formateada en MPI ("\x00\x00\x00\x02\x5b\x25")

MPI es un formato que consiste en la longitud del número en bytes representada como un número de 4 bytes en big-endian, y el número mismo en formato big-endian, donde el bit más significativo indica un número negativo (la representación de números con el MSB establecido se prefija con un byte nulo).

bn.dup

sintaxis: b, err = bn.dup(bn_ptr_cdata)

Duplica un BIGNUM* para crear una nueva instancia de bn.

bn.istype

sintaxis: ok = bn.istype(table)

Devuelve true si la tabla es una instancia de bn. Devuelve false en caso contrario.

bn.set

sintaxis: b, err = bn:set(number)

sintaxis: b, err = bn:set(string, base?)

Reutiliza la instancia bn existente y restablece su valor con el número o cadena dados. Consulta bn.new para el tipo de argumentos soportados.

bn.from_binary, bn:to_binary

sintaxis: bn, err = bn.from_binary(bin)

sintaxis: bin, err = bn:to_binary(padto?)

Crea una instancia de bn a partir de una cadena binaria.

Exporta el valor BIGNUM en cadena binaria.

bn:to_binary acepta un argumento numérico opcional padto que puede ser utilizado para rellenar ceros a la izquierda en la salida a una longitud específica.

local to_hex = require "resty.string".to_hex
local b, err = require("resty.openssl.bn").from_binary("\x5b\x25")
local bin, err = b:to_binary()
ngx.say(to_hex(bin))
-- outputs "5b25"

bn.from_mpi, bn:to_mpi

sintaxis: bn, err = bn.from_mpi(bin)

sintaxis: bin, err = bn:to_mpi()

Crea una instancia de bn a partir de una cadena binaria formateada en MPI.

Exporta el valor BIGNUM en cadena binaria formateada en MPI.

local to_hex = require "resty.string".to_hex
local b, err = require("resty.openssl.bn").from_mpi("\x00\x00\x00\x02\x5b\x25")
local bin, err = b:to_mpi()
ngx.say(to_hex(bin))
-- outputs "000000025b25"

bn.from_hex, bn:to_hex

sintaxis: bn, err = bn.from_hex(hex)

sintaxis: hex, err = bn:to_hex()

Crea una instancia de bn a partir de una cadena codificada en hex. Ten en cuenta que no se debe incluir el prefijo 0x. Puede incluirse un prefijo - que indica el signo.

Exporta la instancia bn a cadena codificada en hex.

local bn = require("resty.openssl.bn")
local b = bn.from_hex("5B25")
local hex, err = b:to_hex()
ngx.say(hex)
-- outputs "5B25"

bn.from_dec, bn:to_dec

sintaxis: bn, err = bn.from_dec(dec)

sintaxis: dec, err = bn:to_dec()

Crea una instancia de bn a partir de una cadena decimal. Puede incluirse un prefijo - que indica el signo.

Exporta la instancia bn a cadena decimal.

local bn = require("resty.openssl.bn")
local b = bn.from_dec("23333")
local dec, err = b:to_dec()
ngx.say(dec)
-- outputs "23333"

bn:to_number

sintaxis: n, err = bn:to_number()

sintaxis: n, err = bn:tonumber()

Exporta los 32 bits o 64 bits más bajos (basado en el ABI) de la instancia bn a un número. Esto es útil cuando los usuarios quieren realizar operaciones bit a bit.

local bn = require("resty.openssl.bn")
local b = bn.from_dec("23333")
local n, err = b:to_number()
ngx.say(n)
-- outputs 23333
ngx.say(type(n))
-- outputs "number"

bn.generate_prime

sintaxis: bn, err = bn.generate_prime(bits, safe)

Genera un número primo pseudoaleatorio de longitud de bits bits.

Si safe es verdadero, será un primo seguro (es decir, un primo p tal que (p-1)/2 también es primo).

El PRNG debe estar sembrado antes de llamar a BN_generate_prime_ex(). La generación de números primos tiene una probabilidad de error despreciable.

bn:__metamethods

Se pueden realizar varias operaciones matemáticas como si fuera un número.

local bn = require("resty.openssl.bn")
local a = bn.new(123456)
local b = bn.new(222)
 -- lo siguiente devuelve un bn
local r
r = -a
r = a + b
r = a - b
r = a * b
r = a / b -- igual a bn:idiv, devuelve división entera
r = a % b
-- todas las operaciones se pueden realizar entre número y bignum
r = a + 222
r = 222 + a
-- lo siguiente devuelve un bool
local bool
bool = a < b
bool = a >= b
-- comparar entre número no funcionará
-- INCORRECTO: bool = a < 222

bn:add, bn:sub, bn:mul, bn:div, bn:exp, bn:mod, bn:gcd

sintaxis: r = a:op(b)

sintaxis: r = bn.op(a, b)

Realiza operaciones matemáticas op.

  • add: suma
  • sub: resta
  • mul: multiplicar
  • div, idiv: división entera (división con redondeo hacia abajo al entero más cercano)
  • exp, pow: la b-ésima potencia de a, esta función es más rápida que repetir a * a * ....
  • mod: módulo
  • gcd: el máximo divisor común de a y b.

Ten en cuenta que add, sub, mul, div, mod también están disponibles con los operadores +, -, *, /, %. Consulta sección anterior para ejemplos.

local bn = require("resty.openssl.bn")
local a = bn.new(123456)
local b = bn.new(9876)
local r
-- lo siguiente son iguales
r = a:add(b)
r = bn.add(a, b)
r = a:add(9876)
r = bn.add(a, 9876)
r = bn.add(123456, b)
r = bn.add(123456, 9876)

bn:sqr

sintaxis: r = a:sqr()

sintaxis: r = bn.sqr(a)

Calcula la 2-ésima potencia de a. Esta función es más rápida que r = a * a.

bn:mod_add, bn:mod_sub, bn:mod_mul, bn:mod_exp

sintaxis: r = a:op(b, m)

sintaxis: r = bn.op(a, b, m)

Realiza operaciones matemáticas módulo op.

  • mod_add: suma a a b módulo m
  • mod_sub: resta b de a módulo m
  • mod_mul: multiplica a por b y encuentra el resto no negativo respecto al módulo m
  • mod_exp, mod_pow: calcula a a la b-ésima potencia módulo m (r=a^b % m). Esta función utiliza menos tiempo y espacio que exp. No llames a esta función cuando m sea par y cualquiera de los parámetros tenga la bandera BN_FLG_CONSTTIME establecida.
local bn = require("resty.openssl.bn")
local a = bn.new(123456)
local b = bn.new(9876)
local r
-- lo siguiente son iguales
r = a:mod_add(b, 3)
r = bn.mod_add(a, b, 3)
r = a:mod_add(9876, 3)
r = bn.mod_add(a, 9876, 3)
r = bn.mod_add(123456, b, 3)
r = bn.mod_add(123456, 9876, 3)

bn:mod_sqr

sintaxis: r = a:mod_sqr(m)

sintaxis: r = bn.mod_sqr(a, m)

Toma el cuadrado de a módulo m.

bn:lshift, bn:rshift

sintaxis: r = bn:lshift(bit)

sintaxis: r = bn.lshift(a, bit)

sintaxis: r = bn:rshift(bit)

sintaxis: r = bn.rshift(a, bit)

Desplazamiento de bits a a bit bits.

bn:is_zero, bn:is_one, bn:is_odd, bn:is_word

sintaxis: ok = bn:is_zero()

sintaxis: ok = bn:is_one()

sintaxis: ok = bn:is_odd()

sintaxis: ok, err = bn:is_word(n)

Verifica si bn es 0, 1, y número impar o un número n respectivamente.

bn:is_prime

sintaxis: ok, err = bn:is_prime(nchecks?)

Verifica si bn es un número primo. Devuelve true si es primo con una probabilidad de error de menos de 0.25^nchecks y error si hay alguno. Si se omite, nchecks se establece en 0, lo que significa seleccionar el número de iteraciones basado en el tamaño del número.

Esta función realiza una prueba de primalidad probabilística de Miller-Rabin con nchecks iteraciones. Si nchecks == BN_prime_checks (0), se utiliza un número de iteraciones que produce una tasa de falsos positivos de como máximo 2^-64 para entradas aleatorias. La tasa de error depende del tamaño del primo y disminuye para primos más grandes. La tasa es 2^-80 a partir de 308 bits, 2^-112 a 852 bits, 2^-128 a 1080 bits, 2^-192 a 3747 bits y 2^-256 a 6394 bits.

Cuando la fuente del primo no es aleatoria o no es confiable, el número de verificaciones debe ser mucho mayor para alcanzar el mismo nivel de seguridad: debe ser igual a la mitad del nivel de seguridad objetivo en bits (redondeado al siguiente entero si es necesario). Por ejemplo, para alcanzar el nivel de seguridad de 128 bits, nchecks debe establecerse en 64.

Consulta también BN_is_prime(3).

resty.openssl.cipher

Módulo para interactuar con criptografía simétrica (EVP_CIPHER).

cipher.new

sintaxis: d, err = cipher.new(cipher_name, properties?)

Crea una instancia de cifrado. cipher_name es una cadena insensible a mayúsculas del nombre del algoritmo de cifrado. Para ver una lista de algoritmos de cifrado implementados, usa openssl.list_cipher_algorithms o openssl list -cipher-algorithms.

A partir de OpenSSL 3.0, esta función acepta un parámetro opcional properties para seleccionar explícitamente el proveedor para obtener algoritmos.

cipher.istype

sintaxis: ok = cipher.istype(table)

Devuelve true si la tabla es una instancia de cipher. Devuelve false en caso contrario.

cipher.set_buffer_size

sintaxis: ok = cipher.set_buffer_size(sz)

Redimensiona el tamaño del búfer interno utilizado por todas las instancias de cifrado. El tamaño de búfer predeterminado es de 1024 bytes.

Si esperas pasar texto de entrada mayor a 1024 bytes a la vez a update(), encrypt() o decrypt(), establecer el búfer a un tamaño mayor que el tamaño de entrada esperado mejorará el rendimiento al permitir que más código sea JIT-able.

Evita llamar a esta función en la ruta crítica, ya que esto reasigna el búfer cada vez que se llama.

cipher:get_provider_name

sintaxis: name = cipher:get_provider_name()

Devuelve el nombre del proveedor de cipher.

Esta función está disponible en OpenSSL 3.0 o posterior.

cipher:gettable_params, cipher:settable_params, cipher:get_param, cipher:set_params

Consulta los parámetros configurables o recuperables y establece o obtiene parámetros. Consulta Generic EVP parameter getter/setter.

cipher:encrypt

sintaxis: s, err = cipher:encrypt(key, iv?, s, no_padding?, aead_aad?)

Cifra el texto s con la clave key y el IV iv. Devuelve el texto cifrado en cadena binaria cruda y un error si hay alguno. Opcionalmente acepta un booleano no_padding que le dice al cifrado que habilite o deshabilite el relleno y por defecto es false (habilitar relleno). Si no_padding es true, la longitud de s debe ser un múltiplo del tamaño del bloque o se producirá un error.

Al usar el modo GCM o CCM o el cifrado chacha20-poly1305, también es posible pasar los Datos Adicionales Autenticados (AAD) como el quinto argumento.

Esta función es un atajo de cipher:init, cipher:set_aead_aad (si corresponde) y luego cipher:final.

cipher:decrypt

sintaxis: s, err = cipher:decrypt(key, iv?, s, no_padding?, aead_aad?, aead_tag?)

Descifra el texto s con la clave key y el IV iv. Devuelve el texto descifrado en cadena binaria cruda y un error si hay alguno. Opcionalmente acepta un booleano no_padding que le dice al cifrado que habilite o deshabilite el relleno y por defecto es false (habilitar relleno). Si no_padding es true, la longitud de s debe ser un múltiplo del tamaño del bloque o se producirá un error; además, el relleno en el texto descifrado no se eliminará.

Al usar el modo GCM o CCM o el cifrado chacha20-poly1305, también es posible pasar los Datos Adicionales Autenticados (AAD) como el quinto argumento y la etiqueta de autenticación como el sexto argumento.

Esta función es un atajo de cipher:init, cipher:set_aead_aad (si corresponde), cipher:set_aead_tag (si corresponde) y luego cipher:final.

cipher:init

sintaxis: ok, err = cipher:init(key, iv?, opts?)

Inicializa el cifrado con la clave key y el IV iv. El tercer argumento opcional es una tabla que consiste en:

{
    is_encrypt = false,
    no_padding = false,
}

Se necesita llamar a esta función antes de cipher:update y cipher:final si el cifrado no se ha inicializado ya. Pero no cipher:encrypt y cipher:decrypt.

Si deseas reutilizar la instancia cipher múltiples veces, es necesario llamar a esta función para limpiar el estado interno del cifrado. Las funciones abreviadas cipher:encrypt y cipher:decrypt ya se encargan de la inicialización y el reinicio.

cipher:update

sintaxis: s, err = cipher:update(partial, ...)

Actualiza el cifrado con una o más cadenas. Si el cifrado tiene más datos que el tamaño del bloque para vaciar, la función devolverá una cadena no vacía como primer argumento. Esta función se puede usar de manera continua para cifrar o descifrar un flujo de datos continuo.

cipher:update_aead_aad

sintaxis: ok, err = cipher:update_aead_aad(aad)

Proporciona datos AAD al cifrado, esta función se puede llamar más de una vez.

cipher:get_aead_tag

sintaxis: tag, err = cipher:get_aead_tag(size?)

Obtiene la etiqueta de autenticación del cifrado con longitud especificada como size. Si se omite, se devolverá una etiqueta con longitud de la mitad del tamaño del bloque.

Esta función solo se puede llamar después de que se haya terminado la cifrado.

cipher:set_aead_tag

sintaxis: ok, err = cipher:set_aead_tag(tag)

Establece la etiqueta de autenticación del cifrado con tag.

Esta función solo se puede llamar antes de que comience la descifrado.

cipher:final

sintaxis: s, err = cipher:final(partial?)

Devuelve el texto cifrado o descifrado en cadena binaria cruda, opcionalmente acepta una cadena para cifrar o descifrar.

-- cifrado
local c, err = require("resty.openssl.cipher").new("aes256")
c:init(string.rep("0", 32), string.rep("0", 16), {
    is_encrypt = true,
})
c:update("🦢")
local cipher, err = c:final()
ngx.say(ngx.encode_base64(cipher))
-- outputs "vGJRHufPYrbbnYYC0+BnwQ=="
-- O:
local c, err = require("resty.openssl.cipher").new("aes256")
local cipher, err = c:encrypt(string.rep("0", 32), string.rep("0", 16), "🦢")
ngx.say(ngx.encode_base64(cipher))
-- outputs "vGJRHufPYrbbnYYC0+BnwQ=="

-- descifrado
local encrypted = ngx.decode_base64("vGJRHufPYrbbnYYC0+BnwQ==")
local c, err = require("resty.openssl.cipher").new("aes256")
c:init(string.rep("0", 32), string.rep("0", 16), {
    is_encrypt = false,
})
c:update(encrypted)
local cipher, err = c:final()
ngx.say(cipher)
-- outputs "🦢"
-- O:
local c, err = require("resty.openssl.cipher").new("aes256")
local cipher, err = c:decrypt(string.rep("0", 32), string.rep("0", 16), encrypted)
ngx.say(cipher)
-- outputs "🦢"

Nota: en algunas implementaciones como libsodium o Java, los cifrados AEAD añaden la tag (o MAC) al final del texto cifrado. En tales casos, los usuarios necesitarán cortar manualmente la tag con el tamaño correcto (generalmente 16 bytes) y pasar el texto cifrado y la tag por separado.

Consulta examples/aes-gcm-aead.lua para un ejemplo de uso de modos AEAD con autenticación.

cipher:derive

sintaxis: key, iv, err = cipher:derive(key, salt?, count?, md?)

Deriva una clave y un IV (si corresponde) a partir del material dado que se puede utilizar en el cifrado actual. Esta función es útil principalmente para trabajar con claves que ya se han derivado del mismo algoritmo. Las aplicaciones más nuevas deben usar un algoritmo más moderno como PBKDF2 proporcionado por kdf.derive.

count es el número de iteraciones a realizar. Si se omite, se establece en 1. Ten en cuenta que las versiones recientes de la herramienta CLI openssl enc utilizan automáticamente PBKDF2 si -iter se establece en un valor mayor que 1, mientras que esta función no lo hará. Para usar PBKDF2 para derivar una clave, consulta kdf.derive.

md es el nombre del resumen a utilizar, puede tomar uno de los valores md2, md5, sha o sha1. Si se omite, se establece por defecto en sha1.

local cipher = require("resty.openssl.cipher").new("aes-128-cfb")
local key, iv, err = cipher:derive("x")
-- equivalente a `openssl enc -aes-128-cfb -pass pass:x -nosalt -P -md sha1`

resty.openssl.digest

Módulo para interactuar con el resumen de mensajes (EVP_MD_CTX).

digest.new

sintaxis: d, err = digest.new(digest_name?, properties?)

Crea una instancia de resumen. digest_name es una cadena insensible a mayúsculas del nombre del algoritmo de resumen. Para ver una lista de algoritmos de resumen implementados, usa openssl.list_digest_algorithms o openssl list -digest-algorithms.

Si se omite digest_name, se establece por defecto en sha1. Específicamente, el digest_name "null" representa un resumen "nulo" que no hace nada: es decir, el hash que devuelve tiene longitud cero.

A partir de OpenSSL 3.0, esta función acepta un parámetro opcional properties para seleccionar explícitamente el proveedor para obtener algoritmos.

digest.istype

sintaxis: ok = digest.istype(table)

Devuelve true si la tabla es una instancia de digest. Devuelve false en caso contrario.

digest:get_provider_name

sintaxis: name = digest:get_provider_name()

Devuelve el nombre del proveedor de digest.

Esta función está disponible en OpenSSL 3.0 o posterior.

digest:gettable_params, digest:settable_params, digest:get_param, digest:set_params

Consulta los parámetros configurables o recuperables y establece o obtiene parámetros. Consulta Generic EVP parameter getter/setter.

digest:update

sintaxis: ok, err = digest:update(partial, ...)

Actualiza el resumen con una o más cadenas.

digest:final

sintaxis: str, err = digest:final(partial?)

Devuelve el resumen en cadena binaria cruda, opcionalmente acepta una cadena para resumir.

```lua local d, err = require("resty.openssl.digest").new("sha256") d:update("🦢") local