pwbox is a JS library for password-based encryption. It is similar to
NaCl/libsodium's built-in secretbox
, only it implements
encryption based on passwords rather on secret keys.
Behind the scenes, pwbox uses crypto-primitves from NaCl/libsodium:
pwhash_scryptsalsa208sha256
for key derivationsecretbox
routines for key-based symmetric encryption
Security Notice. Use this software at your own risk. You should think carefully before using this (or any other) software to ensure browser-based client-side security; browser environments are somewhat unsecure.
Import pwbox to your project:
var pwbox = require('pwbox');
...and use it similarly to secretbox
in TweetNaCl.js:
var password = 'pleaseletmein';
var message = new Uint8Array([ 65, 66, 67 ]);
pwbox(message, password).then(box => {
console.log(box);
return pwbox.open(box, password);
}).then(opened => {
console.log(opened);
});
pwbox
(encryption routine) and pwbox.open
(decryption routine) are asynchronous;
they support either callbacks or promises.
See the API docs for more details.
The same example as above, with callbacks.
var password = 'pleaseletmein';
var message = new Uint8Array([ 65, 66, 67 ]);
pwbox(message, password, function (err, box) {
console.log(box);
pwbox.open(box, password, function (err, opened) {
console.log(opened);
});
});
You may also invoke pwbox
and pwbox.open
with a single-argument callback.
Just use .orFalse
after the call:
var box = // ...
pwbox.open.orFalse(box, password, function (opened) {
if (!opened) {
// do error handling
return;
}
// use opened
});
In this case, the callback will be called with false
if an error occurs during the call.
pwbox requires for a message to be a Uint8Array
instance. This means you can
encrypt binary data (e.g., private keys) without any conversion. If you want
to encrypt string data, you need to convert it to Uint8Array
. This can be
accomplished in several ways.
Node has Buffer.from(str, encoding)
method
and its older version, new Buffer(str, encoding)
to
convert from strings to byte buffers.
For the complementary operation, you may use buffer.toString(encoding)
.
These methods are also available
via the buffer
package in browser environments. As Buffer
s
inherit from Uint8Array
, you may freely pass them as messages.
Browsers can also use
built-in enodeURIComponent
and decodeURIComponent
methods for the conversion:
function toUint8Array (str) {
str = unescape(encodeURIComponent(str));
var buffer = new Uint8Array(str.length);
for (var i = 0; i < buffer.length; i++) {
buffer[i] = str[i].charCodeAt(0);
}
return buffer;
}
function fromUint8Array (buffer) {
var encodedString = String.fromCharCode.apply(null, buffer);
var decodedString = decodeURIComponent(escape(encodedString));
return decodedString;
}
Tip. Although it's not strictly necessary, you may convert the password into a
Uint8Array
in the same way as the message.
pwbox supports tuning the scrypt parameters using opslimit
and memlimit
from
libsodium. These parameters determine the amount of computations and
the RAM usage, respectively, for pwbox
and pwbox.open
.
pwbox(message, password, {
opslimit: 1 << 20, // 1M
memlimit: 1 << 25 // 32M
}).then(box => console.log(box));
The default values for opslimit
and memlimit
are also taken from libsodium
(524288
and 16777216
, respectively). With the default parameters, pwbox
uses 16 MB of RAM and completes
with a comfortable 100ms delay in Node, several hundred ms in browsers
on desktops/laptops, and under a second on smartphones.
You may use increased parameter values for better security;
see the crypto spec for more details.
pwbox may use one of the following cryptographic backends:
- libsodium-wrappers-sumo
- tweetnacl + scrypt-async (default)
To use a non-default backend, call pwbox.withCrypto
with 'tweetnacl'
or 'libsodium'
; it will return the
object with the same interface as pwbox
itself.
var sodiumPwbox = require('pwbox').withCrypto('libsodium');
sodiumPwbox(message, password).then(/* ... */);
You may even supply your own backend by passing an object to withCrypto
!
See documentation for more details.
require('pwbox/lite')
loads a simplified version of pwbox, which
uses a fixed backend (tweetnacl + scrypt-async) and has no withCrypto
function.
This is the preferred way to use pwbox in browsers, as the full version
of the librabry is quite bulky. You may use 'pwbox/lite'
together with
your favorite browserifier (say, browserify
or webpack
), or
import a readymade browserified and minified lite package directly
from the dist directory of the package.
Copyright (c) 2017, Exonum Team
pwbox is licensed under Apache 2.0 license.