Baguette/sodium.cr
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Documentation.

Browse source
This commit is contained in:
Didactic Drunk 2019-07-09 00:42:56 -07:00
parent 96b215cf54
commit fc60839d5b
6 changed files with 12 additions and 15 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

12
README.md
View file

@ -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. |

3
src/sodium/cipher/cipher.cr Normal file
View file

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

2
src/sodium/cipher/secret_stream.cr
View file

@ -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.
#

7
src/sodium/kdf.cr
View file

@ -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}")

2
src/sodium/secret_box.cr
View file

@ -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

1
src/sodium/sign/secret_key.cr
View file

@ -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: