Documentation additions [ci skip]

master
Didactic Drunk 2019-06-26 21:10:42 -07:00
parent a5d1d14297
commit 3a078523f5
1 changed files with 36 additions and 6 deletions

View File

@ -8,7 +8,8 @@ receipt, they can decrypt and authenticate the message as having come from you.
## Installation ## Installation
**[Install libsodium](https://download.libsodium.org/doc/installation/)**, then: **[Optionally Install libsodium.](https://download.libsodium.org/doc/installation/)**
A recent version of libsodium is automatically downloaded and compiled if you don't install your own version.
Add this to your application's `shard.yml`: Add this to your application's `shard.yml`:
@ -18,6 +19,35 @@ dependencies:
github: didactic-drunk/cox github: didactic-drunk/cox
``` ```
## Features
- Public-Key Cryptography
- [x] Crypto Box Easy
- [ ] Sealed Box
- [x] Combined Signatures
- [x] Detached Signatures
- Secret-Key Cryptography
- [x] Secret Box
- [ ] Salsa20
- [ ] XSalsa20
- [ ] ChaCha20
- [ ] XChaCha20
- Hashing
- [x] Blake2b
- [ ] SipHash
- Password Hashing
- [x] Argon2 (Use for new applications)
- [ ] Scrypt (For compatibility with older applications)
- Other
- [x] Key Derivation
- [ ] One time auth
Several libsodium API's are already provided by Crystal:
* SHA-2 (Use [OpenSSL::Digest](https://crystal-lang.org/api/latest/OpenSSL/Digest.html))
* HMAC SHA-2 (Use [OpenSSL::HMAC](https://crystal-lang.org/api/latest/OpenSSL/HMAC.html))
* Random (Use [Random::Secure](https://crystal-lang.org/api/latest/Random/Secure.html))
## Usage ## Usage
```crystal ```crystal
@ -42,7 +72,7 @@ decrypted = Cox.decrypt(encrypted, nonce, alice.public, bob.secret)
String.new(decrypted) # => "Hello World!" String.new(decrypted) # => "Hello World!"
``` ```
## Public key signing ### Public key signing
```crystal ```crystal
message = "Hello World!" message = "Hello World!"
@ -55,7 +85,7 @@ signature = Cox.sign_detached(message, signing_pair.secret)
Cox.verify_detached(signature, message, signing_pair.public) # => true Cox.verify_detached(signature, message, signing_pair.public) # => true
``` ```
## Secret Key Encryption ### Secret Key Encryption
```crystal ```crystal
key = Cox::SecretKey.random key = Cox::SecretKey.random
@ -67,7 +97,7 @@ key = Cox::SecretKey.new key
message = key.decrypt_easy encrypted, nonce message = key.decrypt_easy encrypted, nonce
``` ```
## Blake2b ### Blake2b
```crystal ```crystal
key = Bytes.new Cox::Blake2B::KEY_SIZE key = Bytes.new Cox::Blake2B::KEY_SIZE
salt = Bytes.new Cox::Blake2B::SALT_SIZE salt = Bytes.new Cox::Blake2B::SALT_SIZE
@ -85,7 +115,7 @@ digest.update data
output = d.hexdigest output = d.hexdigest
``` ```
## Key derivation ### Key derivation
```crystal ```crystal
kdf = Cox::Kdf.new kdf = Cox::Kdf.new
@ -96,7 +126,7 @@ subkey3 = kdf.derive "context2", 32, 0
subkey4 = kdf.derive "context2", 64, 1 subkey4 = kdf.derive "context2", 64, 1
``` ```
## Password Hashing ### Password Hashing
```crystal ```crystal
pwhash = Cox::Pwhash.new pwhash = Cox::Pwhash.new