Description

Deimos binding to libsodium xor wrapper

Package Information

Version0.1.2 (2017-Apr-10)
Homepage https://github.com/carblue/sodium
Repository https://github.com/carblue/sodium
LicenseISC license
CopyrightCopyright © 2017-, Carsten Blüggel
AuthorsCarsten Blüggel
Registered byCarsten Blüggel
Sub packages
sodium:deimos
sodium:wrapper
Dependencies

sodium:deimos

Installation

To use this package, put the following dependency into your project's dependencies section:

dub.json
dub.sdl

Readme

Build state

Build Status Coverage Status

sodium

Twofold binding to libsodium, current C-source version 1.0.12, released on Mar 12, 2017 [https://github.com/jedisct1/libsodium]

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

dub.json sets dependency sodium:deimos as default. For the 'wrapper' subPackage, explicitely choose dependency: sodium:wrapper

Some restructuring (subPackages)/changing importPath and sourcePath was done for version 0.1.0 (different from previous 0.08) in order to have the 'wrapper' subPackage sit aside subPackage 'deimos'.
Thus code that already used versions<0.1.0 needs to replace 'import sodium...' by either 'import deimos.sodium...' or 'import wrapper.sodium...'.

Maybe, usage of 'wrapper' isn't possible, if function randombytessetimplementation shall be used (or maybe (I did't test that) there is a way to use it before this runs: wrapper.sodium.core:shared static this(), which calls sodium_init()). The unittests of subPackage 'wrapper' include a lot of function usage examples, the next is a simple application example based on sodium:deimos, using rdmd:

cd example/source  &&  chmod 775 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]
cryptoaeadaes256gcmisavailable
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.
The case is different, more complex with sodium:wrapper: It shall provide more D-convenience and @safe callables making it hard to use functions in a wrong way, but this may involve the heap allocation's cost.

  1. The unittests make permissive use of heap allocations by means of GC allocated memory, but don't handle real secrets and aren't meant for release builds, thus no security problem.
  2. Most new functions are "overloads" (just D friendly wrappers around the C function calls).
    Some are as simple as taking a D slice and pass it's .ptr and .length to be safe or require a static array to ensure .length, thus don't themselves allocate heap memory and have attribute @nogc (and calling them doesn't postulate heap allocation either; the D slice parameter is welcoming arguments being static arrays as well as dyn. heap allocated arrays).
    Many functions call enforce to ensure, that some requirement is fullfilled, thus may allocate only just before the program bails out.
    The residual: They use heap allocation !
  3. Other functions perform convenience procedures or part of procedures shown in the Sodium documentaion, like DH keyexchange and may make generous use of heap memory.

Available versions

0.1.2 0.1.1 0.1.0 0.0.8 0.0.7 0.0.6 0.0.5 0.0.4 0.0.3 0.0.2 0.0.1 ~master