Skip to content
crypto; from kruptein to hide or conceal
JavaScript
Branch: master
Clone or download
Latest commit f08f8ba Sep 8, 2019

README.md

kruptein

crypto; from kruptein to hide or conceal

npm Downloads Codacy Badge Known Vulnerabilities Build Status codecov

Install

To install npm install kruptein

Methods

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

Options

  • secret: (Required) Ciphertext passphrase
  • algorithm: (Optional) Cipher algorithm from crypto.getCiphers(). Default: aes-256-gcm.
  • hashing: (Optional) Hash algorithm from crypto.getHashes(). Default: sha512.
  • encodeas: (Optional) Output encoding. Currently only supports binary.
  • 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.

Tests

To test npm test

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 isn't what you would like; see the options section above.

.set(plaintext)

To create new ciphertext.

let opts = {
  secret: 'squirrel'
}, ciphertext;

const kruptein = require('kruptein')(opts);

ciphertext = kruptein.set('Operation mincemeat was an example of deception');

.set(plaintext, [aad])

To create new ciphertext providing custom 'additional authentication data'.

let opts = {
  secret: 'squirrel'
}, ciphertext;

const kruptein = require('kruptein')(opts);

let aad = func_to_generate_aad();

ciphertext = kruptein.set('Operation mincemeat was an example of deception', aad);

.get(ciphertext)

To retrieve plaintext;

let opts = {
  secret: 'squirrel'
}, ciphertext;

const kruptein = require('kruptein')(opts);

plaintext = kruptein.get(ciphertext);

.get(ciphertext, [{at: auth_tag])

To retrieve plaintext using an external authentication tag

let opts = {
  secret: 'squirrel'
}, ciphertext;

const kruptein = require('kruptein')(opts);

let at = func_to_provide_authentication_tag(ciphertext);

plaintext = kruptein.get(ciphertext, at);

.get(ciphertext, [{aad: aad}])

To retrieve plaintext using some optional additional authentication data

let opts = {
  secret: 'squirrel'
}, ciphertext;

const kruptein = require('kruptein')(opts);

let aad = func_to_provide_authentication_data();

plaintext = kruptein.get(ciphertext, aad);

Output

The object .set() creates takes the following format;

Non-Authenticated Ciphers

For those ciphers that DO NOT support authentication modes the following structure is returned.

{
  'hmac': "<calculated hmac>",
  'ct': "<binary format of resulting ciphertext>",
  'iv': "<buffer format of generated/supplied iv>"
}

Authenticated Ciphers

For those ciphers that DO support authentication modes the following structure is returned. Important: Note that in the event additional authentication data (aad) is not provided a digest of the derived key & iv is used.

{
  'hmac': "<calculated hmac>",
  'ct': "<binary format of resulting ciphertext>",
  'iv': "<buffer format of generated/supplied iv>",
  'at': "<buffer format of generated authentication tag>",
  'aad': "<buffer format of generated/supplied additional authentication data>"
}

Cryptography References

This module was developed to conform to the recommendations provided regarding algorithm type, mode, key size, iv size & implementation, digests, key derivation & management etc. For details on publications referenced see below:

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.

You can’t perform that action at this time.