From 65b12cddd94dd7499e5b52d112ec348d22fe4b21 Mon Sep 17 00:00:00 2001 From: Didactic Drunk <1479616+didactic-drunk@users.noreply.github.com> Date: Sat, 29 Jun 2019 19:49:57 -0700 Subject: [PATCH] Documentation. --- src/sodium/crypto_box/secret_key.cr | 4 +++- src/sodium/digest/blake2b.cr | 12 +++++++----- src/sodium/kdf.cr | 27 ++++++++++++++++++++------- src/sodium/secret_box.cr | 3 +++ src/sodium/sign/secret_key.cr | 5 +++++ 5 files changed, 38 insertions(+), 13 deletions(-) diff --git a/src/sodium/crypto_box/secret_key.cr b/src/sodium/crypto_box/secret_key.cr index bf6ec18..b05a78f 100644 --- a/src/sodium/crypto_box/secret_key.cr +++ b/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 diff --git a/src/sodium/digest/blake2b.cr b/src/sodium/digest/blake2b.cr index 63aa5cb..c206cd2 100644 --- a/src/sodium/digest/blake2b.cr +++ b/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 diff --git a/src/sodium/kdf.cr b/src/sodium/kdf.cr index c67516f..2cc0430 100644 --- a/src/sodium/kdf.cr +++ b/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 diff --git a/src/sodium/secret_box.cr b/src/sodium/secret_box.cr index 86f2549..e1122e4 100644 --- a/src/sodium/secret_box.cr +++ b/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" diff --git a/src/sodium/sign/secret_key.cr b/src/sodium/sign/secret_key.cr index 3222481..db7700c 100644 --- a/src/sodium/sign/secret_key.cr +++ b/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