seald-reversibility-tools

A tool to use to fully decrypt all your data stored with the Seald SDK.

This uses the reversibility exports that Seald provides their customers upon request.

This is intended as a one-way tool to leave Seald.

This tool is a Node.JS library, intended to be used in .js scripts that a developper writes to do this process.

This process is done in 3 steps:

• Getting a database of decrypted identities
• Getting a database of decrypted session keys
• Decrypting the data itself

The full documentation can be found here.

An example project using it is available here.

Seald data export

To obtain this export, you must contact Seald support. You will need to provide a public key to encrypt the data.

To generate a pair of keys, you can use the following code example:

import { node as sscrypto } from 'sscrypto'
import fs from 'node:fs'

const rsaKeyPair = await sscrypto.PrivateKey.generate(4096)

await fs.promises.writeFile('publicKey.key', rsaKeyPair.toB64({ publicOnly: true }), 'utf8')
await fs.promises.writeFile('privateKey.key', rsaKeyPair.toB64(), 'utf8')

Running this code creates two files:

• A 'publicKey.key' file, containing the encryption key that you must provide to us in order to export the data.
• A 'privateKey.key' file, containing the key that will be used to decrypt the exported data.

Getting a database of decrypted identities

A database of decrypted identities (the output of this step) is a JSONLines file, containing:

{ sealdId: string, deviceId: string, identity: string }

The identity field here contains the Base64 encoding of the identity buffer.

This file can be constructed in multiple ways.

First, it can be done directly by the developer, by calling sealdSdk.exportIdentity() on their clients, then sending these identities back to their server, and constructing this file themselves.

Also, this database can be obtained by using the decryptSsksExport(ssksExportPath, privateKey, outputPath, { appId, ssksTmrKeysPath, ssksStrictPasswordsPath }) function of the reversibility tools.

In this function call:

• ssksExportPath is the path to the export file for SSKS provided by Seald
• privateKey is an SSCrypto instance of your private key for which the exports were encrypted
• outputPath is the path to which to write the output file (the directory must already exist). If the file already exists, it will be overwritten.
• appId is your Seald App ID
• ssksTmrKeysPath is an optional argument, if you want to retrieve the identities from SSKS 2MR. It is the path to a file that is exported from your database, containing the twoManRuleKey or rawTwoManRuleKey for each user of your app, stored in a JSONLines file, in the following format:

{ userId: string, sealdId?: string, deviceId?: string, rawTwoManRuleKey?: string, twoManRuleKey?: string }

Each line must contain one, and only one, of rawTwoManRuleKey or twoManRuleKey. The fields sealdId and deviceId are optional, and are used to check that the decrypted identity indeed corresponds to what is expected.

• ssksStrictPasswordsPath is an optional argument, if you want to retrieve the identities from SSKS Password. It is the path to a file that is exported from your database, containing the password or rawEncryptionKey for each user of your app, stored in a JSONLines file, in the following format:

{ userId: string, sealdId?: string, deviceId?: string, password?: string, rawEncryptionKey?: string }

Each line must contain one, and only one, of password or rawEncryptionKey. The fields sealdId and deviceId are optional, and are used to check that the decrypted identity indeed corresponds to what is expected.

Getting a database of decrypted session keys

Once you have the database of decrypted identities, you can use the decryptApiExport(apiExportPath, decryptedIdentitiesPath, privateKey, outputPath, { tmrAccessesOverEncryptionKeysPath?, symEncKeysPath?, appId? }) function of the reversibility tools.

In this function call:

• apiExportPath is the path to the export file for the main Seald API provided by Seald
• decryptedIdentitiesPath is the path to the file that is the result of the previous step
• privateKey is an SSCrypto instance of your private key for which the exports were encrypted
• tmrAccessesOverEncryptionKeysPath is an optional argument, if you want to retrieve session keys from TMR Accesses. This should be the path to a file that is exported from your database, containing the rawOverEncryptionKey for each TMR Access, stored in a JSONLines file, in the following format:

{ sessionId: string, tmrAccessId: string, rawOverEncryptionKey: string }

• groupTmrTemporaryKeysOverEncryptionKeysPath is an optional argument, if you want to retrieve session keys from TMR temporary keys. This should be the path to a file that is exported from your database, containing the rawOverEncryptionKey for each TMR Temporary key, stored in a JSONLines file, in the following format:

{ gTMRTKId: string, rawOverEncryptionKey: string }

• symEncKeysPath is an optional argument, if you want to retrieve session keys from SymEncKeys. This should be the path to a file that is exported from your database, containing the Sym Enc Keys, stored in a JSONLines file, in the following format:

{ sessionId: string, symEncKeyId: string, rawSecret?: string, rawSymKey?: string, password?: string }

• appId is your Seald App ID. It is required only if you pass symEncKeysPath.

Each line must contain one, and only one, of password or the pair rawSecret and rawSymKey.

This will result in a JSONLines file in the following format:

{ sessionId: string, key: string }

Decrypting the data itself

Once you have the database of decrypted session keys, you can use the decryptMessage(encryptedMessage, decryptedSessionKeysPath, { raw , sessionId }) and decryptFile(encryptedFileStream, decryptedSessionKeysPath, { sessionId }) functions to decrypt messages and files respectively.

In the decryptMessage function call:

• encryptedMessage is the encrypted message to decrypt
• decryptedSessionKeysPath is the path to the file that is the result of the previous step
• raw is an optional boolean that defaults to false, and that you shoud set to true if the message was encrypted as a raw message
• sessionId is the session ID to which this message corresponds. Optional if the message is not raw. Required if the message is raw.

This returns the content of the decrypted message as a string.

In the decryptFile function call:

• encryptedFileStream is a Readable stream of the file to decrypt
• decryptedSessionKeysPath is the path to the file that is the result of the previous step
• sessionId is the session ID to which this file corresponds. Optional.

This returns:

• stream, which is a Readable stream which contains the content of the decrypted file
• promise, which resolves as soon as the parsing is finished and which contains the file size size , the file name filename, the protocol version protocol, and the parsed session ID mid