Seald: documentation

# 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

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

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.

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

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:

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.

# Library

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

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.

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

# Information about JSON Web Tokens

Anonymous encryption is done in two steps:

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

Each of these two steps must be authorized by a JSON Web Token.

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 other hand, it is recommended to define an iat to limit in time the use of the JWT in question.

On the contrary, the message creation is done in a single request. It is therefore recommended defining both an iat, to limit in time the use of the JWT, and 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 message creation, in order to be able to define a jti on the message creation JWT, so that it can be used only once.

# Usage

Now you have everything you need to do an anonymous encryption. This is done with the function anonymousSDK.encrypt.

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 message creation.
  • sealdIds: Required. Array of Seald IDs of the recipients of the message to create.

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

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

Example of use:

← JSON Web Tokens →