Seald: documentation

English

Français

English

Français

Anonymous encryption ​

In addition to the full SDK, Seald also offers an anonymous encryption SDK. This enables your application to provide a way for users without Seald identity (unregistered users or users who are not logged-in) to encrypt data for users with a Seald identity. You can also use it to have your server encrypt data for your users.

As a security measure, yourserver must allow these anonymous encryptions using JSON Web tokens.

Import and instantiation ​

The Seald Anonymous Encryption SDK is imported separately from the full SDK.

Browser ​

There are three ways to use the Anonymous SDK in your browser, depending on your needs and the architecture of your web application.

Polyfilled library ​

javascript
import AnonymousSDKBuilder from '@seald-io/sdk/anonymous' // if your bundler supports custom entry-points (supported by Webpack 5)

const anonymousSDK = AnonymousSDKBuilder({ apiURL })
javascript
import AnonymousSDKBuilder from '@seald-io/sdk/anonymous-browser' // if your bundler supports custom entry-points (supported by Webpack 5) and you want to explicitely import the browser version

const anonymousSDK = AnonymousSDKBuilder({ apiURL })
javascript
import AnonymousSDKBuilder from '@seald-io/sdk/browser/anonymous-sdk.polyfilled.js' // explicit import

const anonymousSDK = AnonymousSDKBuilder({ apiURL })

This is a bundle, which already includes all necessary libraries, dependencies, and polyfills.

Use this method if you are using a bundler such as webpack, but you do not want to configure your bundler to include necessary polyfills.

Library ​

javascript
import AnonymousSDKBuilder from '@seald-io/sdk/anonymous-browser-library' // if your bundler supports custom entry-points (supported by Webpack 5)

const anonymousSDK = AnonymousSDKBuilder({ apiURL })
javascript
import AnonymousSDKBuilder from '@seald-io/sdk/browser/anonymous-sdk.js' // explicit import

const anonymousSDK = AnonymousSDKBuilder({ apiURL })

This imports @seald-io/sdk/browser/anonymous-sdk.js, which is the wrapper for the browser.

Use this method if you use a bundler like Webpack. For this, refer to the section Custom bundling and transpilation of the import guide.

This method is recommended, as it reduces the duplication of dependencies and polyfills, so it minimizes the final size of your application.

Bundle ​

Copy the file @seald-io/sdk/browser/anonymous-sdk.browser.js into your project, then load it in a <script> tag.

html
<html>
<head>
...
<script src="/libraries/anonymous-sdk.browser.js"></script>
<script>
var anonymousSDK = window.AnonymousSDK({ apiURL })
</script>
...
</head>
</html>

This is a bundle, which already includes all necessary libraries, dependencies, and polyfills.

It exposes the Anonymous SDK constructor function in the global variable window.AnonymousSDK.

Node.js / Electron ​

javascript
import { AnonymousSDKBuilder } from '@seald-io/sdk'

const anonymousSDK = AnonymousSDKBuilder({ apiURL })

This imports the Node wrapper for the Anonymous SDK.

You may want to use this on your NodeJS server, in an Electron desktop application, for your unit-tests ...

React-Native ​

Installation ​

The Anonymous SDK for react-native has peer dependencies that must be installed separately:

  • react-native-modpow
  • react-native-get-random-values

You can install them with the command:

sh
npm i -S react-native-modpow react-native-get-random-values

Bundle ​

If you do not configure the transpilation of your application yourself, you can use the bundled, transpiled and minified version of the Anonymous SDK. It can be used as is.

javascript
import AnonymousSDKBuilder from '@seald-io/sdk/anonymous-react-native' // if your bundler supports custom entry-points (not supported by Metro)

const anonymousSDK = AnonymousSDKBuilder({ apiURL })
javascript
import AnonymousSDKBuilder from '@seald-io/sdk/react-native/anonymous-sdk-react-native.bundle.js' // explicit import

const anonymousSDK = AnonymousSDKBuilder({ apiURL })

Library ​

If your application is itself transpiled, you can import the source library. This will allow you to optimise the size of your application.

javascript
import AnonymousSDKBuilder from '@seald-io/sdk/anonymous-react-native-library' // if your bundler supports custom entry-points (not supported by Metro)

const anonymousSDK = AnonymousSDKBuilder({ apiURL })
javascript
import AnonymousSDKBuilder from '@seald-io/sdk/react-native/anonymous-sdk-react-native.js' // explicit import

const anonymousSDK = AnonymousSDKBuilder({ apiURL })

This library will need to be transpiled before it can be used. See the Custom bundling and transpilation section of the import guide.

JSON Web Tokens ​

As a security measure, your server must allow these anonymous encryptions using JSON Web tokens.

Anonymous encryption is done in two steps:

  • recovery of the recipients' encryption keys
  • creation of the session for these recipients

Each of these two steps must be authorized by a JSON Web Token. You will find detailed examples of how to generate these JWTs in multiple programming languages in the paragraph JWTs for anonymous encryption of our documentation page about JWTs.

TIP

Retrieving recipient keys may require multiple queries. It is therefore strongly advised not to define a jti on the JWT in question, otherwise requests after the first one may fail.

On the contrary, the session creation is done in a single request. It is therefore recommended defining a jti, to avoid the same JWT being used several times during the allowed time interval.

TIP

Even if technically nothing prevents to use only one JWT for both operations, it is recommended to create two different JWTs for key retrieval and for session creation, in order to be able to define a jti on the session creation JWT, so that it can be used only once.

For more information about the generation of JSON Web Tokens, refer to this documentation

Usage ​

Now you have everything you need to do an anonymous encryption. This can be done with one of these two functions:

anonymousSDK.encrypt ​

This function allows you to directly encrypt a file.

The noteworthy arguments for this function are:

  • clearFile: Required. The file to encrypt. Can be a string, a Buffer, a Blob, a WebStream ReadableStream, or a Node Readable stream. If you are using a ReadableStream or a Readable, you must also give the fileSize argument.
  • getKeysToken: Optional. The JWT used for the key retrieval. If not supplied, the key retrieval will use encryptionToken.
  • encryptionToken: Required. The JWT used for session creation.
  • sealdIds: Required. Array of Seald IDs of the recipients of the session to create.

The return value of this function is a Promise, containing:

  • id: string, ID of the session for the encrypted file.
  • encryptedFile: newly encrypted file, in the same format as the given clearFile.

Example of use:

javascript
const { id, encryptedFile } = await anonymousSDK.encrypt({
  getKeysToken,
  encryptionToken,
  sealdIds: [user1SealdId, user2SealdId],
  clearFile: clearFileBuffer,
  filename: 'test.txt'
})

anonymousSDK.createEncryptionSession ​

This function allows you to create an AnonymousEncryptionSession, which you can then use to encrypt and decrypt files and messages.

The noteworthy arguments for this function are:

  • getKeysToken: Optional. The JWT used for the key retrieval. If not supplied, the key retrieval will use encryptionToken.
  • encryptionToken: Required. The JWT used for session creation.
  • sealdIds: Required. Array of Seald IDs of the recipients of the session to create.

The return value of this function is a Promise, containing an AnonymousEncryptionSession, which you can use to encrypt and decrypt files and messages.

Example of use:

javascript
// Create an `AnonymousEncryptionSession`
const session = await anonymousSDK.createEncryptionSession({
  getKeysToken,
  encryptionToken,
  sealdIds: [user1SealdId, user2SealdId]
})
// Encrypt a file
const encryptedFile = await session.encryptFile({
  clearFile: clearFileBuffer,
  filename: 'test.txt'
})
// Encrypt a message
const encryptedMessage = await session.encryptMessage('Secret Message')