protectData

The iExec tool suite supports deployment of applications where the user of the application has complete and total control over access to their data. This ensures privacy and security when invoking these applications. Through use of the protectData method, a user may encrypt and secure any type of data. Encryption occurs on the client side, supporting the user's control over their data.

Usage

This is an asynchronous method that supports both the promise and observable patterns. Examples of each are provided below. Regardless of the invocation pattern, the method accepts a JSON object containing the data to encrypt and an optional name to identify the data.

An email address, for example, may be submitted as:

const protectedData = await dataProtector.protectData({
    data: {
        email: '[e-mail]'
    }
})

Your object may contain any number of custom keys. The following example illustrates protection of multiple categories of data within one object:

const protectedData = await dataProtector.protectData({
    data: {
      email: '[e-mail]',
      SMTPserver: {
          port: 5000,
          smtp_server: 'smtp.gmail.com'
      }
  }
})

Return value example

The exact style of result differs based on which invocation pattern you use but the overall content is the same. The result object includes the specified optional name parameter, along with metadata including the owner, schema for the protected data, creation timestamp, transaction hash, and a uint8-encoded array representing the zipped data for the object.

Parameters

The protectData method accepts the following parameters

data (required)

This is the actual data the user is protecting, provided as a JSON object with any number of custom keys. The data is encrypted and stored as an NFT.

name (optional)

Allows providing a descriptive name for the protected data. This is considered public metadata, describing the protected data.

The name is public and not encrypted. If you don't pass a name to your protected data we will automatically define it as "Untitled".

Result

The protectData method returns the following fields, either as a JSON object or as individual fields depending on whether you use the promise or observable pattern respectively.

name

The optional name provided during invocation of the method. If no name is specified this value defaults to Untitled.

address

The ETH address of the newly created protectedData.

owner

The ETH address of the creator and owner of this protectedData.

schema

Metadata describing the fields provided in the data parameter. The data types are automatically detected and listed in the schema.

The following data types are automatically detected:

• Scalars

  • boolean

  • number

  • string

• Binary:

  • application/octet-stream

  • application/pdf

  • application/xml

  • application/zip

  • audio/midi

  • audio/mpeg

  • audio/x-wav

  • image/bmp

  • image/gif

  • image/jpeg

  • image/png

  • image/webp

  • video/mp4

  • video/mpeg

  • video/x-msvideo

Any undetected binary data type is categorized as application/octet-stream

creationTimestamp

A unix-style timestamp indicating the creation time of this protectedData.

transactionHash

The ID of the transaction that happened on iExec's side chain. You may view details on the transaction using the iExec explorer.

zipFile

This is a binary representation of the data stored in the protectedData. This is intended as debug data and we will remove this in a future SDK release.

encryptionKey

The encryption key generated by the client to encrypt the data. This key is for your own usage. You will not have to share it in the context of the iExec protocol or developer tools.

Example invocations

You may invoke the protectData method using either the promise pattern or the observable pattern. Examples of both approaches are included below.

1. With promise

Sample invocation with promise pattern

const protectedData = await dataProtector.protectData({
  data: {
    email: "[e-mail]",
  },
});

Return value example with promise pattern

{
  name: "My protected data name",
  address: "0x459FA81e0731e1dd39DD578fa16E31ADe898023e",
  owner: "0xda225B8325A1818A4239a68990349987C4221828",
  schema: {
    email: "string"
  },
  creationTimestamp: 1685371355,
  transactionHash: "0x83c79bcf6e09861aa41d990024a16145dbb384ac19926789810cf59c94bac14f",
  zipFile: { ... },
  encryptionKey: "m/c3TZHr7K7CYhf991OzfL4ROmtbmORPtFsiBK546mI="
}

The zip file generated is a uint8array, so if you want to handle the binary data or download it consider adding a zip extension to it.

2. With observable

Sample invocation with observable pattern

const protectedData = await dataProtector.protectDataObservable({
    data: {
        email: '[e-mail]'
    }
}).subscribe({
      next: (data) => {
        if (mounted.current) {
          const { message } = data;
          switch (message) {
            case "DATA_SCHEMA_EXTRACTED":
              const dataSchema = data.schema;
              //Execute your customized logic here
              break;
            case "ZIP_FILE_CREATED":
              const zipFileUint8array= data.zipFile;
              //Execute your customized logic here
              break;
            case "ENCRYPTION_KEY_CREATED":
              //Execute your customized logic here
              break;
            case "FILE_ENCRYPTED":
              //Execute your customized logic here
              break;
            case "ENCRYPTED_FILE_UPLOADED":
              const multiaddr = data.multiaddr ;
              //Execute your customized logic here
              break;
            case "PROTECTED_DATA_DEPLOYMENT_REQUEST":
              //Execute your customized logic here
              break;
            case "PROTECTED_DATA_DEPLOYMENT_SUCCESS":
              const dataAddress = data.address;
              //Execute your customized logic here
              break;
            case "PUSH_SECRET_TO_SMS_SIGN_REQUEST":
              //Execute your customized logic here
              break;
            case "PUSH_SECRET_TO_SMS_SUCCESS":
              //Execute your customized logic here
              break;
            default:
          }

      },
      error: (e) => {
        //Setup how you handle errors
      },
      complete: () => {
        //Will be executed once the Protected Data creation is completed
      }
})

Return value example with observable pattern

Message	Return value
DATA_SCHEMA_EXTRACTED	schema: { "email": "string" }
ZIP_FILE_CREATED	zipFile: { ... }
ENCRYPTION_KEY_CREATED	encryptionKey: 'Hm/c3TZHr7K7CYhf991OzfL4ROmtbmORPtFsiBK546mI='ja
FILE_ENCRYPTED	encryptedFile: uint8array, checksum: '0xcc2e86e73a429d7c2c38669ea61db2f07e78300f24687143dbf915133fd316c3'
ENCRYPTED_FILE_UPLOADED	cid: 'ipfs.io/ipfs/QmVcYV3SCwYrN71QJwJ62L67o8NVKkZZse1r2JmwX5sUJa', multiaddr: '/ipfs/QmVcYV3SCwYrN71QJwJ62L67o8NVKkZZse1r2JmwX5sUJa'
PROTECTED_DATA_DEPLOYMENT_REQUEST	owner: '0xda225B8325A1818A4239a68990349987C4221828', name: 'My protected data name', schema: { "email": "string" }, multiaddr: '/ipfs/QmVcYV3SCwYrN71QJwJ62L67o8NVKkZZse1r2JmwX5sUJa', checksum: '0xcc2e86e73a429d7c2c38669ea61db2f07e78300f24687143dbf915133fd316c3'
PROTECTED_DATA_DEPLOYMENT_SUCCESS	address: '0x459FA81e0731e1dd39DD578fa16E31ADe898023e', owner: '0xda225B8325A1818A4239a68990349987C4221828', txHash: '0x83c79bcf6e09861aa41d990024a16145dbb384ac19926789810cf59c94bac14f'
PUSH_SECRET_TO_SMS_SIGN_REQUEST	Empty
PUSH_SECRET_TO_SMS_SUCCESS	Empty