![Introducing Enhanced Alert Actions and Triage Functionality](https://cdn.sanity.io/images/cgdhsj6q/production/fe71306d515f85de6139b46745ea7180362324f0-2530x946.png?w=800&fit=max&auto=format)
Product
Introducing Enhanced Alert Actions and Triage Functionality
Socket now supports four distinct alert actions instead of the previous two, and alert triaging allows users to override the actions taken for all individual alerts.
libsodium-wrappers
Advanced tools
Readme
The sodium crypto library compiled to WebAssembly and pure Javascript using Emscripten, with automatically generated wrappers to make it easy to use in web applications.
The complete library weights 188 Kb (minified, gzipped, includes pure js + webassembly versions) and can run in a web browser as well as server-side.
Supported browsers/JS engines:
The dist directory contains pre-built scripts. Copy the files from one of its subdirectories to your application:
libsodium-wrappers
is the module your application should load, which
will in turn automatically load libsodium
as a dependency.The modules are also available on npm:
If you prefer Bower:
bower install libsodium.js
Load the sodium-wrappers
module. The returned object contains a .ready
property: a promise that must be resolve before the sodium functions
can be used.
Example:
const _sodium = require('libsodium-wrappers');
(async() => {
await _sodium.ready;
const sodium = _sodium;
let key = sodium.crypto_secretstream_xchacha20poly1305_keygen();
let res = sodium.crypto_secretstream_xchacha20poly1305_init_push(key);
let [state_out, header] = [res.state, res.header];
let c1 = sodium.crypto_secretstream_xchacha20poly1305_push(state_out,
sodium.from_string('message 1'), null,
sodium.crypto_secretstream_xchacha20poly1305_TAG_MESSAGE);
let c2 = sodium.crypto_secretstream_xchacha20poly1305_push(state_out,
sodium.from_string('message 2'), null,
sodium.crypto_secretstream_xchacha20poly1305_TAG_FINAL);
let state_in = sodium.crypto_secretstream_xchacha20poly1305_init_pull(header, key);
let r1 = sodium.crypto_secretstream_xchacha20poly1305_pull(state_in, c1);
let [m1, tag1] = [sodium.to_string(r1.message), r1.tag];
let r2 = sodium.crypto_secretstream_xchacha20poly1305_pull(state_in, c2);
let [m2, tag2] = [sodium.to_string(r2.message), r2.tag];
console.log(m1);
console.log(m2);
})();
The sodium.js
file includes both the core libsodium functions, as
well as the higher-level Javascript wrappers. It can be loaded
asynchronusly.
A sodium
object should be defined in the global namespace, with the
following properties:
onload
: the function to call after the wrapper is initialized.totalMemory
(optional): the maximum amount of memory that sodium can use.
The default value should be fine for most applications, unless you
need to use password hashing functions with a large amount of memory.Example:
<script>
window.sodium = {
onload: function (sodium) {
let h = sodium.crypto_generichash(64, sodium.from_string('test'));
console.log(sodium.to_hex(h));
}
};
</script>
<script src="sodium.js" async></script>
crypto_aead
crypto_auth
crypto_box
crypto_box_seal
crypto_generichash
crypto_hash
crypto_kdf
crypto_kx
crypto_onetimeauth
crypto_pwhash
crypto_scalarmult
crypto_secretbox
crypto_secretstream
crypto_shorthash
crypto_sign
crypto_stream
randombytes
from_base64()
, to_base64()
with an optional second parameter
whose value is one of: base64_variants.ORIGINAL
, base64_variants.ORIGINAL_NO_PADDING
,
base64_variants.URLSAFE
or s.base64_variants.URLSAFE_NO_PADDING
. Default is base64_variants.URLSAFE_NO_PADDING
.from_hex()
, to_hex()
from_string()
, to_string()
pad(<buffer>, <block size>)
, unpad(<buffer>, <block size>)
memcmp()
(constant-time check for equality, returns true
or false
)compare() (constant-time comparison. Values must have the same size. Returns
-1,
0or
1`)memzero()
(applies to Uint8Array
objects)increment()
(increments an arbitrary-long number stored as a
little-endian Uint8Array
- typically to increment nonces)add()
(adds two arbitrary-long numbers stored as little-endian
Uint8Array
vectors)is_zero()
(constant-time, checks Uint8Array
objects for all zeros)The API exposed by the wrappers is identical to the one of the C library, except that buffer lengths never need to be explicitly given.
Binary input buffers should be Uint8Array
objects. However, if a string
is given instead, the wrappers will automatically convert the string
to an array containing a UTF-8 representation of the string.
Example:
var key = sodium.randombytes_buf(sodium.crypto_shorthash_KEYBYTES),
hash1 = sodium.crypto_shorthash(new Uint8Array([1, 2, 3, 4]), key),
hash2 = sodium.crypto_shorthash('test', key);
If the output is a unique binary buffer, it is returned as a
Uint8Array
object.
However, an extra parameter can be given to all wrapped functions, in order to specify what format the output should be in. Valid options are `uint8array' (default), 'text', 'base64' and 'hex'.
Example (shorthash):
var key = sodium.randombytes_buf(sodium.crypto_shorthash_KEYBYTES),
hash_hex = sodium.crypto_shorthash('test', key, 'hex');
Example (secretbox):
// Load your secret key from a safe place and reuse it across multiple
// secretbox calls. (Obviously don't use this example key for anything
// real.)
//
var secret = Buffer.from('724b092810ec86d7e35c9d067702b31ef90bc43a7b598626749914d6a3e033ed', 'hex');
// Given a message as a string, return a Buffer containing the
// nonce (in the first 24 bytes) and the encrypted content.
var encrypt = function(message) {
// You must use a different nonce for each message you encrypt.
var nonce = Buffer.from(sodium.randombytes_buf(sodium.crypto_box_NONCEBYTES));
var buf = Buffer.from(message);
return Buffer.concat([nonce, Buffer.from(sodium.crypto_secretbox_easy(buf, nonce, secret))]);
},
// Decrypt takes a Buffer and returns the decrypted message as plain text.
var decrypt = function(encryptedBuffer) {
var nonce = encryptedBuffer.slice(0, sodium.crypto_box_NONCEBYTES);
var encryptedMessage = encryptedBuffer.slice(sodium.crypto_box_NONCEBYTES);
return sodium.crypto_secretbox_open_easy(encryptedMessage, nonce, secret, 'text');
}
In addition, the from_hex
, to_hex
, from_string
, and to_string
functions are available to explicitly convert hexadecimal, and
arbitrary string representations from/to Uint8Array
objects.
Functions returning more than one output buffer are returning them as
an object. For example, the sodium.crypto_box_keypair()
function
returns the following object:
{ keyType: 'curve25519', privateKey: (Uint8Array), publicKey: (Uint8Array) }
The standard version (in the dist/browsers
and dist/modules
directories) contains the high-level functions, and is the recommended
one for most projects.
Alternatively, the "sumo" version, available in the
dist/browsers-sumo
and dist/modules-sumo
directories contains all
the symbols from the original library. This includes undocumented,
untested, deprecated, low-level and easy to misuse functions.
The crypto_pwhash_*
function set is also only included in the Sumo
version. The high amount of heap memory (allocated after loading)
required by these functions may not be desirable when they are not
being used.
The sumo version is slightly larger than the standard version, and should be used only if you really need the extra symbols it provides.
If you want to compile the files yourself, the following dependencies need to be installed on your system:
yarn global add uglify-es
)Running make
will clone libsodium, build it, test it, build the
wrapper, and create the modules and minified distribution files.
Built by Ahmad Ben Mrad, Frank Denis and Ryan Lester.
This wrapper is distributed under the ISC License.
FAQs
The Sodium cryptographic library compiled to pure JavaScript (wrappers)
The npm package libsodium-wrappers receives a total of 498,916 weekly downloads. As such, libsodium-wrappers popularity was classified as popular.
We found that libsodium-wrappers demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Product
Socket now supports four distinct alert actions instead of the previous two, and alert triaging allows users to override the actions taken for all individual alerts.
Security News
Polyfill.io has been serving malware for months via its CDN, after the project's open source maintainer sold the service to a company based in China.
Security News
OpenSSF is warning open source maintainers to stay vigilant against reputation farming on GitHub, where users artificially inflate their status by manipulating interactions on closed issues and PRs.