Box documentation, kotlin 1.4.20

buildSrc/src/main/kotlin/Deps.kt

@@ -16,8 +16,8 @@
 
 object Versions {
     val kotlinCoroutines = "1.4.1"
-    val kotlin = "1.4.10"
+    val kotlin = "1.4.20"
-    val kotlinSerialization = "1.0.0"
+    val kotlinSerialization = "1.0.1"
     val kotlinSerializationPlugin = "1.4.10"
     val atomicfu = "0.14.3-M2-2-SNAPSHOT" //NOTE: my linux arm32 and arm64 build
     val nodePlugin = "1.3.0"

multiplatform-crypto-libsodium-bindings/build.gradle.kts

@@ -613,6 +613,7 @@ tasks {
                 includes.from(
                     "src/commonMain/kotlin/com.ionspin.kotlin.crypto/aead/Aead.md",
                     "src/commonMain/kotlin/com.ionspin.kotlin.crypto/auth/Auth.md",
+                    "src/commonMain/kotlin/com.ionspin.kotlin.crypto/box/Box.md",
                     "src/commonMain/kotlin/com.ionspin.kotlin.crypto/CryptoModule.md")
                 displayName.set("Kotlin multiplatform")
             }

multiplatform-crypto-libsodium-bindings/src/commonMain/kotlin/com.ionspin.kotlin.crypto/box/Box.kt

@@ -20,38 +20,7 @@ data class BoxEncryptedDataAndTag(val ciphertext: UByteArray, val tag: UByteArra
 class BoxCorruptedOrTamperedDataException() : RuntimeException("MAC validation failed. Data is corrupted or tampered with.")
 
 /**
- * Authenticated encryption (crypto_box_* API)
+ * Box API uses public-key (asymmetric) encryption to
- *
- * Using public-key authenticated encryption, Bob can encrypt a confidential message specifically for Alice, using Alice's public key.
- * Using Bob's public key, Alice can compute a shared secret key. Using Alice's public key and his secret key,
- * Bob can compute the exact same shared secret key. That shared secret key can be used to verify that the encrypted
- * message was not tampered with, before eventually decrypting it.
- * Alice only needs Bob's public key, the nonce and the ciphertext. Bob should never ever share his secret key,
- * even with Alice.
- * And in order to send messages to Alice, Bob only needs Alice's public key. Alice should never ever share her secret
- * key either, even with Bob.
- * Alice can reply to Bob using the same system, without having to generate a distinct key pair.
- * The nonce doesn't have to be confidential, but it should be used with just one invocation of crypto_box_easy() for a
- * particular pair of public and secret keys.
- * One easy way to generate a nonce is to use randombytes_buf(), considering the size of the nonces the risk of any
- * random collisions is negligible. For some applications, if you wish to use nonces to detect missing messages or to
- * ignore replayed messages, it is also acceptable to use a simple incrementing counter as a nonce. A better alternative
- * is to use the crypto_secretstream() API.
- * When doing so you must ensure that the same value can never be re-used (for example you may have multiple threads
- * or even hosts generating messages using the same key pairs).
- * As stated above, senders can decrypt their own messages, and compute a valid authentication tag for any messages
- * encrypted with a given shared secret key. This is generally not an issue for online protocols. If this is not
- * acceptable, check out the Sealed Boxes section, as well as the Key Exchange section in this documentation.
- *
- *
- * Sealed boxes (crypto_box_seal_* API)
- *
- * Sealed boxes are designed to anonymously send messages to a recipient given its public key.
- * Only the recipient can decrypt these messages, using its private key. While the recipient can verify the integrity
- * of the message, it cannot verify the identity of the sender.
- * A message is encrypted using an ephemeral key pair, whose secret part is destroyed right after the encryption process.
- * Without knowing the secret key used for a given message, the sender cannot decrypt its own message later.
- * And without additional data, a message cannot be correlated with the identity of its sender.
  */
 expect object Box {
     /**

multiplatform-crypto-libsodium-bindings/src/commonMain/kotlin/com.ionspin.kotlin.crypto/box/Box.md

@@ -0,0 +1,29 @@
+# Package com.ionspin.kotlin.crypto.box
+
+## Box API - Asymmetric/Public-key authenticated encryption
+
+Public key encryption is a system that relies on a pair of keys to establish secure communication.
+
+A simplified overview of communication between Bob and Alice using public-key encryption:
+- Key exchange
+1. Alice creates 2 keys, one public, one private (public key is actually calculated from the private key)
+1. Bob creates 2 keys, one public, one private
+1. Alice sends her **public** key to Bob
+1. Bob does the same and sends his **public** key to Alice
+- Encryption 
+
+Alice wants to establish a secure communication channel with Bob, they already changed public keys in previous steps.
+1. Alice uses Bobs **private** key to encrypt a *secret value* (Usually just a key for symmetric encryption)
+1. Alice sends encrypted data to Bob
+1. Bob is the only one who has the matching private key, and can decrypt the data
+1. Bob and Alice now posses the same *secret value* and can start communicating (i.e. by using XChaCha20Poly1305 
+symmetric encryption and using the *secret value* as the symmetric key)
+
+Bob would do the same if he wanted to initiate the secure communication.
+
+This set of functions also contains another use case called `sealed boxes` in libsodium. 
+Sealed box is designed to anonymously send a message to a recipient. Libsodium documentation explains it as follows:
+> A message is encrypted using an ephemeral key pair, whose secret part is destroyed right after the encryption process.
+  Without knowing the secret key used for a given message, the sender cannot decrypt its own message later. And without additional data, a message cannot be correlated with the identity of its sender.
+
+