update crypto docs

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"`
 

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"`