Started adding Auth doc, added aead doc for specific functions

multiplatform-crypto-libsodium-bindings/src/commonMain/kotlin/com.ionspin.kotlin.crypto/aead/Aead.md

@@ -2,7 +2,8 @@
 
 ## Authenticated encryption with associated data
 
-This is a form of symmetric encryption, that assures both confidentiality and authenticity of the data. 
+This is a form of symmetric encryption, that assures both confidentiality and authenticity of the data to be encrypted as well
+as associated data that will not be encrypted. 
 
 In general it works like this:
 
@@ -14,11 +15,11 @@ Inputs:
 
 Simplified encryption algorithm:
 1. Encrypt message with key and nonce
-1. Apply MAC to encrypted message + unencrypted associated data to generate authentication data (tag)
+1. Apply MAC algorithm to encrypted message + unencrypted associated data to generate authentication data (tag)
 1. Send the encrypted data + associated data + authentication data + nonce
 
 Simplified decryption algorithm:
-1. Apply MAC to encrypted message + unencrypted associated data to generate authentication data
+1. Apply MAC algorithm to encrypted message + unencrypted associated data to generate authentication data
 1. If the generated authenticated data, and the received authentication data match, proceed, otherwise sound the alarm and stop.
 1. Decrypt the encrypted data
 1. Return the decrypted data and associated data to the user

multiplatform-crypto-libsodium-bindings/src/commonMain/kotlin/com.ionspin.kotlin.crypto/aead/AuthenticatedEncryptionWithAssociatedData.kt

@@ -30,13 +30,15 @@ data class AeadEncryptedDataAndTag(val data: UByteArray, val tag: UByteArray)
 /**
  * An exception thrown when tag generated from received data and key doesn't match the received tag
  */
-class AeadCorrupedOrTamperedDataException() : RuntimeException("Tag (authentication data) validation failed. Data is corrupted or tampered with.")
+class AeadCorrupedOrTamperedDataException() :
+    RuntimeException("Tag (authentication data) validation failed. Data is corrupted or tampered with.")
 
 /**
- * This is a form of symmetric encryption, that assures both confidentiality and authenticity of the data.
+ * This is a form of symmetric encryption, that assures both confidentiality and authenticity of the data to be encrypted as well
+as associated data that will not be encrypted.
  *
  * Offered here are three implementations of (x)ChaCha20-Poly1305 construction:
- * - ChaCha20Poly1305 - uses 64bit nonce
+ * - ChaCha20Poly1305 - uses 64bit nonce, safe to encrypt
  * - ChaCha20Poly1305-IETF - uses 96bit nonce (standardised by [RFC8439](https://tools.ietf.org/html/rfc8439)
  * - XChaCha20Poly1305 - uses 192bit nonce - recommended choice
  *
@@ -51,9 +53,21 @@ class AeadCorrupedOrTamperedDataException() : RuntimeException("Tag (authenticat
  *
  * Combined mode returns encrypted data and tag as one UByteArray, while detached mode returns them as separate UByteArrays.
  * To be kotlin idiomatic we are returning detached tag and encrypted data inside a wrapper data class [AeadEncryptedDataAndTag]
+ *
+ * Also provided are key generation convenience functions for each variant. (Which is in practice the same, since the keys
+ * same length for each variant)
  */
 expect object AuthenticatedEncryptionWithAssociatedData {
     // X - Ietf
+    /**
+     * Encrypt the message and return encrypted data and tag using xChaChaPoly1305 (192 bit nonce)
+     *
+     * @param message message to encrypt
+     * @param associatedData associated data the won't be encrypted, but will be authenticated
+     * @param nonce a **unique** nonce
+     * @param key secret key
+     * @return encrypted data and tag (in that order)
+     */
     fun xChaCha20Poly1305IetfEncrypt(
         message: UByteArray,
         associatedData: UByteArray,
@@ -61,13 +75,34 @@ expect object AuthenticatedEncryptionWithAssociatedData {
         key: UByteArray
     ): UByteArray
 
+    /**
+     * Check if authentication data (tag) is correct, then decrypt the message and return decrypted data.
+     * Using xChaChaPoly1305 (192 bit nonce)
+     *
+     * @param ciphertextAndTag message to decrypt
+     * @param associatedData associated data the won't be encrypted, but will be authenticated
+     * @param nonce a nonce used to encrypt the message
+     * @param key secret key
+     * @return decrypted data
+     * @throws AeadCorrupedOrTamperedDataException if authentication data (tag) cannot be verified
+     */
     fun xChaCha20Poly1305IetfDecrypt(
-        ciphertext: UByteArray,
+        ciphertextAndTag: UByteArray,
         associatedData: UByteArray,
         nonce: UByteArray,
         key: UByteArray
     ): UByteArray
 
+    /**
+     * Encrypt the message and return encrypted data and tag using xChaChaPoly1305 (192 bit nonce) as
+     * separate arrays (but wrapped inside [AeadEncryptedDataAndTag]
+     *
+     * @param message message to encrypt
+     * @param associatedData associated data the won't be encrypted, but will be authenticated
+     * @param nonce a **unique** nonce
+     * @param key secret key
+     * @return encrypted data and tag wrapped inside [AeadEncryptedDataAndTag] data class instance
+     */
     fun xChaCha20Poly1305IetfEncryptDetached(
         message: UByteArray,
         associatedData: UByteArray,
@@ -75,6 +110,18 @@ expect object AuthenticatedEncryptionWithAssociatedData {
         key: UByteArray
     ): AeadEncryptedDataAndTag
 
+    /**
+     * Check if authentication data (tag) is correct, then decrypt the message and return decrypted data.
+     * Using xChaChaPoly1305 (192 bit nonce)
+     *
+     * @param ciphertext message to decrypt
+     * @param tag authenticatoin data (tag)
+     * @param associatedData associated data the won't be encrypted, but will be authenticated
+     * @param nonce a nonce used to encrypt the message
+     * @param key secret key
+     * @return decrypted data
+     * @throws AeadCorrupedOrTamperedDataException if authentication data (tag) cannot be verified
+     */
     fun xChaCha20Poly1305IetfDecryptDetached(
         ciphertext: UByteArray,
         tag: UByteArray,
@@ -84,21 +131,48 @@ expect object AuthenticatedEncryptionWithAssociatedData {
     ): UByteArray
 
     // Ietf
-
+    /**
+     * Encrypt the message and return encrypted data and tag using ChaChaPoly1305-IETF (96 bit nonce)
+     *
+     * @param message message to encrypt
+     * @param associatedData associated data the won't be encrypted, but will be authenticated
+     * @param nonce a **unique** nonce
+     * @param key secret key
+     * @return encrypted data and tag (in that order)
+     */
     fun chaCha20Poly1305IetfEncrypt(
         message: UByteArray,
         associatedData: UByteArray,
         nonce: UByteArray,
         key: UByteArray
     ): UByteArray
-
+    /**
+     * Check if authentication data (tag) is correct, then decrypt the message and return decrypted data.
+     * Using ChaChaPoly1305-IETF (96 bit nonce)
+     *
+     * @param ciphertextAndTag message to decrypt
+     * @param associatedData associated data the won't be encrypted, but will be authenticated
+     * @param nonce a nonce used to encrypt the message
+     * @param key secret key
+     * @return decrypted data
+     * @throws AeadCorrupedOrTamperedDataException if authentication data (tag) cannot be verified
+     */
     fun chaCha20Poly1305IetfDecrypt(
-        ciphertext: UByteArray,
+        ciphertextAndTag: UByteArray,
         associatedData: UByteArray,
         nonce: UByteArray,
         key: UByteArray
     ): UByteArray
-
+    /**
+     * Encrypt the message and return encrypted data and tag using ChaChaPoly1305-IETF (96 bit nonce) as
+     * separate arrays (but wrapped inside [AeadEncryptedDataAndTag]
+     *
+     * @param message message to encrypt
+     * @param associatedData associated data the won't be encrypted, but will be authenticated
+     * @param nonce a **unique** nonce
+     * @param key secret key
+     * @return encrypted data and tag wrapped inside [AeadEncryptedDataAndTag] data class instance
+     */
     fun chaCha20Poly1305IetfEncryptDetached(
         message: UByteArray,
         associatedData: UByteArray,
@@ -106,6 +180,18 @@ expect object AuthenticatedEncryptionWithAssociatedData {
         key: UByteArray
     ): AeadEncryptedDataAndTag
 
+    /**
+     * Check if authentication data (tag) is correct, then decrypt the message and return decrypted data.
+     * Using xChaChaPoly1305 (96 bit nonce)
+     *
+     * @param ciphertext message to decrypt
+     * @param tag authenticatoin data (tag)
+     * @param associatedData associated data the won't be encrypted, but will be authenticated
+     * @param nonce a nonce used to encrypt the message
+     * @param key secret key
+     * @return decrypted data
+     * @throws AeadCorrupedOrTamperedDataException if authentication data (tag) cannot be verified
+     */
     fun chaCha20Poly1305IetfDecryptDetached(
         ciphertext: UByteArray,
         tag: UByteArray,
@@ -115,28 +201,66 @@ expect object AuthenticatedEncryptionWithAssociatedData {
     ): UByteArray
 
     // Original chacha20poly1305
-
+    /**
+     * Encrypt the message and return encrypted data and tag using ChaChaPoly1305 (64 bit nonce)
+     *
+     * @param message message to encrypt
+     * @param associatedData associated data the won't be encrypted, but will be authenticated
+     * @param nonce a **unique** nonce
+     * @param key secret key
+     * @return encrypted data and tag (in that order)
+     */
     fun chaCha20Poly1305Encrypt(
         message: UByteArray,
         associatedData: UByteArray,
         nonce: UByteArray,
         key: UByteArray
     ): UByteArray
-
+    /**
+     * Check if authentication data (tag) is correct, then decrypt the message and return decrypted data.
+     * Using ChaChaPoly1305 (64 bit nonce)
+     *
+     * @param ciphertextAndTag message to decrypt
+     * @param associatedData associated data the won't be encrypted, but will be authenticated
+     * @param nonce a nonce used to encrypt the message
+     * @param key secret key
+     * @return decrypted data
+     * @throws AeadCorrupedOrTamperedDataException if authentication data (tag) cannot be verified
+     */
     fun chaCha20Poly1305Decrypt(
-        ciphertext: UByteArray,
+        ciphertextAndTag: UByteArray,
         associatedData: UByteArray,
         nonce: UByteArray,
         key: UByteArray
     ): UByteArray
-
+    /**
+     * Encrypt the message and return encrypted data and tag using ChaChaPoly1305 (64 bit nonce) as
+     * separate arrays (but wrapped inside [AeadEncryptedDataAndTag]
+     *
+     * @param message message to encrypt
+     * @param associatedData associated data the won't be encrypted, but will be authenticated
+     * @param nonce a **unique** nonce
+     * @param key secret key
+     * @return encrypted data and tag wrapped inside [AeadEncryptedDataAndTag] data class instance
+     */
     fun chaCha20Poly1305EncryptDetached(
         message: UByteArray,
         associatedData: UByteArray,
         nonce: UByteArray,
         key: UByteArray
     ): AeadEncryptedDataAndTag
-
+    /**
+     * Check if authentication data (tag) is correct, then decrypt the message and return decrypted data.
+     * Using xChaChaPoly1305 (64 bit nonce)
+     *
+     * @param ciphertext message to decrypt
+     * @param tag authenticatoin data (tag)
+     * @param associatedData associated data the won't be encrypted, but will be authenticated
+     * @param nonce a nonce used to encrypt the message
+     * @param key secret key
+     * @return decrypted data
+     * @throws AeadCorrupedOrTamperedDataException if authentication data (tag) cannot be verified
+     */
     fun chaCha20Poly1305DecryptDetached(
         ciphertext: UByteArray,
         tag: UByteArray,
@@ -145,9 +269,20 @@ expect object AuthenticatedEncryptionWithAssociatedData {
         key: UByteArray
     ): UByteArray
 
-
-    fun xChaCha20Poly1305IetfKeygen() : UByteArray
-    fun chaCha20Poly1305IetfKeygen() : UByteArray
-    fun chaCha20Poly1305Keygen() : UByteArray
+    /**
+     * Generate a random 32byte key for use with xChaCha20Poly1305
+     * @return secret key
+     */
+    fun xChaCha20Poly1305IetfKeygen(): UByteArray
+    /**
+     * Generate a random 32 byte key for use with ChaCha20Poly1305-IETF
+     * @return secret key
+     */
+    fun chaCha20Poly1305IetfKeygen(): UByteArray
+    /**
+     * Generate a random 32 byte key for use with ChaCha20Poly1305
+     * @return secret key
+     */
+    fun chaCha20Poly1305Keygen(): UByteArray
 
 }

multiplatform-crypto-libsodium-bindings/src/commonMain/kotlin/com.ionspin.kotlin.crypto/auth/Auth.kt

@@ -19,18 +19,32 @@ val crypto_auth_hmacsha256_BYTES = 32
 val crypto_auth_hmacsha512_KEYBYTES = 32
 val crypto_auth_hmacsha512_BYTES = 64
 
+/**
+ * Authentication is a process of generating authentication data (tag) for a certain message. Its purpose is to assure
+ * that the data hasn't been corrupted or tampered with during the transport.
+ *
+ * We support 3 variants:
+ * - without suffix - HMAC-SHA512-256 (HMAC SHA512 with just the first 256 bits used)
+ * - *HmacSha256 - HMAC-SHA256
+ * - *HmacSha512 - HMAC-SHA512
+ *
+ * Each variant supports three operations:
+ * - keygen - generate appropriate key for MAC function
+ * - auth - generate the authentication data (tag/mac)
+ * - verify - verify that the authenticatoin data (tag/mac) is correct
+ */
 expect object Auth {
 
     fun authKeygen() : UByteArray
     fun auth(message: UByteArray, key: UByteArray) : UByteArray
-    fun authVerify(mac: UByteArray, message: UByteArray, key: UByteArray) : Boolean
+    fun authVerify(tag: UByteArray, message: UByteArray, key: UByteArray) : Boolean
 
     fun authHmacSha256Keygen() : UByteArray
     fun authHmacSha256(message: UByteArray, key: UByteArray) : UByteArray
-    fun authHmacSha256Verify(mac: UByteArray, message: UByteArray, key: UByteArray) : Boolean
+    fun authHmacSha256Verify(tag: UByteArray, message: UByteArray, key: UByteArray) : Boolean
 
     fun authHmacSha512Keygen() : UByteArray
     fun authHmacSha512(message: UByteArray, key: UByteArray) : UByteArray
-    fun authHmacSha512Verify(mac: UByteArray, message: UByteArray, key: UByteArray) : Boolean
+    fun authHmacSha512Verify(tag: UByteArray, message: UByteArray, key: UByteArray) : Boolean
 
 }

multiplatform-crypto-libsodium-bindings/src/commonMain/kotlin/com.ionspin.kotlin.crypto/auth/Auth.md

@@ -0,0 +1,21 @@
+# Package com.ionspin.kotlin.crypto.auth
+
+## Authentication
+
+Authentication is a process of generating authentication data (tag) for a certain message. Its purpose is to assure
+that the data hasn't been corrupted or tampered with during the transport.
+
+In general, it works like this:
+
+Inputs:
+- Message to authenticate
+- Key to use for authentication
+
+Sending side algorithm:
+1. Apply MAC to message
+1. Send the message + authentication data (tag)
+
+Receiving side:
+1. Apply the MAC to the received message
+1. If the generated authenticated data (tag), and the received authentication data (received tag) match, proceed, otherwise sound the alarm and stop.
+1. Return the message to the user