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
DataService
Data Service
KeyFace
Keys Face
KeyService
Key Service
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 |
LimitsService
BaseService.register(as, executor, storage, options) ⇒ 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
AESPlugin.register()
Register this plugin
Kind: static method of AESPlugin
HKDFPlugin
HKDF plugin
HKDFPlugin.register()
Register this plugin
Kind: static method of HKDFPlugin
HMACPlugin
HMAC plugin
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.
PasswordPlugin.register()
Register this plugin
Kind: static method of PasswordPlugin
PBKDF2Plugin
PBKDF2 plugin
PBKDF2Plugin.register()
Register this plugin
Kind: static method of PBKDF2Plugin
RSAPlugin
RSA plugin
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
-
instance
vaultPlugin.defaultBits()
Default bits to use, if applicable
Kind: instance method of VaultPlugin
boolean
vaultPlugin.isAsymetric() ⇒ 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
VaultPlugin.getPlugin(name) ⇒ 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
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
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 |
boolean
encryptedStorage.isLocked() ⇒ Check if storage is locked
Kind: instance method of EncryptedStorage
Returns: boolean
- true, if locked
KeyInfo
Sealed key info
new KeyInfo(info)
C-tor
Param | Type | Default | Description |
---|---|---|---|
info | object |
{} |
optional default values |
SQLStorage
SQL secret storage
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