magic

magic is a lightweight wrapper around the crypto interface to OpenSSL and the libsodium library which provides a standard cryptography API for internal use, consistent with best current practices recommended by the product security team at Auth0. Named not for what it is intended to do, but for what it is intended to prevent.

All public functions support both callbacks and promises (and therefore async/await), allowing easy integration into any preexisting codebase. All constructions requiring secret keys will generate them as necessary if they are not supplied, and return them for future use.

Why use magic

Most libraries offering a cryptography toolkit allow for a variety of configuration. Usually the reasoning behind this is to empower the developer to configure the cryptography functions as they like. At the same time however this requires developers to be knowledgable of what the different parameters are for and how they affect the security of the function output. Bad choices in parameters can lead to insecure cryptography with disastrous results.

magic is a library that supports as little configuration as possible allowing developers to use a cryptography library without needing expert knowledge. Secure configuration is embedded in the library following best current practices recommended by the Product Security team at Auth0.

:warning: WARNING

Load auth0-magic before any process listener is added or remove all uncaughtException process listeners right after requiring magic.

auth0-magic currently uses libsodium.js#0.7.6 which removes all uncaughtException listeners during the module load .libsodium.js needs to do that because it is generated by EMScripten which adds listeners during build. Related issue in libsodium.js repo here

Example:

  const magic = require('auth0-magic');
  process.removeAllListeners('uncaughtException');

Install

npm install auth0-magic

Usage

magic offers a variety of functions for the following cases:

• Encryption
  • Symmetric Authenticated Encryption
  • Asymmetric Authenticated Encryption
  • Streams Symmetric Authenticated Encryption
• Authentication
  • Signing using PKI
  • HMAC
• Password hashing
  • argon2
  • bcrypt

magic also offers a variety of utility functions:

• RSA key pair generation
• Time safe comparison
• UID generation
• Random bytes generation
• Hashing

Magic implements a core and and alt API. The core api implements the recommended algorithms for each cryptographic operation. When in doubt, please use them. The alt api implements alternative algorithms for each cryptographic operation. They should only be used over the core api when required by an external specification or interoperability concerns.

Detailed documentation on the supported API can be found in the /docs folder

Recommended input type

It is recommended that magic is always used with node.js buffers for all (non-boolean) inputs, with the exception of passwords.

Due to the variety of tasks to which it may be put, the library attempts to be as unopinionated about encoding as it is opinionated about algorithms. There is minimal decoding functionality, which will attempt to break down any plaintext input as utf-8 and any cryptographic input (keys, ciphertexts, macs, signatures, etc.) as hex. If as a consumer of this library you decide to depend on this builtin decoder it is recommended that you extensively test it to make sure your inputs are being parsed appropriately. When in doubt, it is always safer to parse them yourself and pass in binary data.