Documentation.

src/sodium/crypto_box/secret_key.cr

@@ -1,6 +1,8 @@
 require "../lib_sodium"
 
 module Sodium::CryptoBox
+  # Key used for encryption + authentication or encryption without authentication, not for unencrypted signing.
+  #
   # 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().
   class SecretKey < Key
@@ -65,7 +67,7 @@ module Sodium::CryptoBox
       end
     end
 
-    # Anonymously receive messages without signatures.
+    # Anonymously receive messages without a signatures.
     # For authenticated messages use `secret_key.box(recipient_public_key).decrypt`.
     def decrypt(src)
       encrypt src.to_slice

src/sodium/digest/blake2b.cr

@@ -5,11 +5,6 @@ module Sodium::Digest
   #
   # Compatible with the Crystal OpenSSL::Digest interface.
   #
-  # digest_size is selectable.  Use 32 for Blake2b256 (libsodium default), 64 for Blake2b512
-  # or any value between OUT_SIZE_MIN and OUT_SIZE_MAX.  Many libsodium bindings only support [256] or [256 and 512] bit output.
-  #
-  # `key`, `salt`, and `personal` are all optional in the constructor.  Most other libsodium bindings don't support them.
-  #
   # Usage:
   # ```
   # digest = Blake2b.new
@@ -46,6 +41,13 @@ module Sodium::Digest
     @salt = StaticArray(UInt8, 16).new 0
     @personal = StaticArray(UInt8, 16).new 0
 
+    # Create a new Blake2b Digest.
+    #
+    # digest_size is selectable.  Use 32 for Blake2b256 (libsodium default), 64 for Blake2b512
+    # or any value between OUT_SIZE_MIN and OUT_SIZE_MAX.  Many libsodium bindings only support [256] or [256 and 512] bit output.
+    #
+    # `key`, `salt`, and `personal` are all optional.  Most other libsodium bindings don't support them.
+    # Check the other implementation(s) you need to interoperate with before using.
     def initialize(@digest_size : Int32 = OUT_SIZE, key : Bytes? = nil, salt : Bytes? = nil, personal : Bytes? = nil)
       if k = key
         raise ArgumentError.new("key larger than KEY_SIZE_MAX(#{KEY_SIZE_MAX}), got #{k.bytesize}") if k.bytesize > KEY_SIZE_MAX

src/sodium/kdf.cr

@@ -2,11 +2,23 @@ require "./lib_sodium"
 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:
+  # ```
+  # kdf = KDF.new
+  # subkey_id = 0
+  # output_size = 16
+  # subkey = kdf.derive "8bytectx", subkey_id, output_size
+  # ```
   class Kdf
     include Wipe
 
-    KDF_KEY_SIZE     = LibSodium.crypto_kdf_keybytes
-    KDF_CONTEXT_SIZE = LibSodium.crypto_kdf_contextbytes
+    KEY_SIZE     = LibSodium.crypto_kdf_keybytes
+    CONTEXT_SIZE = LibSodium.crypto_kdf_contextbytes
 
     @[Wipe::Var]
     getter bytes : Bytes
@@ -18,8 +30,8 @@ module Sodium
     # 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(bytes : Bytes)
-      if bytes.bytesize != KDF_KEY_SIZE
-        raise ArgumentError.new("bytes must be #{KDF_KEY_SIZE}, got #{bytes.bytesize}")
+      if bytes.bytesize != KEY_SIZE
+        raise ArgumentError.new("bytes must be #{KEY_SIZE}, got #{bytes.bytesize}")
       end
 
       @bytes = bytes
@@ -31,7 +43,7 @@ module Sodium
     #
     # Make sure to save kdf.bytes before kdf goes out of scope.
     def initialize
-      @bytes = Random::Secure.random_bytes(KDF_KEY_SIZE)
+      @bytes = Random::Secure.random_bytes(KEY_SIZE)
     end
 
     # Derive a consistent subkey based on `context` and `subkey_id`.
@@ -41,8 +53,9 @@ module Sodium
     # * subkey_size must be 16..64 bytes as of libsodium 1.0.17
     #
     def derive(context, subkey_id, subkey_size)
-      if context.bytesize != KDF_CONTEXT_SIZE
-        raise ArgumentError.new("context must be #{KDF_CONTEXT_SIZE}, got #{context.bytesize}")
+      context = context.to_slice
+      if context.bytesize != CONTEXT_SIZE
+        raise ArgumentError.new("context must be #{CONTEXT_SIZE}, got #{context.bytesize}")
       end
 
       subkey = Bytes.new subkey_size

src/sodium/secret_box.cr

@@ -3,6 +3,9 @@ require "./lib_sodium"
 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::SecretKey.new
   # message = "foobar"

src/sodium/sign/secret_key.cr

@@ -1,6 +1,11 @@
 require "../lib_sodium"
 
 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:
   # ```
   # key = SecretKey.new