From 5391be4b8acb57baae80b2f7e204bf95ac52ca72 Mon Sep 17 00:00:00 2001 From: dagger Date: Sat, 22 Aug 2026 17:47:59 +0700 Subject: [PATCH] update crypto docs --- doc/en/scripting/builtins/libcrypto.md | 56 ++++++++++++++------------ doc/ru/scripting/builtins/libcrypto.md | 19 ++------- 2 files changed, 33 insertions(+), 42 deletions(-) diff --git a/doc/en/scripting/builtins/libcrypto.md b/doc/en/scripting/builtins/libcrypto.md index 19b93e433..b3106d104 100644 --- a/doc/en/scripting/builtins/libcrypto.md +++ b/doc/en/scripting/builtins/libcrypto.md @@ -1,14 +1,6 @@ # *crypto* library -The library provides common cryptographic functions for mods - -TLS and HTTP are not part of this library. They can use crypto for expensive -operations - -Keys, signatures, hashes and encrypted data are passed as regular Lua strings. -Strings may contain zero bytes - -The current API version is available in `crypto.API_VERSION` +The library provides common cryptographic functions ## Hashing @@ -17,24 +9,27 @@ crypto.sha256(data: str) -> str crypto.sha384(data: str) -> str crypto.sha512(data: str) -> str crypto.md5(data: str) -> str + crypto.hash(hash: str, data: str) -> str crypto.hmac(hash: str, key: str, data: str) -> str ``` Supported names are `SHA256`, `SHA384`, `SHA512` and `MD5` -MD5 is provided for old formats. SHA256 should be used for new data +MD5 is needed for compatibility with old formats. SHA256 is better for new data -Large data can be hashed in parts +Large files can be passed in parts ```lua local hash = crypto.hash_new("SHA256") + hash:update(part1) hash:update(part2) + local result = hash:final() ``` -Call `reset` before using the context again +The context can be cleared with `reset` after `final` ## Signatures @@ -45,7 +40,11 @@ crypto.ed25519_sign(private_key: str, message: str) -> str crypto.ed25519_verify(public_key: str, message: str, signature: str) -> true -> false, error +``` +Ed25519 keys are 32 bytes long. A signature is 64 bytes long + +```lua crypto.ecdsa_keypair(curve: str) -> private_key, public_key crypto.ecdsa_public(curve: str, private_key: str) -> str crypto.ecdsa_sign(curve: str, private_key: str, message: str, hash: str) -> str @@ -53,24 +52,27 @@ crypto.ecdsa_verify(curve: str, public_key: str, message: str, signature: str, hash: str) -> true -> false, error +``` +Available curves are `P-256`, `P-384` and `P-521` + +An ECDSA public key is stored as an uncompressed SEC1 point. A signature is +stored in DER format + +```lua crypto.rsa_pkcs1_verify(hash: str, modulus: str, exponent: str, message: str, signature: str) -> true -> false, error + crypto.rsa_pss_verify(hash: str, modulus: str, exponent: str, message: str, signature: str, salt_length: int) -> true -> false, error ``` -Ed25519 keys are 32 bytes and signatures are 64 bytes - -ECDSA supports `P-256`, `P-384` and `P-521`. Public keys use the uncompressed -SEC1 format and signatures use DER - -RSA modulus and exponent use big endian. A `salt_length` of `-1` uses the hash -size. RSA key generation is not provided, Ed25519 is easier for new keys +RSA modulus and exponent are passed in big endian. A `salt_length` value of `-1` +uses the hash size ## Key exchange @@ -85,9 +87,9 @@ crypto.p256_public(private_key: str) -> str crypto.p256_shared(private_key: str, peer_public_key: str) -> str ``` -`x25519` and `x25519_shared` do the same operation +`x25519` and `x25519_shared` perform the same operation -Pass the shared secret through HKDF before using it as a key +The shared secret should not be used as a ready key. Pass it through HKDF first ## Encryption @@ -109,29 +111,31 @@ AES GCM accepts 16 and 32 byte keys ChaCha20 Poly1305 uses a 32 byte key and a 12 byte nonce -A 16 byte tag is appended to ciphertext. Decryption returns nothing when the -tag is invalid +A 16 byte tag is appended to encrypted data -Never use the same nonce twice with the same key +Never reuse a nonce with the same key ## Other functions ```lua crypto.random_bytes(length: int) -> str crypto.constant_time_equal(left: str, right: str) -> bool + crypto.hkdf_extract(hash: str, salt: str, ikm: str) -> str crypto.hkdf_expand(hash: str, prk: str, info: str, length: int) -> str + crypto.pbkdf2(hash: str, password: str, salt: str, iterations: int, length: int) -> str crypto.scrypt(password: str, salt: str, n: int, r: int, p: int, length: int, [optional]max_memory: int=0) -> str + crypto.features() -> table ``` Use scrypt or PBKDF2 with a random salt for passwords. A regular SHA256 hash is -not suitable for password storage +not suitable for passwords -`features` returns the OpenSSL version and available functions +`features` returns the OpenSSL version and a list of available features An invalid signature returns `false, "invalid_signature"` diff --git a/doc/ru/scripting/builtins/libcrypto.md b/doc/ru/scripting/builtins/libcrypto.md index dce86d401..50112710b 100644 --- a/doc/ru/scripting/builtins/libcrypto.md +++ b/doc/ru/scripting/builtins/libcrypto.md @@ -1,14 +1,6 @@ # Библиотека *crypto* -Библиотека предоставляет основные криптографические функции для модов - -TLS и HTTP в нее не входят. Эти протоколы используют crypto для тяжелых -вычислений - -Все бинарные значения передаются обычными Lua строками. Это касается ключей, -подписей, хешей и зашифрованных данных. Строки могут содержать нулевые байты - -Текущая версия API находится в `crypto.API_VERSION` +Библиотека предоставляет основные криптографические функции ## Хеширование @@ -83,9 +75,6 @@ crypto.rsa_pss_verify(hash: str, modulus: str, exponent: str, Модуль и экспонента RSA передаются в big endian. Значение `salt_length = -1` использует размер хеша -Генерации RSA ключей в библиотеке нет. Для новых ключей проще использовать -Ed25519 - ## Обмен ключами ```lua @@ -124,8 +113,7 @@ AES GCM принимает ключи размером 16 или 32 байта ChaCha20 Poly1305 использует ключ размером 32 байта и nonce размером 12 байт -В конец зашифрованных данных добавляется тег размером 16 байт. При неверном -теге функция расшифровки ничего не возвращает +В конец зашифрованных данных добавляется тег размером 16 байт Нельзя повторно использовать один nonce с тем же ключом @@ -149,8 +137,7 @@ crypto.features() -> table Для хранения паролей следует использовать scrypt или PBKDF2 со случайной солью. Обычный SHA256 для паролей не подходит -`features` возвращает версию OpenSSL и список доступных возможностей. Это -можно использовать если мод запускается на разных сборках движка +`features` возвращает версию OpenSSL и список доступных возможностей Неверная подпись возвращает `false, "invalid_signature"`