A simple AES-GCM cipher codec (for encrypting and decrypting)
npm install @root/cipherBecause you don't have to be an expert to _use_ cryptography!
- Keys can be 128-, 192-, or 256-bit (16, 24, or 32 bytes)
- Plain input can be raw Uint8Arrays or (UTF-8) Strings
- Encrypted output can be Base64UrlSafe Strings, or raw Uint8Arrays
0. Example
1. Generate a Key
2. Initialize the Cipher (Codec)
3. Encrypt (Cipher) Data
4. Decrypt (Decipher) Data
5. Convert between Bytes, Hex, Base64, and URL-Safe Base64
6. API
7. Implementation Details
Encrypt and Decrypt with AES-GCM.
``js
let Cipher = require("@root/cipher");
let cipher = Cipher.create(sharedSecret);
let plainBytes = [0xde, 0xad, 0xbe, 0xef];
let encBase64UrlSafe = cipher.encrypt(plainBytes);
let originalBytes = Cipher.decrypt(encBase64UrlSafe);
`
Copy-and-Paste Snippets for the Masses
`js
// Generate a 128-bit, 192-bit, or 256-bit AES secret:
let secretBytes = new Uint8Array(16); // or 24, or 32
crypto.getRandomValues(secretBytes);
let secretHex = Cipher.utils.bytesTohex(secretBytes);
`
`js
let secretHex = process.env.APP_SECRET_KEY;
let secretBytes = Cipher.utils.hexToBytes(secretHex);
let cipher = Cipher.create(sharedSecret);
`
#### Plain Bytes => Encrypted Base64UrlSafe
`sh`
let plainBytes = [0xde, 0xad, 0xbe, 0xef];
let encBase64UrlSafe = cipher.encrypt(plainBytes);
console.info("Encrypted (URL-Safe Base64)", encBase64UrlSafe);
#### Plain String => Encrypted Base64UrlSafe
`sh`
let plainText = "123-45-6789";
let encBase64UrlSafe = cipher.encryptString(plainText);
console.info("Encrypted (URL-Safe Base64)", encBase64UrlSafe);
#### Plain Bytes => Encrypted Bytes
`sh`
let plainBytes = [0xde, 0xad, 0xbe, 0xef];
let encBytes = cipher.encryptAsBytes(plainBytes);
console.info("Encrypted (Bytes)", encBytes);
#### Plain String => Encrypted Bytes
`sh`
let plainText = "123-45-6789";
let encBytes = cipher.encryptStringAsBytes(plainText);
console.info("Encrypted (Bytes)", encBytes);
#### Encrypted String => Plain Bytes
`sh`
let bytes = cipher.decrypt(encBase64UrlSafe);
console.info("Plain (Bytes)", bytes);
#### Encrypted Bytes => Plain Bytes
`sh`
let bytes = cipher.decryptBytes(encBytes);
console.info("Plain (Bytes)", bytes);
#### Encrypted String => Plain String
`sh`
let text = cipher.decryptToString(encBase64UrlSafe);
console.info("Plain (Text)", text);
#### Encrypted Bytes => Plain String
`sh`
let text = cipher.decryptBytesToString(encBytes);
console.info("Plain (Text)", text);
Doing what Uint8Array should do, but doesn't.
#### Bytes <=> Hex
`sh`
let hex = Cipher.utils.bytesToHex(bytes);
let bytes = Cipher.utils.hexToBytes(hex);
#### Bytes <=> Base64
`js`
let base64 = Cipher.utils.bytesToBase64(bytes);
let bytes = Cipher.utils.base64ToBytes(base64);
#### Bytes <=> URL-Safe Base64
`sh`
let base64urlsafe = Cipher.utils.bytesToUrlSafe(bytes);
let bytes = Cipher.utils.urlSafeToBytes(base64urlsafe);
`text
Cipher.create(keyBytes) => cipher instance
cipher.encrypt(bytes) => Promise
cipher.encryptString(string) => Promise
cipher.encryptAsBytes(bytes) => Promise
cipher.encryptStringAsBytes(string) => Promise
cipher.decrypt(encrypted) => Promise
cipher.decryptToString(encrypted) => Promise
cipher.decryptBytes(encBytes) => Promise
cipher.decryptBytesToString(encBytes) => Promise
`
`text
Cipher.utils.bytesToHex(bytes) => hex string
Cipher.utils.hexToBytes(hex) => bytes
Cipher.utils.bytesToBase64(bytes) => base64
Cipher.utils.base64ToBytes(base64) => bytes
Cipher.utils.bytesToUrlSafe(bytes) => url-safe base64 string
Cipher.utils.urlSafeToBytes(url64) => bytes
``
The _Initialization Vector_ (_IV_) is a _salt_ that prevents known-plaintext
attacks - meaning that if you encrypt the same message with the same key twice,
you get a different encrypted output.
The first 12-bytes (96-bits) are for the _IV_. The following bytes are the data
and the _Tag_.
If the data is somehow corrupted or truncated, but the first bytes are intact,
it may be possible to use the IV to restore some of the partial data (though
_Tag_ verification will likely fail).
Copyright 2021-Present Root, Inc
This Source Code Form is subject to the terms of the Mozilla \
Public License, v. 2.0. If a copy of the MPL was not distributed \
with this file, You can obtain one at \
https://mozilla.org/MPL/2.0/.