# 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, in order to avoid misuse of your encryption quotas, your server 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.

# Library

This imports @seald-io/sdk-web/lib/anonymous-sdk.js, which is the version bundled for web browsers.

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.

# 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.

# Bundle

Copy the file @seald-io/sdk-web/lib/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({})

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 ...

You will need to install node-fetch separately:

npm i -S node-fetch

# React-Native

# Installation

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

  • react-native-modpow

You can install it with the command:

npm i -S react-native-modpow

# 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, in order to avoid misuse of your encryption quotas, your server must allow these anonymous encryptions using JSON Web tokens.

# Creating a JWTSharedSecret

To create a JSON Web Token, you first need a JWTSharedSecret.

You can create, list, and delete JWTSharedSecrets, which allow to create JSON Web Tokens for your team, on the DashboardAPI.

In order to create a JWTSharedSecret, you can make a POST /dashboardapi/v2/jwtsharedsecret/, with the request body:

{
  "permissions": Array<Permission>
}
Permissions

Each JWTSharedSecret has permissions, and it can assign any or all of the permissions it has to each JSON Web Token it creates.

Permission are integers. Possible values are as follows:

  • PERMISSION_ALL = -1: all permissions.
  • PERMISSION_ANONYMOUS_CREATE_MESSAGE = 0: allows creating JSON Web Tokens which can anonymously create messages.
  • PERMISSION_ANONYMOUS_FIND_KEYS = 1: allows creating JSON Web Tokens which can retrieve the recipients' encryption keys.
  • PERMISSION_ANONYMOUS_FIND_SIGCHAIN = 2: allows creating JSON Web Tokens which can retrieve the recipients' SigChain. Unused.

Once the JWTSharedSecret is created, you will need to retrieve this JWTSharedSecret and its JWTSharedSecretId to enable your server to create JSON Web Tokens.

TIP

JWTSharedSecret is, as the name implies, secret. Please take appropriate measures to store it securely.

However, JWTSharedSecretId is not secret.

Example request to create a JWTSharedSecret:

curl -X POST https://dashboard.seald.io/dashboardapi/v2/jwtsharedsecret/ \
  -H 'X-DASHBOARD-API-KEY: YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{"permissions": [1]}'

Example response:

{
  "id": "32266d8c-2085-490a-8ef5-259ea35e1501", // UUID : JWTSharedSecretId
  "created": "2021-11-09T10:49:09.490338Z", // Timestamp ISO
  "shared_secret": "c9kijQo1kJgieXZ9TAHFj9R0TgHb4bgLhDnWWRgjq4TmBzUdSB5mzuOcBb0gQMSi", // String : JWTSharedSecret
  "permissions": [ 1 ] // Array<Permission>
}

# Creating a JSON Web Token

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.

The JSON Web Token, or JWT, is created with the JWTSharedSecret and its JWTSharedSecretId: it has the JWTSharedSecretId as iss, and is signed with the JWTSharedSecret with the HS256 algorithm.

Its payload is:

Name Type Description
iss string "Issuer" : the JWTSharedSecretId
iat? number "Issued at" : timestamp the the JWT creation. Optional. If defined, the JWT expires 10 min after creation. If not, it does not expire.
jti? number "JWT ID" : unique nonce. Must never be re-used. Optional. If defined, the JWT is usable only once. If not, it is usable until its potential expiration.
scopes? Array<Permission> List of this JWT's permissions. Optional. Must be a subset of the JWTSharedSecret's permissions. If defined, the JWT is limited to these permissions only. If not, it has all the permissions assigned to the creating JWTSharedSecret.
recipients Array<string> List of sealdIds of recipients for whom this JWT is authorized to perform operations.
owner? string Optional for retrieving recipient keys. Necessary for message creation. sealdId of the user who will own the created messages.

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 to define 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.

Example of creating a JWT in Python:

Example of creating a JWT in Node.JS:

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: