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:

• FTN13: FutoIn Secure Vault

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
  • .PING_VERSION
  • .register(as, ccm, name, endpoint, [credentials], [options])

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

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

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
  • instance
    • .defaultBits()
    • .isAsymetric() ⇒ boolean
    • .generate(as, options)
    • .validateKey(as, key)
    • .derive(as, base, bits, hash, options)
    • .pubkey(as, key, options)
    • .encrypt(as, key, data, options)
    • .decrypt(as, key, edata, options)
    • .sign(as, key, data, options)
    • .verify(as, key, edata, sig, options)
    • .random(as, size)
  • static
    • .registerPlugin(name, impl)
    • .getPlugin(name) ⇒ VaultPlugin

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)
  • .isLocked() ⇒ boolean

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