Zum Inhalt

openssl

# *openssl*: FFI-basierte OpenSSL-Bindung für nginx-module-lua

## Installation

Wenn Sie das RPM-Repository-Abonnement noch nicht eingerichtet haben, [melden Sie sich an](https://www.getpagespeed.com/repo-subscribe). Dann können Sie mit den folgenden Schritten fortfahren.

### CentOS/RHEL 7 oder 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

Um diese Lua-Bibliothek mit NGINX zu verwenden, stellen Sie sicher, dass nginx-module-lua installiert ist.

Dieses Dokument beschreibt lua-resty-openssl v1.8.0, veröffentlicht am 10. Juni 2026.

FFI-basierte OpenSSL-Bindung für LuaJIT, unterstützt OpenSSL 3, 4 und die 1.1.1-Serie.

Die Unterstützung für OpenSSL 1.1.0, 1.0.2 und BoringSSL wurde eingestellt, ist jedoch weiterhin im 0.x-Zweig verfügbar.

Build-Status luarocks opm

Beschreibung

lua-resty-openssl ist eine FFI-basierte OpenSSL-Bindungsbibliothek, die derzeit OpenSSL 3.x, 4.x und die 1.1.1-Serie unterstützt.

Zusammenfassung

Diese Bibliothek ist stark inspiriert von luaossl und verwendet eine Namenskonvention, die näher am ursprünglichen OpenSSL-API liegt. Zum Beispiel wird eine Funktion namens X509_set_pubkey in der OpenSSL C-API als resty.openssl.x509:set_pubkey exponiert. CamelCases werden durch underscore_cases ersetzt, zum Beispiel wird X509_set_serialNumber zu resty.openssl.x509:set_serial_number. Ein weiterer Unterschied zu luaossl besteht darin, dass Fehler niemals mit error() ausgelöst werden, sondern stattdessen als letzter Parameter zurückgegeben werden.

Jede von new() zurückgegebene Lua-Tabelle enthält ein cdata-Objekt ctx. Benutzer sollen ffi.gc nicht manuell setzen oder den entsprechenden Destruktor der ctx-Struktur (wie *_free-Funktionen) aufrufen.

resty.openssl

Dieses Metamodul bietet eine Versionssanitätsprüfung gegen die verknüpfte OpenSSL-Bibliothek.

openssl.load_library

syntax: name, err = openssl.load_library()

Versucht, OpenSSL-Shared-Bibliotheken zu laden. Diese Funktion versucht eine Reihe bekannter Bibliotheksnamenmuster und gibt den Namen der crypto-Bibliothek zurück, wenn sie erfolgreich geladen wurde, oder einen Fehler, falls vorhanden.

Wenn Sie sich im resty CLI oder OpenResty mit aktiviertem SSL befinden, ist es nicht notwendig, diese Funktion aufzurufen.

openssl.load_modules

syntax: openssl.load_modules()

Lädt alle verfügbaren Untermodule in das aktuelle Modul:

  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"),

Ab OpenSSL 3.0 sind auch provider, mac und ctx verfügbar.

openssl.luaossl_compat

syntax: openssl.luaossl_compat()

Bietet eine luaossl-ähnliche API, die die Namensgebung im camelCase verwendet; Benutzer können eine Drop-in-Ersetzung erwarten.

Zum Beispiel wird pkey:get_parameters auf pkey:getParameters abgebildet.

Beachten Sie, dass nicht alle luaossl-APIs implementiert wurden, bitte überprüfen Sie die README für die Quelle der Wahrheit.

openssl.get_fips_mode

syntax: enabled = openssl.get_fips_mode()

Gibt einen booleschen Wert zurück, der angibt, ob der FIPS-Modus aktiviert ist.

openssl.set_fips_mode

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

Schaltet den FIPS-Modus ein oder aus.

lua-resty-openssl unterstützt folgende Modi:

OpenSSL 1.0.2-Serie mit FIPS 2.0-Modul

Kompilieren Sie das Modul gemäß Sicherheitsrichtlinie.

OpenSSL 3 FIPS-Anbieter

Siehe https://wiki.openssl.org/index.php/OpenSSL_3.0 Abschnitt 7. Kompilieren Sie den Anbieter gemäß der Anleitung und installieren Sie die fipsmodule.cnf, die mit dem Hash des FIPS-Anbieters fips.so übereinstimmt.

Ab OpenSSL 3.0 schaltet diese Funktion auch die Standard-Eigenschaften für EVP-Funktionen ein und aus. Wenn sie aktiviert ist, werden alle Anwendungen, die die EVP_* API verwenden, auf FIPS-konforme Implementierungen umgeleitet und haben keinen Zugriff auf nicht-FIPS-konforme Algorithmen.

Das Aufrufen dieser Funktion entspricht dem Laden des fips-Anbieters und dem Aufrufen von openssl.set_default_properties("fips=yes").

Wenn der FIPS-Anbieter geladen ist, aber die Standard-Eigenschaften nicht gesetzt sind, verwenden Sie Folgendes, um die FIPS-Implementierung explizit abzurufen. 

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()) -- gibt "default" aus
local c = assert(cipher.new("aes256", "fips=yes"))
print(c:get_provider_name()) -- gibt "fips" aus

openssl.get_fips_version_text

syntax: text, err = openssl.get_fips_version_text()

Gibt den Versionstext des FIPS-Moduls zurück, verfügbar in OpenSSL 3.0 oder später.

openssl.set_default_properties

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

Setzt die Standard-Eigenschaften für alle zukünftigen EVP-Algorithmusabrufe, sowohl implizit als auch explizit. Siehe "ALGORITHM FETCHING" in crypto(7) für Informationen über implizite und explizite Abrufe.

openssl.list_cipher_algorithms

syntax: ret = openssl.list_cipher_algorithms(hide_provider?)

Gibt verfügbare Verschlüsselungsalgorithmen in einem Array zurück. Setzen Sie hide_provider auf true, um den Anbieternamen aus dem Ergebnis auszublenden.

openssl.list_digest_algorithms

syntax: ret = openssl.list_digest_algorithms(hide_provider?)

Gibt verfügbare Hash-Algorithmen in einem Array zurück. Setzen Sie hide_provider auf true, um den Anbieternamen aus dem Ergebnis auszublenden.

openssl.list_mac_algorithms

syntax: ret = openssl.list_mac_algorithms(hide_provider?)

Gibt verfügbare MAC-Algorithmen in einem Array zurück. Setzen Sie hide_provider auf true, um den Anbieternamen aus dem Ergebnis auszublenden.

openssl.list_kdf_algorithms

syntax: ret = openssl.list_kdf_algorithms(hide_provider?)

Gibt verfügbare KDF-Algorithmen in einem Array zurück. Setzen Sie hide_provider auf true, um den Anbieternamen aus dem Ergebnis auszublenden.

openssl.list_ssl_ciphers

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

Gibt die Standard-SSL-Verschlüsselungen als String zurück. cipher_list (vor TLSv1.3) und ciphersuites (TLSv1.3) können verwendet werden, um die Verschlüsselungseinstellungen zu erweitern, die protocol entsprechen. OpenSSL 4.x lehnt "SSLv3" ab, da die Unterstützung für SSLv3 entfernt wurde.

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

Ein Modul zur Bereitstellung von OSSL_LIB_CTX-Kontextwechseln.

OSSL_LIB_CTX ist ein interner OpenSSL-Bibliothekskontexttyp. Anwendungen können ihren eigenen zuweisen, können jedoch auch NULL verwenden, um einen Standardkontext mit Funktionen zu verwenden, die ein OSSL_LIB_CTX-Argument akzeptieren.

Siehe OSSL_LIB_CTX.3 für tiefere Informationen.

Der Kontext ist derzeit für folgende Module wirksam:

Dieses Modul ist in OpenSSL 3.0 oder später verfügbar.

ctx.new

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

Erstellt einen neuen Kontext und verwendet ihn als Standardkontext für dieses Modul. Wenn request_context_only auf true gesetzt ist, wird der Kontext nur im Kontext der aktuellen Anfrage verwendet. conf_file kann optional eine OpenSSL-Konfigurationsdatei angeben, um den Kontext zu erstellen.

Der erstellte Kontext wird automatisch mit seinem gegebenen Lebenszyklus freigegeben.

-- initialisiere eine AES-Verschlüsselungsinstanz nur aus der gegebenen Anbieterimplementierung
-- für die aktuelle Anfrage, ohne andere Teile des Codes
-- oder zukünftige Anfragen von der Verwendung des gleichen Algorithmus zu stören.
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), "🦢"))
-- muss den Anbieter und den ctx nicht freigeben, sie werden automatisch GC'ed

ctx.free

syntax: ctx.free(request_context_only?)

Gibt den Kontext frei, der zuvor von ctx.new erstellt wurde.

resty.openssl.err

Ein Modul zur Bereitstellung von Fehlermeldungen.

err.format_error

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

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

Gibt die letzte Fehlermeldung aus dem letzten Fehlercode zurück. Fehler werden formatiert als:

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

Für OpenSSL-Versionen vor 3.0 werden Fehler formatiert als:

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

Wenn all_errors auf true gesetzt ist, werden alle Fehler, nicht nur der letzte, in einem einzigen String zurückgegeben. Alle Fehler, die von dieser Bibliothek intern ausgelöst werden, werfen nur den letzten Fehler.

Zum Beispiel:

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

syntax: code = err.get_last_error_code()

Gibt den letzten Fehlercode zurück.

err.get_lib_error_string

syntax: lib_error_message = err.get_lib_error_string(code?)

Gibt den Bibliotheksnamen des letzten Fehlercodes als String zurück. Wenn code gesetzt ist, wird der Bibliotheksname zurückgegeben, der dem angegebenen Fehlercode entspricht.

err.get_reason_error_string

syntax: reason_error_message = err.get_reason_error_string(code?)

Gibt den Grund des letzten Fehlercodes als String zurück. Wenn code gesetzt ist, wird der Grund zurückgegeben, der dem angegebenen Fehlercode entspricht.

resty.openssl.version

Ein Modul zur Bereitstellung von Versionsinformationen.

resty.openssl.provider

Modul zur Interaktion mit Anbietern. Dieses Modul funktioniert nur mit OpenSSL 3.0 oder später.

provider.load

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

Lädt den Anbieter mit name. Wenn try auf true gesetzt ist, wird OpenSSL die Fallback-Anbieter nicht deaktivieren, wenn der Anbieter nicht geladen und initialisiert werden kann. Wenn der Anbieter jedoch erfolgreich geladen wird, werden die Fallback-Anbieter deaktiviert.

Standardmäßig lädt diese Funktion den Anbieter in den Standardkontext, was bedeutet, dass er auch andere Anwendungen im selben Prozess beeinflusst, die den Standardkontext verwenden. Wenn ein solches Verhalten nicht gewünscht ist, sollten Sie ctx verwenden, um den Anbieter nur in einem begrenzten Umfang zu laden.

provider.istype

syntax: ok = pkey.provider(table)

Gibt true zurück, wenn die Tabelle eine Instanz von provider ist. Gibt andernfalls false zurück.

provider.is_available

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

Überprüft, ob ein benannter Anbieter verfügbar ist.

provider.set_default_search_path

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

Gibt den Standard-Suchpfad an, der verwendet werden soll, um nach Anbietern zu suchen.

provider:unload

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

Entlädt einen Anbieter, der zuvor von provider.load geladen wurde.

provider:self_test

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

Führt die Selbsttests eines Anbieters auf Anfrage durch. Wenn die Selbsttests fehlschlagen, wird der Anbieter keine weiteren Dienste und Algorithmen bereitstellen.

provider:get_params

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

Gibt einen oder mehrere Anbieterparameterwerte zurück.

local pro = require "resty.openssl.provider"

local p = pro.load("default")

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

local result = assert(p:get_params("name", "version", "buildinfo", "status"))
print(require("cjson").encode(result))
-- gibt Metadaten des Anbieters aus; Version und Buildinfo variieren je nach OpenSSL-Version

resty.openssl.pkey

Modul zur Interaktion mit privaten und öffentlichen Schlüsseln (EVP_PKEY).

Jeder Schlüsseltyp unterstützt möglicherweise nur einen Teil der Operationen:

Schlüsseltype Vorhandenen Schlüssel laden Schlüsselerzeugung Verschlüsseln/Entschlüsseln Signieren/Überprüfen Schlüsselaustausch
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)

Direkte Unterstützung für Verschlüsselung und Entschlüsselung für EC und ECX existiert nicht, aber Prozesse wie ECIES sind möglich mit pkey:derive, kdf und cipher.

pkey.new

Vorhandenen Schlüssel laden

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

Unterstützt das Laden eines privaten oder öffentlichen Schlüssels im PEM-, DER- oder JWK-Format, das als erstes Argument string übergeben wird.

Der zweite Parameter opts akzeptiert eine optionale Tabelle, um das Verhalten beim Laden des Schlüssels einzuschränken.

  • opts.format: explizit auf "PEM", "DER", "JWK" setzen, um ein bestimmtes Format zu laden, oder auf "*" setzen, um automatisch zu erkennen
  • opts.type: explizit auf "pr" für privaten Schlüssel, "pu" für öffentlichen Schlüssel setzen; auf "*" setzen, um automatisch zu erkennen

Beim Laden eines PEM-codierten RSA-Schlüssels kann es sich entweder um einen PKCS#8-codierten SubjectPublicKeyInfo/PrivateKeyInfo oder um einen PKCS#1-codierten RSAPublicKey/RSAPrivateKey handeln.

Beim Laden eines verschlüsselten PEM-codierten Schlüssels kann das passphrase zum Entschlüsseln entweder in opts.passphrase oder opts.passphrase_cb festgelegt werden:

pkey.new(pem_or_der_text, {
  format = "*", -- Auswahl zwischen "PEM", "DER", "JWK" oder "*" zur automatischen Erkennung
  type = "*", -- Auswahl zwischen "pr" für privaten Schlüssel, "pu" für öffentlichen Schlüssel und "*" zur automatischen Erkennung
  passphrase = "secret password", -- das PEM-Verschlüsselungspasswort
  passphrase_cb = function()
    return "secret password"
  end, -- die Rückruffunktion für das PEM-Verschlüsselungspasswort
}

Beim Laden von JWK gibt es einige Einschränkungen: - Stellen Sie sicher, dass der kodierte JSON-Text übergeben wird, er muss base64-decodiert sein. - Die Einschränkung von opts.type für JWK-Schlüssel erfordert OpenSSL 3.0 oder später und lua-resty-openssl 1.6.0 oder später. Bei OpenSSL 1.1.1 oder älteren Versionen von lua-resty-openssl entscheiden die Parameter im bereitgestellten JSON, ob ein privater oder öffentlicher Schlüssel geladen wird; die Angabe von type führt zu einem Fehler; auch der öffentliche Schlüsselteils für OKP-Schlüssel (der x-Parameter) wird nicht beachtet und aus dem privaten Schlüsselteils (dem d-Parameter) abgeleitet, wenn er angegeben ist. - Unterstützt werden nur die Schlüsseltypen RSA, P-256, P-384 und P-512 EC, Ed25519, X25519, Ed448 und X448 OKP-Schlüssel. - Signaturen und Überprüfungen müssen die Option ecdsa_use_raw verwenden, um mit JWS-Standards für EC-Schlüssel zu arbeiten. Siehe pkey:sign und pkey.verify für Details. - Wenn Sie außerhalb von OpenResty arbeiten, müssen Sie eine JSON-Bibliothek (cjson oder dkjson) und basexx installieren.

Schlüsselerzeugung

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

Generiert einen neuen öffentlichen oder privaten Schlüssel.

Um einen RSA-Schlüssel zu generieren, kann die config-Tabelle die Felder bits und exp enthalten, um die Schlüsselerzeugung zu steuern. Wenn config ausgegeben wird, generiert diese Funktion einen 2048-Bit-RSA-Schlüssel mit einem exponent von 65537, was äquivalent ist zu:

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

Um einen EC- oder DH-Schlüssel zu generieren, siehe pkey.paramgen für mögliche Werte der config-Tabelle. Zum Beispiel:

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

Es ist auch möglich, PEM-codierte EC- oder DH-Parameter an config.param zur Schlüsselerzeugung zu übergeben:

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

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

Es ist auch möglich, rohe pkeyopt-Steuerzeichenfolgen in der config-Tabelle zu übergeben, wie sie im CLI-Programm genpkey verwendet werden. Siehe openssl-genpkey(1) für eine Liste von Optionen.

Zum Beispiel:

pkey.new({
  type = 'RSA',
  bits = 2048,
  exp = 65537,
})
-- ist dasselbe wie
pkey.new({
  type = 'RSA',
  exp = 65537,
  "rsa_keygen_bits:4096",
})

Schlüsselzusammensetzung

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

Setzt einen öffentlichen oder privaten Schlüssel unter Verwendung vorhandener Parameter zusammen. Um die Liste der Parameter für jeden Schlüssel zu sehen, siehe pkey:set_parameters.

Nur type und params sollten in der config-Tabelle existieren, alle anderen Schlüssel werden ignoriert.

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

syntax: ok = pkey.istype(table)

Gibt true zurück, wenn die Tabelle eine Instanz von pkey ist. Gibt andernfalls false zurück.

pkey.paramgen

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

Generiert Parameter für EC- oder DH-Schlüssel und gibt sie als PEM-codierten Text aus.

Für EC-Schlüssel:

Parameter Beschreibung
type "EC"
curve EC-Kurven. Wenn weggelassen, wird standardmäßig "prime192v1" verwendet. Um eine Liste der unterstützten EC-Kurven zu sehen, verwenden Sie openssl ecparam -list_curves.

Für DH-Schlüssel:

Parameter Beschreibung
type "DH"
bits Generiert einen neuen DH-Parameter mit bits langen Primzahlen. Wenn weggelassen, wird standardmäßig 2048 verwendet. Ab OpenSSL 3.0 ist nur eine Bitlänge von 2048 erlaubt.
group Verwendet vordefinierte Gruppen anstelle von neuen. bit wird ignoriert, wenn group gesetzt ist.

Mögliche Werte für group sind: - 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',
})

Es ist auch möglich, rohe pkeyopt-Steuerzeichenfolgen in der config-Tabelle zu übergeben, wie sie im CLI-Programm genpkey verwendet werden. Siehe openssl-genpkey(1) für eine Liste von Optionen.

pkey:get_provider_name

syntax: name = pkey:get_provider_name()

Gibt den Anbieternamen von pkey zurück.

Diese Funktion ist in OpenSSL 3.0 oder später verfügbar.

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

Abfragen von setzbaren oder abrufbaren Parametern und Setzen oder Abrufen von Parametern. Siehe Generic EVP parameter getter/setter.

pkey:get_parameters

syntax: parameters, err = pk:get_parameters()

Gibt eine Tabelle zurück, die die parameters der pkey-Instanz enthält.

pkey:set_parameters

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

Setzt die Parameter des pkey aus einer Tabelle params. Wenn der Parameter nicht in der Tabelle params gesetzt ist, bleibt er in der pkey-Instanz unberührt.

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

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

local ok, err = pk:set_parameters(parameters)

Parameter für RSA-Schlüssel:

Parameter Beschreibung Typ
n Modulus, der sowohl für den öffentlichen als auch für den privaten Schlüssel gilt bn
e Öffentlicher Exponent bn
d Privater Exponent bn
p Erster Faktor von n bn
q Zweiter Faktor von n bn
dmp1 d mod (p - 1), Exponent1 bn
dmq1 d mod (q - 1), Exponent2 bn
iqmp (InverseQ)(q) = 1 mod p, Koeffizient bn

Parameter für EC-Schlüssel:

Parameter Beschreibung Typ
private Privater Schlüssel bn
public Öffentlicher Schlüssel bn
x x-Koordinate des öffentlichen Schlüssels bn
y y-Koordinate des öffentlichen Schlüssels bn
group Die benannte Kurvengruppe [NID] als Zahl, wenn sie in set_parameters() übergeben wird, ist es auch möglich, die textuelle Darstellung zu verwenden. Dies unterscheidet sich von luaossl, wo eine EC_GROUP-Instanz zurückgegeben wird.

Es ist nicht möglich, x, y gleichzeitig mit public zu setzen, da x und y im Grunde eine andere Darstellung von public sind. Derzeit ist es auch nur möglich, x und y gleichzeitig zu setzen.

Parameter für DH-Schlüssel:

Parameter Beschreibung Typ
private Privater Schlüssel bn
public Öffentlicher Schlüssel bn
p Primärmodulus bn
q Referenzposition bn
g Basisgenerator bn

Parameter für Curve25519- und Curve448-Schlüssel:

Parameter Beschreibung Typ
private Rohprivater Schlüssel, dargestellt als Bytes string
public Rohöffentlicher Schlüssel, dargestellt als Bytes string

pkey:is_private

syntax: ok = pk:is_private()

Überprüft, ob pk ein privater Schlüssel ist. Gibt true zurück, wenn es sich um einen privaten Schlüssel handelt, andernfalls false.

pkey:get_key_type

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

Gibt ein ASN1_OBJECT des Schlüssels vom privaten Schlüssel als Tabelle zurück.

Ab lua-resty-openssl 1.6.0 kann ein optionales Argument nid_only auf true gesetzt werden, um nur die numerische NID des Schlüssels zurückzugeben.

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

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

pkey:get_size

syntax: size, err = pk:get_size()

Gibt die maximale geeignete Größe für die Ausgabepuffer für fast alle Operationen zurück, die mit pkey durchgeführt werden können.

Für RSA-Schlüssel ist dies die Größe des Modulus. Für EC-, Ed25519- und Ed448-Schlüssel ist dies die Größe des privaten Schlüssels. Für DH-Schlüssel ist dies die Größe des Primärmodulus.

pkey:get_default_digest_type

syntax: obj, err = pk:get_default_digest_type()

Gibt ein ASN1_OBJECT des Schlüssels vom privaten Schlüssel als Tabelle zurück. Ein zusätzliches Feld mandatory wird ebenfalls in der Tabelle zurückgegeben; wenn mandatory true ist, können keine anderen Hashes verwendet werden.

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

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

pkey:sign

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

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

Führt eine Hash-Signierung mit dem privaten Schlüssel durch, der in der pkey-Instanz definiert ist. Der erste Parameter muss eine resty.openssl.digest-Instanz oder ein String sein. Gibt den signierten Text und einen Fehler zurück, falls vorhanden.

Wenn eine digest-Instanz als erster Parameter übergeben wird, sollte sie nicht final() aufgerufen haben; Benutzer sollten nur update() verwenden. Dieser Modus unterstützt nur RSA- und EC-Schlüssel.

Wenn ein String als erster Parameter übergeben wird, gibt der Parameter md_alg den Namen an, der beim Signieren verwendet werden soll. Wenn md_alg undefiniert ist, führt diese Funktion standardmäßig SHA256 für RSA- und EC-Schlüssel durch. Für Ed25519- oder Ed448-Schlüssel führt diese Funktion eine PureEdDSA-Signatur durch, es sollte kein Nachrichten-Hash angegeben werden und wird nicht verwendet.

Für RSA-Schlüssel ist es auch möglich, das padding-Schema mit folgenden Optionen anzugeben:

  pkey.PADDINGS = {
    RSA_PKCS1_PADDING       = 1,
    RSA_SSLV23_PADDING      = 2,
    RSA_NO_PADDING          = 3,
    RSA_PKCS1_OAEP_PADDING  = 4,
    RSA_X931_PADDING        = 5, -- nur signieren
    RSA_PKCS1_PSS_PADDING   = 6, -- nur signieren und überprüfen
  }

Wenn padding RSA_PKCS1_PSS_PADDING ist, ist es möglich, die PSS-Salzlänge anzugeben, indem opts.pss_saltlen gesetzt wird.

Für EC-Schlüssel führt diese Funktion eine ECDSA-Signatur durch. Beachten Sie, dass OpenSSL keine EC-Digitalsignatur (ECDSA) mit dem veralteten MD5-Hashalgorithmus unterstützt und bei dieser Kombination einen Fehler zurückgibt. Siehe EVP_DigestSign(3) für eine Liste von Algorithmen und zugehörigen öffentlichen Schlüsselalgorithmen. Normalerweise wird die ECDSA-Signatur im ASN.1 DER-Format codiert. Wenn die opts-Tabelle ein Feld ecdsa_use_raw mit einem wahren Wert enthält, wird eine Binärdarstellung mit nur der Verkettung der binären Darstellung pr und ps zurückgegeben. Dies ist beispielsweise nützlich, um die Signatur als JWS zu senden.

opts ist eine Tabelle, die zusätzliche Parameter mit folgenden Optionen akzeptiert:

{
  pss_saltlen, -- Für PSS-Modus gibt diese Option die Salzlänge an.
  mgf1_md, -- Für PSS- und OAEP-Padding wird der MGF1-Hash gesetzt. Wenn der MGF1-Hash im PSS-Modus nicht explizit gesetzt ist, wird der Signier-Hash verwendet.
  oaep_md, -- Der Hash, der für die OAEP-Hashfunktion verwendet wird. Wenn nicht explizit gesetzt, wird SHA1 verwendet.
}

Es ist auch möglich, rohe pkeyopt-Steuerzeichenfolgen zu übergeben, wie sie im pkeyutl-CLI-Programm verwendet werden. Dies ermöglicht es Benutzern, Optionen zu übergeben, die nicht explizit als Parameter unterstützt werden. Siehe openssl-pkeyutl(1) für eine Liste von Optionen.

pk:sign(message, nil, pk.PADDINGS.RSA_PKCS1_OAEP_PADDING, {
  oaep_md = "sha256",
})
-- ist dasselbe wie
pk:sign(message, nil, nil, {
  "rsa_padding_mode:oaep",
  "rsa_oaep_md:sha256",
})
-- im pkeyutl CLI entspricht das obige: `openssl pkeyutl -sign -pkeyopt rsa_padding_mode:oaep -pkeyopt rsa_oaep_md:sha256

Um eine Nachricht zu signieren, ohne einen Nachrichten-Hash durchzuführen, siehe pkey:sign_raw.

pkey:verify

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

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

Überprüft eine Signatur (die der String sein kann, der von pkey:sign zurückgegeben wird). Der zweite Parameter muss eine resty.openssl.digest-Instanz sein, die denselben Hash-Algorithmus verwendet wie bei sign oder ein String. ok gibt true zurück, wenn die Überprüfung erfolgreich ist, und false andernfalls. Beachten Sie, dass bei einem Überprüfungsfehler err nicht gesetzt wird, wenn OpenSSL 1.1.1 oder niedriger verwendet wird.

Wenn digest-Instanzen als zweiter Parameter übergeben werden, sollte sie nicht final() aufgerufen haben; Benutzer sollten nur update() verwenden. Dieser Modus unterstützt nur RSA- und EC-Schlüssel.

Wenn ein String als zweiter Parameter übergeben wird, gibt der Parameter md_alg den Namen an, der beim Überprüfen verwendet werden soll. Wenn md_alg undefiniert ist, führt diese Funktion standardmäßig SHA256 für RSA- und EC-Schlüssel durch. Für Ed25519- oder Ed448-Schlüssel führt diese Funktion eine PureEdDSA-Überprüfung durch, es sollte kein Nachrichten-Hash angegeben werden und wird nicht verwendet.

Wenn der Schlüssel ein RSA-Schlüssel ist, akzeptiert die Funktion ein optionales Argument padding, dessen Werte dieselben sind wie die in pkey:sign. Wenn padding RSA_PKCS1_PSS_PADDING ist, ist es möglich, die PSS-Salzlänge anzugeben, indem opts.pss_saltlen gesetzt wird.

Für EC-Schlüssel führt diese Funktion eine ECDSA-Überprüfung durch. Normalerweise sollte die ECDSA-Signatur im ASN.1 DER-Format codiert sein. Wenn die opts-Tabelle ein Feld ecdsa_use_raw mit einem wahren Wert enthält, behandelt diese Bibliothek signature als Verkettung der binären Darstellung pr und ps. Dies ist beispielsweise nützlich, um die Signatur als JWS zu überprüfen.

opts ist eine Tabelle, die zusätzliche Parameter akzeptiert, deren Werte dieselben sind wie die in pkey:sign.

-- RSA- und EC-Schlüssel
local pk, err = require("resty.openssl.pkey").new()
local digest, err = require("resty.openssl.digest").new("SHA256")
digest:update("dog")
-- FALSCH:
-- digest:final("dog")
local signature, err = pk:sign(digest)
-- verwendet standardmäßig SHA256
local signature, err = pk:sign("dog")
ngx.say(ngx.encode_base64(signature))
-- verwendet SHA256 und PSS-Padding
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)
-- verwendet standardmäßig SHA256
local ok, err = pk:verify(signature, "dog")
-- verwendet SHA256 und PSS-Padding
local ok, err = pk:verify(signature_pss, "dog", "sha256", pk.PADDINGS.RSA_PKCS1_PSS_PADDING)

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

Um eine Nachricht zu überprüfen, ohne einen Nachrichten-Hash durchzuführen, siehe pkey:verify_raw und pkey:verify_recover.

pkey:encrypt

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

Verschlüsselt den Klartext txt mit einer pkey-Instanz, die einen öffentlichen Schlüssel enthalten muss.

Der optionale zweite Parameter padding hat dieselbe Bedeutung wie in pkey:sign. Wenn weggelassen, wird padding standardmäßig auf pkey.PADDINGS.RSA_PKCS1_PADDING gesetzt.

Der dritte optionale Parameter opts hat dieselbe Bedeutung wie in pkey:sign.

pkey:decrypt

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

Entschlüsselt den Chiffretext cipher_txt mit einer pkey-Instanz, die einen privaten Schlüssel enthalten muss.

Der optionale zweite Parameter padding hat dieselbe Bedeutung wie in pkey:sign. Wenn weggelassen, wird padding standardmäßig auf pkey.PADDINGS.RSA_PKCS1_PADDING gesetzt.

Der dritte optionale Parameter opts hat dieselbe Bedeutung wie in 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)
-- gibt 256 aus
local decrypted, err = privkey:decrypt(s)
ngx.say(decrypted)
-- gibt "🦢" aus

pkey:sign_raw

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

Signiert den Chiffretext cipher_txt mit einer pkey-Instanz, die einen privaten Schlüssel enthalten muss.

Der optionale zweite Parameter padding hat dieselbe Bedeutung wie in pkey:sign. Wenn weggelassen, wird padding standardmäßig auf pkey.PADDINGS.RSA_PKCS1_PADDING gesetzt.

Der dritte optionale Parameter opts hat dieselbe Bedeutung wie in pkey:sign.

Diese Funktion kann auch als "private Verschlüsselung" in einigen Implementierungen wie NodeJS oder PHP bezeichnet werden. Beachten Sie, dass diese Funktion trotz des Funktionsnamens nicht sicher genug ist, um als Verschlüsselung betrachtet zu werden. Bei der Entwicklung neuer Anwendungen sollten Benutzer pkey:sign für die Signierung mit Hash oder pkey:encrypt für die Verschlüsselung verwenden.

Siehe examples/raw-sign-and-recover.lua für ein Beispiel.

pkey:verify_raw

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

Überprüft den Chiffretext signature mit der Nachricht data unter Verwendung einer pkey-Instanz, die einen öffentlichen Schlüssel enthalten muss. Es setzt den Nachrichten-Hash auf md_alg, berechnet jedoch den Nachrichten-Hash nicht automatisch; mit anderen Worten, diese Funktion geht davon aus, dass data bereits mit md_alg gehasht wurde.

Wenn md_alg undefiniert ist, führt diese Funktion für RSA- und EC-Schlüssel standardmäßig SHA256 durch. Für Ed25519- oder Ed448-Schlüssel wird kein Standardwert gesetzt.

Der optionale vierte Parameter padding hat dieselbe Bedeutung wie in pkey:sign. Wenn weggelassen, wird padding standardmäßig auf pkey.PADDINGS.RSA_PKCS1_PADDING gesetzt.

Der fünfte optionale Parameter opts hat dieselbe Bedeutung wie in pkey:sign.

Siehe examples/raw-sign-and-recover.lua für ein Beispiel.

pkey:verify_recover

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

Überprüft den Chiffretext signature mit einer pkey-Instanz, die einen öffentlichen Schlüssel enthalten muss, und gibt auch den ursprünglichen Text zurück, der signiert wurde. Dieser Vorgang wird nur von RSA-Schlüsseln unterstützt.

Der optionale zweite Parameter padding hat dieselbe Bedeutung wie in pkey:sign. Wenn weggelassen, wird padding standardmäßig auf pkey.PADDINGS.RSA_PKCS1_PADDING gesetzt.

Der dritte optionale Parameter opts hat dieselbe Bedeutung wie in pkey:sign.

Diese Funktion kann auch als "öffentliche Entschlüsselung" in einigen Implementierungen wie NodeJS oder PHP bezeichnet werden.

Siehe examples/raw-sign-and-recover.lua für ein Beispiel.

pkey:derive

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

Leitet den öffentlichen Schlüsselalgorithmus des gemeinsamen Geheimnisses peer_key ab, das eine pkey-Instanz sein muss.

Siehe examples/x25519-dh.lua für ein Beispiel, wie der Schlüsselaustausch für X25519-Schlüssel mit dem DH-Algorithmus funktioniert.

pkey:tostring

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

Gibt den privaten oder öffentlichen Schlüssel der pkey-Instanz im PEM-formatierten Text aus. Das erste Argument muss eine Wahl zwischen public, PublicKey, private, PrivateKey oder nil sein.

Das zweite Argument fmt kann PEM, DER, JWK oder nil sein. Wenn beide Argumente weggelassen werden, gibt diese Funktion die PEM-Darstellung des öffentlichen Schlüssels zurück.

Wenn is_pkcs1 auf true gesetzt ist, wird die Ausgabe mit einer PKCS#1 RSAPublicKey-Struktur codiert; die PKCS#1-Codierung wird derzeit für RSA-Schlüssel im PEM-Format unterstützt. Das Schreiben eines PKCS#1-codierten RSA-Schlüssels wird derzeit nicht unterstützt, wenn OpenSSL 3.0 oder später verwendet wird.

pkey:to_PEM

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

Entspricht pkey:tostring(private_or_public, "PEM", is_pkcs1).

resty.openssl.bn

Modul zur Exposition der BIGNUM-Struktur. Beachten Sie, dass bignum eine große Ganzzahl ist, keine Fließkommaoperationen (wie Quadratwurzel) unterstützt werden.

bn.new

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

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

Erstellt eine bn-Instanz. Das erste Argument kann sein:

  • nil, um eine leere bn-Instanz zu erstellen.
  • Eine Lua-Zahl, um die bn-Instanz zu initialisieren.
  • Eine Zeichenfolge, um die bn-Instanz zu initialisieren. Das zweite Argument base gibt die Basis der Zeichenfolge an und kann Werte annehmen, die mit der Ruby OpenSSL.BN-API kompatibel sind:
  • 10 oder weggelassen, für dezimale Zeichenfolgen ("23333")
  • 16, für hexadezimal codierte Zeichenfolgen ("5b25")
  • 2, für binäre Zeichenfolgen ("\x5b\x25")
  • 0, für MPI-formatierte Zeichenfolgen ("\x00\x00\x00\x02\x5b\x25")

MPI ist ein Format, das die Länge der Zahl in Bytes als 4-Byte-big-endian-Zahl darstellt, und die Zahl selbst im big-endian-Format, wobei das bedeutendste Bit eine negative Zahl signalisiert (die Darstellung von Zahlen mit dem gesetzten MSB wird mit einem Nullbyte vorangestellt).

bn.dup

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

Dupliziert ein BIGNUM*, um eine neue bn-Instanz zu erstellen.

bn.istype

syntax: ok = bn.istype(table)

Gibt true zurück, wenn die Tabelle eine Instanz von bn ist. Gibt andernfalls false zurück.

bn.set

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

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

Verwendet die vorhandene bn-Instanz erneut und setzt ihren Wert mit der angegebenen Zahl oder Zeichenfolge zurück. Siehe bn.new für die unterstützten Argumenttypen.

bn.from_binary, bn:to_binary

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

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

Erstellt eine bn-Instanz aus einer binären Zeichenfolge.

Exportiert den BIGNUM-Wert in einer binären Zeichenfolge.

bn:to_binary akzeptiert ein optionales Zahlenargument padto, das verwendet werden kann, um führende Nullen auf die Ausgabe auf eine bestimmte Länge zu polstern.

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

bn.from_mpi, bn:to_mpi

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

syntax: bin, err = bn:to_mpi()

Erstellt eine bn-Instanz aus einer MPI-formatierte binären Zeichenfolge.

Exportiert den BIGNUM-Wert in einer MPI-formatierte binären Zeichenfolge.

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))
-- gibt "000000025b25" aus

bn.from_hex, bn:to_hex

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

syntax: hex, err = bn:to_hex()

Erstellt eine bn-Instanz aus einer hexadezimal codierten Zeichenfolge. Beachten Sie, dass das führende 0x nicht enthalten sein sollte. Ein führendes -, das das Vorzeichen angibt, kann enthalten sein.

Exportiert die bn-Instanz in eine hexadezimal codierte Zeichenfolge.

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

bn.from_dec, bn:to_dec

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

syntax: dec, err = bn:to_dec()

Erstellt eine bn-Instanz aus einer dezimalen Zeichenfolge. Ein führendes -, das das Vorzeichen angibt, kann enthalten sein.

Exportiert die bn-Instanz in eine dezimale Zeichenfolge.

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

bn:to_number

syntax: n, err = bn:to_number()

syntax: n, err = bn:tonumber()

Exportiert die niedrigsten 32 Bit oder 64 Bit (basierend auf dem ABI) der bn-Instanz in eine Zahl. Dies ist nützlich, wenn Benutzer bitweise Operationen durchführen möchten.

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

bn.generate_prime

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

Generiert eine pseudo-zufällige Primzahl mit der Bitlänge bits.

Wenn safe true ist, wird es eine sichere Primzahl sein (d.h. eine Primzahl p, sodass (p-1)/2 ebenfalls prim ist).

Der PRNG muss vor dem Aufruf von BN_generate_prime_ex() initialisiert werden. Die Wahrscheinlichkeit eines Fehlers bei der Primzahlgenerierung ist vernachlässigbar.

bn:__metamethods

Verschiedene mathematische Operationen können durchgeführt werden, als ob es sich um eine Zahl handelt.

local bn = require("resty.openssl.bn")
local a = bn.new(123456)
local b = bn.new(222)
 -- die folgenden geben eine bn zurück
local r
r = -a
r = a + b
r = a - b
r = a * b
r = a / b -- gleichbedeutend mit bn:idiv, gibt ganzzahlige Division zurück
r = a % b
-- alle Operationen können zwischen Zahlen und Bignum durchgeführt werden
r = a + 222
r = 222 + a
-- die folgenden geben einen booleschen Wert zurück
local bool
bool = a < b
bool = a >= b
-- Vergleiche zwischen Zahlen funktionieren nicht
-- FALSCH: bool = a < 222

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

syntax: r = a:op(b)

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

Führt mathematische Operationen op durch.

  • add: addieren
  • sub: subtrahieren
  • mul: multiplizieren
  • div, idiv: ganzzahlige Division (Division mit Abrundung auf die nächste ganze Zahl)
  • exp, pow: die b-te Potenz von a, diese Funktion ist schneller als wiederholtes a * a * ....
  • mod: modulo
  • gcd: den größten gemeinsamen Teiler von a und b.

Beachten Sie, dass add, sub, mul, div, mod auch mit den Operatoren +, -, *, /, % verfügbar sind. Siehe obiger Abschnitt für Beispiele.

local bn = require("resty.openssl.bn")
local a = bn.new(123456)
local b = bn.new(9876)
local r
-- die folgenden sind gleich
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

syntax: r = a:sqr()

syntax: r = bn.sqr(a)

Berechnet die 2-te Potenz von a. Diese Funktion ist schneller als r = a * a.

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

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

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

Führt modulo-mathematische Operationen op durch.

  • mod_add: addiert a zu b modulo m
  • mod_sub: subtrahiert b von a modulo m
  • mod_mul: multipliziert a mit b und findet den nicht-negativen Rest bezüglich des Modulus m
  • mod_exp, mod_pow: berechnet a zur b-ten Potenz modulo m (r=a^b % m). Diese Funktion benötigt weniger Zeit und Speicherplatz als exp. Rufen Sie diese Funktion nicht auf, wenn m gerade ist und einer der Parameter das BN_FLG_CONSTTIME-Flag gesetzt hat.
local bn = require("resty.openssl.bn")
local a = bn.new(123456)
local b = bn.new(9876)
local r
-- die folgenden sind gleich
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

syntax: r = a:mod_sqr(m)

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

Nimmt das Quadrat von a modulo m.

bn:lshift, bn:rshift

syntax: r = bn:lshift(bit)

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

syntax: r = bn:rshift(bit)

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

Bitverschiebung a um bit Bits.

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

syntax: ok = bn:is_zero()

syntax: ok = bn:is_one()

syntax: ok = bn:is_odd()

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

Überprüft, ob bn 0, 1 und eine ungerade Zahl oder eine Zahl n ist.

bn:is_prime

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

Überprüft, ob bn eine Primzahl ist. Gibt true zurück, wenn es prim ist, mit einer Fehlerwahrscheinlichkeit von weniger als 0.25^nchecks und einem Fehler, falls vorhanden. Wenn weggelassen, wird nchecks auf 0 gesetzt, was bedeutet, dass die Anzahl der Iterationen basierend auf der Größe der Zahl ausgewählt wird.

Diese Funktion führt einen Miller-Rabin-probabilistischen Primzahltest mit nchecks-Iterationen durch. Wenn nchecks == BN_prime_checks (0) ist, wird eine Anzahl von Iterationen verwendet, die eine falsch-positive Rate von höchstens 2^-64 für zufällige Eingaben ergibt. Die Fehlerquote hängt von der Größe der Primzahl ab und sinkt für größere Primzahlen. Die Rate beträgt 2^-80 ab 308 Bit, 2^-112 bei 852 Bit, 2^-128 bei 1080 Bit, 2^-192 bei 3747 Bit und 2^-256 bei 6394 Bit.

Wenn die Quelle der Primzahl nicht zufällig oder nicht vertrauenswürdig ist, müssen die Anzahl der Überprüfungen viel höher sein, um dasselbe Maß an Sicherheit zu erreichen: Sie sollte der Hälfte des angestrebten Sicherheitsniveaus in Bits entsprechen (auf die nächste ganze Zahl aufgerundet, falls erforderlich). Um beispielsweise das 128-Bit-Sicherheitsniveau zu erreichen, sollte nchecks auf 64 gesetzt werden.

Siehe auch BN_is_prime(3).

resty.openssl.cipher

Modul zur Interaktion mit symmetrischer Kryptografie (EVP_CIPHER).

cipher.new

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

Erstellt eine Verschlüsselungsinstanz. cipher_name ist eine nicht groß-/kleinschreibungsempfindliche Zeichenfolge des Namens des Verschlüsselungsalgorithmus. Um eine Liste der implementierten Verschlüsselungsalgorithmen anzuzeigen, verwenden Sie openssl.list_cipher_algorithms oder openssl list -cipher-algorithms.

Ab OpenSSL 3.0 akzeptiert diese Funktion einen optionalen properties-Parameter, um explizit den Anbieter auszuwählen, um Algorithmen abzurufen.

cipher.istype

syntax: ok = cipher.istype(table)

Gibt true zurück, wenn die Tabelle eine Instanz von cipher ist. Gibt andernfalls false zurück.

cipher.set_buffer_size

syntax: ok = cipher.set_buffer_size(sz)

Ändert die interne Puffergröße, die von allen Verschlüsselungsinstanzen verwendet wird. Die Standardpuffergröße beträgt 1024 Bytes.

Wenn Sie erwarten, dass Sie Eingabetexte größer als 1024 Bytes auf einmal an update(), encrypt() oder decrypt() übergeben, verbessert das Setzen des Puffers auf eine Größe, die größer als die erwartete Eingabgröße ist, die Leistung, indem mehr Code JIT-fähig gemacht wird.

Vermeiden Sie es, diese Funktion im Hotpath aufzurufen, da dies den Puffer jedes Mal neu zuweist, wenn sie aufgerufen wird.

cipher:get_provider_name

syntax: name = cipher:get_provider_name()

Gibt den Anbieternamen von cipher zurück.

Diese Funktion ist in OpenSSL 3.0 oder später verfügbar.

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

Abfragen von setzbaren oder abrufbaren Parametern und Setzen oder Abrufen von Parametern. Siehe Generic EVP parameter getter/setter.

cipher:encrypt

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

Verschlüsselt den Text s mit dem Schlüssel key und der IV iv. Gibt den verschlüsselten Text in einer rohen binären Zeichenfolge und einen Fehler zurück, falls vorhanden. Akzeptiert optional einen booleschen Wert no_padding, der dem Cipher mitteilt, ob Padding aktiviert oder deaktiviert werden soll, und standardmäßig auf false (Padding aktivieren) gesetzt ist. Wenn no_padding true ist, muss die Länge von s ein Vielfaches der Blockgröße sein, oder es tritt ein Fehler auf.

Wenn GCM- oder CCM-Modus oder chacha20-poly1305-Cipher verwendet wird, ist es auch möglich, die zusätzlichen authentifizierten Daten (AAD) als fünften Parameter zu übergeben.

Diese Funktion ist eine Abkürzung für cipher:init, cipher:set_aead_aad (falls zutreffend) und dann cipher:final.

cipher:decrypt

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

Entschlüsselt den Text s mit dem Schlüssel key und der IV iv. Gibt den entschlüsselten Text in einer rohen binären Zeichenfolge und einen Fehler zurück, falls vorhanden. Akzeptiert optional einen booleschen Wert no_padding, der dem Cipher mitteilt, ob Padding aktiviert oder deaktiviert werden soll, und standardmäßig auf false (Padding aktivieren) gesetzt ist. Wenn no_padding true ist, muss die Länge von s ein Vielfaches der Blockgröße sein, oder es tritt ein Fehler auf; außerdem wird das Padding im entschlüsselten Text nicht entfernt.

Wenn GCM- oder CCM-Modus oder chacha20-poly1305-Cipher verwendet wird, ist es auch möglich, die zusätzlichen authentifizierten Daten (AAD) als fünften Parameter und das Authentifizierungstag als sechsten Parameter zu übergeben.

Diese Funktion ist eine Abkürzung für cipher:init, cipher:set_aead_aad (falls zutreffend), cipher:set_aead_tag (falls zutreffend) und dann cipher:final.

cipher:init

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

Initialisiert den Cipher mit dem Schlüssel key und der IV iv. Der optionale dritte Parameter ist eine Tabelle, die Folgendes enthält:

{
    is_encrypt = false,
    no_padding = false,
}

Die Aufrufende Funktion ist erforderlich, bevor cipher:update und cipher:final aufgerufen werden, wenn der Cipher nicht bereits initialisiert wurde. Aber nicht cipher:encrypt und cipher:decrypt.

Wenn Sie die cipher-Instanz mehrere Male wiederverwenden möchten, ist es erforderlich, diese Funktion aufzurufen, um den internen Zustand des Ciphers zu löschen. Die Abkürzungsfunktionen cipher:encrypt und cipher:decrypt kümmern sich bereits um die Initialisierung und Rücksetzung.

cipher:update

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

Aktualisiert den Cipher mit einem oder mehreren Strings. Wenn der Cipher mehr Daten hat als die Blockgröße, gibt die Funktion eine nicht leere Zeichenfolge als erstes Argument zurück. Diese Funktion kann in einem Streaming-Modus verwendet werden, um kontinuierliche Datenströme zu verschlüsseln oder zu entschlüsseln.

cipher:update_aead_aad

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

Stellt AAD-Daten für den Cipher bereit, diese Funktion kann mehr als einmal aufgerufen werden.

cipher:get_aead_tag

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

Erhält das Authentifizierungstag vom Cipher mit der Länge, die als size angegeben ist. Wenn weggelassen, wird ein Tag mit der Länge der Hälfte der Blockgröße zurückgegeben. Die Größe darf die Blockgröße nicht überschreiten.

Diese Funktion kann nur aufgerufen werden, nachdem die Verschlüsselung abgeschlossen ist.

cipher:set_aead_tag

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

Setzt das Authentifizierungstag des Ciphers mit tag.

Diese Funktion kann nur aufgerufen werden, bevor die Entschlüsselung beginnt.

cipher:final

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

Gibt den verschlüsselten oder entschlüsselten Text in einer rohen binären Zeichenfolge zurück, akzeptiert optional einen String, um zu verschlüsseln oder zu entschlüsseln.

-- Verschlüsselung
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))
-- gibt "vGJRHufPYrbbnYYC0+BnwQ==" aus
-- ODER:
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))
-- gibt "vGJRHufPYrbbnYYC0+BnwQ==" aus

-- Entschlüsselung
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)
-- gibt "🦢" aus
-- ODER:
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)
-- gibt "🦢" aus

Hinweis: In einigen Implementierungen wie libsodium oder Java fügen AEAD-Verschlüsselungen das tag (oder MAC) am Ende des verschlüsselten Chiffretexts an. In solchen Fällen müssen Benutzer das tag manuell mit der richtigen Größe (normalerweise 16 Bytes) abschneiden und den Chiffretext und das tag separat übergeben.

Siehe examples/aes-gcm-aead.lua für ein Beispiel zur Verwendung von AEAD-Modi mit Authentifizierung.

cipher:derive

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

Leitet einen Schlüssel und eine IV (falls zutreffend) aus den gegebenen Materialien ab, die im aktuellen Cipher verwendet werden können