![Soda](assets/logo-xsmall.png) Soda [![Hex Version](https://img.shields.io/hexpm/v/soda.svg)](https://hex.pm/packages/soda) [![Gitlab-CI](https://gitlab.com/starbelly/soda/badges/master/pipeline.svg)](https://gitlab.com/starbelly/soda/commits/master) [![Travis-CI](https://travis-ci.org/starbelly/soda.svg?branch=master)](https://travis-ci.org/starbelly/soda) (https://gitlab.com/starbelly/soda/commits/master) [![License](https://img.shields.io/badge/License-MIT-blue.svg)]()
============

Libsodium bindings for Erlang

## About

Soda provides Erlang bindings to the Sodium Crypto Library ([libsodium](https://download.libsodium.org/doc/)).

Working with Soda is simple in both Erlang and Elixr.

- ***Erlang***
```erlang
1> N = soda:nonce(aead_xchacha20poly1305_ietf).
<<115,97,120,157,28,208,118,165,137,95,122,152,195,49,52,
  188,73,136,216,201,77,183,29,144>>
2> {ok, H} = soda:password_hash("foo").
{ok,<<"$argon2id$v=19$m=65536,t=2,p=1$Isq7U9BICzjQKL7HhrpdtA$8WEFXpc6a3ef+DMZELmmxA23xTCQq9CpN6/NPHXBUPg">>}
2> true = soda:password_verify(H, "foo").
true
```

- ***Elixir***
```elixir
iex(1)> n = :soda.nonce(:aead_xchacha20poly1305_ietf)
<<115,97,120,157,28,208,118,165,137,95,122,152,195,49,52,
  188,73,136,216,201,77,183,29,144>>
iex(2)> {:ok, h} = :soda.password_hash("foo")
{:ok,<<"$argon2id$v=19$m=65536,t=2,p=1$Isq7U9BICzjQKL7HhrpdtA$8WEFXpc6a3ef+DMZELmmxA23xTCQq9CpN6/NPHXBUPg">>}
iex(3)> true = :soda.password_verify(h, "foo")
true
```

## Installation

### Rebar3

```erlang
{deps, [{soda, "1.0.1"}]}
```

### Mix

```elixir
def deps do
  [{:soda, "~> 1.0.1"}]
end
```

## Usage

### Soda

#### nonce/1 

```erlang
1> N = soda:nonce(aead_xchacha20poly1305_ietf).
<<115,97,120,157,28,208,118,165,137,95,122,152,195,49,52,
  188,73,136,216,201,77,183,29,144>>
```

#### rand/1

```erlang
soda:rand(42).
<<83,247,61,202,83,171,99,56,51,108,141,82,255,186,41,26,
  215,4,229,148,72,204,131,248,8,86,196,104,95,...>>
```

#### password_hash/1 and password_verify/2

```erlang
1> {ok, H} = soda:password_hash("thuper thecret").
{ok,<<"$argon2id$v=19$m=65536,t=2,p=1$rPQCfeJLuKMoLei+d5o9uA$7LsyBNEnYVq2JOpTgD2cil+swou5gvewoEjcuQznYq0">>}
2> true = soda:password_verify(H, "thuper thecret").
true
```

##### aead_encrypt/2 and aead_decrypt/4

```erlang
1> {ok, Ciphered, Nonce, Key} = soda:aead_encrypt(<<"Secret Msg">>, <<"Additional Data">>).
{ok,<<183,123,21,95,51,26,85,197,41,226,96,91,26,28,16,
      110,85,123,18,239,29,57,11,30,228,61>>,
    <<238,32,82,106,137,223,37,173,68,177,216,210,169,168,126,
      245,10,247,27,161,127,195,217,24>>,
    <<8,108,139,115,235,95,95,44,128,74,18,186,2,207,2,83,79,
      53,115,239,12,118,198,100,198,...>>}
2> soda:aead_decrypt(Ciphered, <<"Additional Data">>, Nonce, Key).
{ok,<<"Secret Msg">>}
```

### Soda API

 For advanced usage soda provides soda_api

#### AEAD constructions

##### XChaCha20-Poly1305 construction

1. Generate a public nonce
```erlang
1> N = soda_api:randombytes(24).
<<115,97,120,157,28,208,118,165,137,95,122,152,195,49,52,
  188,73,136,216,201,77,183,29,144>>
```

2. Generate a secret key using the soda_api module
```erlang
2> K = soda_api:aead_xchacha20poly1305_ietf_keygen().
<<234,19,163,89,73,193,122,110,11,196,215,227,56,193,126,
  110,228,27,49,107,19,123,43,168,255,60,92,13,49,...>>
```

3. Encrypt a message with some non-confidential additional data and our secret key and nonce
```erlang
3> C = soda_api:aead_xchacha20poly1305_ietf_encrypt(<<"Hello, Mike?">>, <<"Hello, Joe.">>, N, K ).
<<218,218,199,94,171,25,110,199,107,224,186,225,52,248,
  185,1,53,39,16,167,91,24,155,31,143,195,89,87>>
```

4. Decrypt the ciphered message using our additional data, nonce, and key
```erlang
4> D = soda_api:aead_xchacha20poly1305_ietf_decrypt(C, <<"Hello, Joe.">>, N, K).
<<"Hello, Mike?">>
```

## Reference

 - [libsodium](https://download.libsodium.org/doc/)

## Inspirado

- [jlouis/enacl](https://github.com/jlouis/enacl)