# poly-crypto

**Poly**glot **Crypto**graphy. High-level cryptographic functions that are
interoperable between NodeJS and PHP 7.2+ (and 8.0+).

[![NPM Link](https://badgen.net/npm/v/poly-crypto?v=2.2.0)](https://npmjs.com/package/poly-crypto)
[![Packagist Link](https://img.shields.io/packagist/php-v/poly-crypto/poly-crypto/2.1.0)](https://packagist.org/packages/poly-crypto/poly-crypto)
[![Language](https://badgen.net/static/language/TS?v=2.2.0)](https://github.com/search?q=repo:kensnyder/poly-crypto++language:TypeScript&type=code)
[![Build Status](https://github.com/kensnyder/poly-crypto/actions/workflows/workflow.yml/badge.svg?v=2.2.0)](https://github.com/kensnyder/poly-crypto/actions)
[![Code Coverage](https://codecov.io/gh/kensnyder/poly-crypto/branch/main/graph/badge.svg?v=2.2.0)](https://codecov.io/gh/kensnyder/poly-crypto)
[![Gzipped Size](https://badgen.net/bundlephobia/minzip/poly-crypto?label=minzipped&v=2.2.0)](https://bundlephobia.com/package/poly-crypto@2.2.0)
[![Dependency details](https://badgen.net/bundlephobia/dependency-count/poly-crypto?v=2.2.0)](https://www.npmjs.com/package/poly-crypto?activeTab=dependencies)
[![Tree shakeable](https://badgen.net/bundlephobia/tree-shaking/poly-crypto?v=2.2.0)](https://www.npmjs.com/package/poly-crypto)
[![ISC License](https://badgen.net/github/license/kensnyder/poly-crypto?v=2.2.0)](https://opensource.org/licenses/ISC)

## Project Goals

1. APIs that work exactly the same on NodeJS and PHP 7.2+ (and 8.0+)
2. Package for Node that can be used on serverless functions without external C
   bindings
3. Two-way symmetric encryption with a key or with password and salt
4. Password hashing
5. Support ESM with tree shaking; support CommonJS; Written in TypeScript

## Installation

You can use PolyCrypto in JavaScript, PHP, or both.

```bash
# NodeJS
npm install poly-crypto

# PHP
composer require poly-crypto/poly-crypto
```

## Cheatsheet

| Section                                                     | NodeJS                                                  | PHP                                                          |
| ----------------------------------------------------------- | ------------------------------------------------------- | ------------------------------------------------------------ |
| [Encrypt with key](#encrypt-and-decrypt-with-key)           | PolyAES.withKey(key).encrypt(data)                      | PolyAES::withKey($key)->encrypt($data)                       |
| [Decrypt with key](#encrypt-and-decrypt-with-key)           | PolyAES.withKey(key).decrypt(encrypted)                 | PolyAES::withKey($key)->decrypt($encrypted)                  |
| [Encrypt with password](#encrypt-and-decrypt-with-password) | PolyAES.withPassword(password, salt).encrypt(data)      | PolyAES::withPassword($password, $salt)->encrypt($data)      |
| [Decrypt with password](#encrypt-and-decrypt-with-password) | PolyAES.withPassword(password, salt).decrypt(encrypted) | PolyAES::withPassword($password, $salt)->decrypt($encrypted) |
| [Bcrypt hash](#password-hashing)                            | PolyBcrypt.hash(password)                               | PolyBcrypt::hash($password)                                  |
| [Bcrypt verify](#password-hashing)                          | PolyBcrypt.verify(password, hash)                       | PolyBcrypt::verify($password, $hash)                         |
| [Digest functions](#digest-functions)                       | PolyDigest.sha256(data)                                 | PolyDigest::sha256($data)                                    |
| [Random functions](#random-functions)                       | PolyRand.slug(length)                                   | PolyRand::slug($length)                                      |
| [Base conversion](#base-conversion)                         | PolyConvert.base(digits, fromBase, toBase)              | PolyRand::base($digits, $fromBase, $toBase)                  |

## Table of Contents

1. [Technology choices](#technology-choices)
    1. [AES-255 GCM](#aes-256-gcm)
    1. [Bcrypt](#bcrypt)
    1. [Randomness](#randomness)
1. [Use Cases](#use-cases)
1. [Misuse](#misuse)
1. [AES encryption](#aes-encryption)
    1. [Encrypt and decrypt with key](#encrypt-and-decrypt-with-key)
    1. [Encrypt and decrypt with password](#encrypt-and-decrypt-with-password)
1. [Password hashing](#password-hashing)
1. [Digest functions](#digest-functions)
1. [Random functions](#random-functions)
1. [Base conversion](#base-conversion)
1. [Command line utilities](#command-line-utilities)
1. [Browser usage](#browser-usage)
1. [JavaScript direct import](#javascript-direct-import)
1. [Unit tests](#unit-tests)
1. [Open Source ISC License](#license)
1. [Changelog](https://github.com/kensnyder/poly-crypto/blob/master/CHANGELOG.md)

## Technology choices

### AES-256 GCM

As of December 2022, AES-256 Encryption with GCM block mode is a reputable and
secure method that is available across PHP and NodeJS without any extensions.
With the right arguments and options, these 2 languages can decrypt one
another's encrypted strings using PHP's openssl\_\* functions and npm's
node-forge.

### Bcrypt

As of January 2025, Bcrypt password hashing is reputable and secure. These 2
languages can hash and verify one another's hashes: npm's bcrypt-js and PHP's
password_hash function.

### Randomness

Cryptographic randomness is tricky. These 2 languages can provide secure
randomness:
PHP's random_bytes() and Node's crypto.randomBytes() functions.

## Use cases

poly-crypto's basic use cases:

|     | Case                                                     | Input                                | Output                          | NodeJS                                             |
| --- | -------------------------------------------------------- | ------------------------------------ | ------------------------------- | -------------------------------------------------- |
| 1.  | Encrypt data that you can to decrypt later               | Encryption key string                | base-64 encoded string          | PolyAES.withKey(hexKey).encrypt(data)              |
| 2.  | Encrypt data for a user that he or she can decrypt later | User-supplied password & system salt | base-64 encoded string          | PolyAES.withPassword(password, salt).encrypt(data) |
| 3.  | Hash passwords with bcrypt                               | Password string                      | bcrypt hash                     | PolyBcrypt.hash(password)                          |
| 4.  | Check if a password matches the given bcrypt hash        | Password string & bcrypt hash        | True if password matches        | PolyBcrypt.verify(password, hash)                  |
| 5.  | Calculate digests (e.g. sha256)                          | String data                          | digest string                   | PolyDigest.sha256(data)                            |
| 6.  | Generate random slugs                                    | number of characters                 | a string with random characters | PolyRand.slug(numCharacters)                       |
| 7.  | Convert numbers between bases                            | number to convert                    | converted number                | PolyConvert.base(input, from, to)                  |

## Misuse

1. **File encryption.** poly-crypto modules are not meant to be used to encrypt
   entire files. You'll want to use a C-based library that is designed to
   encrypt large amounts of data quickly. For example, consider the following:
    1. poly-crypto is not fast for large files.
    1. AES-256 GCM encryption can be parallelized in languages that support
       threading for faster processing
1. **Streaming data.** PolyAES is not designed to encrypt streaming data.
1. **Secure key storage.** If you store encryption keys or user passwords in
   plain text, encryption will not provide protection. You'll want to store keys
   in a secure parameter store.
1. **Digests for passwords.** Do not use md5 or any sha digest for hashing
   passwords, even if you use salt. PolyBcrypt is the only poly-crypto module
   designed for hashing passwords.

### AES Encryption

#### Encrypt and decrypt with key

**Note:** key should be a 64-character hex-encoded string stored in a secure
param store. To generate a cryptographically secure random key,
use `PolyAES.generateKey(64)`.

NodeJS:

```js
import { PolyAES } from 'poly-crypto';

const hexKey = '64-char hex encoded string from secure param store';
const encrypted = PolyAES.withKey(hexKey).encrypt(data);
const decrypted = PolyAES.withKey(hexKey).decrypt(encrypted);
```

PHP:

```php
<?php

require_once('vendor/autoload.php');
use PolyCrypto\PolyAES;

$hexKey = '64-char hex encoded string from secure param store';
$encrypted = PolyAES::withKey($hexKey)->encrypt($data);
$decrypted = PolyAES::withKey($hexKey)->decrypt($encrypted);
```

**Note:** You can re-use the "cipher" object. For example:

NodeJS:

```js
import { PolyAES } from 'poly-crypto';

const hexKey = '64-char hex encoded string from secure param store';
const cipher = PolyAES.withKey(hexKey);
const encrypted = cipher.encrypt(data);
const decrypted = cipher.decrypt(encrypted);
```

PHP:

```php
<?php

require_once('vendor/autoload.php');
use PolyCrypto\PolyAES;

$hexKey = '64-char hex encoded string from secure param store';
$cipher = PolyAES::withKey($hexKey);
$encrypted = $cipher->encrypt($data);
$decrypted = $cipher->decrypt($encrypted);
```

#### Encrypt and decrypt with password

NodeJS:

```js
import { PolyAES } from 'poly-crypto';

const password = 'String from user';
const salt = 'String from secure param store';
const encrypted = PolyAES.withPassword(password, salt).encrypt(data);
const decrypted = PolyAES.withPassword(password, salt).decrypt(encrypted);
```

PHP:

```php
<?php

require_once('vendor/autoload.php');
use PolyCrypto\PolyAES;

$password = 'String from user';
$salt = 'String from secure param store';
$encrypted = PolyAES::withPassword($password, $salt)->encrypt($data);
$decrypted = PolyAES::withPassword($password, $salt)->decrypt($encrypted);
```

**Note:** You can re-use the "cipher" as an object.

### Password hashing

Bcrypt hashes are designed to store user passwords with a max length of 72
bytes. If a longer string is passed, an exception will be thrown. Keep in mind
that Unicode characters require multiple bytes.

Bcrypt conveniently stores salt along with the password. That ensures that
identical passwords will get different hashes. As such, you cannot compare two
hashes, you must use the `PolyBcrypt.verify()` function to see if the given
password matches the hash you have on record.

NodeJS:

```js
import { PolyBcrypt } from 'poly-crypto';

const password = 'Password from a user';
const hash = PolyBcrypt.hash(password);
const isCorrect = PolyBcrypt.verify(password, hash);
```

PHP:

```php
<?php

require_once('vendor/autoload.php');
use PolyCrypto\PolyBcrypt;

$password = 'Password from a user';
$hash = PolyBcrypt::hash($password);
$isCorrect = PolyBcrypt::verify($password, $hash);
```

### Digest functions

Standard one-way digest functions.

NodeJS:

```js
import { PolyDigest } from 'poly-crypto';

PolyDigest.sha512(data);
PolyDigest.sha256(data);
PolyDigest.sha1(data);
PolyDigest.md5(data);
```

PHP:

```php
<?php

require_once('vendor/autoload.php');
use PolyCrypto\PolyDigest;

PolyDigest::sha512($data);
PolyDigest::sha256($data);
PolyDigest::sha1($data);
PolyDigest::md5($data);
```

### Random functions

Simple functions to generate random values synchronously.

NodeJS:

```js
import { PolyRand } from 'poly-crypto';

// generate a string containing numbers and letters minus vowels
// suitable for resources such as URLs with random strings
PolyRand.slug(length);

// generate a string containing hexadecimal characters
PolyRand.hex(length);

// generate a string containing numbers and lowercase letters
// that are unambiguous when written down
PolyRand.fax(length);

// generate a string containing lowercase letters minus vowels
const symbolList = 'bcdfghjklmnpqrstvwxyz'.split('');
PolyRand.string(length, symbolList);

// generate random bytes in binary form
PolyRand.bytes(length);

// generate a uuid v4
PolyRand.uuidv4();
```

PHP:

```php
<?php

require_once('vendor/autoload.php');
use PolyCrypto\PolyRand;

// generate a string containing numbers and letters minus vowels
// suitable for resources such as URLs with random strings
PolyRand::slug($length);

// generate a string containing hexadecimal characters
PolyRand::hex($length);

// generate a string containing numbers and lowercase letters
// that are unambiguous when written down
PolyRand::fax($length);

// generate a string containing lowercase letters minus vowels
$symbolList = explode('', 'bcdfghjklmnpqrstvwxyz');
PolyRand::string($length, $symbolList);

// generate random bytes in binary form
PolyRand::bytes($length);

// generate a uuid v4
PolyRand::uuidv4();
```

### Base conversion

Simple functions to convert numbers from one base to another, up to base 95.

Useful in some situations:

- You have a long string in a low base but want fewer characters
- You need to limit to a smaller character set but don't care about string length
- You want output to contain no vowels, ensuring no swear words are present

NodeJS:

```js
import { PolyConvert } from 'poly-crypto';

PolyConvert.base('1011', 2, 10); // '11'
PolyConvert.base('FF', 16, 10); // '255'
PolyConvert.base('18446744073709551615', 10, 62); // 'lYGhA16ahyf'
PolyConvert.base('And_TypeScript_too!', 92, 62); // 'btjYsDwwuWrElSt7WRf2g'

PolyConvert.fax.applyBase('4BD3DBDFCBCJDBJCD737BC6H43', 10, 21); // '467BCDFHJKMNPQRTVWXY'
```

PHP:

```php
<?php

require_once('vendor/autoload.php');
use PolyCrypto\PolyConvert;

PolyConvert::base('1011', 2, 10); // '11'
PolyConvert::base('FF', 16, 10); // '255'
PolyConvert::base('18446744073709551615', 10, 62); // 'lYGhA16ahyf'
PolyConvert::base('And_TypeScript_too!', 92, 62); // 'btjYsDwwuWrElSt7WRf2g'
```

## Command line utilities

poly-crypto functions can be used from the command line if Node JS is installed.

### Global install of poly-crypto

You'll have the following commands as symlinks:

```bash
# Global install command and arguments        # JavaScript equivalent
# ------------------------------------------- # ---------------------
npx key-encrypt $hexKey $plaintext            # PolyAES.withKey(hexKey).encrypt(plaintext)
npx key-decrypt $hexKey $ciphertext           # PolyAES.withKey(hexKey).decript(ciphertext)
npx pass-encrypt $password $salt $plaintext   # PolyAES.withPassword(password, salt).encrypt(plaintext)
npx pass-decrypt $password $salt $ciphertext  # PolyAES.withPassword(password, salt).decrypt(plaintext)
npx bcrypt-hash $password                     # PolyBcrypt.hash(password)
npx bcrypt-verify $password $againstHash      # PolyBcrypt.verify(password, againstHash)
npx poly-digest $algo $string                 # PolyDigest[algo](data) where algo is one of: sha1, sha256, sha512, md5
npx poly-rand $type $length                   # PolyRand[type](length) where type is one of: slug, hex, fax, bytes, uuidv4
npx poly-rand-string $length $symbolString    # PolyRand.string(length, symbolList) where symbolList is a string containing allowed characters
npx poly-convert-base $input $from $to        # PolyConvert.base(input, from, to)
```

## Browser usage

All poly-crypto modules do indeed function in the browser. There are only a few use
cases where encrypting in the browser is a good idea. If you have a good reason to
use poly-crypto in the browser, see the following section for instructions on
directly importing a Poly\* module.

## JavaScript direct import

If you are using ESM or a bundler such as
[vite](https://vitejs.dev) or [esbuild](https://esbuild.github.io)
you will benefit from tree shaking by using an import statement.

```js
import { PolyBcrypt } from 'poly-crypto';
```

## Unit tests

```bash
# test both languages
npm run test:all

# PHP
./vendor/bin/kahlan --spec=php/tests

# NodeJS
npm test
```

## Contributing

Contributions welcome! See
[CONTRIBUTING.md](https://github.com/kensnyder/poly-crypto/blob/master/CONTRIBUTING.md)
.

## License

Open Source, under the [ISC License](https://opensource.org/licenses/ISC).