From 6183a2eb6bea4c4fb570b5d2d175f1c363538604 Mon Sep 17 00:00:00 2001
From: Ugljesa Jovanovic <ugljesa.jovanovic@ionspin.com>
Date: Wed, 18 Nov 2020 21:03:21 +0100
Subject: [PATCH] Aead docs

---
 .../com.ionspin.kotlin.crypto/aead/Aead.md    | 25 +++++++++++++++-
 ...thenticatedEncryptionWithAssociatedData.kt | 29 +++++++++++++++++--
 2 files changed, 51 insertions(+), 3 deletions(-)

diff --git a/multiplatform-crypto-libsodium-bindings/src/commonMain/kotlin/com.ionspin.kotlin.crypto/aead/Aead.md b/multiplatform-crypto-libsodium-bindings/src/commonMain/kotlin/com.ionspin.kotlin.crypto/aead/Aead.md
index b302ce5..0c325af 100644
--- a/multiplatform-crypto-libsodium-bindings/src/commonMain/kotlin/com.ionspin.kotlin.crypto/aead/Aead.md
+++ b/multiplatform-crypto-libsodium-bindings/src/commonMain/kotlin/com.ionspin.kotlin.crypto/aead/Aead.md
@@ -1,4 +1,27 @@
 # Package com.ionspin.kotlin.crypto.aead
 
-Package AEAD stuff here
+## Authenticated encryption with associated data
+
+This is a form of symmetric encryption, that assures both confidentiality and authenticity of the data. 
+
+In general it works like this:
+
+Inputs:
+- Message to encrypt and authenticate
+- Key to use for encryption
+- **Unique** nonce
+- Additional data that is not encrypted but also authenticated
+
+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. 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. 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
+
+
 
diff --git a/multiplatform-crypto-libsodium-bindings/src/commonMain/kotlin/com.ionspin.kotlin.crypto/aead/AuthenticatedEncryptionWithAssociatedData.kt b/multiplatform-crypto-libsodium-bindings/src/commonMain/kotlin/com.ionspin.kotlin.crypto/aead/AuthenticatedEncryptionWithAssociatedData.kt
index 6388806..e19d781 100644
--- a/multiplatform-crypto-libsodium-bindings/src/commonMain/kotlin/com.ionspin.kotlin.crypto/aead/AuthenticatedEncryptionWithAssociatedData.kt
+++ b/multiplatform-crypto-libsodium-bindings/src/commonMain/kotlin/com.ionspin.kotlin.crypto/aead/AuthenticatedEncryptionWithAssociatedData.kt
@@ -22,11 +22,36 @@ val crypto_aead_chacha20poly1305_KEYBYTES = 32
 val crypto_aead_chacha20poly1305_NPUBBYTES = 8
 val crypto_aead_chacha20poly1305_ABYTES = 16
 
-
+/**
+ * A data class wrapping returned encrypted data and and tag from aead encrypt functions.
+ */
 data class AeadEncryptedDataAndTag(val data: UByteArray, val tag: UByteArray)
 
-class AeadCorrupedOrTamperedDataException() : RuntimeException("MAC validation failed. Data is corrupted or tampered with.")
+/**
+ * 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.")
 
+/**
+ * This is a form of symmetric encryption, that assures both confidentiality and authenticity of the data.
+ *
+ * Offered here are three implementations of (x)ChaCha20-Poly1305 construction:
+ * - ChaCha20Poly1305 - uses 64bit nonce
+ * - ChaCha20Poly1305-IETF - uses 96bit nonce (standardised by [RFC8439](https://tools.ietf.org/html/rfc8439)
+ * - XChaCha20Poly1305 - uses 192bit nonce - recommended choice
+ *
+ * The only difference is the size of the nonce, and how is the nonce used.
+ *
+ * (x)ChaCha20 is a streaming cipher develop by Daniel J. Bernstein. He is also the author of Poly1305 a fast Message
+ * Authentication Code system
+ *
+ * Libsodium offers two additional variants for each of the aforementioned variants:
+ * - Combined
+ * - Detached
+ *
+ * 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]
+ */
 expect object AuthenticatedEncryptionWithAssociatedData {
     // X - Ietf
     fun xChaCha20Poly1305IetfEncrypt(