#319 - implemented 'protocols' key derivation scheme for encryption

thehenrytsai · web-flow · commit 67dd57aea8fa · 2023-04-26T16:07:42.000-07:00
diff --git a/README.md b/README.md
@@ -3,7 +3,7 @@
 # Decentralized Web Node (DWN) SDK
 
 Code Coverage
-![Statements](https://img.shields.io/badge/statements-94.03%25-brightgreen.svg?style=flat) ![Branches](https://img.shields.io/badge/branches-93.54%25-brightgreen.svg?style=flat) ![Functions](https://img.shields.io/badge/functions-91.75%25-brightgreen.svg?style=flat) ![Lines](https://img.shields.io/badge/lines-94.03%25-brightgreen.svg?style=flat)
+![Statements](https://img.shields.io/badge/statements-94.07%25-brightgreen.svg?style=flat) ![Branches](https://img.shields.io/badge/branches-93.58%25-brightgreen.svg?style=flat) ![Functions](https://img.shields.io/badge/functions-91.8%25-brightgreen.svg?style=flat) ![Lines](https://img.shields.io/badge/lines-94.07%25-brightgreen.svg?style=flat)
 
 ## Introduction
 
diff --git a/json-schemas/records/records-write.json b/json-schemas/records/records-write.json
@@ -42,7 +42,7 @@
               "derivationScheme": {
                 "type": "string",
                 "enum": [
-                  "protocol-context"
+                  "protocols"
                 ]
               },
               "algorithm": {
diff --git a/src/core/dwn-error.ts b/src/core/dwn-error.ts
@@ -27,9 +27,10 @@ export enum DwnErrorCode {
   RecordsDeriveLeafPrivateKeyUnSupportedCurve = 'RecordsDeriveLeafPrivateKeyUnSupportedCurve',
   RecordsDeriveLeafPublicKeyUnSupportedCurve = 'RecordsDeriveLeafPublicKeyUnSupportedCurve',
   RecordsInvalidAncestorKeyDerivationSegment = 'RecordsInvalidAncestorKeyDerivationSegment',
+  RecordsProtocolsDerivationSchemeMissingProtocol = 'RecordsProtocolsDerivationSchemeMissingProtocol',
   RecordsWriteGetEntryIdUndefinedAuthor = 'RecordsWriteGetEntryIdUndefinedAuthor',
   RecordsWriteValidateIntegrityEncryptionCidMismatch = 'RecordsWriteValidateIntegrityEncryptionCidMismatch',
   Secp256k1KeyNotValid = 'Secp256k1KeyNotValid',
   UrlProtocolNotNormalized = 'UrlProtocolNotNormalized',
-  UrlPrococolNotNormalizable = 'UriPrococolNotNormalizable'
+  UrlProtocolNotNormalizable = 'UrlProtocolNotNormalizable'
 };
diff --git a/src/interfaces/records/messages/records-write.ts b/src/interfaces/records/messages/records-write.ts
@@ -18,7 +18,6 @@ import { EncryptionAlgorithm } from '../../../utils/encryption.js';
 import { GeneralJwsSigner } from '../../../jose/jws/general/signer.js';
 import { getCurrentTimeInHighPrecision } from '../../../utils/time.js';
 import { Jws } from '../../../utils/jws.js';
-import { KeyDerivationScheme } from '../../../utils/hd-key.js';
 import { Message } from '../../../core/message.js';
 import { ProtocolAuthorization } from '../../../core/protocol-authorization.js';
 import { Records } from '../../../utils/records.js';
@@ -204,7 +203,7 @@ export class RecordsWrite extends Message<RecordsWriteMessage> {
     // `attestation` generation
     const descriptorCid = await computeCid(descriptor);
     const attestation = await RecordsWrite.createAttestation(descriptorCid, options.attestationSignatureInputs);
-    const encryption = await RecordsWrite.createEncryptionProperty(options.encryptionInput, descriptor, contextId);
+    const encryption = await RecordsWrite.createEncryptionProperty(recordId, contextId, descriptor, options.encryptionInput);
 
     // `authorization` generation
     const authorization = await RecordsWrite.createAuthorization(
@@ -456,9 +455,10 @@ export class RecordsWrite extends Message<RecordsWriteMessage> {
    * Creates the `encryption` property if encryption input is given. Else `undefined` is returned.
    */
   private static async createEncryptionProperty(
-    encryptionInput: EncryptionInput | undefined,
+    recordId: string,
+    contextId: string | undefined,
     descriptor: RecordsWriteDescriptor,
-    contextId: string | undefined // there is opportunity here to streamline the arguments, e.g. `contextId` feels very specialized
+    encryptionInput: EncryptionInput | undefined
   ): Promise<EncryptionProperty | undefined> {
     if (encryptionInput === undefined) {
       return undefined;
@@ -467,13 +467,12 @@ export class RecordsWrite extends Message<RecordsWriteMessage> {
     // encrypt the data encryption key once per key derivation scheme
     const keyEncryption: EncryptedKey[] = [];
     for (const keyEncryptionInput of encryptionInput.keyEncryptionInputs) {
-      // NOTE: right now only `protocol-context` scheme is supported so we will assume that's the scheme without additional switch/if statements
-      // derive the leaf public key
-      const leafDerivationPath = [KeyDerivationScheme.ProtocolContext, descriptor.protocol!, contextId!];
+
+      const fullDerivationPath = Records.constructKeyDerivationPath(keyEncryptionInput.publicKey.derivationScheme, recordId, contextId, descriptor);
 
       // NOTE: right now only `ECIES-ES256K` algorithm is supported for asymmetric encryption,
       // so we will assume that's the algorithm without additional switch/if statements
-      const leafPublicKey = await Records.deriveLeafPublicKey(keyEncryptionInput.publicKey, leafDerivationPath);
+      const leafPublicKey = await Records.deriveLeafPublicKey(keyEncryptionInput.publicKey, fullDerivationPath);
       const keyEncryptionOutput = await Encryption.eciesSecp256k1Encrypt(leafPublicKey, encryptionInput.key);
 
       const encryptedKey = Encoder.bytesToBase64Url(keyEncryptionOutput.ciphertext);
diff --git a/src/utils/encryption.ts b/src/utils/encryption.ts
@@ -3,7 +3,7 @@ import * as eccrypto from 'eccrypto';
 import { Readable } from 'readable-stream';
 
 /**
- * Utility class for performing common encryption operations.
+ * Utility class for performing common, non-DWN specific encryption operations.
  */
 export class Encryption {
   /**
diff --git a/src/utils/hd-key.ts b/src/utils/hd-key.ts
@@ -3,7 +3,7 @@ import type { PrivateJwk, PublicJwk } from '../jose/types.js';
 import { Secp256k1 } from './secp256k1.js';
 
 export enum KeyDerivationScheme {
-  ProtocolContext = 'protocol-context'
+  Protocols = 'protocols'
 }
 
 export type DerivedPublicJwk = {
diff --git a/src/utils/records.ts b/src/utils/records.ts
@@ -1,6 +1,6 @@
 import type { Readable } from 'readable-stream';
-import type { UnsignedRecordsWriteMessage } from '../interfaces/records/types.js';
 import type { DerivedPrivateJwk, DerivedPublicJwk } from './hd-key.js';
+import type { RecordsWriteDescriptor, UnsignedRecordsWriteMessage } from '../interfaces/records/types.js';
 
 import { Encoder } from './encoder.js';
 import { Encryption } from './encryption.js';
@@ -20,7 +20,7 @@ export class Records {
     ancestorPrivateKey: DerivedPrivateJwk,
     cipherStream: Readable
   ): Promise<Readable> {
-    const { encryption, contextId, descriptor } = recordsWrite;
+    const { recordId, contextId, descriptor, encryption } = recordsWrite;
 
     // look for an encrypted symmetric key that is encrypted using the same scheme as the given derived private key
     const matchingEncryptedKey = encryption!.keyEncryption.find(key => key.derivationScheme === ancestorPrivateKey.derivationScheme);
@@ -31,13 +31,11 @@ export class Records {
       );
     }
 
-    // NOTE: right now only `protocol-context` scheme is supported so we will assume that's the scheme without additional switch/if statements
-    // derive the leaf private key
-    const leafDerivationPath = [KeyDerivationScheme.ProtocolContext, descriptor.protocol!, contextId!];
+    const fullDerivationPath = Records.constructKeyDerivationPath(matchingEncryptedKey.derivationScheme, recordId, contextId, descriptor);
 
     // NOTE: right now only `ECIES-ES256K` algorithm is supported for asymmetric encryption,
     // so we will assume that's the algorithm without additional switch/if statements
-    const leafPrivateKey = await Records.deriveLeafPrivateKey(ancestorPrivateKey, leafDerivationPath);
+    const leafPrivateKey = await Records.deriveLeafPrivateKey(ancestorPrivateKey, fullDerivationPath);
     const encryptedKeyBytes = Encoder.base64UrlToBytes(matchingEncryptedKey.encryptedKey);
     const ephemeralPublicKey = Secp256k1.publicJwkToBytes(matchingEncryptedKey.ephemeralPublicKey);
     const keyEncryptionInitializationVector = Encoder.base64UrlToBytes(matchingEncryptedKey.initializationVector);
@@ -58,6 +56,51 @@ export class Records {
     return plaintextStream;
   }
 
+  /**
+   * Constructs full key derivation path using the specified scheme.
+   */
+  public static constructKeyDerivationPath(
+    _keyDerivationScheme: KeyDerivationScheme,
+    recordId: string,
+    contextId: string | undefined,
+    descriptor: RecordsWriteDescriptor
+  ): string[] {
+
+    // NOTE: right now only `protocols` derivation scheme is supported so we will assume that's the scheme without additional switch/if statements
+    const fullDerivationPath = Records.constructKeyDerivationPathUsingProtocolsScheme(recordId, contextId, descriptor);
+    return fullDerivationPath;
+  }
+
+  /**
+   * Constructs the full key derivation path using `protocols` scheme.
+   */
+  private static constructKeyDerivationPathUsingProtocolsScheme(
+    recordId: string,
+    contextId: string | undefined,
+    descriptor: RecordsWriteDescriptor
+  ): string[] {
+    // ensure `protocol` is defined
+    // NOTE: no need to check `protocolPath` and `contextId` because earlier code ensures that if `protocol` is defined, those are defined also
+    if (descriptor.protocol === undefined) {
+      throw new DwnError(
+        DwnErrorCode.RecordsProtocolsDerivationSchemeMissingProtocol,
+        'Unable to construct key derivation path using `protocols` scheme because `protocol` is missing.'
+      );
+    }
+
+    const protocolPathSegments = descriptor.protocolPath!.split('/');
+    const fullDerivationPath = [
+      KeyDerivationScheme.Protocols,
+      descriptor.protocol,
+      contextId!,
+      ...protocolPathSegments,
+      descriptor.dataFormat,
+      recordId
+    ];
+
+    return fullDerivationPath;
+  }
+
   /**
    * Derives a descendant public key given an ancestor public key.
    * NOTE: right now only `ECIES-ES256K` algorithm is supported for asymmetric encryption,
diff --git a/src/utils/url.ts b/src/utils/url.ts
@@ -28,7 +28,7 @@ export function normalizeProtocolUri(url: string): string {
     result.hash = '';
     return removeTrailingSlash(result.href);
   } catch (e) {
-    throw new DwnError(DwnErrorCode.UrlPrococolNotNormalizable, 'Could not normalize protocol URI');
+    throw new DwnError(DwnErrorCode.UrlProtocolNotNormalizable, 'Could not normalize protocol URI');
   }
 }
 
diff --git a/tests/interfaces/records/handlers/records-query.spec.ts b/tests/interfaces/records/handlers/records-query.spec.ts
@@ -652,7 +652,7 @@ describe('RecordsQueryHandler.handle()', () => {
           key                  : dataEncryptionKey,
           keyEncryptionInputs  : [{
             publicKey: {
-              derivationScheme : KeyDerivationScheme.ProtocolContext,
+              derivationScheme : KeyDerivationScheme.Protocols,
               derivationPath   : [],
               derivedPublicKey : alice.keyPair.publicJwk // reusing signing key for encryption purely as a convenience
             }
@@ -685,11 +685,16 @@ describe('RecordsQueryHandler.handle()', () => {
 
         // test able to decrypt the message using a derived key
         const rootPrivateKey: DerivedPrivateJwk = {
-          derivationScheme  : KeyDerivationScheme.ProtocolContext,
+          derivationScheme  : KeyDerivationScheme.Protocols,
           derivationPath    : [],
           derivedPrivateKey : alice.keyPair.privateJwk
         };
-        const relativeDescendantDerivationPath = [KeyDerivationScheme.ProtocolContext, protocol, message.contextId!];
+        const relativeDescendantDerivationPath = Records.constructKeyDerivationPath(
+          KeyDerivationScheme.Protocols,
+          message.recordId,
+          message.contextId,
+          message.descriptor
+        );
         const descendantPrivateKey: DerivedPrivateJwk = await HdKey.derivePrivateKey(rootPrivateKey, relativeDescendantDerivationPath);
 
         const cipherStream = DataStream.fromBytes(Encoder.base64UrlToBytes(unsignedRecordsWrite.encodedData!));
diff --git a/tests/interfaces/records/handlers/records-read.spec.ts b/tests/interfaces/records/handlers/records-read.spec.ts
@@ -1,11 +1,11 @@
 import type { DerivedPrivateJwk } from '../../../../src/utils/hd-key.js';
-import emailProtocolDefinition from '../../../vectors/protocol-definitions/email.json' assert { type: 'json' };
 import type { EncryptionInput } from '../../../../src/interfaces/records/messages/records-write.js';
 import type { ProtocolDefinition } from '../../../../src/index.js';
-import socialMediaProtocolDefinition from '../../../vectors/protocol-definitions/social-media.json' assert { type: 'json' };
 
 import chaiAsPromised from 'chai-as-promised';
+import emailProtocolDefinition from '../../../vectors/protocol-definitions/email.json' assert { type: 'json' };
 import sinon from 'sinon';
+import socialMediaProtocolDefinition from '../../../vectors/protocol-definitions/social-media.json' assert { type: 'json' };
 import chai, { expect } from 'chai';
 
 import { Comparer } from '../../../utils/comparer.js';
@@ -401,7 +401,7 @@ describe('RecordsReadHandler.handle()', () => {
           key                  : dataEncryptionKey,
           keyEncryptionInputs  : [{
             publicKey: {
-              derivationScheme : KeyDerivationScheme.ProtocolContext,
+              derivationScheme : KeyDerivationScheme.Protocols,
               derivationPath   : [],
               derivedPublicKey : alice.keyPair.publicJwk // reusing signing key for encryption purely as a convenience
             }
@@ -431,11 +431,16 @@ describe('RecordsReadHandler.handle()', () => {
 
         // test able to decrypt the message using a derived key
         const rootPrivateKey: DerivedPrivateJwk = {
-          derivationScheme  : KeyDerivationScheme.ProtocolContext,
+          derivationScheme  : KeyDerivationScheme.Protocols,
           derivationPath    : [],
           derivedPrivateKey : alice.keyPair.privateJwk
         };
-        const relativeDescendantDerivationPath = [KeyDerivationScheme.ProtocolContext, protocol, message.contextId!];
+        const relativeDescendantDerivationPath = Records.constructKeyDerivationPath(
+          KeyDerivationScheme.Protocols,
+          message.recordId,
+          message.contextId,
+          message.descriptor
+        );
         const descendantPrivateKey: DerivedPrivateJwk = await HdKey.derivePrivateKey(rootPrivateKey, relativeDescendantDerivationPath);
 
         const unsignedRecordsWrite = readReply.record!;
@@ -446,7 +451,7 @@ describe('RecordsReadHandler.handle()', () => {
         expect(Comparer.byteArraysEqual(plaintextBytes, bobMessageBytes)).to.be.true;
 
         // test unable to decrypt the message if derived key has an unexpected path
-        const invalidDerivationPath = [KeyDerivationScheme.ProtocolContext, protocol, 'invalidContextId'];
+        const invalidDerivationPath = [KeyDerivationScheme.Protocols, protocol, 'invalidContextId'];
         const inValidDescendantPrivateKey: DerivedPrivateJwk = await HdKey.derivePrivateKey(rootPrivateKey, invalidDerivationPath);
         await expect(Records.decrypt(unsignedRecordsWrite, inValidDescendantPrivateKey, cipherStream)).to.be.rejectedWith(
           DwnErrorCode.RecordsInvalidAncestorKeyDerivationSegment
diff --git a/tests/interfaces/records/handlers/records-write.spec.ts b/tests/interfaces/records/handlers/records-write.spec.ts
@@ -1,18 +1,17 @@
+import type { GenerateFromRecordsWriteOut } from '../../../utils/test-data-generator.js';
+import type { QueryResultEntry } from '../../../../src/core/types.js';
+import type { RecordsWriteMessage } from '../../../../src/interfaces/records/types.js';
+import type { EncryptionInput, ProtocolDefinition } from '../../../../src/index.js';
+
 import chaiAsPromised from 'chai-as-promised';
 import credentialIssuanceProtocolDefinition from '../../../vectors/protocol-definitions/credential-issuance.json' assert { type: 'json' };
 import dexProtocolDefinition from '../../../vectors/protocol-definitions/dex.json' assert { type: 'json' };
 import emailProtocolDefinition from '../../../vectors/protocol-definitions/email.json' assert { type: 'json' };
 import messageProtocolDefinition from '../../../vectors/protocol-definitions/message.json' assert { type: 'json' };
-import socialMediaProtocolDefinition from '../../../vectors/protocol-definitions/social-media.json' assert { type: 'json' };
-
 import sinon from 'sinon';
+import socialMediaProtocolDefinition from '../../../vectors/protocol-definitions/social-media.json' assert { type: 'json' };
 import chai, { expect } from 'chai';
 
-import type { GenerateFromRecordsWriteOut } from '../../../utils/test-data-generator.js';
-import type { QueryResultEntry } from '../../../../src/core/types.js';
-import type { RecordsWriteMessage } from '../../../../src/interfaces/records/types.js';
-import type { EncryptionInput, ProtocolDefinition } from '../../../../src/index.js';
-
 import { asyncGeneratorToArray } from '../../../../src/utils/array.js';
 import { base64url } from 'multiformats/bases/base64';
 import { DataStoreLevel } from '../../../../src/store/data-store-level.js';
@@ -1440,7 +1439,7 @@ describe('RecordsWriteHandler.handle()', () => {
           keyEncryptionInputs  : [{
             algorithm : EncryptionAlgorithm.EciesSecp256k1,
             publicKey : {
-              derivationScheme : KeyDerivationScheme.ProtocolContext,
+              derivationScheme : KeyDerivationScheme.Protocols,
               derivationPath   : [],
               derivedPublicKey : alice.keyPair.publicJwk // reusing signing key for encryption purely as a convenience
             }
diff --git a/tests/interfaces/records/messages/records-write.spec.ts b/tests/interfaces/records/messages/records-write.spec.ts
@@ -1,15 +1,16 @@
+import type { EncryptionInput } from '../../../../src/interfaces/records/messages/records-write.js';
 import type { RecordsWriteMessage } from '../../../../src/interfaces/records/types.js';
 
 import chaiAsPromised from 'chai-as-promised';
 import sinon from 'sinon';
 import chai, { expect } from 'chai';
 
 import { DwnErrorCode } from '../../../../src/core/dwn-error.js';
-import { Jws } from '../../../../src/index.js';
 import { MessageStoreLevel } from '../../../../src/store/message-store-level.js';
 import { RecordsWrite } from '../../../../src/interfaces/records/messages/records-write.js';
 import { TestDataGenerator } from '../../../utils/test-data-generator.js';
 import { getCurrentTimeInHighPrecision, sleep } from '../../../../src/utils/time.js';
+import { Jws, KeyDerivationScheme } from '../../../../src/index.js';
 
 
 chai.use(chaiAsPromised);
@@ -175,6 +176,34 @@ describe('RecordsWrite', () => {
 
       await expect(createPromise2).to.be.rejectedWith('`protocol` and `protocolPath` must both be defined or undefined at the same time');
     });
+
+    it('should throw if attempting to use `protocol` key derivation scheme on non-protocol-based record', async () => {
+      const alice = await TestDataGenerator.generatePersona();
+
+      const dataEncryptionInitializationVector = TestDataGenerator.randomBytes(16);
+      const dataEncryptionKey = TestDataGenerator.randomBytes(32);
+      const encryptionInput: EncryptionInput = {
+        initializationVector : dataEncryptionInitializationVector,
+        key                  : dataEncryptionKey,
+        keyEncryptionInputs  : [{
+          publicKey: {
+            derivationScheme : KeyDerivationScheme.Protocols,
+            derivationPath   : [],
+            derivedPublicKey : alice.keyPair.publicJwk // reusing signing key for encryption purely as a convenience
+          }
+        }]
+      };
+
+      // intentionally generating a record that is not protocol-based
+      const createPromise = RecordsWrite.create({
+        authorizationSignatureInput : Jws.createSignatureInput(alice),
+        dataFormat                  : 'application/json',
+        data                        : TestDataGenerator.randomBytes(10),
+        encryptionInput
+      });
+
+      await expect(createPromise).to.be.rejectedWith(DwnErrorCode.RecordsProtocolsDerivationSchemeMissingProtocol);
+    });
   });
 
   describe('createFrom()', () => {
diff --git a/tests/utils/records.spec.ts b/tests/utils/records.spec.ts

Original file line number	Diff line number	Diff line change
`@@ -42,7 +42,7 @@`
`42`	`42`	`"derivationScheme": {`
`43`	`43`	`"type": "string",`
`44`	`44`	`"enum": [`
`45`		`- "protocol-context"`
	`45`	`+ "protocols"`
`46`	`46`	`]`
`47`	`47`	`},`
`48`	`48`	`"algorithm": {`
Original file line number	Diff line number	Diff line change
`@@ -3,7 +3,7 @@ import type { PrivateJwk, PublicJwk } from '../jose/types.js';`
`3`	`3`	`import { Secp256k1 } from './secp256k1.js';`
`4`	`4`
`5`	`5`	`export enum KeyDerivationScheme {`
`6`		`- ProtocolContext = 'protocol-context'`
	`6`	`+ Protocols = 'protocols'`
`7`	`7`	`}`
`8`	`8`
`9`	`9`	`export type DerivedPublicJwk = {`
Original file line number	Diff line number	Diff line change
`@@ -28,7 +28,7 @@ export function normalizeProtocolUri(url: string): string {`
`28`	`28`	`result.hash = '';`
`29`	`29`	`return removeTrailingSlash(result.href);`
`30`	`30`	`} catch (e) {`
`31`		`- throw new DwnError(DwnErrorCode.UrlPrococolNotNormalizable, 'Could not normalize protocol URI');`
	`31`	`+ throw new DwnError(DwnErrorCode.UrlProtocolNotNormalizable, 'Could not normalize protocol URI');`
`32`	`32`	`}`
`33`	`33`	`}`
`34`	`34`