nile-secrets
v0.2.5
Published
Envelope encryption for nile projects using nodejs.
Downloads
256
Readme
nile-secrets
Envelope encryption for nile projects using nodejs.
Envelope Encryption
Envelope encryption uses a single secret key to encrypt a collection of several secrets. This process is more convenient and more efficient than externally encrypting each secret independently.
Nile Encryption
nile has a great feature that automatically decrypts secret ciphers from AWS KMS. This package is intended to supplement this feature by making it more convenient to secure a collection of secrets.
Usage
Setup
- Add envelope key to
nile.yml
...
override:
project:
...
environment:
SECRET_KEY: %{abcdef}
...
...
- Add scripts to
package.json
...
"scripts": {
...
"decrypt": "node -e \"require('nile-secrets').decryptFiles({environment:process.argv[1]})\"",
"encrypt": "node -e \"require('nile-secrets').encryptFiles({environment:process.argv[1]})\"",
...
},
...
- Add configs to
package.json
...
"config": {
...
"secrets": {
"keyName": "SECRET_KEY"
...
}
...
},
...
Encrypting secrets
- Create an environment-specific file at
secrets/${environment}.json
that contains all of your secret configuration npm run encrypt ${environment}
Note: When encrypting/decrypting a secrets file, the source will be deleted to avoid source truth ambiguity
Note: Add secrets/*.json
to your project's .gitignore
file to avoid accidentally checking in unencrypted secrets
Editing secrets
npm run decrypt ${environment}
- Edit your
secrets/${environment}.json
file npm run encrypt ${environment}
Using secrets in your code
With Callback
var nileSecrets = require('nile-secrets');
nileSecrets(
{
environment:process.env.DEPLOYMENT
},
(secrets) => {
// use your secrets here
}
);
With Promise
var nileSecrets = require('nile-secrets');
nileSecrets({
environment:process.env.DEPLOYMENT
})
.then((secrets) => {
// use your secrets here
});
Options
Ways to configure options, from highest priority to lowest:
- parameter hash object to the nileSecrets method
package.json
config fields
Option Fields and Default Values
- key [
undefined
] - keyCipher / config.secrets.keyCipher [
undefined
] - nileFile / config.secrets.nileFile [
"./nile.yml"
] - environment [
undefined
] - keyName / config.secrets.keyName [
"CIPHER_KEY"
] - envName / config.secrets.envName [
"NODE_ENV"
] - name [
undefined
] - glob [
undefined
] - dir / config.secrets.dir [
"./secrets"
] - ciphertextExt / config.secrets.ciphertextExt [
".bin"
] - plaintextExt / config.secrets.plaintextExt [
".json"
] - algorithm / config.secrets.algorithm [
"aes256"
] - json / config.secrets.json [
plaintextExt === ".json"
]
Determining the envelope key
- If the
key
parameter is provided, it is used directly as the encryption key - Else if the
keyCipher
parameter is provided, it is decrypted via AWS KMS to retrieve the encryption key - Else if the
environment
parameter (cannot be set inpackage.json
since it is shared by multiple environments in the project) is provided, the keyCipher is parsed from the environment variable namedkeyName
found in the corresponding environment in thenile.yml
file. - Else if the
envName
parameter is provided, theenvironment
is determined from the corresponding environment variable and used withkeyName
andnile.yml
as above.
Determining the source file
- If the
name
parameter is provided, use it as the base of the filename - Else if the
environment
parameter is provided (or can be determined fromenvName
as above), use it as the base of the filename - If decrypting, use
ciphertextExt
parameter as ext - Else if encrypting, use
plaintextExt
parameter as ext - return path.resolve(dir, filename + ext)
Exposed Methods
- decrypt(params, [cbk])
decrypt the ciphertext file and return the plaintext secrets via callback or Promise
Note: this method is aliased as the root of the package
- decryptFiles(params, [cbk])
decrypt the ciphertext file and write to plaintext file in the secrets directory. When decrypting files, you may provide a glob to decrypt multiple files, which will override dir
and name
parameters.
Note: this method will delete the corresponding ciphertext file to avoid source truth ambiguity
- decryptSync(params)
decrypt the ciphertext file and return the plaintext secrets directly
Note: when using the *Sync version of decrypt, the cipher key cannot be retrieved from AWS and must be provided directly either via the key
parameter or via the environment using the keyName
parameter
- encrypt(plaintext, params, [cbk])
encrypt the plaintext secrets into the ciphertext file and acknowledge completion via callback or Promise
- encryptFiles(params, [cbk])
decrypt the plaintext file and write to ciphertext file in the secrets directory. When encrypting files, you may provide a glob to decrypt multiple files, which will override dir
and name
parameters.
Note: this method will delete the corresponding plaintext file to avoid source truth ambiguity
- getKey(params, [cbk])
return the envelope key as determined using the above algorithm