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

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