QPQ-AG/enacl
10
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Quick run over documentation

Browse Source
This commit is contained in:
Jesper Louis Andersen 2021-06-22 14:03:50 +02:00
parent ec64b0de73
commit 47ff11e956
1 changed files with 25 additions and 36 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

61
README.md
View File

@ -6,41 +6,37 @@ Frank Denis took the source and made it far more portable in the
libsodium library. The enacl project is somewhat misnamed, as it uses libsodium library. The enacl project is somewhat misnamed, as it uses
libsodium as the underlying driver. libsodium as the underlying driver.
## INSTALL/Requirements: ## INSTALL/Requirements
* Erlang/OTP above 17.3. This library *needs* the dirty scheduler * New-ish Erlang installation. Tested back to version 22.3, but version 21 *may*
implementation from 17.3 and onwards. The library relies on dirty work as well.
scheduler support in order to handle long-running cryptography jobs,
by moving them off the main Erlang scheduler and letting the dirty
schedulers handle the work. This keeps the Erlang VM responsive while
doing large amounts of cryptographic processing.
* Is tested with Erlang 22.3. Erlang version 21 *may* work, but that isn't
the current testing target.
* *Requires* the libsodium library, and has been tested with version * *Requires* the libsodium library, and has been tested with version
1.0.18. Lower versions might work, or they might fail to compile, 1.0.18. Lower versions might work, or they might fail to compile,
due to missing functionality. due to missing functionality. In particular, this means your libsodium installation
*Note:* If installing on systems which cuts packages into must be fairly recent as well.
subpackages, make sure you also get the "-dev" package containing
the header files necessary in order to compile software linking to *Note:* If installing on systems which cuts packages into
libsodium. subpackages, make sure you also get the "-dev" package containing
the header files necessary in order to compile software linking to
libsodium.
To build the software execute: To build the software execute:
make make
or or
rebar compile rebar compile
To build and run licensed eqc test execute: To build and run licensed eqc test execute:
make eqc_run make eqc_run
To build and run eqc-mini version of test execute: To build and run eqc-mini version of test execute:
make eqc_mini_run make eqc_mini_run
## Features: ## Features
* Complete NaCl library, implementing all default functionality. * Complete NaCl library, implementing all default functionality.
* Implements a large set of additional functionality from libsodium. * Implements a large set of additional functionality from libsodium.
@ -62,21 +58,17 @@ In addition, I would like to thank Steve Vinoski, Rickard Green, and
Sverker Eriksson for providing the Dirty Scheduler API in the first Sverker Eriksson for providing the Dirty Scheduler API in the first
place. place.
# USING: ## Usage
In general, consult the libsodium documentation at In general, consult the libsodium documentation at [Libsodium documentation](https://download.libsodium.org/doc/)
https://download.libsodium.org/doc/
The original NaCl documentation is nowadays largely superceded by the The original NaCl documentation is nowadays largely superceded by the
libsodium documentation, but it is still worth a visit libsodium documentation, but it is still worth a visit [NaCl website](https://nacl.cr.yp.to)
https://nacl.cr.yp.to
but also note that our interface has full Edoc documentation, but also note that our interface has full Edoc documentation,
generated by executing generated by executing
rebar3 doc rebar3 doc
## Hints ## Hints
@ -134,11 +126,11 @@ However, their correct use is still needed in order to be secure:
a foreign system as an oracle in order to learn the structure of a a foreign system as an oracle in order to learn the structure of a
string, breaking the cryptograhic system in the process. string, breaking the cryptograhic system in the process.
# Versions ## Versions
See CHANGELOG.md See CHANGELOG.md
# Overview ## Overview
The NaCl cryptographic library provides a number of different The NaCl cryptographic library provides a number of different
cryptographic primitives. In the following, we split up the different cryptographic primitives. In the following, we split up the different
@ -200,7 +192,7 @@ This implements cryptography where there is a shared secret key between parties.
* *String comparison:* Implements guaranteed constant-time string * *String comparison:* Implements guaranteed constant-time string
comparisons to protect against timing attacks. comparisons to protect against timing attacks.
# Rationale ## Rationale
Doing crypto right in Erlang is not that easy. For one, the crypto Doing crypto right in Erlang is not that easy. For one, the crypto
system has to be rather fast, which rules out Erlang as the main system has to be rather fast, which rules out Erlang as the main
@ -252,7 +244,7 @@ perhaps being able to switch faster. There are plans to rerun these
tests on OSX and Illumos as well, in order to investigate the numbers tests on OSX and Illumos as well, in order to investigate the numbers
on more platforms. on more platforms.
# Testing ## Testing
Every primitive has been stress-tested through the use of Erlang Every primitive has been stress-tested through the use of Erlang
QuickCheck with both *positive* and *negative* testing. This has been QuickCheck with both *positive* and *negative* testing. This has been
@ -279,11 +271,8 @@ sure we have no memory leaks as they will show themselves under the
extensive QuickCheck test cases we run. It has been verified there are extensive QuickCheck test cases we run. It has been verified there are
no leaks in the code. no leaks in the code.
# Notes ## Notes
[0] Other people have worked on bits and pieces of NaCl. These are [0] Other people have worked on bits and pieces of NaCl. These are
just the 3 main authors. Please see the page just the 3 main authors. Please see the page [NaCl](http://nacl.cr.yp.to)
http://nacl.cr.yp.to
for the full list of authors. for the full list of authors.