From 264b111d822aa2ce9ed1497447052cc03584eabd Mon Sep 17 00:00:00 2001
From: Miguel Oliveira <miguel.oliveira4224@gmail.com>
Date: Sat, 5 Mar 2022 13:01:30 -0300
Subject: [PATCH] Document BLAKE3, ChaCha20 and AEAD

---
 aead.lua     | 26 ++++++++++++++++++++++++++
 blake3.lua   | 23 +++++++++++++++++++++++
 chacha20.lua | 14 ++++++++++++++
 3 files changed, 63 insertions(+)

diff --git a/aead.lua b/aead.lua
index 552c18a..d5b3d63 100644
--- a/aead.lua
+++ b/aead.lua
@@ -1,3 +1,8 @@
+--- The ChaCha20Poly1305AEAD authenticated encryption with associated data (AEAD) construction.
+--
+-- @module aead
+--
+
 local expect   = require "cc.expect".expect
 local chacha20 = require "ccryptolib.chacha20"
 local poly1305 = require "ccryptolib.poly1305"
@@ -5,6 +10,16 @@ local poly1305 = require "ccryptolib.poly1305"
 local bxor = bit32.bxor
 local bor = bit32.bor
 
+--- Encrypts a message.
+--
+-- @tparam string key A 32-byte random key.
+-- @tparam string nonce A 12-byte per-message unique nonce.
+-- @tparam string message The message to be encrypted.
+-- @tparam string aad Arbitrary associated data to authenticate on decryption.
+-- @tparam[opt=20] number rounds The number of ChaCha20 rounds to use.
+-- @treturn string The ciphertext.
+-- @treturn string The 16-byte authentication tag.
+--
 local function encrypt(key, nonce, message, aad, rounds)
     expect(1, key, "string")
     assert(#key == 32, "key length must be 32")
@@ -32,6 +47,17 @@ local function encrypt(key, nonce, message, aad, rounds)
     return ciphertext, tag
 end
 
+--- Decrypts a message.
+--
+-- @tparam string key The key used on encryption.
+-- @tparam string nonce The nonce used on encryption.
+-- @tparam string ciphertext The ciphertext to be decrypted.
+-- @tparam string aad The arbitrary associated data used on encryption.
+-- @tparam string tag The authentication tag returned on encryption.
+-- @tparam[opt=20] number rounds The number of rounds used on encryption.
+-- @treturn[1] string The decrypted plaintext.
+-- @treturn[2] nil If authentication has failed.
+--
 local function decrypt(key, nonce, tag, ciphertext, aad, rounds)
     expect(1, key, "string")
     assert(#key == 32, "key length must be 32")
diff --git a/blake3.lua b/blake3.lua
index c147b81..dd6185c 100644
--- a/blake3.lua
+++ b/blake3.lua
@@ -1,3 +1,8 @@
+--- The BLAKE3 cryptographic hash function.
+--
+-- @module blake3
+--
+
 local expect = require "cc.expect".expect
 
 local unpack = unpack or table.unpack
@@ -197,6 +202,12 @@ end
 
 local mod = {}
 
+--- Hashes data using BLAKE3.
+--
+-- @tparam string message The input message.
+-- @tparam[opt=32] number len The desired hash length, in bytes.
+-- @treturn string The hash.
+--
 function mod.digest(message, len)
     expect(1, message, "string")
     expect(2, len, "number", "nil")
@@ -206,6 +217,13 @@ function mod.digest(message, len)
     return blake3(IV, 0, message, len)
 end
 
+--- Performs a keyed hash.
+--
+-- @tparam string key A 32-byte random key.
+-- @tparam string message The input message.
+-- @tparam[opt=32] number len The desired hash length, in bytes.
+-- @treturn string The keyed hash.
+--
 function mod.digestKeyed(key, message, len)
     expect(1, key, "string")
     assert(#key == 32, "key length must be 32")
@@ -217,6 +235,11 @@ function mod.digestKeyed(key, message, len)
     return blake3({("<I4I4I4I4I4I4I4I4"):unpack(key)}, KEYED_HASH, message, len)
 end
 
+--- Makes a context-based key derivation function (KDF).
+--
+-- @tparam string context The context for the KDF.
+-- @treturn function(material:string [, len:number]):string The KDF.
+--
 function mod.deriveKey(context)
     expect(1, context, "string")
 
diff --git a/chacha20.lua b/chacha20.lua
index 5041bfc..ac85952 100644
--- a/chacha20.lua
+++ b/chacha20.lua
@@ -1,3 +1,8 @@
+--- The ChaCha20 stream cipher.
+--
+-- @module chacha20
+--
+
 local expect = require "cc.expect".expect
 
 local bxor = bit32.bxor
@@ -5,6 +10,15 @@ local rol = bit32.lrotate
 
 local mod = {}
 
+--- Encrypts/Decrypts data using ChaCha20.
+--
+-- @tparam string key A 32-byte random key.
+-- @tparam string nonce A 12-byte per-message unique nonce.
+-- @tparam string message A plaintext or ciphertext.
+-- @tparam[opt=20] number rounds The number of ChaCha20 rounds to use.
+-- @tparam[opt=1] number offset The block offset to generate the keystream at.
+-- @treturn string The resulting ciphertext or plaintext.
+--
 function mod.crypt(key, nonce, message, rounds, offset)
     expect(1, key, "string")
     assert(#key == 32, "key length must be 32")