openssl

# *openssl*: Vinculação OpenSSL baseada em FFI para nginx-module-lua

## Instalação

Se você ainda não configurou a assinatura do repositório RPM, [inscreva-se](https://www.getpagespeed.com/repo-subscribe). Em seguida, você pode prosseguir com os seguintes passos.

### CentOS/RHEL 7 ou 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 com NGINX, certifique-se de que o nginx-module-lua esteja instalado.

Este documento descreve lua-resty-openssl v1.8.0 lançado em 10 de junho de 2026.

---

Vinculação OpenSSL baseada em FFI para LuaJIT, suportando OpenSSL 3, 4 e a série 1.1.1.

O suporte para OpenSSL 1.1.0, 1.0.2 e BoringSSL foi removido, mas ainda está disponível na branch 0.x.

Descrição

lua-resty-openssl é uma biblioteca de vinculação OpenSSL baseada em FFI, atualmente suporta OpenSSL 3.x, 4.x e a série 1.1.1.

Sinopse

Esta biblioteca é fortemente inspirada pelo luaossl e usa uma convenção de nomenclatura mais próxima da API original do OpenSSL. Por exemplo, uma função chamada X509_set_pubkey na API C do OpenSSL é exposta como resty.openssl.x509:set_pubkey. CamelCase é substituído por underscore_case, por exemplo, X509_set_serialNumber se torna resty.openssl.x509:set_serial_number. Outra diferença em relação ao luaossl é que os erros nunca são lançados usando error(), mas em vez disso retornam como último parâmetro.

Cada tabela Lua retornada por new() contém um objeto cdata ctx. Os usuários não devem definir manualmente ffi.gc ou chamar o destrutor correspondente da struct ctx (como funções *_free).

resty.openssl

Este módulo meta fornece uma verificação de sanidade da versão em relação à biblioteca OpenSSL vinculada.

openssl.load_library

sintaxe: name, err = openssl.load_library()

Tenta carregar bibliotecas compartilhadas do OpenSSL. Esta função tenta alguns padrões de nome de biblioteca conhecidos e retorna o nome da biblioteca crypto quando é carregada com sucesso, ou um erro, se houver.

Ao executar dentro do CLI resty ou OpenResty com SSL habilitado, chamar esta função não é necessário.

openssl.load_modules

sintaxe: openssl.load_modules()

Carrega todos os submódulos disponíveis no módulo atual:

  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 do OpenSSL 3.0, provider, mac e ctx também estão disponíveis.

openssl.luaossl_compat

sintaxe: openssl.luaossl_compat()

Fornece uma API no estilo luaossl que usa nomenclatura camelCase; os usuários podem esperar uma substituição direta.

Por exemplo, pkey:get_parameters é mapeado para pkey:getParameters.

Observe que nem toda a API luaossl foi implementada, consulte o README para a fonte da verdade.

openssl.get_fips_mode

sintaxe: enabled = openssl.get_fips_mode()

Retorna um booleano indicando se o modo FIPS está habilitado.

openssl.set_fips_mode

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

Alterna o modo FIPS ligado ou desligado.

lua-resty-openssl suporta os seguintes modos:

Série OpenSSL 1.0.2 com módulo fips 2.0

Compile o módulo de acordo com a política de segurança,

Provedor FIPS do OpenSSL 3

Consulte https://wiki.openssl.org/index.php/OpenSSL_3.0 Seção 7 Compile o provedor de acordo com o guia, instale o fipsmodule.cnf que corresponde ao hash do provedor FIPS fips.so.

A partir do OpenSSL 3.0, esta função também ativa e desativa propriedades padrão para funções EVP. Quando ativado, todos os aplicativos que usam a API EVP_* serão redirecionados para implementações compatíveis com FIPS e não terão acesso a algoritmos não compatíveis com FIPS.

Chamar esta função é equivalente a carregar o provedor fips e chamar openssl.set_default_properties("fips=yes").

Se o provedor FIPS estiver carregado, mas as propriedades padrão não estiverem definidas, use o seguinte para buscar explicitamente a implementação 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

sintaxe: text, err = openssl.get_fips_version_text()

Retorna o texto da versão do módulo FIPS, disponível no OpenSSL 3.0 ou posterior.

openssl.set_default_properties

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

Define as propriedades padrão para todas as futuras buscas de algoritmos EVP, implícitas e explícitas. Consulte "BUSCA DE ALGORITMOS" em crypto(7) para informações sobre busca implícita e explícita.

openssl.list_cipher_algorithms

sintaxe: ret = openssl.list_cipher_algorithms(hide_provider?)

Retorna algoritmos de cifra disponíveis em um array. Defina hide_provider como true para ocultar o nome do provedor do resultado.

openssl.list_digest_algorithms

sintaxe: ret = openssl.list_digest_algorithms(hide_provider?)

Retorna algoritmos de digestão disponíveis em um array. Defina hide_provider como true para ocultar o nome do provedor do resultado.

openssl.list_mac_algorithms

sintaxe: ret = openssl.list_mac_algorithms(hide_provider?)

Retorna algoritmos MAC disponíveis em um array. Defina hide_provider como true para ocultar o nome do provedor do resultado.

openssl.list_kdf_algorithms

sintaxe: ret = openssl.list_kdf_algorithms(hide_provider?)

Retorna algoritmos KDF disponíveis em um array. Defina hide_provider como true para ocultar o nome do provedor do resultado.

openssl.list_ssl_ciphers

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

Retorna cifras SSL padrão como uma string. cipher_list (antes do TLSv1.3) e ciphersuites (TLSv1.3) podem ser usados para expandir as configurações de cifra que correspondem a protocol. OpenSSL 4.x rejeita "SSLv3" porque o suporte ao SSLv3 foi removido.

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

Um módulo para fornecer alternâncias de contexto OSSL_LIB_CTX.

OSSL_LIB_CTX é um tipo de contexto de biblioteca OpenSSL interno. Aplicativos podem alocar o seu próprio, mas também podem usar NULL para usar um contexto padrão com funções que aceitam um argumento OSSL_LIB_CTX.

Consulte OSSL_LIB_CTX.3 para uma leitura mais profunda.

O contexto é atualmente eficaz nos seguintes módulos:

• cipher
• digest
• kdf
• mac
• pkcs12.encode
• pkey
• provider
• rand
• x509, x509.csr, x509.crl e algumas funções de x509.store

Este módulo está disponível no OpenSSL 3.0 ou posterior.

ctx.new

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

Cria um novo contexto e usa como contexto padrão para este módulo. Quando request_context_only é definido como verdadeiro, o contexto é usado apenas dentro do contexto da requisição atual. conf_file pode opcionalmente especificar um arquivo de configuração do OpenSSL para criar o contexto.

O contexto criado é automaticamente liberado com seu ciclo de vida dado.

-- inicializa uma instância de cifra AES a partir da implementação do provedor dado apenas
-- para a requisição atual, sem interferir em outras partes do código
-- ou em requisições futuras que usam o mesmo 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), "🦢"))
-- não é necessário liberar o provedor e ctx, eles são coletados automaticamente

ctx.free

sintaxe: ctx.free(request_context_only?)

Libera o contexto que foi previamente criado por ctx.new.

resty.openssl.err

Um módulo para fornecer mensagens de erro.

err.format_error

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

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

Retorna a última mensagem de erro do último código de erro. Os erros são formatados como:

[ctx_msg]: código: [return_code]: erro:[código de erro]:[nome da biblioteca]:[nome da função]:[string de razão]:[nome do arquivo]:[número da linha]:

Para versões do OpenSSL anteriores a 3.0, os erros são formatados como:

[ctx_msg]: código: [return_code]: [nome do arquivo]:[número da linha]:erro:[código de erro]:[nome da biblioteca]:[nome da função]:[string de razão]:

Se all_errors estiver definido como true, todos os erros, não apenas o mais recente, serão retornados em uma única string. Todos os erros lançados por esta biblioteca internamente apenas lançam o erro mais recente.

Por exemplo:

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: erro:4800065:rotinas PEM:PEM_do_header:bad decrypt:crypto/pem/pem_lib.c:467:

err.get_last_error_code

sintaxe: code = err.get_last_error_code()

Retorna o último código de erro.

err.get_lib_error_string

sintaxe: lib_error_message = err.get_lib_error_string(code?)

Retorna o nome da biblioteca do último código de erro como string. Se code estiver definido, retorna o nome da biblioteca correspondente ao código de erro fornecido.

err.get_reason_error_string

sintaxe: reason_error_message = err.get_reason_error_string(code?)

Retorna a razão do último código de erro como string. Se code estiver definido, retorna a razão correspondente ao código de erro fornecido.

resty.openssl.version

Um módulo para fornecer informações de versão.

resty.openssl.provider

Módulo para interagir com provedores. Este módulo funciona apenas no OpenSSL 3.0 ou posterior.

provider.load

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

Carrega o provedor com name. Se try estiver definido como verdadeiro, o OpenSSL não desativará os provedores de fallback se o provedor não puder ser carregado e inicializado. Se o provedor for carregado com sucesso, no entanto, os provedores de fallback são desativados.

Por padrão, esta função carrega o provedor no contexto padrão, o que significa que afetará outros aplicativos no mesmo processo que usam o contexto padrão também. Se esse comportamento não for desejado, considere usar ctx para carregar o provedor apenas em um escopo limitado.

provider.istype

sintaxe: ok = pkey.provider(table)

Retorna true se a tabela for uma instância de provider. Retorna false caso contrário.

provider.is_available

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

Verifica se um provedor nomeado está disponível para uso.

provider.set_default_search_path

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

Especifica o caminho de pesquisa padrão que deve ser usado para procurar provedores.

provider:unload

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

Descarrega um provedor que foi previamente carregado por provider.load.

provider:self_test

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

Executa os testes de autoavaliação de um provedor sob demanda. Se os testes de autoavaliação falharem, o provedor falhará em fornecer quaisquer serviços e algoritmos adicionais.

provider:get_params

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

Retorna um ou mais valores de parâmetros do provedor.

local pro = require "resty.openssl.provider"

local p = pro.load("default")

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

local result = assert(p:get_params("name", "version", "buildinfo", "status"))
print(require("cjson").encode(result))
-- produz metadados do provedor; versão e buildinfo variam conforme a versão do OpenSSL

resty.openssl.pkey

Módulo para interagir com chaves privadas e chaves públicas (EVP_PKEY).

Cada tipo de chave pode suportar apenas parte das operações:

Tipo de Chave	Carregar chave existente	Geração de chave	Criptografar/Descriptografar	Assinar/Verificar	Troca de Chave
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)

O suporte direto para criptografia e descriptografia para EC e ECX não existe, mas processos como ECIES são possíveis com pkey:derive, kdf e cipher.

pkey.new

Carregar chave existente

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

Suporta o carregamento de uma chave privada ou pública no formato PEM, DER ou JWK passada como primeiro argumento string.

O segundo parâmetro opts aceita uma tabela opcional para restringir o comportamento de carregamento da chave.

• opts.format: defina explicitamente como "PEM", "DER", "JWK" para carregar um formato específico ou defina como "*" para detecção automática
• opts.type: defina explicitamente como "pr" para chave privada, "pu" para chave pública; defina como "*" para detecção automática

Ao carregar uma chave RSA codificada em PEM, ela pode ser codificada em PKCS#8 como SubjectPublicKeyInfo/PrivateKeyInfo ou em PKCS#1 como RSAPublicKey/RSAPrivateKey.

Ao carregar uma chave codificada em PEM criptografada, a passphrase para descriptografá-la pode ser definida em opts.passphrase ou opts.passphrase_cb:

pkey.new(pem_or_der_text, {
  format = "*", -- escolha de "PEM", "DER", "JWK" ou "*" para detecção automática
  type = "*", -- escolha de "pr" para chave privada, "pu" para chave pública e "*" para detecção automática
  passphrase = "senha secreta", -- a senha de criptografia PEM
  passphrase_cb = function()
    return "senha secreta"
  end, -- a função de callback da senha de criptografia PEM
}

Ao carregar JWK, há algumas ressalvas: - Certifique-se de que o texto JSON codificado seja passado, ele deve ter sido decodificado em base64. - Restringir opts.type para chaves JWK requer OpenSSL 3.0 ou posterior e lua-resty-openssl 1.6.0 ou posterior. Com OpenSSL 1.1.1 ou versões mais antigas lançamentos do lua-resty-openssl, os parâmetros no JSON fornecido decidirão se uma chave privada ou pública é carregada, especificar type resultará em um erro; também a parte da chave pública para chaves OKP (o parâmetro x) não é respeitada e derivada da parte da chave privada (o parâmetro d) se estiver especificada. - Apenas tipos de chave RSA, P-256, P-384 e P-512 EC, Ed25519, X25519, Ed448 e X448 OKP são suportados. - Assinaturas e verificações devem usar a opção ecdsa_use_raw para funcionar com os padrões JWS para chaves EC. Consulte pkey:sign e pkey.verify para mais detalhes. - Ao executar fora do OpenResty, é necessário instalar uma biblioteca JSON (cjson ou dkjson) e basexx.

Geração de chave

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

Gera uma nova chave pública ou chave privada.

Para gerar uma chave RSA, a tabela config pode ter os campos bits e exp para controlar a geração da chave. Quando config é emitido, esta função gera uma chave RSA de 2048 bits com exponent de 65537, o que é equivalente a:

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

Para gerar uma chave EC ou DH, consulte pkey.paramgen para os valores possíveis da tabela config. Por exemplo:

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

Também é possível passar parâmetros EC ou DH codificados em PEM para config.param para geração de chave:

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

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

Também é possível passar strings de controle pkeyopt brutas na tabela config como usado no programa CLI genpkey. Consulte openssl-genpkey(1) para uma lista de opções.

Por exemplo:

pkey.new({
  type = 'RSA',
  bits = 2048,
  exp = 65537,
})
-- é o mesmo que
pkey.new({
  type = 'RSA',
  exp = 65537,
  "rsa_keygen_bits:4096",
})

Composição de chave

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

Componha uma chave pública ou privada usando parâmetros existentes. Para ver a lista de parâmetros para cada chave, consulte pkey:set_parameters.

Apenas type e params devem existir na tabela config, todas as outras chaves serão 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

sintaxe: ok = pkey.istype(table)

Retorna true se a tabela for uma instância de pkey. Retorna false caso contrário.

pkey.paramgen

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

Gera parâmetros para chave EC ou DH e os exporta como texto codificado em PEM.

Para chave EC:

Parâmetro	Descrição
type	"EC"
curve	Curvas EC. Se omitido, o padrão é "prime192v1". Para ver a lista de curvas EC suportadas, use openssl ecparam -list_curves.

Para chave DH:

Parâmetro	Descrição
type	"DH"
bits	Gera um novo parâmetro DH com primo de comprimento bits. Se omitido, o padrão é 2048. A partir do OpenSSL 3.0, apenas bits iguais a 2048 são permitidos.
group	Use grupos pré-definidos em vez de gerar um novo. bit será ignorado se group estiver definido.

Valores possíveis para group são: - 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',
})

Também é possível passar strings de controle pkeyopt brutas na tabela config como usado no programa CLI genpkey. Consulte openssl-genpkey(1) para uma lista de opções.

pkey:get_provider_name

sintaxe: name = pkey:get_provider_name()

Retorna o nome do provedor de pkey.

Esta função está disponível no OpenSSL 3.0 ou posterior.

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

Consulta parâmetros settable ou gettable e define ou obtém parâmetros. Consulte Generic EVP parameter getter/setter.

pkey:get_parameters

sintaxe: parameters, err = pk:get_parameters()

Retorna uma tabela contendo os parameters da instância pkey.

pkey:set_parameters

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

Define os parâmetros da pkey a partir de uma tabela params. Se o parâmetro não estiver definido na tabela params, ele permanece inalterado na instância pkey.

local pk, err = require("resty.openssl.pkey").new()
local parameters, err = pk:get_parameters()
local e = parameters.e
ngx.say(e:to_number())
-- produz 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 chave RSA:

Parâmetro	Descrição	Tipo
n	módulo comum a ambas as chaves pública e privada	bn
e	expoente público	bn
d	expoente privado	bn
p	primeiro fator de n	bn
q	segundo fator de n	bn
dmp1	d mod (p - 1), expoente1	bn
dmq1	d mod (q - 1), expoente2	bn
iqmp	(InverseQ)(q) = 1 mod p, coeficiente	bn

Parâmetros para chave EC:

Parâmetro	Descrição	Tipo
private	chave privada	bn
public	chave pública	bn
x	coordenada x da chave pública	bn
y	coordenada y da chave pública	bn
group	o grupo de curva nomeado	[NID] como um número, quando passado como set_parameters(), também é possível usar a representação textual. Isso é diferente de luaossl, onde uma instância EC_GROUP é retornada.

Não é possível definir x, y com public ao mesmo tempo, pois x e y são basicamente outra representação de public. Além disso, atualmente só é possível definir x e y ao mesmo tempo.

Parâmetros para chave DH:

Parâmetro	Descrição	Tipo
private	chave privada	bn
public	chave pública	bn
p	módulo primo	bn
q	posição de referência	bn
g	gerador base	bn

Parâmetros para chaves Curve25519 e Curve448:

Parâmetro	Descrição	Tipo
private	chave privada bruta representada como bytes	string
public	chave pública bruta representada como bytes	string

pkey:is_private

sintaxe: ok = pk:is_private()

Verifica se pk é uma chave privada. Retorna verdadeiro se for uma chave privada, retorna falso se for uma chave pública.

pkey:get_key_type

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

Retorna um ASN1_OBJECT do tipo de chave da chave privada como uma tabela.

A partir da versão 1.6.0 do lua-resty-openssl, um argumento opcional nid_only pode ser definido como true para retornar apenas o NID numérico da chave.

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

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

pkey:get_size

sintaxe: size, err = pk:get_size()

Retorna o tamanho máximo adequado para os buffers de saída para quase todas as operações que podem ser feitas com pkey.

Para chave RSA, este é o tamanho do módulo. Para chaves EC, Ed25519 e Ed448, este é o tamanho da chave privada. Para chave DH, este é o tamanho do módulo primo.

pkey:get_default_digest_type

sintaxe: obj, err = pk:get_default_digest_type()

Retorna um ASN1_OBJECT do tipo de chave da chave privada como uma tabela. Um campo adicional mandatory também é retornado na tabela, se mandatory for verdadeiro, então outros digests não podem ser usados.

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

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

pkey:sign

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

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

Realiza uma assinatura de digestão usando a chave privada definida na instância pkey. O primeiro parâmetro deve ser uma instância de resty.openssl.digest ou uma string. Retorna o texto assinado e um erro, se houver.

Ao passar uma instância de digest como primeiro parâmetro, ela não deve ter sido chamada final(); os usuários devem apenas usar update(). Este modo suporta apenas chaves RSA e EC.

Ao passar uma string como primeiro parâmetro, o parâmetro md_alg especificará o nome a ser usado ao assinar. Quando md_alg não estiver definido, para chaves RSA e EC, esta função faz SHA256 por padrão. Para chaves Ed25519 ou Ed448, esta função faz uma assinatura PureEdDSA, nenhuma digestão de mensagem deve ser especificada e não será usada.

Para chave RSA, também é possível especificar o esquema de padding com as seguintes opções:

  pkey.PADDINGS = {
    RSA_PKCS1_PADDING       = 1,
    RSA_SSLV23_PADDING      = 2,
    RSA_NO_PADDING          = 3,
    RSA_PKCS1_OAEP_PADDING  = 4,
    RSA_X931_PADDING        = 5, -- apenas assinar
    RSA_PKCS1_PSS_PADDING   = 6, -- apenas assinar e verificar
  }

Quando padding é RSA_PKCS1_PSS_PADDING, é possível especificar o comprimento do sal PSS definindo opts.pss_saltlen.

Para chave EC, esta função realiza uma assinatura ECDSA. Observe que o OpenSSL não suporta assinatura digital EC (ECDSA) com o algoritmo de hash obsoleto MD5 e retornará um erro nessa combinação. Consulte EVP_DigestSign(3) para uma lista de algoritmos e algoritmos de chave pública associados. Normalmente, a assinatura ECDSA é codificada no formato ASN.1 DER. Se a tabela opts contiver um campo ecdsa_use_raw com um valor verdadeiro, um binário com apenas a concatenação da representação binária pr e ps é retornado. Isso é útil, por exemplo, para enviar a assinatura como JWS.

opts é uma tabela que aceita parâmetros adicionais com as seguintes opções:

{
  pss_saltlen, -- Para o modo PSS, esta opção especifica o comprimento do sal.
  mgf1_md, -- Para o preenchimento PSS e OAEP, define o digest MGF1. Se o digest MGF1 não for definido explicitamente no modo PSS, então o digest de assinatura é usado.
  oaep_md, -- O digest usado para a função de hash OAEP. Se não definido explicitamente, então SHA1 é usado.
}

Também é possível passar strings de controle pkeyopt brutas como usadas no programa CLI pkeyutl. Isso permite que os usuários passem opções que não são explicitamente suportadas como parâmetros acima. Consulte openssl-pkeyutl(1) para uma lista de opções.

pk:sign(message, nil, pk.PADDINGS.RSA_PKCS1_OAEP_PADDING, {
  oaep_md = "sha256",
})
-- é o mesmo que
pk:sign(message, nil, nil, {
  "rsa_padding_mode:oaep",
  "rsa_oaep_md:sha256",
})
-- no CLI pkeyutl, o acima é equivalente a: `openssl pkeyutl -sign -pkeyopt rsa_padding_mode:oaep -pkeyopt rsa_oaep_md:sha256

Para assinar uma mensagem sem fazer digestão de mensagem, consulte pkey:sign_raw.

pkey:verify

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

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

Verifica uma assinatura (que pode ser a string retornada por pkey:sign). O segundo argumento deve ser uma instância de resty.openssl.digest que usa o mesmo algoritmo de digestão que foi usado em sign ou uma string. ok retorna true se a verificação for bem-sucedida e false caso contrário. Observe que, quando a verificação falha, err não será definido quando usado com OpenSSL 1.1.1 ou inferior.

Ao passar instâncias de digest como segundo parâmetro, não deve ter sido chamada final(); os usuários devem apenas usar update(). Este modo suporta apenas chaves RSA e EC.

Ao passar uma string como segundo parâmetro, o parâmetro md_alg especificará o nome a ser usado ao verificar. Quando md_alg não estiver definido, para chaves RSA e EC, esta função faz SHA256 por padrão. Para chaves Ed25519 ou Ed448, esta função realiza uma verificação PureEdDSA, nenhuma digestão de mensagem deve ser especificada e não será usada.

Quando a chave for uma chave RSA, a função aceita um argumento opcional padding cujas escolhas de valores são as mesmas que as de pkey:sign. Quando padding é RSA_PKCS1_PSS_PADDING, é possível especificar o comprimento do sal PSS definindo opts.pss_saltlen.

Para chave EC, esta função realiza uma verificação ECDSA. Normalmente, a assinatura ECDSA deve ser codificada no formato ASN.1 DER. Se a tabela opts contiver um campo ecdsa_use_raw com um valor verdadeiro, esta biblioteca tratará signature como a concatenação da representação binária pr e ps. Isso é útil, por exemplo, para verificar a assinatura como JWS.

opts é uma tabela que aceita parâmetros adicionais cujas escolhas de valores são as mesmas que as de pkey:sign.

-- Chaves RSA e EC
local pk, err = require("resty.openssl.pkey").new()
local digest, err = require("resty.openssl.digest").new("SHA256")
digest:update("dog")
-- ERRADO:
-- digest:final("dog")
local signature, err = pk:sign(digest)
-- usa SHA256 por padrão
local signature, err = pk:sign("dog")
ngx.say(ngx.encode_base64(signature))
-- usa SHA256 e preenchimento 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 padrão
local ok, err = pk:verify(signature, "dog")
-- usa SHA256 e preenchimento PSS
local ok, err = pk:verify(signature_pss, "dog", "sha256", pk.PADDINGS.RSA_PKCS1_PSS_PADDING)

-- Chaves Ed25519 e 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 uma mensagem sem fazer digestão de mensagem, consulte pkey:verify_raw e pkey:verify_recover.

pkey:encrypt

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

Criptografa o texto simples txt com uma instância de pkey, que deve conter uma chave pública.

O segundo argumento opcional padding tem o mesmo significado que em pkey:sign. Se omitido, padding padrão é pkey.PADDINGS.RSA_PKCS1_PADDING.

O terceiro argumento opcional opts tem o mesmo significado que em pkey:sign.

pkey:decrypt

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

Descriptografa o texto cifrado cipher_txt com uma instância de pkey, que deve conter uma chave privada.

O segundo argumento opcional padding tem o mesmo significado que em pkey:sign. Se omitido, padding padrão é pkey.PADDINGS.RSA_PKCS1_PADDING.

O terceiro argumento opcional opts tem o mesmo significado que em 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)
-- produz 256
local decrypted, err = privkey:decrypt(s)
ngx.say(decrypted)
-- produz "🦢"

pkey:sign_raw

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

Assina o texto cifrado cipher_txt com uma instância de pkey, que deve conter uma chave privada.

O segundo argumento opcional padding tem o mesmo significado que em pkey:sign. Se omitido, padding padrão é pkey.PADDINGS.RSA_PKCS1_PADDING.

O terceiro argumento opcional opts tem o mesmo significado que em pkey:sign.

Esta função também pode ser chamada de "criptografia privada" em algumas implementações como NodeJS ou PHP. Observe que, apesar do nome da função, esta função não é segura o suficiente para ser considerada criptografia. Ao desenvolver novos aplicativos, os usuários devem usar pkey:sign para assinar com digestão, ou pkey:encrypt para criptografia.

Consulte examples/raw-sign-and-recover.lua para um exemplo.

pkey:verify_raw

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

Verifica o texto cifrado signature com a mensagem data usando uma instância de pkey, que deve conter uma chave pública. Define a digestão da mensagem para md_alg, mas não calcula a digestão da mensagem automaticamente; em outras palavras, esta função assume que data já foi hasheada com md_alg.

Quando md_alg não estiver definido, para chaves RSA e EC, esta função faz SHA256 por padrão. Para chaves Ed25519 ou Ed448, nenhum valor padrão é definido.

O quarto argumento opcional padding tem o mesmo significado que em pkey:sign. Se omitido, padding padrão é pkey.PADDINGS.RSA_PKCS1_PADDING.

O quinto argumento opcional opts tem o mesmo significado que em pkey:sign.

Consulte examples/raw-sign-and-recover.lua para um exemplo.

pkey:verify_recover

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

Verifica o texto cifrado signature com uma instância de pkey, que deve conter uma chave pública, e também retorna o texto original que está sendo assinado. Esta operação é suportada apenas por chave RSA.

O segundo argumento opcional padding tem o mesmo significado que em pkey:sign. Se omitido, padding padrão é pkey.PADDINGS.RSA_PKCS1_PADDING.

O terceiro argumento opcional opts tem o mesmo significado que em pkey:sign.

Esta função também pode ser chamada de "descriptografia pública" em algumas implementações como NodeJS ou PHP.

Consulte examples/raw-sign-and-recover.lua para um exemplo.

pkey:derive

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

Deriva a chave compartilhada do algoritmo de chave pública peer_key, que deve ser uma instância de pkey.

Consulte examples/x25519-dh.lua para um exemplo de como a troca de chaves funciona para chaves X25519 com o algoritmo DH.

pkey:tostring

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

Saídas da chave privada ou chave pública da instância pkey em texto formatado em PEM. O primeiro argumento deve ser uma escolha de public, PublicKey, private, PrivateKey ou nil.

O segundo argumento fmt pode ser PEM, DER, JWK ou nil. Se ambos os argumentos forem omitidos, esta função retorna a representação PEM da chave pública.

Se is_pkcs1 estiver definido como verdadeiro, a saída é codificada usando uma estrutura PKCS#1 RSAPublicKey; a codificação PKCS#1 atualmente é suportada para chave RSA em formato PEM. Escrever uma chave RSA codificada em PKCS#1 atualmente não é suportado ao usar OpenSSL 3.0 ou posterior.

pkey:to_PEM

sintaxe: 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 expor a estrutura BIGNUM. Observe que bignum é um inteiro grande, nenhuma operação de ponto flutuante (como raiz quadrada) é suportada.

bn.new

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

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

Cria uma instância bn. O primeiro argumento pode ser:

• nil para criar uma instância bn vazia.
• Um número Lua para inicializar a instância bn.
• Uma string para inicializar a instância bn. O segundo argumento base especifica a base da string, e pode assumir valores (compatíveis com a API Ruby OpenSSL):
• 10 ou omitido, para string decimal ("23333")
• 16, para string codificada em hex ("5b25")
• 2, para string binária ("\x5b\x25")
• 0, para string formatada em MPI ("\x00\x00\x00\x02\x5b\x25")

MPI é um formato que consiste no comprimento do número em bytes representado como um número de 4 bytes em big-endian, e o número em si em formato big-endian, onde o bit mais significativo sinaliza um número negativo (a representação de números com o MSB definido é prefixada com um byte nulo).

bn.dup

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

Duplica um BIGNUM* para criar uma nova instância bn.

bn.istype

sintaxe: ok = bn.istype(table)

Retorna true se a tabela for uma instância de bn. Retorna false caso contrário.

bn.set

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

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

Reutiliza a instância bn existente e redefine seu valor com o número ou string fornecidos. Consulte bn.new para o tipo de argumentos suportados.

bn.from_binary, bn:to_binary

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

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

Cria uma instância bn a partir de uma string binária.

Exporta o valor BIGNUM em string binária.

bn:to_binary aceita um argumento numérico opcional padto que pode ser usado para adicionar zeros à esquerda à saída para um comprimento específico.

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))
-- produz "5b25

bn.from_mpi, bn:to_mpi

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

sintaxe: bin, err = bn:to_mpi()

Cria uma instância bn a partir de uma string binária formatada em MPI.

Exporta o valor BIGNUM em string binária formatada em 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))
-- produz "000000025b25

bn.from_hex, bn:to_hex

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

sintaxe: hex, err = bn:to_hex()

Cria uma instância bn a partir de uma string codificada em hex. Observe que o prefixo 0x não deve ser incluído. Um prefixo - indicando o sinal pode ser incluído.

Exporta a instância bn para string codificada em hex.

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

bn.from_dec, bn:to_dec

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

sintaxe: dec, err = bn:to_dec()

Cria uma instância bn a partir de uma string decimal. Um prefixo - indicando o sinal pode ser incluído.

Exporta a instância bn para string decimal.

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

bn:to_number

sintaxe: n, err = bn:to_number()

sintaxe: n, err = bn:tonumber()

Exporta os 32 bits ou 64 bits mais baixos (com base no ABI) da instância bn para um número. Isso é útil quando os usuários desejam realizar operações bit a bit.

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

bn.generate_prime

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

Gera um número primo pseudo-aleatório de comprimento em bits bits.

Se safe for verdadeiro, será um primo seguro (ou seja, um primo p de modo que (p-1)/2 também seja primo).

O PRNG deve ser semeado antes de chamar BN_generate_prime_ex(). A geração de números primos tem uma probabilidade de erro desprezível.

bn:__metamethods

Várias operações matemáticas podem ser realizadas como se fossem um número.

local bn = require("resty.openssl.bn")
local a = bn.new(123456)
local b = bn.new(222)
 -- o seguinte retorna um bn
local r
r = -a
r = a + b
r = a - b
r = a * b
r = a / b -- igual a bn:idiv, retorna divisão inteira
r = a % b
-- todas as operações podem ser realizadas entre número e bignum
r = a + 222
r = 222 + a
-- o seguinte retorna um bool
local bool
bool = a < b
bool = a >= b
-- comparar entre número não funcionará
-- ERRADO: bool = a < 222

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

sintaxe: r = a:op(b)

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

Realiza operações matemáticas op.

• add: adicionar
• sub: subtrair
• mul: multiplicar
• div, idiv: divisão inteira (divisão com arredondamento para baixo para o inteiro mais próximo)
• exp, pow: a b-ésima potência de a, esta função é mais rápida que a * a * ....
• mod: módulo
• gcd: o maior divisor comum de a e b.

Observe que add, sub, mul, div, mod também estão disponíveis com os operadores +, -, *, /, %. Veja seção acima para exemplos.

local bn = require("resty.openssl.bn")
local a = bn.new(123456)
local b = bn.new(9876)
local r
-- os seguintes são iguais
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

sintaxe: r = a:sqr()

sintaxe: r = bn.sqr(a)

Calcula a 2-ésima potência de a. Esta função é mais rápida que r = a * a.

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

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

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

Realiza operações matemáticas de módulo op.

• mod_add: adiciona a a b módulo m
• mod_sub: subtrai b de a módulo m
• mod_mul: multiplica a por b e encontra o resto não negativo em relação ao módulo m
• mod_exp, mod_pow: calcula a à b-ésima potência módulo m (r=a^b % m). Esta função usa menos tempo e espaço do que exp. Não chame esta função quando m for par e qualquer um dos parâmetros tiver a flag BN_FLG_CONSTTIME definida.

local bn = require("resty.openssl.bn")
local a = bn.new(123456)
local b = bn.new(9876)
local r
-- os seguintes são iguais
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

sintaxe: r = a:mod_sqr(m)

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

Toma o quadrado de a módulo m.

bn:lshift, bn:rshift

sintaxe: r = bn:lshift(bit)

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

sintaxe: r = bn:rshift(bit)

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

Deslocamento de bits a para bit bits.

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

sintaxe: ok = bn:is_zero()

sintaxe: ok = bn:is_one()

sintaxe: ok = bn:is_odd()

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

Verifica se bn é 0, 1, e número ímpar ou um número n, respectivamente.

bn:is_prime

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

Verifica se bn é um número primo. Retorna true se for primo com uma probabilidade de erro de menos de 0.25^nchecks e erro, se houver. Se omitido, nchecks é definido como 0, o que significa selecionar o número de iterações com base no tamanho do número.

Esta função realiza um teste de primalidade probabilístico de Miller-Rabin com nchecks iterações. Se nchecks == BN_prime_checks (0), um número de iterações é usado que resulta em uma taxa de falso positivo de no máximo 2^-64 para entrada aleatória. A taxa de erro depende do tamanho do primo e diminui para primos maiores. A taxa é 2^-80 a partir de 308 bits, 2^-112 a 852 bits, 2^-128 a 1080 bits, 2^-192 a 3747 bits e 2^-256 a 6394 bits.

Quando a fonte do primo não é aleatória ou não confiável, o número de verificações precisa ser muito maior para alcançar o mesmo nível de garantia: deve ser igual à metade do nível de segurança alvo em bits (arredondado para cima para o próximo inteiro, se necessário). Por exemplo, para alcançar o nível de segurança de 128 bits, nchecks deve ser definido como 64.

Consulte também BN_is_prime(3).

resty.openssl.cipher

Módulo para interagir com criptografia simétrica (EVP_CIPHER).

cipher.new

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

Cria uma instância de cifra. cipher_name é uma string de nome de algoritmo de cifra que não diferencia maiúsculas de minúsculas. Para ver uma lista de algoritmos de cifra implementados, use openssl.list_cipher_algorithms ou openssl list -cipher-algorithms.

A partir do OpenSSL 3.0, esta função aceita um parâmetro opcional properties para selecionar explicitamente o provedor para buscar algoritmos.

cipher.istype

sintaxe: ok = cipher.istype(table)

Retorna true se a tabela for uma instância de cipher. Retorna false caso contrário.

cipher.set_buffer_size

sintaxe: ok = cipher.set_buffer_size(sz)

Redimensiona o tamanho do buffer interno usado por todas as instâncias de cifra. O tamanho padrão do buffer é 1024 bytes.

Se você espera passar texto de entrada maior que 1024 bytes de uma só vez para update(), encrypt() ou decrypt(), definir o buffer para um tamanho maior que o esperado melhorará o desempenho ao permitir que mais código seja JITável.

Evite chamar esta função no caminho quente, pois isso realoca o buffer toda vez que é chamada.

cipher:get_provider_name

sintaxe: name = cipher:get_provider_name()

Retorna o nome do provedor de cipher.

Esta função está disponível no OpenSSL 3.0 ou posterior.

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

Consulta parâmetros settable ou gettable e define ou obtém parâmetros. Consulte Generic EVP parameter getter/setter.

cipher:encrypt

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

Criptografa o texto s com a chave key e IV iv. Retorna o texto criptografado em string binária bruta e erro, se houver. Opcionalmente aceita um booleano no_padding que informa à cifra para habilitar ou desabilitar o preenchimento e, por padrão, é false (habilitar preenchimento). Se no_padding for true, o comprimento de s deve ser um múltiplo do tamanho do bloco ou ocorrerá um erro.

Ao usar o modo GCM ou CCM ou cifra chacha20-poly1305, também é possível passar os Dados Adicionais Autenticados (AAD) como o quinto argumento.

Esta função é um atalho para cipher:init, cipher:set_aead_aad (se aplicável) e depois cipher:final.

cipher:decrypt

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

Descriptografa o texto s com a chave key e IV iv. Retorna o texto descriptografado em string binária bruta e erro, se houver. Opcionalmente aceita um booleano no_padding que informa à cifra para habilitar ou desabilitar o preenchimento e, por padrão, é false (habilitar preenchimento). Se no_padding for true, o comprimento de s deve ser um múltiplo do tamanho do bloco ou ocorrerá um erro; além disso, o preenchimento no texto descriptografado não será removido.

Ao usar o modo GCM ou CCM ou cifra chacha20-poly1305, também é possível passar os Dados Adicionais Autenticados (AAD) como o quinto argumento e a tag de autenticação como o sexto argumento.

Esta função é um atalho para cipher:init, cipher:set_aead_aad (se aplicável), cipher:set_aead_tag (se aplicável) e depois cipher:final.

cipher:init

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

Inicializa a cifra com a chave key e IV iv. O terceiro argumento opcional é uma tabela que consiste em:

{
    is_encrypt = false,
    no_padding = false,
}

Chamar esta função é necessário antes de cipher:update e cipher:final se a cifra não estiver sendo inicializada já. Mas não cipher:encrypt e cipher:decrypt.

Se você deseja reutilizar a instância cipher várias vezes, chamar esta função é necessário para limpar o estado interno da cifra. As funções abreviadas cipher:encrypt e cipher:decrypt já cuidam da inicialização e redefinição.

cipher:update

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

Atualiza a cifra com uma ou mais strings. Se a cifra tiver mais dados do que o tamanho do bloco para descarregar, a função retornará uma string não vazia como primeiro argumento. Esta função pode ser usada de forma contínua para criptografar ou descriptografar um fluxo de dados contínuo.

cipher:update_aead_aad

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

Fornece dados AAD para a cifra, esta função pode ser chamada mais de uma vez.

cipher:get_aead_tag

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

Obtém a tag de autenticação da cifra com comprimento especificado como size. Se omitido, uma tag com comprimento da metade do tamanho do bloco será retornada. O tamanho não pode exceder o tamanho do bloco.

Esta função só pode ser chamada após a criptografia ser concluída.

cipher:set_aead_tag

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

Define a tag de autenticação da cifra com tag.

Esta função só pode ser chamada antes que a descriptografia comece.

cipher:final

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

Retorna o texto criptografado ou descriptografado em string binária bruta, opcionalmente aceita uma string para criptografar ou descriptografar.

-- criptografia
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))
-- produz "vGJRHufPYrbbnYYC0+BnwQ=="
-- OU:
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))
-- produz "vGJRHufPYrbbnYYC0+BnwQ=="

-- descriptografia
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)
-- produz "🦢"
-- OU:
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)
-- produz "🦢"

Nota: em algumas implementações como libsodium ou Java, cifras AEAD anexam a tag (ou MAC) no final do texto cifrado criptografado. Nesses casos, os usuários precisarão cortar manualmente a tag com o tamanho correto (geralmente 16 bytes) e passar o texto cifrado e a tag separadamente.

Consulte examples/aes-gcm-aead.lua para um exemplo de uso de modos AEAD com autenticação.

cipher:derive

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

Deriva uma chave e IV (se aplicável) a partir do material dado que pode ser usado na cifra atual. Esta função é útil principalmente para trabalhar com chaves que já foram derivadas do mesmo algoritmo. Aplicativos mais novos devem usar um algoritmo mais moderno, como PBKDF2 fornecido por kdf.derive.

count é a contagem de iterações a serem realizadas. Se omitido, é definido como 1. Observe que versões recentes do ferramenta CLI openssl enc usam automaticamente PBKDF2 se -iter for definido como maior que 1, enquanto esta função não o fará. Para usar PBKDF2 para derivar uma chave, consulte kdf.derive.

md é o nome do digest de mensagem a ser usado, pode assumir um dos valores md2, md5, sha ou sha1. Se omitido, o padrão é 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 interagir com digestão de mensagem (EVP_MD_CTX).

digest.new

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

Cria uma instância de digestão. digest_name é uma string de nome de algoritmo de digestão que não diferencia maiúsculas de minúsculas. Para ver uma lista de algoritmos de digestão implementados, use openssl.list_digest_algorithms ou openssl list -digest-algorithms.

Se digest_name for omitido, o padrão é sha1. Especificamente, o nome do digest "null" representa um digest de mensagem "nulo" que não faz nada: ou seja, o hash que retorna tem comprimento zero.

A partir do OpenSSL 3.0, esta função aceita um parâmetro opcional properties para selecionar explicitamente o provedor para buscar algoritmos.

digest.istype

sintaxe: ok = digest.istype(table)

Retorna true se a tabela for uma instância de digest. Retorna false caso contrário.

digest:get_provider_name

sintaxe: name = digest:get_provider_name()

Retorna o nome do provedor de digest.

Esta função está disponível no OpenSSL 3.0 ou posterior.

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

Consulta parâmetros settable ou gettable e define ou obtém parâmetros. Consulte Generic EVP parameter getter/setter.

digest:update

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

Atualiza o digest com uma ou mais strings.

digest:final

sintaxe: *str, err = digest:final(partial?