From 95ee0e63b1cdde86b53fb26e2369a75e8e1179f2 Mon Sep 17 00:00:00 2001 From: Didactic Drunk <1479616+didactic-drunk@users.noreply.github.com> Date: Fri, 28 Jun 2019 13:26:31 -0700 Subject: [PATCH] Documentation. [skip ci] --- README.md | 55 ++++++++++++++++++++++++++++++++++++------------------- 1 file changed, 36 insertions(+), 19 deletions(-) diff --git a/README.md b/README.md index 267cb2a..666ec7e 100644 --- a/README.md +++ b/README.md @@ -6,41 +6,39 @@ Updated Crystal bindings for the [libsodium API](https://libsodium.gitbook.io/do ## Features -- Public-Key Cryptography - - [x] Crypto Box Easy - - [ ] Sealed Box - - [ ] Combined Signatures - - [x] Detached Signatures +- [Public-Key Cryptography](https://libsodium.gitbook.io/doc/public-key_cryptography) + - [x] [Crypto Box Easy](https://libsodium.gitbook.io/doc/public-key_cryptography/authenticated_encryption) + - [ ] [Sealed Box](https://libsodium.gitbook.io/doc/public-key_cryptography/sealed_boxes) + - [ ] [Combined Signatures](https://libsodium.gitbook.io/doc/public-key_cryptography/public-key_signatures) + - [x] [Detached Signatures](https://libsodium.gitbook.io/doc/public-key_cryptography/public-key_signatures) - [Secret-Key Cryptography](https://libsodium.gitbook.io/doc/secret-key_cryptography) - Secret Box - [x] [Combined mode](https://libsodium.gitbook.io/doc/secret-key_cryptography/authenticated_encryption) - - [ ] Detached mode - - Streaming - - [ ] XChaCha20 Poly1305 - - AEAD - - [ ] [AES256-GCM (Requires hardware acceleration)](https://libsodium.gitbook.io/doc/secret-key_cryptography/aead) - - [ ] XChaCha20-Poly1305-IETF - - [ ] ChaCha20-Poly1305-IETF - - [ ] ChaCha20-Poly1305 -- Hashing + - [ ] [Detached mode](https://libsodium.gitbook.io/doc/secret-key_cryptography/authenticated_encryption) + - [AEAD](https://libsodium.gitbook.io/doc/secret-key_cryptography/aead) + - [ ] AES256-GCM (Requires hardware acceleration) + - [ ] XChaCha20-Poly1305-IETF + - [ ] ChaCha20-Poly1305-IETF + - [ ] ChaCha20-Poly1305 +- [Hashing](https://libsodium.gitbook.io/doc/hashing) - [x] ☑ [Blake2b](https://libsodium.gitbook.io/doc/hashing/generic_hashing) - [ ] [SipHash](https://libsodium.gitbook.io/doc/hashing/short-input_hashing) - [Password Hashing](https://libsodium.gitbook.io/doc/password_hashing) - [x] [Argon2](https://libsodium.gitbook.io/doc/password_hashing/the_argon2i_function) (Use for new applications) - - [ ] Scrypt (For compatibility with older applications) + - [ ] [Scrypt](https://libsodium.gitbook.io/doc/advanced/scrypt) (For compatibility with older applications) - Other - [x] [Key Derivation](https://libsodium.gitbook.io/doc/key_derivation) - [ ] [Key Exchange](https://libsodium.gitbook.io/doc/key_exchange) -- Advanced - - Stream Ciphers +- [Advanced](https://libsodium.gitbook.io/doc/advanced0 + - [Stream Ciphers](https://libsodium.gitbook.io/doc/advanced/stream_ciphers) - [x] XSalsa20 - [x] Salsa20 - [x] XChaCha20 - [x] ChaCha20 Ietf - [x] ChaCha20 - - [ ] One time auth + - [ ] [One time auth](https://libsodium.gitbook.io/doc/advanced/poly1305) - [ ] Padding - - [?] Semi-automatic memory wiping. + - (Partial) Semi-automatic memory wiping. ☑ Indicate specs are compared against test vectors from another source. @@ -62,6 +60,25 @@ dependencies: github: didactic-drunk/cox ``` +## What should I use for my application? + +| Class | | +| --- | --- | +| `CryptoBox` `Sign` `SecretBox` | I don't know much about crypto. | +| `Cox::CryptoBox::PrivateKey` | I want to encrypt + authenticate data using public key encryption. | +| `Cox::Sign::PrivateKey` | I want to sign or verify messages without encryption. | +| `Cox::SecretBox` | 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) | +| `Cox::Blake2b` | I want to hash data fast and securely. | +| `Cox::SipHash` | I want to hash data really fast and less securely. (not implemented yet) | +| `Cox::Pwhash` | I want to hash a password and store it. | +| `Cox::Pwhash` | I want to derive a key from a password. | +| `Cox::Kdf` | I have a high quality master key and want to make subkeys. | +| `Cox::Cipher::Chalsa` | What goes with guacamole? | +| Everything else | I want to design my own crypto protocol and probably do it wrong. | + +The `specs` provide the best examples of how to use or misuse this shard. + ## Usage ### CryptoBox easy encryption