node-s3-encryption-client)

Node.js implementation of the KMS Envelope Encryption for AWS S3

The Amazon S3 Encryption Client (http://docs.aws.amazon.com/kms/latest/developerguide/services-s3.html#sse-client)
currently only exists for Java and Ruby. This library implements KMS envelope encryption
(http://docs.aws.amazon.com/kms/latest/developerguide/workflow.html) for Javascript, adding
an option to choose the cipher algorithm and the S3 objects encoding. It exposes getObject and putObject
from the AWS S3 client, with KMS encryption options for client-side encryption.

Methods

$3

Functions exactly the same as http://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/S3.html#getObject-property,
except that it will transparently decrypt the object if a KMS key is present in its Metadata. Additional params
are as follows.

#### EncryptionContext
Same as the EncryptionContext property here: http://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/KMS.html#generateDataKey-property
Must be specified for decryption (i.e. getObject) if it was specified during encryption (i.e. putObject).

$3

Functions exactly the same as http://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/S3.html#putObject-property,
but with a few additional parameters, as follows.

#### KmsParams
A JSON document matching the params here: http://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/KMS.html#generateDataKey-property
At the very least, KmaParams.KeyId must be defined in order for encryption to happen. Note that, per AWS documentation,
either NumberOfBytes or KeySpec is required in addition to KeyId. Also note that if an EncryptionContext is given,
it must also be specified in the call to getObject.

#### CipherAlgorithm
The cipher algorithm to use when encrypting the object. Find the list by looking at crypto.getCiphers(). Optional,
will be ignored if KmsKeyId is missing.

#### DecryptedEncoding
The character encoding of the file to be uploaded to S3, to be used when encrypting (and thus decrypting) the
object. Optional, will be ignored if KmsKeyId is missing.

$3

Optionally call this method with a value > 0 in order to persist the object in an in-memory cache. This can be used
to avoid repetitively loading objects from S3 and decrypting via KMS in functions that are frequently executed. The
argument is the number of milliseconds for which the S3 object should remain in the cache before becoming stale. Keep
in mind that this limit will only be met as long as the function remains in memory in Lambda (i.e. does not follow
a cold-start of the function). Obviously, using a cache introduces the risk of the in-memory version getting out of
sync with the object in S3; be sure to balance performance against a reasonable TTL that will allow the function to
absorb edits to the object in a timely manner.

Methodology

You can read about KMS envelope encryption above, but here's the summary:

To encrypt:
1. Create a KMS key (it is assumed that you have already done this)
2. Use the key from #1 to generate a KMS Data Key
3. Use the KMS Data Key's Plaintext to encrypt your file
4. Put the file into S3 with the KMS Data Key's CiphertextBlob in the object's Metadata
5. Also include the cipher algorithm and decrypted encoding in the object's Metadata

To decrypt:
1. Get the object
2. Get the CiphertextBlob from the object's Metadata
3. Decrypt the CiphertextBlob using the KMS library (don't need the original KMS KeyId)
4. Use the decrypted key plus the cipher algorithm and decrypted encoding (from the Metadata)
to decrypt the object content

Since you sometimes need to manually upload encrypted objects to S3 manually (i.e. not using this library), there
is a bash script included in the /bin folder that performs the "To encrypt" steps above:
s3-put-encrypted.

Design Decisions

$3

I decided to keep the callback structure in line with the AWS SDK, to most closely match that API - even though I
prefer Promises. If you'd like to use this library as Promises, it's up to you promisify it (as would would the
AWS SDK).

$3

I may be wrong, but it seems like the Java SDK for the S3 Encryption Client doesn't use a salt. This library matches
that decision, mostly because the crypto Cipher/Decipher classes don't support a salt. It might be possible to support
a salt using a different part of the crypto library, but it would require a major reworking of the flow because the KMS
Data Key is base64 but openssl functions that use a salt require hex.

License

Licensed under the Apache License, Version 2.0: http://www.apache.org/licenses/LICENSE-2.0