fix: add serializationOptions flag for AAD UTF8 sorting

Author: josecorella

modules/cache-material/src/build_cryptographic_materials_cache_key_helpers.ts

@@ -22,7 +22,7 @@ export function buildCryptographicMaterialsCacheKeyHelpers<
   sha512: (...data: (Uint8Array | string)[]) => Promise<Uint8Array>
 ): CryptographicMaterialsCacheKeyHelpersInterface<S> {
   const { serializeEncryptionContext, serializeEncryptedDataKey } =
-    serializeFactory(fromUtf8)
+    serializeFactory(fromUtf8, {utf8Sorting: false})
 
   return {
     buildEncryptionMaterialCacheKey,
@@ -80,7 +80,7 @@ export function buildCryptographicMaterialsCacheKeyHelpers<
      * However, the RAW Keyring wants _only_ the ADD.
      * So, I just slice off the length.
      */
-    const serializedContext = serializeEncryptionContext(context).slice(2)
+    const serializedContext = serializeEncryptionContext(context, {utf8Sorting: false}).slice(2)
     return sha512(serializedContext)
   }
 }

modules/decrypt-browser/src/decrypt_client.ts

@@ -22,7 +22,7 @@ export function buildDecrypt(
 } {
   const {
     commitmentPolicy = CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT,
-    maxEncryptedDataKeys = false,
+    maxEncryptedDataKeys = false
   } = typeof options === 'string' ? { commitmentPolicy: options } : options
 
   /* Precondition: browser buildDecrypt needs a valid commitmentPolicy. */
@@ -35,7 +35,7 @@ export function buildDecrypt(
 
   const clientOptions: ClientOptions = {
     commitmentPolicy,
-    maxEncryptedDataKeys,
+    maxEncryptedDataKeys
   }
   return {
     decrypt: _decrypt.bind({}, clientOptions),

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

@@ -46,7 +46,7 @@ describe('decrypt', () => {
   it('Precondition: _decrypt needs a valid commitmentPolicy.', async () => {
     await expect(
       _decrypt(
-        { commitmentPolicy: 'fake_policy' as any, maxEncryptedDataKeys: false },
+        { commitmentPolicy: 'fake_policy' as any, maxEncryptedDataKeys: false},
         {} as any,
         {} as any
       )

modules/decrypt-node/src/decrypt_client.ts

@@ -31,6 +31,7 @@ export function buildDecrypt(
   const {
     commitmentPolicy = CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT,
     maxEncryptedDataKeys = false,
+    utf8Sorting = false
   } = typeof options === 'string' ? { commitmentPolicy: options } : options
 
   /* Precondition: node buildDecrypt needs a valid commitmentPolicy. */
@@ -44,6 +45,7 @@ export function buildDecrypt(
   const clientOptions: ClientOptions = {
     commitmentPolicy,
     maxEncryptedDataKeys,
+    utf8Sorting
   }
   return {
     decryptUnsignedMessageStream: _decryptStream.bind(

modules/encrypt-browser/src/encrypt.ts

@@ -31,7 +31,6 @@ import {
 import { fromUtf8 } from '@aws-sdk/util-utf8-browser'
 import { getWebCryptoBackend } from '@aws-crypto/web-crypto-backend'
 
-const serialize = serializeFactory(fromUtf8)
 const { messageAADContentString, messageAAD } = aadFactory(fromUtf8)
 
 export interface EncryptInput {
@@ -47,7 +46,7 @@ export interface EncryptResult {
 }
 
 export async function _encrypt(
-  { commitmentPolicy, maxEncryptedDataKeys }: ClientOptions,
+  { commitmentPolicy, maxEncryptedDataKeys, utf8Sorting }: ClientOptions,
   cmm: KeyringWebCrypto | WebCryptoMaterialsManager,
   plaintext: Uint8Array,
   {
@@ -122,6 +121,10 @@ export async function _encrypt(
 
   const { getSubtleEncrypt, keyCommitment } = await getEncryptInfo(messageId)
 
+  const maybeUtf8Sorting = utf8Sorting ?? false;
+  
+  const serialize = serializeFactory(fromUtf8, {utf8Sorting: maybeUtf8Sorting})
+  
   const messageHeader = serialize.buildMessageHeader({
     suite: material.suite,
     encryptedDataKeys: material.encryptedDataKeys,

modules/encrypt-browser/src/encrypt_client.ts

@@ -23,6 +23,7 @@ export function buildEncrypt(
   const {
     commitmentPolicy = CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT,
     maxEncryptedDataKeys = false,
+    utf8Sorting = false
   } = typeof options === 'string' ? { commitmentPolicy: options } : options
 
   /* Precondition: browser buildEncrypt needs a valid commitmentPolicy. */
@@ -36,6 +37,7 @@ export function buildEncrypt(
   const clientOptions: ClientOptions = {
     commitmentPolicy,
     maxEncryptedDataKeys,
+    utf8Sorting
   }
   return {
     encrypt: _encrypt.bind({}, clientOptions),

modules/encrypt-node/src/encrypt_client.ts

@@ -27,6 +27,7 @@ export function buildEncrypt(
   const {
     commitmentPolicy = CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT,
     maxEncryptedDataKeys = false,
+    utf8Sorting = false
   } = typeof options === 'string' ? { commitmentPolicy: options } : options
 
   /* Precondition: node buildEncrypt needs a valid commitmentPolicy. */
@@ -40,6 +41,7 @@ export function buildEncrypt(
   const clientOptions: ClientOptions = {
     commitmentPolicy,
     maxEncryptedDataKeys,
+    utf8Sorting
   }
   return {
     encryptStream: _encryptStream.bind({}, clientOptions),

modules/encrypt-node/src/encrypt_stream.ts

@@ -33,8 +33,6 @@ import { pipeline } from 'readable-stream'
 import { Duplex } from 'stream'
 
 const fromUtf8 = (input: string) => Buffer.from(input, 'utf8')
-const { serializeMessageHeader, headerAuthIv, buildMessageHeader } =
-  serializeFactory(fromUtf8)
 
 export interface EncryptStreamInput {
   suiteId?: AlgorithmSuiteIdentifier
@@ -53,7 +51,7 @@ export interface EncryptStreamInput {
  * @param op EncryptStreamInput
  */
 export function _encryptStream(
-  { commitmentPolicy, maxEncryptedDataKeys }: ClientOptions,
+  { commitmentPolicy, maxEncryptedDataKeys, utf8Sorting }: ClientOptions,
   cmm: KeyringNode | NodeMaterialsManager,
   op: EncryptStreamInput = {}
 ): Duplex {
@@ -111,15 +109,17 @@ export function _encryptStream(
         'maxEncryptedDataKeys exceeded.'
       )
 
+      const maybeUtf8Sorting = utf8Sorting ?? false;
       const { getCipher, messageHeader, rawHeader, dispose, getSigner } =
-        getEncryptionInfo(material, frameLength)
+        getEncryptionInfo(material, frameLength, maybeUtf8Sorting)
 
       wrappingStream.emit('MessageHeader', messageHeader)
 
       const encryptStream = getFramedEncryptStream(
         getCipher,
         messageHeader,
         dispose,
+        maybeUtf8Sorting,
         { plaintextLength, suite: material.suite }
       )
       const signatureStream = new SignatureStream(getSigner)
@@ -140,9 +140,12 @@ export function _encryptStream(
 
 export function getEncryptionInfo(
   material: NodeEncryptionMaterial,
-  frameLength: number
+  frameLength: number,
+  utf8Sorting: boolean
 ) {
   const { getCipherInfo, dispose, getSigner } = getEncryptHelper(material)
+  const { serializeMessageHeader, headerAuthIv, buildMessageHeader } =
+    serializeFactory(fromUtf8, {utf8Sorting})
   const { suite, encryptionContext, encryptedDataKeys } = material
   const { ivLength, messageFormat } = material.suite
 

modules/encrypt-node/src/framed_encrypt_stream.ts

@@ -18,8 +18,6 @@ import {
 } from '@aws-crypto/material-management-node'
 
 const fromUtf8 = (input: string) => Buffer.from(input, 'utf8')
-const serialize = serializeFactory(fromUtf8)
-const { finalFrameHeader, frameHeader } = serialize
 const aadUtility = aadFactory(fromUtf8)
 
 interface AccumulatingFrame {
@@ -47,6 +45,7 @@ export function getFramedEncryptStream(
   getCipher: GetCipher,
   messageHeader: MessageHeader,
   dispose: () => void,
+  utf8Sorting: boolean,
   {
     plaintextLength,
     suite,
@@ -107,6 +106,7 @@ export function getFramedEncryptStream(
         getCipher,
         isFinalFrame: false,
         suite,
+        utf8Sorting
       })
 
       // Reset frame state for next frame
@@ -129,6 +129,7 @@ export function getFramedEncryptStream(
         getCipher,
         isFinalFrame: true,
         suite,
+        utf8Sorting
       })
 
       this._flushEncryptFrame(encryptFrame)
@@ -205,10 +206,11 @@ type EncryptFrameInput = {
   getCipher: GetCipher
   isFinalFrame: boolean
   suite: NodeAlgorithmSuite
+  utf8Sorting: boolean
 }
 
 export function getEncryptFrame(input: EncryptFrameInput): EncryptFrame {
-  const { pendingFrame, messageHeader, getCipher, isFinalFrame, suite } = input
+  const { pendingFrame, messageHeader, getCipher, isFinalFrame, suite, utf8Sorting } = input
   const { sequenceNumber, contentLength, content } = pendingFrame
   const { frameLength, contentType, messageId } = messageHeader
   /* Precondition: The content length MUST correlate with the frameLength.
@@ -226,6 +228,9 @@ export function getEncryptFrame(input: EncryptFrameInput): EncryptFrame {
       isFinalFrame,
     })}`
   )
+  const serialize = serializeFactory(fromUtf8, {utf8Sorting})
+  const { finalFrameHeader, frameHeader } = serialize
+  
   const frameIv = serialize.frameIv(suite.ivLength, sequenceNumber)
   const bodyHeader = Buffer.from(
     isFinalFrame

modules/encrypt-node/test/framed_encrypt_stream.test.ts

@@ -28,6 +28,7 @@ describe('getFramedEncryptStream', () => {
       getCipher,
       {} as any,
       () => {},
+      false,
       {} as any
     )
     expect(test._transform).is.a('function')
@@ -36,13 +37,13 @@ describe('getFramedEncryptStream', () => {
   it('Precondition: plaintextLength must be within bounds.', () => {
     const getCipher: any = () => {}
     expect(() =>
-      getFramedEncryptStream(getCipher, {} as any, () => {}, {
+      getFramedEncryptStream(getCipher, {} as any, () => {}, false, {
         plaintextLength: -1,
         suite,
       })
     ).to.throw(Error, 'plaintextLength out of bounds.')
     expect(() =>
-      getFramedEncryptStream(getCipher, {} as any, () => {}, {
+      getFramedEncryptStream(getCipher, {} as any, () => {}, false, {
         plaintextLength: Number.MAX_SAFE_INTEGER + 1,
         suite,
       })
@@ -52,7 +53,7 @@ describe('getFramedEncryptStream', () => {
      * I want to make sure that I don't have an errant off by 1 error.
      */
     expect(() =>
-      getFramedEncryptStream(getCipher, {} as any, () => {}, {
+      getFramedEncryptStream(getCipher, {} as any, () => {}, false, {
         plaintextLength: Number.MAX_SAFE_INTEGER,
         suite,
       })
@@ -61,7 +62,7 @@ describe('getFramedEncryptStream', () => {
 
   it('Precondition: Must not process more than plaintextLength.', () => {
     const getCipher: any = () => {}
-    const test = getFramedEncryptStream(getCipher, {} as any, () => {}, {
+    const test = getFramedEncryptStream(getCipher, {} as any, () => {}, false, {
       plaintextLength: 8,
       suite,
     })
@@ -78,6 +79,7 @@ describe('getFramedEncryptStream', () => {
       getCipher,
       { frameLength } as any,
       () => {},
+      false,
       {} as any
     )
 
@@ -112,6 +114,7 @@ describe('getEncryptFrame', () => {
         encryptedDataKeys: [],
       },
       suite,
+      utf8Sorting: false,
     }
     const test1 = getEncryptFrame(input)
     expect(test1.content).to.equal(input.pendingFrame.content)
@@ -146,6 +149,7 @@ describe('getEncryptFrame', () => {
         encryptedDataKeys: [],
       },
       suite,
+      utf8Sorting: false
     }
 
     expect(() => getEncryptFrame(inputFinalFrameToLarge)).to.throw(
@@ -172,6 +176,7 @@ describe('getEncryptFrame', () => {
         encryptedDataKeys: [],
       },
       suite,
+      utf8Sorting: false
     }
 
     // Make sure that it must be equal as long as we are here...

modules/kms-keyring-node/src/kms_hkeyring_node_helpers.ts

@@ -33,7 +33,7 @@ import {
   PROVIDER_ID_HIERARCHY_AS_BYTES,
 } from './constants'
 import { BranchKeyIdSupplier } from '@aws-crypto/kms-keyring'
-import { serializeFactory, uuidv4Factory } from '@aws-crypto/serialize'
+import { serializeFactory, SerializeOptions, uuidv4Factory } from '@aws-crypto/serialize'
 
 export const stringToUtf8Bytes = (input: string): Buffer =>
   Buffer.from(input, 'utf-8')
@@ -45,8 +45,9 @@ const hexBytesToString = (input: Uint8Array): string =>
   Buffer.from(input).toString('hex')
 export const { uuidv4ToCompressedBytes, decompressBytesToUuidv4 } =
   uuidv4Factory(stringToHexBytes, hexBytesToString)
+export const utf8Sorting: SerializeOptions = {utf8Sorting: false}
 export const { serializeEncryptionContext } =
-  serializeFactory(stringToUtf8Bytes)
+  serializeFactory(stringToUtf8Bytes, utf8Sorting)
 
 export function getBranchKeyId(
   { branchKeyId, branchKeyIdSupplier }: IKmsHierarchicalKeyRingNode,
@@ -372,7 +373,7 @@ export function wrapAad(
    * So, I just slice off the length.
    */
   const aad = Buffer.from(
-    serializeEncryptionContext(encryptionContext).slice(2)
+    serializeEncryptionContext(encryptionContext, utf8Sorting).slice(2)
   )
 
   return Buffer.concat([

modules/kms-keyring-node/test/kms_hkeyring_node.helpers.test.ts

@@ -6,6 +6,7 @@ import {
   wrapAad,
   destructureCiphertext,
   serializeEncryptionContext,
+  utf8Sorting,
   unwrapEncryptedDataKey,
   wrapPlaintextDataKey,
 } from '../src/kms_hkeyring_node_helpers'
@@ -156,7 +157,7 @@ describe('KmsHierarchicalKeyRingNode: helpers', () => {
       ).to.deep.equal(branchKeyVersionAsBytes)
 
       startIdx += branchKeyVersionAsBytes.length
-      const expectedAad = serializeEncryptionContext(encryptionContext).slice(2)
+      const expectedAad = serializeEncryptionContext(encryptionContext, utf8Sorting).slice(2)
       expect(wrappedAad.subarray(startIdx)).to.deep.equal(expectedAad)
     })
   })

modules/material-management/src/types.ts

@@ -122,6 +122,7 @@ export type AwsEsdkCreateSecretKey = (key: Uint8Array) => AwsEsdkKeyObject
 export interface ClientOptions {
   commitmentPolicy: CommitmentPolicy
   maxEncryptedDataKeys: number | false
+  utf8Sorting?: boolean | false
 }
 
 export type Newable<T> = { new (...args: any[]): T }