Encryption Wrapper

Class Name	EncryptionWrapper
Extends	Logger
Source	encryption-wrapper.ts
Examples	encryption-wrapper.spec.ts

Encryption processes othen deal with the following questions:

Where to get a key from?
Do I need to generate a new key? How can I store this?
How to fetch a matching crypto?
How to encrypt data?

EncryptionWrapper handles these topcis and offers a fast way to work with encryption.

constructor

new EncryptionWrapper(options);

Create new EncryptionWrapper instance.

Parameters

options - DigitalTwinOptions: runtime-like object with required modules
- cryptoProvider - CryptoProvider: CryptoProvider instance
- nameResolver - NameResolver: NameResolver instance
- profile - Profile: Profile instance
- sharing - Sharing: Sharing instance
- web3 - Web3: Web3 instance
- log - Function (optional): function to use for logging: (message, level) => {...}
- logLevel - LogLevel (optional): messages with this level will be logged with log
- logLog - LogLogInterface (optional): container for collecting log messages
- logLogLevel - LogLevel (optional): messages with this level will be pushed to logLog factory

Returns

EncryptionWrapper instance

Example

const encryptionWrapper = new EncryptionWrapper(runtime);

= CryptoInfos =

getCryptoInfo

encryptionWrapper.getCryptoInfo(keyContext, keyType, cryptorType[, artifacts])

CryptoInfo s are descriptors for encrypted documents. They are stored alongside the encrypted data and provide a hint about the context of the data and how to decrypt them. In the EncryptionWrapper they are also used as an option parameter for the encrypt function.

Parameters

keyContext - any: used to identify key, can be any string (but must not have colons)
keyType - EncryptionWrapperKeyType: defines where keys are stored
cryptorType - EncryptionWrapperCryptorType: cryptor to use
artifacts - any: (optional) additional information for encryption may be required, depends on keyType, see section below for details

artifacts

Depending on keyType different properties are required. artifacts can be omitted, if used keyType is not listed below.

EncryptionWrapperKeyType.Sharing:
- sharingContractId - string: contract address of Shared or MultiShared contract
- sharingId - string (optional): id in a MultiShared contract and only used for them, defaults to null

Returns

Promise returns CryptoInfo: crypto info built out of input arguments

Example

const keyContext = 'my key 15';
const cryptoInfo = await encryptionWrapper.getCryptoInfo(
  keyContext,
  EncryptionWrapperKeyType.Profile,
  EncryptionWrapperCryptorType.Content,
);
console.dir(cryptoInfo);
// Output:
// { algorithm: 'aes-256-cbc',
// block: 198543,
// originator: 'profile:my key 15' }

= Key Handling =

generateKey

encryptionWrapper.generateKey(cryptoInfo);

Generates a new encryption key. Crypto algorithm in cryptoInfo is used to decide on which Cryptor to pick for this.

Parameters

cryptoInfo - CryptoInfo: details for encryption, can be created with getCryptoInfo

Returns

Promise returns any: key to encrypt/decrypt data

Example

const key = await encryptionWrapper.generateKey(cryptoInfo);
console.dir(key);
// Output:
// 'd387d41011a2f04f18930e982ad30c537d29bc12588164cb978d0f70a5d11b3f'

storeKey

encryptionWrapper.storeKey(cryptoInf[, artifacts]);

Store key in respective storage location, depending on given cryptoInfo, additional information may be required, which can be given via artifacts.

Parameters

cryptoInfo - CryptoInfo: details for encryption, can be created with getCryptoInfo
key - any: key to store
artifacts - any: (optional) additional information for encryption may be required, depends on cryptoInfo.originator, see section below for details

artifacts

Depending on cryptoInfo.originator different properties are required. artifacts can be omitted, if used cryptoInfo.originator schema is not listed below. Note, that cryptoInfo.originator schema depends on with which EncryptionWrapperKeyType getCryptoInfo was called.

sharing:.*:
- accountId - string: accountId, that is used to share keys from, executes the internal transaction
- receiver - string (optional): accountId, that receives the key, defaults to accountId

Returns

Promise returns void: resolved when done

Example

const key = await encryptionWrapper.generateKey(cryptoInfo);
await encryptionWrapper.storeKey(cryptoInfo, key);

getKey

encryptionWrapper.getKey(cryptoInf[, artifacts]);

Get key for given cryptoInfo. Can when storing keys in custom storage locations.

Parameters

cryptoInfo - CryptoInfo: details for encryption, can be created with getCryptoInfo
artifacts - any: (optional) additional information for encryption may be required, depends on cryptoInfo.originator, see section below for details

artifacts

Depending on cryptoInfo.originator different properties are required. artifacts can be omitted, if used cryptoInfo.originator schema is not listed below. Note, that cryptoInfo.originator schema depends on with which EncryptionWrapperKeyType getCryptoInfo was called.

sharing:.*:
- accountId - string: accountId, that accesses data, is used to get shared keys with
- propertyName - string (optional): property, that is decrypted, defaults to '*'
custom:.*:
- key - string: accountId, that accesses data, is used to get shared keys with

Returns

Promise returns void: resolved when done

Example

const keyContext = 'my key 15';
const cryptoInfo = await encryptionWrapper.getCryptoInfo(
  keyContext,
  EncryptionWrapperKeyType.Profile,
  EncryptionWrapperCryptorType.Content,
);
console.dir(await encryptionWrapper.getKey(cryptoInfo));
// Output:
// '08bca9594ebaa7812f030f299fa30b51c5a7c3e7b2b66cd0a18c5cf46314aab7'

= Encryption =

encrypt

encryptionHandler.encrypt(toEncrypt, cryptoInfo[, artifacts]);

Encrypt given object, depending on given cryptoInfo, additional information may be required, which can be given via artifacts

Parameters

toEncrypt - any: object to encrypt
cryptoInfo - CryptoInfo: details for encryption, can be created with getCryptoInfos
artifacts - any: (optional) additional information for encryption may be required, depends on cryptoInfo.originator, see section below for details

artifacts

Depending on cryptoInfo.originator different properties are required. artifacts can be omitted, if used cryptoInfo.originator schema is not listed below. Note, that cryptoInfo.originator schema depends on with which EncryptionWrapperKeyType getCryptoInfo was called.

sharing:.*:
- accountId - string: accountId, that accesses data, is used to get shared keys with
- propertyName - string (optional): property, that is encrypted, defaults to '*'
custom:.*:
- key - string: accountId, that accesses data, is used to get shared keys with

Returns

Promise returns Envelope: envelope with encrypted data

Example

const sampleData = {
  foo: TestUtils.getRandomBytes32(),
  bar: Math.random(),
};
const keyContext = 'my key 15';
const cryptoInfo = await encryptionWrapper.getCryptoInfo(
  keyContext,
  EncryptionWrapperKeyType.Profile,
  EncryptionWrapperCryptorType.Content,
);
const encrypted = await encryptionWrapper.encrypt(sampleData, cryptoInfo);
// Output:
// { private:
//    'ec6a2e0401e6270c50a88db31d0a22b677516162925a87bb7ec11a80613275817b883e75ee4bc8f82fe681d3462cf8ad49fce9d08797045b0c4bf6e3407b507f610a6c9678b6d3525c3b951189e4fec5bcbe2e71d5e471c43e6a9b69bbfc2144b59bb56ef57267c3a31c575afc1dcb4cad6aaccd4f71db8e7e40c08910710ea0',
//   cryptoInfo:
//    { algorithm: 'aes-256-cbc',
//      block: 198573,
//      originator:
//       'profile:0xb1c492ee6085679497c73008100c3b3136a75a8519c2a0016fec686a05f1c7f0' } }

decrypt

encryptionHandler.decrypt(toDecrypt[, artifacts]);

Decrypt given Envelope.

Parameters

toDecrypt - any: encrypted envelop
artifacts - any: (optional) additional information for decrypting

artifacts

Depending on cryptoInfo.originator different properties are required. artifacts can be omitted, if used cryptoInfo.originator schema is not listed below. Note, that cryptoInfo.originator schema depends on with which EncryptionWrapperKeyType getCryptoInfo was called.

sharing:.*:
- accountId - string: accountId, that accesses data, is used to get shared keys with
- propertyName - string (optional): property, that is decrypted, defaults to '*'
custom:.*:
- key - string: accountId, that accesses data, is used to get shared keys with

Returns

Promise returns Envelope: envelope with encrypted data

Example

const sampleData = {
  foo: TestUtils.getRandomBytes32(),
  bar: Math.random(),
};
const keyContext = 'my key 15';
const cryptoInfo = await encryptionWrapper.getCryptoInfo(
  keyContext,
  EncryptionWrapperKeyType.Profile,
  EncryptionWrapperCryptorType.Content,
);
const encrypted = await encryptionWrapper.encrypt(sampleData, cryptoInfo);
const decrypted = await encryptionWrapper.decrypt(encrypted);
console.dir(decrypt);
// Output:
// { foo:
//  '0x746dccef8a185d9e34a2778af51e8ee7e513e4035f7a5e2c2d122904a21f32e6',
// bar: 0.618861426409717 }

Additional Components

Enums

DigitalTwinEntryType

Content: content encryption is used for generic data (strings, in memory objects)
File: file encryption is used for binary file data
Unencrypted: unencrypted data encryption can be used to embed unencrypted data in encryption containers

EncryptionWrapperKeyType

Custom: custom key handling means that the key is handled elsewhere and has to be given to profile
Profile: key is stored in profile, usually in property “encryptionKeys”
Sharing: key is stored in Shared or MultiShared contract