jstink 1.1.1 → 1.1.2

package/README.md

@@ -10,7 +10,9 @@ Unfortunately for Javascript developers, [there is no production-ready Javascrip
 
 jstink was built to fill this gap. It provides a very simple API that is hard to misuse, and is compatible with Tink ciphertexts and with [Tinkey](https://developers.google.com/tink/tinkey-overview) encrypted keysets.
 
-jstink currently only supports the Authenticated Encryption with Associated Data (AEAD) encryption primitive with AES256_GCM key types envelope encrypted with AWS KMS keys.
+jstink currently only supports 256 bit AES encryption in GCM mode. AES (Advanced Encryption Standard) is recommended by NIST for federal use in the encryption of classified and unclassified data. GCM (Galois/Counter Mode) is also recommended by NIST and provides authentication as well as encryption - that is it ensures the integrity and authenticity of encrypted data in addition to ensuring confidentiality. GCM also accepts associated data which is authenticated but not encrypted.
+
+jstink currently only supports Tink keysets encrypted with AWS KMS keys.
 
 ## Getting Started
 
@@ -67,7 +69,6 @@ Once you've deployed this keyset, you can make it the default for encryption:
 ```
 tinkey promote-key \
     --key-id <new-key-id> \
-    --key-template AES256_GCM \
     --in keysetv2.json \
     --out keysetv3.json \
     --master-key-uri aws-kms://${MASTER_KEY_ARN}
@@ -77,8 +78,20 @@ Decrypt operations will still use the key that was used for encryption (the encr
 
 ```
 tinkey delete-key \
-    --key-template AES256_GCM \
+    --key-id <key-id> \
     --in keysetv3.json \
     --out keysetv4.json \
     --master-key-uri aws-kms://${MASTER_KEY_ARN}
 ```
+
+## Using Authenticated Associated Data (AAD)
+
+The GCM algorithm used by jstink is an Authenticated Encryption with Associated Data (AEAD) encryption method. This means that it provides for authentication as well as confidentiality, and also allows the message to contain "associated data". This associated data is authenticated but not encrypted. A decryption operation will only work if the same associated data is used for decryption that was used for encryption.
+
+One use of AAD is to bind a ciphertext to it's encryption context. For example, we can use a username as the associated data for data that is encrypted for a specific user:
+
+```javascript
+const ciphertext = await aead.encrypt(userData, username);
+```
+
+This can prevent attacks where encrypted data is 'cut-and-pasted' from one user to another.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "jstink",
-    "version": "1.1.1",
+    "version": "1.1.2",
     "description": "",
     "main": "src/index.js",
     "scripts": {

package/src/aes_gcm.js

@@ -6,7 +6,9 @@ function encrypt(plaintext, associatedData, key) {
     const iv = crypto.randomBytes(12);
     const cipher = crypto.createCipheriv(algorithm, key, iv);
 
-    cipher.setAAD(Buffer.from(associatedData));
+    if (associatedData !== undefined) {
+        cipher.setAAD(Buffer.from(associatedData));
+    }
     const encrypted = cipher.update(plaintext);
     const remaining = cipher.final();
     const tag = cipher.getAuthTag();
@@ -20,7 +22,9 @@ function encrypt(plaintext, associatedData, key) {
 
 function decrypt(ciphertext, associatedData, key, iv, tag) {
     const decipher = crypto.createDecipheriv(algorithm, key, iv);
-    decipher.setAAD(Buffer.from(associatedData));
+    if (associatedData !== undefined) {
+        decipher.setAAD(Buffer.from(associatedData));
+    }
     decipher.setAuthTag(Buffer.from(tag));
     let decrypted = decipher.update(ciphertext);
     decrypted += decipher.final();

package/src/index.js

@@ -10,8 +10,16 @@ async function decryptKeyset(encryptedKeyset) {
     return keysets.create(keysetProtobuf);
 }
 
+/**
+ * Authenticated Encryption with Associated Data (AEAD).
+ *
+ */
 class Aead {
 
+    /**
+     *
+     * @param {object} keyset   The AWK KMS encrypted Tink keyset
+     */
     constructor(keyset) {
         if (!keyset.encryptedKeyset) {
             throw new Error('keyset must contain an encryptedKeyset property');
@@ -25,6 +33,15 @@ class Aead {
         }
     }
 
+    /**
+     * Encrypts the plaintext with the associated data as associated authenticated data.
+     *
+     * @param {string|Buffer} plaintext - the plaintext to be encrypted.
+     * @param {string|Buffer} associatedData - the associated data to be authenticated but not
+     *                                         encrypted. For successful decryption the same
+     *                                         associatedData must be provided.
+     * @returns {Promise<Buffer>} - the ciphertext.
+     */
     encrypt = async (plaintext, associatedData) => {
         await this.init();
         const key = this.decryptedKeys[this.keyset.keysetInfo.primaryKeyId];
@@ -37,6 +54,14 @@ class Aead {
         });
     }
 
+    /**
+     *
+     * @param {Buffer} encrypted - the ciphertext to be decrypted.
+     * @param {string|Buffer} associatedData - the associated data to be authenticated.
+     *                                         For successful decryption must be the same
+     *                                         as used during encryption.
+     * @returns {Promise<Buffer>} - the plaintext.
+     */
     decrypt = async (encrypted, associatedData) => {
         await this.init();
         const {keyId, ciphertext, tag, iv} = ciphertexts.parse(encrypted);

package/tests/index.test.js

@@ -24,18 +24,31 @@ jest.mock('@aws-sdk/client-kms', () => {
 });
 
 describe('jstink', () => {
-    it('should encrypt and decrypt', async () => {
-        const keyset = JSON.parse(fs.readFileSync('tests/keyset.json'));
-        const aead = new Aead(keyset);
 
+    const keyset = JSON.parse(fs.readFileSync('tests/keyset.json'));
+    const aead = new Aead(keyset);
+
+    it('should encrypt and decrypt', async () => {
         const ciphertext = await aead.encrypt('Hello World!', 'customer-id1');
         const plaintext = await aead.decrypt(ciphertext, 'customer-id1');
         expect(plaintext).toBe('Hello World!');
     });
 
+    it('should encrypt and decrypt without associated data', async () => {
+        const ciphertext = await aead.encrypt('Hello World!');
+        const plaintext = await aead.decrypt(ciphertext);
+
+        expect(plaintext).toBe('Hello World!');
+    });
+
+    it('should authenticate associated data', async () => {
+        const ciphertext = await aead.encrypt('Hello World!', 'foo');
+        await expect(aead.decrypt(ciphertext, 'bar')).rejects.toThrow(
+            'Unsupported state or unable to authenticate data'
+        );
+    });
+
     it('should decrypt', async () => {
-        const keyset = JSON.parse(fs.readFileSync('tests/keyset.json'));
-        const aead = new Aead(keyset);
         const ciphertext = fs.readFileSync('tests/encrypted.dat');
         const plaintext = await aead.decrypt(ciphertext, 'customer-id1');
         expect(plaintext).toBe('Hello World!');