sodium ~master

Build state

sodium

Twofold binding to libsodium, a modern, portable, easy to use crypto library; support of current libsodium version v1.0.18, released May 31, 2019.

subPackage deimos: The "import-only" C header's declarations.
subPackage wrapper: The content of deimos + some 'D-friendly' stuff, predominantly overloaded functions and unittests.

The dependency name is either sodium:deimos or sodium:wrapper (for dub build|test simply: :deimos or :wrapper)

IMPORTANT NOTICE
deimos/dub.json and wrapper/dub.json set as default: "versions": ["bin_v1_0_18", "SODIUM_LIBRARY_MINIMAL"]

1. If the binary to link against is not compiled with ./configure --enable-minimal and You want to use the low-level functions, then remove
   , "SODIUM_LIBRARY_MINIMAL"
   from "versions".
2. If not linking against v1.0.18 binary libsodium.so/.dll/.dylib, it's required to specify/change that in deimos/dub.json and wrapper/dub.json:
   In the past while I maintained this binding, it was kind of independent from binary libsodium versions: The last binding release supporting headers of libsodium 1.016 could be used with a binary versioned e.g. 1.014, 1.016 (or probably 1.018, actually not possible), because in C headers (so far) only functions where added, and the compiler/linker would complain, if (new) functions not available from the (older) binary/import library should be called. This also holds for Windows, if You don't trick the compiler with a non-associated pair of import .lib/binary .dll.
   Now for the first time (since v1.0.17) a constant changed it's value as well as a struct size change occured and the easy times are gone.
   This is solved by conditional compilation, which is guided by the following version identifiers, one of which - the correct one matching the binary - must be used: bin_v1_0_18, bin_v1_0_17 or bin_v1_0_16 (bin_v1_0_16 subsumes any libsodium binary version lower than v1.0.16 as well). The dub.json s set bin_v1_0_18 as default, stating the binary version v1.0.18 expected to link against.

A version mismatch of binding-adaption and libsodium binary can do any harm as undefined behavior can do, like memory corruption or worse, a SIGSEGV in the best case.

(The versioning of this binding doesn't matter here, but to make things more intuitive, it'll change to reflect the latest (libsodium C source) header version covered, the next/this will be something like 1.0.18-alpha.1).

wrapper is based on DIP1008/compiler switch -dip1008; this rules out the gdc compiler currently (I didn't find any info about that). dmd/ldc support it since 2.078.3.
DIP1008 is the enabling feature used for @nogc exceptions, implemented via dependency package nogc.
wrapper also supports usage of -dip1000 (includes -dip25). dub build|test :wrapper --config=travis uses that but it's not set as default for any other configuration.
END_NOTICE

wrapper aims at providing at least the same functionality as deimos and provide @trusted @nogc (possibly also pure nothrow) 'D-friendly' alternatives, that are hard to use in a wrong way; [WIP]:
a) 'wrapper' is a superset of 'deimos' in that everything from 'deimos' is reachable, but deliberately not all at your fingertips.
b) all new functions with 'deimos-functionality' have the same name as their 'deimos'-cousins and call them, building either overload sets to choose from, or for parameter-less functions, 'substituting' their cousins.
c) all new functions calculating a variable-length output are restrictive referring to the size of the output-buffer offered, if the required size can be easily known/computed in advance, throwing (a NoGcException) in case of wrong-sized buffers.
This way, if a function succeeds, all output-buffer.length bytes are meaningful and no additional/'deimos'-like function out parameter carrying the meaningful length information is required.
d) Exceptions thrown while checking valid function arguments are NOT allocated by GC, enabling @nobc attribue usage.
e) No need to explicitely call sodiuminit() up-front (wrapper.sodium.core:shared static this() calls it).
f) A few functions with int return type expressing true or false have bool return type in 'wrapper'.
g) Usage of 'wrapper' isn't possible, if function `randombytesset_implementation` shall be used.

The unittests of subPackage 'wrapper' include a lot of function usage examples; the next is a simple application example, using rdmd and file cmdfile, suitable as is for Linux with libsodium.so available (otherwise example/source/cmdfile and/or first line of app.d might need adaption):

$ cd example/source && chmod +x app.d && ./app.d

Expected output (byte values within brackets differing of course):

Unpredictable sequence of 8 bytes: [52, 225, 21, 245, 74, 66, 192, 247]
crypto_aead_aes256gcm_is_available
ciphertext: [76, 18, 112, 219, 144, 230, 206, 219, 40, 255, 78, 43, 172, 49, 129, 175, 4, 235, 81, 224]

Heap allocations: Quoting the Sodium-manual: "Cryptographic operations in Sodium (C binary) never allocate memory on the heap (malloc, calloc, etc.) with the obvious exceptions of cryptopwhash and sodiummalloc."
The same holds, if usage is restricted to sodium:deimos and also holds for many (@nogc) functions of sodium:wrapper.