Documentation.

README.md

@@ -68,15 +68,15 @@ Several features in libsodium are already provided by Crystal:
 | --- | --- |
 | Only use `CryptoBox::SecretKey` `Sign::SecretKey` `SecretBox` | I don't know much about crypto. |
 | [`Sodium::CryptoBox::SecretKey`](https://didactic-drunk.github.io/sodium.cr/Sodium/CryptoBox/SecretKey.html) .box | I want to encrypt + authenticate data using public key encryption. |
-| [`Sodium::Sign::SecretKey`](https://didactic-drunk.github.io/sodium.cr/Sodium/CryptoBox/PublicKey.html) .encrypt | I want anonymously send encrypted data. (No authentication) |
+| [`Sodium::CryptoBox::SecretKey`](https://didactic-drunk.github.io/sodium.cr/Sodium/CryptoBox/PublicKey.html) .encrypt | I want anonymously send encrypted data. (No signatures) |
-| [`Sodium::Sign::SecretKey`](https://didactic-drunk.github.io/sodium.cr/Sodium/Sign/SecretKey.html) | I want to sign or verify messages without encryption. |
+| [`Sodium::Sign::SecretKey`](https://didactic-drunk.github.io/sodium.cr/Sodium/Sign/SecretKey.html) | I want to sign or verify messages. (No encryption) |
 | [`Sodium::SecretBox`](https://didactic-drunk.github.io/sodium.cr/Sodium/SecretBox.html) | I have a shared key and want to encrypt + authenticate data. |
-| AEAD | I have a shared key and want encrypt + authenticate streamed data. (Not implemented yet) |
+| [`Sodium::Cipher::SecretStream`](https://didactic-drunk.github.io/sodium.cr/Sodium/Cipher/SecretStream/XChaCha20Poly1305.html), AEAD | I have a shared key and want encrypt + authenticate streamed data. |
 | [`Sodium::Digest::Blake2b`](https://didactic-drunk.github.io/sodium.cr/Sodium/Digest::Blake2b.html) | I want to hash data fast and securely. |
 | `Sodium::Digest::SipHash` | I want to hash data really fast and less securely. (Not implemented yet) |
-| `Sodium::Pwhash` | I want to hash a password and store it. |
+| [`Sodium::Pwhash`](https://didactic-drunk.github.io/sodium.cr/Sodium/Pwhash.html) | I want to hash a password and store it. |
-| `Sodium::Pwhash` | I want to derive a key from a password. |
+| [`Sodium::Pwhash`](https://didactic-drunk.github.io/sodium.cr/Sodium/Pwhash.html) | I want to derive a key from a password. |
-| `Sodium::Kdf` | I have a high quality master key and want to make subkeys. |
+| [`Sodium::Kdf`](https://didactic-drunk.github.io/sodium.cr/Sodium/Kdf.html) | I have a high quality master key and want to make subkeys. |
 | [`Sodium::Cipher::Chalsa`](https://didactic-drunk.github.io/sodium.cr/Sodium/Cipher/Chalsa.html) | What goes with guacamole? |
 | Everything else | I want to design my own crypto protocol and probably do it wrong. |
 

src/sodium/cipher/cipher.cr

@@ -0,0 +1,3 @@
+# Use Sodium::Cipher::SecretStream::XChaCha20Poly1305 or SecretBox
+module Sodium::Cipher
+end

src/sodium/cipher/secret_stream.cr

@@ -79,9 +79,9 @@ module Sodium::Cipher
     # [Libsodium Secret Stream API](https://libsodium.gitbook.io/doc/secret-key_cryptography/secretstream)
     #
     # This class mimicks the OpenSSL::Cipher interface with minor differences.
+    # * every .update is it's own authenticated message.  Unlike OpenSSL this class doesn't buffer data.  You must handle the framing yourself.
     # * .header must be called for encryption before calling .update
     # * .header= must be called for decryption with the data returned from .header before calling .update
-    # * every .update is it's own authenticated message.  Unlike OpenSSL this class doesn't buffer data.  You must handle the framing yourself.
     # * A tag may be set before encrypting and is set after calling .update when decrypting.
     # * .additional may be set before encrypting and must be set before decrypting.
     #

src/sodium/kdf.cr

@@ -5,7 +5,6 @@ require "./wipe"
 module Sodium
   # Key derivation function
   #
-  # WARNING: This class takes ownership of any key material passed to it.
   # Read **each** constructor WARNING for differences in usage.
   #
   # Usage:
@@ -25,7 +24,8 @@ module Sodium
 
     # Use an existing KDF key.
     #
-    # Optionally erases bytes after copying if erase is set
+    # * Copies key to a new SecureBuffer
+    # * Optionally erases bytes after copying if erase is set
     def initialize(bytes : Bytes, erase = false)
       if bytes.bytesize != KEY_SIZE
         raise ArgumentError.new("bytes must be #{KEY_SIZE}, got #{bytes.bytesize}")
@@ -35,9 +35,6 @@ module Sodium
     end
 
     # Use an existing KDF SecureBuffer key.
-    #
-    # WARNING: This class takes ownership of any key material passed to it.
-    # If you don't want this behavior pass a duplicate of the key to initialize().
     def initialize(@sbuf : SecureBuffer)
       if @sbuf.bytesize != KEY_SIZE
         raise ArgumentError.new("bytes must be #{KEY_SIZE}, got #{sbuf.bytesize}")

src/sodium/secret_box.cr

@@ -5,8 +5,6 @@ require "./nonce"
 module Sodium
   # [https://libsodium.gitbook.io/doc/secret-key_cryptography](https://libsodium.gitbook.io/doc/secret-key_cryptography)
   #
-  # WARNING: This class takes ownership of any key material passed to it.
-  # If you don't want this behavior pass a duplicate of the key/seed to initialize().
   #
   # ```crystal
   # key = Sodium::SecretBox.new

src/sodium/sign/secret_key.cr

@@ -5,7 +5,6 @@ require "./public_key"
 module Sodium
   # Key used for signing/verification only.
   #
-  # WARNING: This class takes ownership of any key material passed to it.
   # If you don't want this behavior pass a duplicate of the key/seed to initialize().
   #
   # Usage: