# garbados-crypt

> Easy password-based encryption, by garbados.

Latest version **3.0.0-beta** (published 2021-08-06) · Apache-2.0 license · 0 weekly downloads

## Install

```sh
npm install garbados-crypt
pnpm add garbados-crypt
yarn add garbados-crypt
bun add garbados-crypt
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 3.0.0-beta |
| Published | 2021-08-06 |
| First published | 2021-05-04 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | none |
| Module format | CommonJS |
| Node | >=12 |
| Dependencies | 3 |
| Unpacked size | 11.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 3 |
| Author | Diana Thayer |
| Maintainers | garbados |

## Links

- npm: https://www.npmjs.com/package/garbados-crypt
- Repository: https://github.com/garbados/crypt
- Issues: https://github.com/garbados/crypt/issues
- npm.io page: https://npm.io/package/garbados-crypt

## Dependencies (3)

- [hash-wasm](https://npm.io/package/hash-wasm.md) ^4.9.0
- [tweetnacl](https://npm.io/package/tweetnacl.md) ^1.0.3
- [tweetnacl-util](https://npm.io/package/tweetnacl-util.md) ^0.15.1

## Recent versions

- 3.0.0-beta (latest) — 2021-08-06
- 2.0.0-beta — 2021-07-31
- 1.0.2-alpha — 2021-05-07
- 1.0.1-alpha — 2021-05-05
- 1.0.0-alpha — 2021-05-04

## README

# garbados-crypt

[![CI](https://github.com/garbados/crypt/actions/workflows/ci.yaml/badge.svg)](https://github.com/garbados/crypt/actions/workflows/ci.yaml)
[![Coverage Status](https://coveralls.io/repos/github/garbados/crypt/badge.svg?branch=master)](https://coveralls.io/github/garbados/crypt?branch=master)
[![Stability](https://img.shields.io/badge/stability-stable-green.svg?style=flat-square)](https://nodejs.org/api/documentation.html#documentation_stability_index)
[![NPM Version](https://img.shields.io/npm/v/garbados-crypt.svg?style=flat-square)](https://www.npmjs.com/package/garbados-crypt)
[![JS Standard Style](https://img.shields.io/badge/code%20style-standard-brightgreen.svg?style=flat-square)](https://github.com/feross/standard)

Easy password-based encryption, by [garbados](https://garbados.github.io/my-blog/).

This library attempts to reflect [informed opinions](https://latacora.micro.blog/2018/04/03/cryptographic-right-answers.html) while respecting realities like resource constraints, tech debt, and so on. The idea is to provide some very simple methods that just do the hard thing for you.

For example:

```javascript
const Crypt = require('garbados-crypt')

const crypt = new Crypt(password)
const encrypted = await crypt.encrypt('hello world')
console.log(encrypted)
> "O/z1zXHQ+..."
const decrypted = await crypt.decrypt(encrypted)
console.log(decrypted)
> "hello world"
```

Crypt only works with plaintext, so remember to use `JSON.stringify()` on objects before encryption and `JSON.parse()` after decryption. For classes and the like, you'll need to choose your own encoding / decoding approach.

## Install

Use [npm](https://www.npmjs.com/) or whatever.

```bash
$ npm i -S garbados-crypt
```

## Usage

First, require the library. Then get to encrypting!

```javascript
const Crypt = require('garbados-crypt')

const crypt = new Crypt(password)
```

### new Crypt(password, [salt, [opts]])

- `password`: A string. Make sure it's good! Or not.
- `salt`: A salt, either as a byte array or a string. If omitted or falsy, a random salt is generated. *Rather than bother carrying this with you, use `crypt.export()` and `Crypt.import()` to transport your credentials!*
- `opts`: Options!
- `opts.iterations`: The number of iterations to use to hash your password via [Argon2](https://en.wikipedia.org/wiki/Argon2). Defaults to 100.
- `opts.saltLength`: The length of the salt to be generated, in bytes. Defaults to 16.
- `opts.memorySize`: The number of kilobytes of RAM to use to generate a cryptographic key from a password. Defaults to 4096 KB. *Must be a power of 2.*
- `opts.parallelism`: The number of threads to use when generating a cryptographic key. Defaults to 1, as Crypt assumes it operates in a single-threaded environment.

#### A note on modifying default settings

Crypt's defaults have been selected to afford a cryptographic strength that does not impose significant performance penalties to applications doing a lot of encrypted reads and writes, such as those using [crypto-pouch](https://github.com/calvinmetcalf/crypto-pouch). If you are facing an attacker with significant resources, such as state actors, consider increasing the `iterations` and `memorySize` options. This will impose notable performance penalties, but as a rule slower cryptography means slower cracking. **You should only modify these settings if you know what you are doing!**

### async Crypt.new(password, [salt, [opts]])

An asynchronous version of Crypt's constructor. Unlike the synchronous constructor, using `.new()` awaits Crypt's setup phase, so that you can explicitly await any problems during setup rather than wait for them to surface during encryption.

### async Crypt.import(password, exportString) => new Crypt

Instantiates a new Crypt instance using an encoded string generated by `crypt.export()`. Use this method to import credentials generated on another device!

- `password`: A string, the same string password you used with the Crypt instance that generated the `exportString`!
- `exportString`: A string generated by `crypt.export()`.

### async crypt.export() => string

Exports a string you can use to create a new Crypt instance with `Crypt.import()`.
*Rather than bother carrying around your password and salt, use this to transport credentials across devices!*

### async crypt.encrypt(plaintext) => ciphertext

- `plaintext`: A string.
- `ciphertext`: A different, encrypted string.

### async crypt.decrypt(ciphertext) => plaintext

- `ciphertext`: An encrypted string produced by `crypt.encrypt()`.
- `plaintext`: The decrypted message as a string.

If decryption fails, for example because your password is incorrect, an error will be thrown.

## Development

First, get the source:

```bash
$ git clone git@github.com:garbados/crypt.git garbados-crypt
$ cd garbados-crypt
$ npm i
```

Use the test suite:

```bash
$ npm test
```

The test suite includes a small benchmarking test, which runs on the server and in the browser, in case you're curious about performance.

To see test coverage:

```bash
$ npm run cov
```

## Regarding passwords

Passwords should be generally considered a form of vulnerability. An attacker that manages to solve your encryption, such as by exfiltrating encrypted values and then brute-forcing the decryption key, may gain access to the password you used to encrypt those values. As a result, I highly advise deriving a strong passcode from a memorable passphrase in a non-reversible way, such as by using Argon2 or another derivation function yourself. By using this passcode only for a specific app, you ensure that an attacker will not be able to discover your passphrase even if they crack the passcode.

You can even do this with Crypt itself:

```javascript
const globalCrypt = await Crypt.new('your_passphrase')
const passcode = await globalCrypt.encrypt('some_context_phrase') // like the name of the associated app or service
const contextCrypt = await Crypt.new(passcode)
// now you can use contextCrypt to encrypt your data
// with strong guarantees that even if an attacker cracks your crypto,
// they will not obtain your passphrase.
```

## How To Securely Store A Password

For a password-based encryption system, it makes sense to have a good reference on how to store passwords in a database. To this effect I have written [this gist](https://gist.github.com/garbados/29ca945d5964ef85e7936804c23edb9d#file-how_to_store_passwords-js) to demonstrate safe password obfuscation and verification. If you have any issue with the advice offered there, leave a comment!

## Why TweetNaCl.js?

This library uses [tweetnacl](https://www.npmjs.com/package/tweetnacl) rather than native crypto. You might have feelings about this.

I chose it because it's fast on NodeJS, bundles conveniently (33kb!), uses top-shelf algorithms, and has undergone a [reasonable audit](https://www.npmjs.com/package/tweetnacl#audits).

That said, I'm open to PRs that replace it with native crypto while retaining Crypt's API.

## License

[Apache-2.0](https://www.apache.org/licenses/LICENSE-2.0)

---
_Source: https://npm.io/package/garbados-crypt · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
