fix: encrypt/decrypt interface should be the same (#189)

resolves #182

The encrypt/decrypt browser and node interfaces were slightly different.
Make all the interfaces the same.
The language is chosen to be similar to the Python ESDK

Author: seebees

modules/client-browser/Readme.md

@@ -69,10 +69,10 @@ const plainText = new Uint8Array([1, 2, 3, 4, 5])
  * the Encryption SDK returns an "encrypted message" that includes the ciphertext, 
  * the encryption context, and the encrypted data keys.
  */ 
-const { cipherMessage } = await encrypt(keyring, plainText, { encryptionContext: context })
+const { ciphertext } = await encrypt(keyring, plainText, { encryptionContext: context })
 
 /* Decrypt the ciphertext using the same keyring */
-const { clearMessage, messageHeader } = await decrypt(keyring, cipherMessage)
+const { plaintext, messageHeader } = await decrypt(keyring, ciphertext)
 
 /* Get the encryption context */
 const { encryptionContext } = messageHeader
@@ -87,8 +87,8 @@ Object
     })
 
 /* If the encryption context is verified, log the plaintext. */
-document.write('</br>Decrypted:' + clearMessage)
-console.log(clearMessage)
+document.write('</br>Decrypted:' + plaintext)
+console.log(plaintext)
 
 ```
 

modules/decrypt-browser/src/decrypt.ts

@@ -40,7 +40,7 @@ const { messageAADContentString, messageAAD } = aadFactory(fromUtf8)
 
 export interface DecryptResult {
   messageHeader: MessageHeader
-  clearMessage: Uint8Array
+  plaintext: Uint8Array
 }
 
 export async function decrypt (
@@ -67,7 +67,7 @@ export async function decrypt (
   // The tag is appended to the Data
   await getSubtleDecrypt(headerIv, rawHeader)(headerAuthTag) // will throw if invalid
 
-  const { clearMessage, readPos } = await bodyDecrypt({ buffer: ciphertext, getSubtleDecrypt, headerInfo })
+  const { plaintext, readPos } = await bodyDecrypt({ buffer: ciphertext, getSubtleDecrypt, headerInfo })
 
   dispose()
 
@@ -81,9 +81,9 @@ export async function decrypt (
     const isValid = await subtleVerify(rawSignature, data)
     /* Postcondition: subtleVerify must validate the signature. */
     needs(isValid, 'Invalid Signature')
-    return { messageHeader, clearMessage }
+    return { messageHeader, plaintext }
   } else {
-    return { messageHeader, clearMessage }
+    return { messageHeader, plaintext }
   }
 }
 
@@ -118,8 +118,8 @@ async function bodyDecrypt ({ buffer, getSubtleDecrypt, headerInfo }: BodyDecryp
     clearBuffers.push(clearBlob)
     readPos = frameInfo.readPos
     if (frameInfo.isFinalFrame) {
-      const clearMessage = concatBuffers(...clearBuffers)
-      return { clearMessage, readPos }
+      const plaintext = concatBuffers(...clearBuffers)
+      return { plaintext, readPos }
     }
   }
 }

modules/decrypt-browser/test/decrypt.test.ts

@@ -23,7 +23,7 @@ import * as fixtures from './fixtures'
 
 describe('decrypt', () => {
   it('buffer', async () => {
-    const { clearMessage: test, messageHeader } = await decrypt(
+    const { plaintext: test, messageHeader } = await decrypt(
       fixtures.decryptKeyring(),
       fixtures.ciphertextAlgAes256GcmIv12Tag16HkdfSha384EcdsaP384()
     )

modules/encrypt-browser/src/encrypt.ts

@@ -54,7 +54,7 @@ export interface EncryptInput {
 
 export interface EncryptResult {
   messageHeader: MessageHeader
-  cipherMessage: Uint8Array
+  ciphertext: Uint8Array
 }
 
 export async function encrypt (
@@ -145,7 +145,7 @@ export async function encrypt (
     bodyContent.push(frameHeader, cipherBufferAndAuthTag)
   }
 
-  const cipherMessage = concatBuffers(
+  const ciphertext = concatBuffers(
     header,
     headerAuthIv,
     headerAuthTag,
@@ -155,11 +155,11 @@ export async function encrypt (
   dispose()
 
   if (typeof subtleSign === 'function') {
-    const signatureArrayBuffer = await subtleSign(cipherMessage)
+    const signatureArrayBuffer = await subtleSign(ciphertext)
     const derSignature = raw2der(new Uint8Array(signatureArrayBuffer), material.suite)
     const signatureInfo = serializeSignatureInfo(derSignature)
-    return { cipherMessage: concatBuffers(cipherMessage, signatureInfo), messageHeader }
+    return { ciphertext: concatBuffers(ciphertext, signatureInfo), messageHeader }
   } else {
-    return { cipherMessage, messageHeader }
+    return { ciphertext, messageHeader }
   }
 }

modules/encrypt-browser/test/encrypt.test.ts

@@ -73,7 +73,7 @@ describe('encrypt structural testing', () => {
     const encryptionContext = { simple: 'context' }
 
     const plaintext = fromUtf8('asdf')
-    const { cipherMessage, messageHeader } = await encrypt(keyRing, plaintext, { encryptionContext })
+    const { ciphertext, messageHeader } = await encrypt(keyRing, plaintext, { encryptionContext })
 
     /* The default algorithm suite will add a signature key to the context.
      * So I only check that the passed context elements exist.
@@ -82,7 +82,7 @@ describe('encrypt structural testing', () => {
     expect(messageHeader.encryptedDataKeys).lengthOf(1)
     expect(messageHeader.encryptedDataKeys[0]).to.deep.equal(edk)
 
-    const messageInfo = deserializeMessageHeader(cipherMessage)
+    const messageInfo = deserializeMessageHeader(ciphertext)
     if (!messageInfo) throw new Error('I should never see this error')
 
     expect(messageHeader).to.deep.equal(messageInfo.messageHeader)
@@ -96,9 +96,9 @@ describe('encrypt structural testing', () => {
   it('can fully parse a framed message', async () => {
     const plaintext = fromUtf8('asdf')
     const frameLength = 1
-    const { cipherMessage } = await encrypt(keyRing, plaintext, { frameLength })
+    const { ciphertext } = await encrypt(keyRing, plaintext, { frameLength })
 
-    const headerInfo = deserializeMessageHeader(cipherMessage)
+    const headerInfo = deserializeMessageHeader(ciphertext)
     if (!headerInfo) throw new Error('this should never happen')
 
     const tagLength = headerInfo.algorithmSuite.tagLength / 8
@@ -107,7 +107,7 @@ describe('encrypt structural testing', () => {
     let bodyHeader: any
     // for every frame...
     for (; i < 4; i++) {
-      bodyHeader = decodeBodyHeader(cipherMessage, headerInfo, readPos)
+      bodyHeader = decodeBodyHeader(ciphertext, headerInfo, readPos)
       if (!bodyHeader) throw new Error('this should never happen')
       readPos = bodyHeader.readPos + bodyHeader.contentLength + tagLength
     }
@@ -117,7 +117,7 @@ describe('encrypt structural testing', () => {
 
     // This implicitly tests that I have consumed all the data,
     // because otherwise the footer section will be too large
-    const footerSection = cipherMessage.slice(readPos)
+    const footerSection = ciphertext.slice(readPos)
     // This will throw if it does not deserialize correctly
     deserializeSignature(footerSection)
   })

modules/example-browser/src/aes_simple.ts

@@ -67,7 +67,7 @@ import { toBase64 } from '@aws-sdk/util-base64-browser'
   const plainText = new Uint8Array([1, 2, 3, 4, 5])
 
   /* Encrypt the data. */
-  const { cipherMessage } = await encrypt(keyring, plainText, { encryptionContext: context })
+  const { ciphertext } = await encrypt(keyring, plainText, { encryptionContext: context })
 
   /* Log the plain text
    * only for testing and to show that it works.
@@ -78,11 +78,11 @@ import { toBase64 } from '@aws-sdk/util-base64-browser'
   /* Log the base64-encoded ciphertext
    * so that you can try decrypting it with another AWS Encryption SDK implementation.
    */
-  const cipherMessageBase64 = toBase64(cipherMessage)
-  console.log(cipherMessageBase64)
-  document.write(cipherMessageBase64)
+  const ciphertextBase64 = toBase64(ciphertext)
+  console.log(ciphertextBase64)
+  document.write(ciphertextBase64)
 
-  const { clearMessage, messageHeader } = await decrypt(keyring, cipherMessage)
+  const { plaintext, messageHeader } = await decrypt(keyring, ciphertext)
 
   /* Grab the encryption context so you can verify it. */
   const { encryptionContext } = messageHeader
@@ -103,6 +103,6 @@ import { toBase64 } from '@aws-sdk/util-base64-browser'
   /* Log the clear message
    * only for testing and to show that it works.
    */
-  document.write('</br>clearMessage:' + clearMessage)
-  console.log(clearMessage)
+  document.write('</br>plaintext:' + plaintext)
+  console.log(plaintext)
 })()

modules/example-browser/src/kms_simple.ts

@@ -92,7 +92,7 @@ declare const AWS_CREDENTIALS: {accessKeyId: string, secretAccessKey:string }
   const plainText = new Uint8Array([1, 2, 3, 4, 5])
 
   /* Encrypt the data. */
-  const { cipherMessage } = await encrypt(keyring, plainText, { encryptionContext: context })
+  const { ciphertext } = await encrypt(keyring, plainText, { encryptionContext: context })
 
   /* Log the plain text
    * only for testing and to show that it works.
@@ -103,11 +103,11 @@ declare const AWS_CREDENTIALS: {accessKeyId: string, secretAccessKey:string }
   /* Log the base64-encoded ciphertext
    * so that you can try decrypting it with another AWS Encryption SDK implementation.
    */
-  const cipherMessageBase64 = toBase64(cipherMessage)
-  console.log(cipherMessageBase64)
-  document.write(cipherMessageBase64)
+  const ciphertextBase64 = toBase64(ciphertext)
+  console.log(ciphertextBase64)
+  document.write(ciphertextBase64)
 
-  const { clearMessage, messageHeader } = await decrypt(keyring, cipherMessage)
+  const { plaintext, messageHeader } = await decrypt(keyring, ciphertext)
 
   /* Grab the encryption context so you can verify it. */
   const { encryptionContext } = messageHeader
@@ -128,6 +128,6 @@ declare const AWS_CREDENTIALS: {accessKeyId: string, secretAccessKey:string }
   /* Log the clear message
    * only for testing and to show that it works.
    */
-  document.write('</br>Decrypted:' + clearMessage)
-  console.log(clearMessage)
+  document.write('</br>Decrypted:' + plaintext)
+  console.log(plaintext)
 })()

modules/example-browser/src/multi_keyring.ts

@@ -122,7 +122,7 @@ declare const AWS_CREDENTIALS: {accessKeyId: string, secretAccessKey:string }
   const plainText = new Uint8Array([1, 2, 3, 4, 5])
 
   /* Encrypt the data. */
-  const { cipherMessage } = await encrypt(keyring, plainText, { encryptionContext: context })
+  const { ciphertext } = await encrypt(keyring, plainText, { encryptionContext: context })
 
   /* Log the plain text
    * only for testing and to show that it works.
@@ -133,9 +133,9 @@ declare const AWS_CREDENTIALS: {accessKeyId: string, secretAccessKey:string }
   /* Log the base64-encoded ciphertext
    * so that you can try decrypting it with another AWS Encryption SDK implementation.
    */
-  const cipherMessageBase64 = toBase64(cipherMessage)
-  console.log(cipherMessageBase64)
-  document.write(cipherMessageBase64)
+  const ciphertextBase64 = toBase64(ciphertext)
+  console.log(ciphertextBase64)
+  document.write(ciphertextBase64)
 
   /* Decrypt the data.
    * This decrypt call could be done with **any** of the 3 keyrings.
@@ -144,7 +144,7 @@ declare const AWS_CREDENTIALS: {accessKeyId: string, secretAccessKey:string }
    * decrypt(aesKeyring, ciphertext)
    * would both work as well.
    */
-  const { clearMessage, messageHeader } = await decrypt(keyring, cipherMessage)
+  const { plaintext, messageHeader } = await decrypt(keyring, ciphertext)
 
   /* Grab the encryption context so you can verify it. */
   const { encryptionContext } = messageHeader
@@ -165,6 +165,6 @@ declare const AWS_CREDENTIALS: {accessKeyId: string, secretAccessKey:string }
   /* Log the clear message
    * only for testing and to show that it works.
    */
-  document.write('</br>Decrypted:' + clearMessage)
-  console.log(clearMessage)
+  document.write('</br>Decrypted:' + plaintext)
+  console.log(plaintext)
 })()

modules/example-browser/src/rsa_simple.ts

@@ -69,7 +69,7 @@ import { toBase64 } from '@aws-sdk/util-base64-browser'
   const plainText = new Uint8Array([1, 2, 3, 4, 5])
 
   /* Encrypt the data. */
-  const { cipherMessage } = await encrypt(keyring, plainText, { encryptionContext: context })
+  const { ciphertext } = await encrypt(keyring, plainText, { encryptionContext: context })
 
   /* Log the plain text
    * only for testing and to show that it works.
@@ -80,11 +80,11 @@ import { toBase64 } from '@aws-sdk/util-base64-browser'
   /* Log the base64-encoded ciphertext
    * so that you can try decrypting it with another AWS Encryption SDK implementation.
    */
-  const cipherMessageBase64 = toBase64(cipherMessage)
-  console.log(cipherMessageBase64)
-  document.write(cipherMessageBase64)
+  const ciphertextBase64 = toBase64(ciphertext)
+  console.log(ciphertextBase64)
+  document.write(ciphertextBase64)
 
-  const { clearMessage, messageHeader } = await decrypt(keyring, cipherMessage)
+  const { plaintext, messageHeader } = await decrypt(keyring, ciphertext)
 
   /* Grab the encryption context so you can verify it. */
   const { encryptionContext } = messageHeader
@@ -105,6 +105,6 @@ import { toBase64 } from '@aws-sdk/util-base64-browser'
   /* Log the clear message
    * only for testing and to show that it works.
    */
-  document.write('</br>clearMessage:' + clearMessage)
-  console.log(clearMessage)
+  document.write('</br>plaintext:' + plaintext)
+  console.log(plaintext)
 })()

modules/integration-browser/src/integration.decrypt.test.ts

@@ -40,8 +40,8 @@ describe('browser decryption vectors', function () {
       const good = fromBase64(plainText)
       try {
         const cmm = await decryptMaterialsManagerWebCrypto(keysInfo)
-        const { clearMessage } = await decrypt(cmm, cipher)
-        expect(good).toEqual(clearMessage)
+        const { plaintext } = await decrypt(cmm, cipher)
+        expect(good).toEqual(plaintext)
       } catch (e) {
         if (!notSupportedMessages.includes(e.message)) throw e
       }

modules/integration-browser/src/integration.encrypt.test.ts

@@ -42,14 +42,14 @@ describe('browser encrypt tests', function () {
       const plainText = fromBase64(plainTextData)
       try {
         const cmm = await encryptMaterialsManagerWebCrypto(keysInfo)
-        const { cipherMessage } = await encrypt(cmm, plainText, encryptOp)
+        const { ciphertext } = await encrypt(cmm, plainText, encryptOp)
         const response = await fetch(decryptOracle, {
           method: 'POST',
           headers: {
             'Content-Type': 'application/octet-stream',
             'Accept': 'application/octet-stream'
           },
-          body: cipherMessage
+          body: ciphertext
         })
         const body = await response.arrayBuffer()
         needs(response.ok, `Failed to decrypt: ${toUtf8(body)}`)