more docs

src/commonMain/kotlin/net/sergeych/crypto2/Container.kt

@@ -12,12 +12,48 @@ import net.sergeych.crypto2.Container.Companion.createWith
  * Multi-key encrypted container with simple adding new keys function that does not need to
  * know all existing keys, e.g., you can add recipients to the container data if you can
  * decrypt it. This is sometimes very important to be able to add recipients to the message
- * keeping existing recipients you know no keys of.
- *
- * See:
+ * keeping existing recipients you know no keys of, or update the message when only one of the
+ * keys is known.
+ * 
  * - [createWith] for more on create a new container
- * - [addRecipients] and various [plus] operators to add recipients
  * - [decryptWith] to decrypt
+ * - [addRecipients] and various [plus] operators to add recipients
+ * - [updateData] to change decrypted content for the same recipient keys
+ *
+ * Some rules:
+ *
+ * When adding public key recipient, it is faster to use your known [Asymmetric.SecretKey], but you
+ * can stay anonymous by just adding [Asymmetric.PublicKey] only.
+ *
+ * Put your data in [SealedBox] if you need to authenticate message origin and timestamp, then put
+ * the sealed box in the [Container], this will conceal signers from attack. In the case you need to
+ * prove message origin without disclosing its content, put the [Container] in the [SealedBox].
+ * Everybody will see who and when have it signed, but only intended recipients could read it.
+ *
+ * Sample:
+ * ```kotlin
+ *    // create container fpr p3.public key destination using our secret key (for speed)
+ *    var c = Container.createWith(data, p1.secretKey to p3.publicKey)
+ *
+ *    // imitation of receiving an encrypted container in binary form
+ *    // so it is not decrypted
+ *    c = Container.decode(c.encoded)
+ *
+ *    // decrypt it with the right key
+ *    c.decryptWith(p3.secretKey)
+ *
+ *
+ *    // add more keys to it: 2 symmetric, public anonymous, and secret-to-public pair (faster)
+ *    c = c + symmetricKey1 + symmetricKey2 + herPublicKey + (MySecretKey to hisPublicKey)
+ *
+ *    // and update data in it (it will be encrypted too), adding random bytes, at least 100 and no
+ *    // more than 200, to make size analysis attack almost impossible
+ *    // in the 100 to 200
+ *    c = c..updateData(data2, 100..22)
+ *
+ *    // now we can send it over the network
+ *    sendOVerTheNetwork(c.encoded)
+ *```
  */
 @Serializable
 sealed class Container {
@@ -83,6 +119,10 @@ sealed class Container {
      */
     operator fun plus(pair: Pair<Asymmetric.SecretKey, Asymmetric.PublicKey>) = addRecipients { key(pair) }
 
+    /**
+     * Update the data in the decrypted container. It keeps the same set of keys and update
+     * the data only.
+     */
     abstract fun updateData(newPlainData: UByteArray,randomFill: IntRange?=null): Container
 
     /**
@@ -241,17 +281,17 @@ sealed class Container {
          *
          * ```kotlin
          * Container.create(plainData) {
-         *     // optional: add a random filling from 10 to 20 bytes
-         *     fill( 10 .. 20 )
+         *    // optional: add a random filling from 10 to 20 bytes
+         *    fill( 10 .. 20 )
          *
-         *     key(symmetricKey1, symmetricKey2) // add two SymmetricKey recipients
+         *    key(symmetricKey1, symmetricKey2) // add two SymmetricKey recipients
          *
-         *     key(publicKey1) // add a Asymmetric.PublicKey recipient anonymously
+         *    key(publicKey1) // add a Asymmetric.PublicKey recipient anonymously
          *
-         *     // More interesting: add publicKey2 and publicKey3 recipients using my
-         *     // secret key as authority. IT is faster and allow to owner of the listed public keys
-         *     // to know it was me who added them to this container.
-         *     key(mySecretKey to publicKey2,mySecretKey to publicKey3)
+         *    // More interesting: add publicKey2 and publicKey3 recipients using my
+         *    // secret key as authority. IT is faster and allow to owner of the listed public keys
+         *    // to know it was me who added them to this container.
+         *    key(mySecretKey to publicKey2,mySecretKey to publicKey3)
          * }
          * ```
 
@@ -380,17 +420,17 @@ sealed class Container {
          * Usage sample:
          * ```kotlin
          * Container.create(plainData) {
-         *     // optional: add a random filling from 10 to 20 bytes
-         *     fill( 10 .. 20 )
+         *    // optional: add a random filling from 10 to 20 bytes
+         *    fill( 10 .. 20 )
          *
-         *     key(symmetricKey1, symmetricKey2) // add two SymmetricKey recipients
+         *    key(symmetricKey1, symmetricKey2) // add two SymmetricKey recipients
          *
-         *     key(publicKey1) // add a Asymmetric.PublicKey recipient anonymously
+         *    key(publicKey1) // add a Asymmetric.PublicKey recipient anonymously
          *
-         *     // More interesting: add publicKey2 and publicKey3 recipients using my
-         *     // secret key as authority. IT is faster and allow to owner of the listed public keys
-         *     // to know it was me who added them to this container.
-         *     key(mySecretKey to publicKey2,mySecretKey to publicKey3)
+         *    // More interesting: add publicKey2 and publicKey3 recipients using my
+         *    // secret key as authority. IT is faster and allow to owner of the listed public keys
+         *    // to know it was me who added them to this container.
+         *    key(mySecretKey to publicKey2,mySecretKey to publicKey3)
          * }
          * ```
          * At least one key should be provided.