From fc60839d5b1646525d9451fc2d9dd82fe5774e34 Mon Sep 17 00:00:00 2001 From: Didactic Drunk <1479616+didactic-drunk@users.noreply.github.com> Date: Tue, 9 Jul 2019 00:42:56 -0700 Subject: [PATCH] Documentation. --- README.md | 12 ++++++------ src/sodium/cipher/cipher.cr | 3 +++ src/sodium/cipher/secret_stream.cr | 2 +- src/sodium/kdf.cr | 7 ++----- src/sodium/secret_box.cr | 2 -- src/sodium/sign/secret_key.cr | 1 - 6 files changed, 12 insertions(+), 15 deletions(-) create mode 100644 src/sodium/cipher/cipher.cr diff --git a/README.md b/README.md index 1dcc99a..1d3cce2 100644 --- a/README.md +++ b/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::Sign::SecretKey`](https://didactic-drunk.github.io/sodium.cr/Sodium/Sign/SecretKey.html) | I want to sign or verify messages without encryption. | +| [`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. (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` | I want to derive a key from a password. | -| `Sodium::Kdf` | I have a high quality master key and want to make subkeys. | +| [`Sodium::Pwhash`](https://didactic-drunk.github.io/sodium.cr/Sodium/Pwhash.html) | I want to hash a password and store it. | +| [`Sodium::Pwhash`](https://didactic-drunk.github.io/sodium.cr/Sodium/Pwhash.html) | I want to derive a key from a password. | +| [`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. | diff --git a/src/sodium/cipher/cipher.cr b/src/sodium/cipher/cipher.cr new file mode 100644 index 0000000..b94c741 --- /dev/null +++ b/src/sodium/cipher/cipher.cr @@ -0,0 +1,3 @@ +# Use Sodium::Cipher::SecretStream::XChaCha20Poly1305 or SecretBox +module Sodium::Cipher +end diff --git a/src/sodium/cipher/secret_stream.cr b/src/sodium/cipher/secret_stream.cr index 085e408..5525de6 100644 --- a/src/sodium/cipher/secret_stream.cr +++ b/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. # diff --git a/src/sodium/kdf.cr b/src/sodium/kdf.cr index a8fc754..2be7b4f 100644 --- a/src/sodium/kdf.cr +++ b/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}") diff --git a/src/sodium/secret_box.cr b/src/sodium/secret_box.cr index bf50a47..4f2ea34 100644 --- a/src/sodium/secret_box.cr +++ b/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 diff --git a/src/sodium/sign/secret_key.cr b/src/sodium/sign/secret_key.cr index fb730fd..465552d 100644 --- a/src/sodium/sign/secret_key.cr +++ b/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: