The public interface for explicit client side encryption
,
line 71Create a new encryption instance
Name Type Descriptionclient MongoClient
The client used for encryption
options object
Additional settings
Name Type DescriptionkeyVaultNamespace string
The namespace of the key vault, used to store encryption keys
keyVaultClient MongoClient optional
A MongoClient used to fetch keys from a key vault. Defaults to client
kmsProviders KMSProviders optional
options for specific KMS providers to use
new ClientEncryption(mongoClient, {
keyVaultNamespace: 'client.encryption',
kmsProviders: {
local: {
key: masterKey // The master key used for encryption/decryption. A 96-byte long Buffer
}
}
});
new ClientEncryption(mongoClient, {
keyVaultNamespace: 'client.encryption',
kmsProviders: {
aws: {
accessKeyId: AWS_ACCESS_KEY,
secretAccessKey: AWS_SECRET_KEY
}
}
});
,
line 204Creates a data key used for explicit encryption and inserts it into the key vault namespace
Name Type Descriptionprovider string
The KMS provider used for this data key. Must be 'aws', 'azure', 'gcp', or 'local'
options object optional
Options for creating the data key
Name Type DescriptionmasterKey AWSEncryptionKeyOptions | AzureEncryptionKeyOptions | GCPEncryptionKeyOptions optional
Idenfities a new KMS-specific key used to encrypt the new data key
keyAltNames Array.<string> optional
An optional list of string alternate names used to reference a key. If a key is created with alternate names, then encryption may refer to the key by the unique alternate name instead of by _id.
callback ClientEncryption~createDataKeyCallback optional
Optional callback to invoke when key is created
the id of the created data key, or rejects with an error. If a callback is provided, returns nothing.
// Using callbacks to create a local key
clientEncryption.createDataKey('local', (err, dataKey) => {
if (err) {
// This means creating the key failed.
} else {
// key creation succeeded
}
});
// Using async/await to create a local key
const dataKeyId = await clientEncryption.createDataKey('local');
// Using async/await to create an aws key
const dataKeyId = await clientEncryption.createDataKey('aws', {
masterKey: {
region: 'us-east-1',
key: 'xxxxxxxxxxxxxx' // CMK ARN here
}
});
// Using async/await to create an aws key with a keyAltName
const dataKeyId = await clientEncryption.createDataKey('aws', {
masterKey: {
region: 'us-east-1',
key: 'xxxxxxxxxxxxxx' // CMK ARN here
},
keyAltNames: [ 'mySpecialKey' ]
});
,
line 343Explicitly decrypt a provided encrypted value
Name Type Descriptionvalue Buffer
An encrypted value
callback ClientEncryption~decryptCallback
Optional callback to invoke when value is decrypted
// Decrypting value with callback API
function decryptMyValue(value, callback) {
clientEncryption.decrypt(value, callback);
}
// Decrypting value with async/await API
async function decryptMyValue(value) {
return clientEncryption.decrypt(value);
}
,
line 281Explicitly encrypt a provided value. Note that either options.keyId or options.keyAltName must
be specified. Specifying both options.keyId and options.keyAltName is considered an error.
value *
The value that you wish to serialize. Must be of a type that can be serialized into BSON
options object Name Type Description keyId ClientEncryption~dataKeyId optional
The id of the Binary dataKey to use for encryption
keyAltName string optional
A unique string name corresponding to an already existing dataKey.
algorithm
The algorithm to use for encryption. Must be either 'AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic' or AEAD_AES_256_CBC_HMAC_SHA_512-Random'
callback ClientEncryption~encryptCallback optional
Optional callback to invoke when value is encrypted
// Encryption with callback API
function encryptMyData(value, callback) {
clientEncryption.createDataKey('local', (err, keyId) => {
if (err) {
return callback(err);
}
clientEncryption.encrypt(value, { keyId, algorithm: 'AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic' }, callback);
});
}
// Encryption with async/await api
async function encryptMyData(value) {
const keyId = await clientEncryption.createDataKey('local');
return clientEncryption.encrypt(value, { keyId, algorithm: 'AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic' });
}
// Encryption using a keyAltName
async function encryptMyData(value) {
await clientEncryption.createDataKey('local', { keyAltNames: 'mySpecialKey' });
return clientEncryption.encrypt(value, { keyAltName: 'mySpecialKey', algorithm: 'AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic' });
}
,
line 129error Error optional
If present, indicates an error that occurred in the creation of the data key
dataKeyId ClientEncryption~dataKeyId optional
If present, returns the id of the created data key
The id of an existing dataKey. Is a bson Binary value.
Can be used for ClientEncryption.encrypt, and can be used to directly
query for the data key itself against the key vault namespace.
,
line 318err Error optional
If present, indicates an error that occurred in the process of decryption
result object optional
If present, is the decrypted result
,
line 238err Error optional
If present, indicates an error that occurred in the process of encryption
result Buffer optional
If present, is the encrypted result
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4