🔐 kruptein

crypto (krip-toh); from kruptein to hide or conceal.

🔒 Encrypt

Encrypt a plaintext message using the default options.

const kruptein = require("kruptein")();
const secret = "S3cre+_Squ1rr3l";
const plaintext = "Some kind of wonderfully private message";

kruptein.set(secret, plaintext, (error, ciphertext) => {
  if (error) {
    throw new Error(error);
  }

  console.log(ciphertext);
});

🔓 Decrypt

Decrypt a ciphertext returned by kruptein.set() using the same secret.

const kruptein = require("kruptein")();
const secret = "S3cre+_Squ1rr3l";
const ciphertext = "<ciphertext returned by kruptein.set()>";

kruptein.get(secret, ciphertext, (error, plaintext) => {
  if (error) {
    throw new Error(error);
  }

  console.log(plaintext);
});

📦 Install

To install npm install kruptein

👓 Methods

• .set(secret, plaintext, [aad], callback)
• .get(secret, ciphertext, [{at: auth_tag, aad: aad}], callback)

🛠️ Options

Industry standards are used for the algorithm, hashing algorithm, key & IV sizes. The default key derivation function is pbkdf2, however use of the scrypt or argon2 can be used as well.

Cryptography options

• algorithm: (Optional) Cipher algorithm from crypto.getCiphers(); AES or ARIA at 192 or 256 bits in gcm, ccm, ocb or cbc mode, or chacha20-poly1305. Default: aes-256-gcm.
• hashing: (Optional) Hash algorithm from crypto.getHashes(); SHA-2 & SHA-3 families only. Default: sha384.
• key_size: (Optional) Key size bytes (should match block size of algorithm). Default: 32
• iv_size: (Optional) IV size bytes. Default: 16.
• at_size: (Optional) Authentication tag size. Applicable to gcm & ocb cipher modes. Default: 128.

Key derivation options

• use_scrypt: (Optional) Use .scrypt() to derive a key. Requires node > v10. Default/Fallback: .pbkdf2().
• use_argon2: (Optional) Use .argon2id() to derive a key. Requires node > v24. Default/Fallback: .pbkdf2().

Encoding options

• encodeas: (Optional) Output encoding. Currently supports binary, latin1, hex, base64 & base64url. Default: base64.
• use_asn1: (Optional) Disable the default ASN.1 encoding. Default: true

📐 Options example

An example of creating a new ciphertext object.

const opts = {
  algorithm: 'aes-256-gcm',
  hashing: 'sha384',
  key_size: 64,
  iv_size: 16,
  at_size: 128,
  use_argon2: true,
  encodeas: 'base64',
  use_asn1: true
}

const kruptein = require("kruptein")(opts || {});

🗝️ Usage

When selecting an algorithm from crypto.getCiphers() the iv and key_size values are calculated auto-magically to make implementation easy.

You can always define your own if the defaults per algorithm and mode aren't what you would like; see the options section above.

The secret must meet complexity requirements

🌱 Output

The .set() method output depends on three factors; the encodeas, algorithm and use_asn1.

For any algorithm that supports authentication (AEAD), the object structure includes the Authentication Tag and the Additional Authentication Data attribute and value.

When the use_asn1 option is enabled (default is true), the result is an ASN.1 value using the encodeas value. While this is a more complex encoding option, it helps standardize & minimize the size of the resulting ciphertext output.

🧪 Test harness

The included test harness, invoked with npm test, makes every attempt to trap and handle errors. Some of which come from side channel or possible malability of the resultant ciphertext.

This can be seen within the test/index.js CI test harness under the HMAC, AT & AAD validation test cases.

npm test covers the default cipher, hash & encoding. npm run test:full (or KRUPTEIN_FULL_MATRIX=1) feeds every cipher & hash reported by crypto.getCiphers() & crypto.getHashes(), and every Buffer encoding, through the library; unsupported combinations must be rejected with an error and supported ones must round-trip.

🧠 References

This module conforms to industry recommendations regarding algorithm type, mode, key size, iv size & implementation, digests, key derivation & management etc. References used provided here:

RFC:

• RFC 2104: HMAC: Keyed-Hashing for Message Authentication
• RFC 3610: Counter with CBC-MAC (CCM)
• RFC 4086: Randomness Requirements for Security
• RFC 4648: The Base16, Base32, and Base64 Data Encodings
• RFC 5084: Using AES-CCM and AES-GCM Authenticated Encryption
• RFC 5794: A Description of the ARIA Encryption Algorithm
• RFC 5869: HMAC-based Extract-and-Expand Key Derivation Function (HKDF)
• RFC 7253: The OCB Authenticated-Encryption Algorithm
• RFC 7914: The scrypt Password-Based Key Derivation Function
• RFC 8018: Password-Based Cryptography Specification
• RFC 8259: The JavaScript Object Notation (JSON) Data Interchange Format
• RFC 8439: ChaCha20 and Poly1305 for IETF Protocols
• RFC 9106: Argon2 Memory-Hard Function for Password Hashing and Proof-of-Work Applications
• X.690: ASN.1 encoding rules: Specification of Basic Encoding Rules (BER), Canonical Encoding Rules (CER) and Distinguished Encoding Rules (DER)
• X.697: ASN.1 encoding rules: Specifications of JavaScript Object Notation Encoding Rules (JER)

NIST:

• SP 800-38A: Block cipher modes of operation
• SP 800-38C: Recommendation for Block Cipher Modes of Operation: The CCM Mode for Authentication and Confidentiality
• SP 800-38D: Recommendation for Block Cipher Modes of Operation: Galois/Counter Mode (GCM) and GMAC
• SP 800-56C: Recommendation for Key-Derivation Methods in Key-Establishment Schemes
• SP 800-57P1: Recommendations for key management
• SP 800-107: Recommendation for Applications Using Approved Hash Algorithms
• SP 800-108: Recommendation for Key Derivation Using Pseudorandom Functions
• SP 800-131A: Transitioning the Use of Cryptographic Algorithms and Key Lengths
• SP 800-132: Recommendation for Password-Based Key Derivation
• SP 800-175B: Guideline for Using Cryptographic Standards in the Federal Government
• SP 800-90A: Recommendation for Random Number Generation Using Deterministic Random Bit Generators

FIPS:

• FIPS 197: Advanced Encryption Standard (AES)
• FIPS 198-1: The Keyed-Hash Message Authentication Code (HMAC)
• FIPS 180-4: Secure Hash Standard (SHS)
• FIPS 186-5: Digital Signature Standard (DSS)
• FIPS 202: SHA-3 Standard: Permutation-Based Hash and Extendable-Output Functions

📡 Contributing

Contributions are welcome & appreciated!

Refer to the contributing document to help facilitate pull requests.

📑 License

This software is licensed under the MIT License.

Copyright Jason Gerfen, 2019.