dart_sodium 2.0.0

dart_sodium is a wrapper library for the Sodium cryptography library (libsodium) written in C (https://libsodium.gitbook.io/). Below you find a list of covered libsodium apis and their counterparts in dart_sodium. Every api is wrapped inside its own mini library.

Secret-key cryptography #

topiclibsodium apidart_sodium lib
Authenticated encryptioncrypto_secretbox_*secret_box
Encrypted streamscrypto_secretstream_*secret_stream
Authenticationcrypto_auth_*auth

Public-key cryptography #

topiclibsodium apidart_sodium lib
Authenticated encryptioncrypto_box_*box
Public-key signaturescrypto_sign_*sign

Hashing #

topiclibsodium apidart_sodium lib
Generic hashcrypto_generichash_*generic_hash

Rest #

topiclibsodium apidart_sodium lib
Random datacrypto_randombytes_*random_bytes
Password hashingcrypto_pwhash_*pwhash

Not every api is fully covered yet. dart_sodium tries to resemble libsodium as much as possible while following Dart's conventions. To avoid repetition dart_sodium's api documentation is rather terse. For more information about apis and algorithms and when to use them I would recommend the libsodium documentation.

How to use #

Before calling any other function of dart_sodium, you should call

import 'package:dart_sodium/sodium.dart' as sodium;

void main(){
    sodium.init()
}

to initialize a suitable random number generator. You just need to do this once per application, not per isolate. Calling init() multiple times has no effect.

You have to install libsodium on your machine. If you use Linux or MacOS you can use the corresponding package manager to do that; in the case of Windows you have to manually copy the .dll into the System32 directory. Alternatively you could copy the shared library into the root directory of your application.

Examples #

Secret box #

final key = secret_box.keyGen();
final msg = utf8.encode('hello world');

final nonce = random_bytes.buffer(secret_box.nonceBytes);
final c = secret_box.easy(msg, nonce, key);

final decrypted = secret_box.openEasy(c, nonce, key);

Secret stream #

final key = secret_stream.keyGen();
final message = utf8.encode('hello world');
final message2 = utf8.encode('hello to the world');

final pushStream = secret_stream.PushStream(key);
final encChunk = pushStream.push(message);
final encChunk2 = pushStream.push(message2, tag: secret_stream.Tag.finalize);

final pullStream = secret_stream.PullStream(key, pushStream.header);
final decChunk = pullStream.pull(encChunk);
final decChunk2 = pullStream.pull(encChunk2);

Password hash #

final password = utf8.encode('my password');
final hash = pwhash.store(
    password, pwhash.OpsLimit.interactive, pwhash.MemLimit.interactive);
final isValid = pwhash.verify(hash, password);

Security #

Please keep in mind that when snapshotted, random_bytes might produce the same output (https://libsodium.gitbook.io/doc/generating_random_data#note).

Since Dart uses a garbage collector you should take measures against heap dump attacks. Be aware that keys and other sensitive information might be in memory for a long time. The GC can move memory around to optimize the layout (eg defragmentation), so overwriting sensitive information might not have the desired effect. In short: Only use dart_sodium on machines / platforms you fully trust and which take approrpiate measures to isolate them from the outside world. Don't use it for client software like a password manager.

example/example.dart

import 'dart:convert';

import 'package:dart_sodium/secret_box.dart' as secret_box;
import 'package:dart_sodium/random_bytes.dart' as random_bytes;
import 'package:dart_sodium/sodium.dart' as sodium;

void main(List<String> args) {
  sodium.init();
  final key = secret_box.keyGen();
  final msg = utf8.encode('hello world');

  final nonce = random_bytes.buffer(secret_box.nonceBytes);
  final c = secret_box.easy(msg, nonce, key);

  final decrypted = secret_box.openEasy(c, nonce, key);
}

Use this package as a library

1. Depend on it

Add this to your package's pubspec.yaml file:


dependencies:
  dart_sodium: ^2.0.0

2. Install it

You can install packages from the command line:

with pub:


$ pub get

with Flutter:


$ flutter pub get

Alternatively, your editor might support pub get or flutter pub get. Check the docs for your editor to learn more.

3. Import it

Now in your Dart code, you can use:


import 'package:dart_sodium/auth.dart';
import 'package:dart_sodium/box.dart';
import 'package:dart_sodium/generic_hash.dart';
import 'package:dart_sodium/helpers.dart';
import 'package:dart_sodium/password_hash.dart';
import 'package:dart_sodium/random_bytes.dart';
import 'package:dart_sodium/secret_box.dart';
import 'package:dart_sodium/secret_stream.dart';
import 'package:dart_sodium/sign.dart';
import 'package:dart_sodium/sodium.dart';
  
Popularity:
Describes how popular the package is relative to other packages. [more]
31
Health:
Code health derived from static analysis. [more]
100
Maintenance:
Reflects how tidy and up-to-date the package is. [more]
100
Overall:
Weighted score of the above. [more]
66
Learn more about scoring.

We analyzed this package on Apr 4, 2020, and provided a score, details, and suggestions below. Analysis was completed with status completed using:

  • Dart: 2.7.1
  • pana: 0.13.6

Dependencies

Package Constraint Resolved Available
Direct dependencies
Dart SDK >=2.6.0 <3.0.0
ffi ^0.1.3 0.1.3
ffi_helper ^1.0.0 1.4.0
meta ^1.1.8 1.1.8
Transitive dependencies
async 2.4.1
collection 1.14.12
Dev dependencies
benchmark_harness ^1.0.5
pedantic ^1.0.0
test ^1.0.0