futoin-secvault

FutoIn Secure Vault reference implementation

Usage no npm install needed!

<script type="module">
  import futoinSecvault from 'https://cdn.skypack.dev/futoin-secvault';
</script>

README

NPM Version NPM Downloads Build Status stable

NPM

About

FutoIn Secure Vault (SV) is a concept to minimize sensitive cryptographic data exposure in projects. It allows different type of key management, data encryption and signing.

This reference implementation is based on encrypted SQL storage. However, the same interface can be implemented in Host Secure Modules (HSM) on demand.

Features:

  • Key types:
    • AES
    • RSA
    • HMAC
    • Password (plain password)
  • Key derivation:
    • PBKDF2
    • HKDF
  • Key manipulations:
    • Generation
    • Injection
    • Encrypted injection
    • Plain exposure
    • Encrypted exposure
    • Wipe out
    • Derivation
    • Public key exposure
  • Data manipulations
    • Encryption & Decryption
    • Signing & Verification

Documentation --> FutoIn Guide

Reference implementation of:

Author: Andrey Galkin

Installation for Node.js

Command line:

$ npm install futoin-secvault --save

or:

$ yarn add futoin-secvault --save

Examples

API documentation

Classes

DataFace

Data Face

DataService

Data Service

KeyFace

Keys Face

KeyService

Key Service

BaseFace

Base Face with neutral common registration functionality

BaseService

Base Service with common registration logic

AESPlugin

AES plugin

HKDFPlugin

HKDF plugin

HMACPlugin

HMAC plugin

PasswordPlugin

Password plugin

Allows passwords from 4 to 255 unicode characters in length. Supports custom characters set through options.chars.

Supports secure password verification.

PBKDF2Plugin

PBKDF2 plugin

RSAPlugin

RSA plugin

VaultPlugin

Base for SecVault plugins

CachedStorageWrapper

Storage wapper with advanced caching & invalidation

DBStorage

Database Encrypted secret storage

EncryptedStorage

Encrypted secret storage base

Assume there is

KeyInfo

Sealed key info

SQLStorage

SQL secret storage

Storage

Secret storage base

DataFace

Data Face

Kind: global class

DataService

Data Service

Kind: global class

KeyFace

Keys Face

Kind: global class

KeyService

Key Service

Kind: global class

BaseFace

Base Face with neutral common registration functionality

Kind: global class
Note: Not official API

BaseFace.LATEST_VERSION

Latest supported FTN13 version

Kind: static property of BaseFace

BaseFace.PING_VERSION

Latest supported FTN4 version

Kind: static property of BaseFace

BaseFace.register(as, ccm, name, endpoint, [credentials], [options])

CCM registration helper

Kind: static method of BaseFace

Param Type Default Description
as AsyncSteps steps interface
ccm AdvancedCCM CCM instance
name string CCM registration name
endpoint * see AdvancedCCM#register
[credentials] * see AdvancedCCM#register
[options] object {} interface options
[options.version] string "1.0" interface version to use

BaseService

Base Service with common registration logic

Kind: global class

new BaseService(storage, options)

C-tor

Param Type Default Description
storage Storage low-level storage instance
options object passed to superclass c-tor
options.failure_limit integer 10000 limit crypt key decrypt failures

BaseService.register(as, executor, storage, options) ⇒ LimitsService

Register futoin.xfers.limits interface with Executor

Kind: static method of BaseService
Returns: LimitsService - instance

Param Type Description
as AsyncSteps steps interface
executor Executor executor instance
storage Storage low-level storage instance
options object implementation defined options

AESPlugin

AES plugin

Kind: global class

AESPlugin.register()

Register this plugin

Kind: static method of AESPlugin

HKDFPlugin

HKDF plugin

Kind: global class

HKDFPlugin.register()

Register this plugin

Kind: static method of HKDFPlugin

HMACPlugin

HMAC plugin

Kind: global class

HMACPlugin.register()

Register this plugin

Kind: static method of HMACPlugin

PasswordPlugin

Password plugin

Allows passwords from 4 to 255 unicode characters in length. Supports custom characters set through options.chars.

Supports secure password verification.

Kind: global class

PasswordPlugin.register()

Register this plugin

Kind: static method of PasswordPlugin

PBKDF2Plugin

PBKDF2 plugin

Kind: global class

PBKDF2Plugin.register()

Register this plugin

Kind: static method of PBKDF2Plugin

RSAPlugin

RSA plugin

Kind: global class

RSAPlugin.register()

Register this plugin

Kind: static method of RSAPlugin

VaultPlugin

Base for SecVault plugins

Kind: global class

vaultPlugin.defaultBits()

Default bits to use, if applicable

Kind: instance method of VaultPlugin

vaultPlugin.isAsymetric() ⇒ boolean

Check if type conforms to asymmetric cryptography requirements

Kind: instance method of VaultPlugin
Returns: boolean - true, if assymetric

vaultPlugin.generate(as, options)

Generate new key

Kind: instance method of VaultPlugin
Note: passes raw key buffer to the next step

Param Type Description
as AsyncSteps AsyncSteps interface
options object implementation-defined options
options.bits integer key length, if applicable

vaultPlugin.validateKey(as, key)

Validate key data

Kind: instance method of VaultPlugin

Param Type Description
as AsyncSteps AsyncSteps interface
key Buffer key data to validate

vaultPlugin.derive(as, base, bits, hash, options)

Derive new key

Kind: instance method of VaultPlugin
Note: passes raw key buffer to the next step

Param Type Default Description
as AsyncSteps AsyncSteps interface
base Buffer base key as is
bits integer key length
hash string hash name to use
options object implementation-defined options
options.salt string "''" salt, if any
options.info string "''" info, if any
options.rounds integer 1000 rounds, if any

vaultPlugin.pubkey(as, key, options)

Get public key from private key

Kind: instance method of VaultPlugin
Note: passes raw key buffer to the next step

Param Type Description
as AsyncSteps AsyncSteps interface
key Buffer raw private key
options object implementation-defined options

vaultPlugin.encrypt(as, key, data, options)

Encrypt arbitrary data

Kind: instance method of VaultPlugin
Note: Passes Buffer { edata | iv | authtag } to the next step

Param Type Default Description
as AsyncSteps AsyncSteps interface
key Buffer raw key
data Buffer raw data
options object implementation-defined options
options.iv Buffer custom IV, if needed
options.aad Buffer additional data, if supported

vaultPlugin.decrypt(as, key, edata, options)

Decrypt arbitrary data

Kind: instance method of VaultPlugin
Note: Passes Buffer of raw data to the next step

Param Type Description
as AsyncSteps AsyncSteps interface
key Buffer raw key
edata object encrypted data as generated by encrypt
options object implementation-defined options
options.aad string additional authentication data, if applicable

vaultPlugin.sign(as, key, data, options)

Encrypt arbitrary data

Kind: instance method of VaultPlugin
Note: Passes Buffer { sig } to the next step

Param Type Description
as AsyncSteps AsyncSteps interface
key Buffer raw key
data Buffer raw data
options object implementation-defined options
options.hash string hash name, if applicable

vaultPlugin.verify(as, key, edata, sig, options)

Decrypt arbitrary data

Kind: instance method of VaultPlugin
Note: Passes Buffer of raw data to the next step

Param Type Description
as AsyncSteps AsyncSteps interface
key Buffer raw key
edata object encrypted data as generated by encrypt
sig Buffer signature to verify
options object implementation-defined options
options.hash string hash name, if applicable

vaultPlugin.random(as, size)

Common API to generate random data

Kind: instance method of VaultPlugin
Note: Passes Buffer of renadom data to the next step

Param Type Description
as AsyncSteps AsyncSteps interface
size integer how many bytes to generate

VaultPlugin.registerPlugin(name, impl)

Register plugin

Kind: static method of VaultPlugin

Param Type Description
name string plugin identifier
impl VaultPlugin plugin implementation

VaultPlugin.getPlugin(name) ⇒ VaultPlugin

Get plugin by name

Kind: static method of VaultPlugin
Returns: VaultPlugin - plugin instance

Param Type Description
name string plugin identifier

CachedStorageWrapper

Storage wapper with advanced caching & invalidation

Kind: global class

new CachedStorageWrapper(ccm, target, options)

C-tor

Param Type Description
ccm AdvancedCCM CCM instance
target Storage target slow storage
options object extra options for fine tune
options.evtpushExecutor object executor instace with PushService
[options.cacheSize] integer max cache entries
[options.ttlMs] integer Cache Time-To-Live in ms
[options.syncDelayMs] integer Cache Sync delay in ms
[options.syncThreads] integer Cache Sync parallelism

DBStorage

Database Encrypted secret storage

Kind: global class

EncryptedStorage

Encrypted secret storage base

Assume there is

Kind: global class

encryptedStorage.setStorageSecret(as, secret, cipher_opts, kdf_opts)

Configure common storage secret which is used to encrypt keys

Kind: instance method of EncryptedStorage

Param Type Default Description
as AsyncSteps AsyncSteps interface
secret Buffer some arbitrary secret
cipher_opts object {} options for encryption/decryption
cipher_opts.type string "AES" cipher type
cipher_opts.bits integer 256 key length for KDF
cipher_opts.mode string "GCM" cipher block mode
cipher_opts.aad string "SecVault" additional auth data
kdf_opts object | null {} KDF options, null to disable
kdf_opts.type string "HKDF" KDF type
kdf_opts.salt string "SecVault" KDF salt
kdf_opts.info string "KEK" info parameter for HKDF
kdf_opts.rounds string 1000 rounds for PBKDF2

encryptedStorage.isLocked() ⇒ boolean

Check if storage is locked

Kind: instance method of EncryptedStorage
Returns: boolean - true, if locked

KeyInfo

Sealed key info

Kind: global class

new KeyInfo(info)

C-tor

Param Type Default Description
info object {} optional default values

SQLStorage

SQL secret storage

Kind: global class

new SQLStorage(ccm, options)

C-tor

Param Type Default Description
ccm AdvancedCCM CCM instance with registered 'secvault' DB
options object options
options.key_table string "enc_keys" name of encrypted key table

Storage

Secret storage base

Kind: global class