viki/node_modules/sodium/docs/sodium.md

General Use

The following objects are available in the sodium library

• api - access to low level libsodium api
• Utils - utility functions
• Hash - all hash functions
• Random - random number generator functions
• Box - public key asymmetric crypto
• SecretKey - symmetric key crypto
• Stream - stream crypto
• Sign - signature generation and validation
• Auth - authentication
• OneTimeAuth - one time authentication
• Nonces - nonce generation
• Key - keys for all crypto functions

Lets generate a random number using by requiring the full sodium library

var sodium = require('sodium');
var n = sodium.api.randombytes_random();

Since we only need to call one method from the low level API we could require just the API functions like this:

var lowLevelApi = require('sodium').api;
var n = lowlevelApi.randombytes_random();

The same method can be applied to the other objects exposed through sodium.

The low level API gives you access to all ported libsodium functions directly. If you have experience using libsodium you can bypass the high-level APIs and use libsodium directly.

Low Level API

node-sodium is a port of libsodium (github repo), which it self is a port of the original NaCl library by Daniel Bernstein. The underlying library provides a C API that is exposed in node-sodium under the .api object. You can use the low level documentation and examples to understand how to use it.

High Level APIs

node-soidum defines a series of high level APIs that try to make it easier for the node developer to use. The high level APIs combine encryption, decryption functions, or sign and verify functions under the same class, while generating the appropriate keys, or nonces and taking care of message padding.

Due to the fact that NaCl defines a rich set of cryptographic functions, there are many different key types, key sizes, encryption primitives, and nonces that need to be generated and used appropriately. If mistakes are made your code won't work, or security will be compromised. The high level API thus provides a set of classes and methods that abstract these details from the developer in an attempt to avoid mistakes.

Nonces

A nonce, or number used once, is an arbitrary number used only once in a cryptographic communication (Wikipedia). As the name implies you should generate a new nonce for every message. By default, in node-sodium, nonces are random numbers of the appropriate size for the cryptographic algorithm being used. The size of each nonce is sufficient that the probability of collision, i.e. generating the same nonce twice, is very low. Therefore there is no need to keep a list of previously used nonces, which saves a lot of time and memory.

Keys

Keys are fundamental to the security of any encryption method, and there are two basic types of keys used in node-sodium, secret keys, and public/secret key pairs.

Secret keys, used by themselves or in a key pair, should always be kept a secret and should never be transmitted in the clear between sender and recipient of any message. There should always be a secure, often times offline, method so that sender and recipient can agree on a secret key. Throughout node-sodium all secret keys use the secretKey or sk variable or parameter name. This allows consistent identification of all secret keys, and special care should be taken in their storage, management and use. Public keys use the publicKey or pk identifier name, and can be shared, sent unencrypted, or stored without major concerns. node-sodium does not provide a Public Key Infrastructure (PKI) with digital certificates by default, so you must consider man-in-the-middle attacks on public keys a possibility, and design your own key trust mechanisms.