Seald: documentation

English

Français

English

Français

SymEncKeys ​

The concept of SymEncKeys is a feature of the Seald SDK that allows retrieving an EncryptionSession without being a direct recipient.

The idea is to transmit a secret (in the form of a password, or a rawSecret/rawSymKey pair) to the recipient, along with the ID of the SymEncKey. This will enable them to retrieve the EncryptionSession.

Here's how SymEncKeys work:

  • The creator of a session adds a SymEncKey using the session.addSymEncKey() method, with a secret. This returns the ID of the newly created SymEncKey.
  • The secret is transmitted out-of-band to the person who will decrypt (for example, via a QRCode). This person can then use sdk.retrieveEncryptionSessionWithSymEncKey() or anonymousSdk.retrieveEncryptionSession() to retrieve the session and decrypt.

How you transmit the secret from the creator to the recipient is up to you, and depends on your use case.

WARNING

This feature is currently only available in the Seald SDK for JavaScript, and has not yet been implemented in the Seald Mobile SDK for Android, iOS, and Flutter.

Creating a SymEncKey ​

The user who created an EncryptionSession, or anyone with access to it and who has the forward right, can create a SymEncKey for this EncryptionSession.

To create a SymEncKey, you need to retrieve the EncryptionSession object and use the session.addSymEncKey() method. This method accepts either:

  • a password;
  • or a rawSecret and rawSymKey pair.

Using a password is simpler, as you only have to transmit this single value to the recipient. However, it is slower, as the SDK derives the rawSecret and rawSymKey from this password, which can take up to a few hundred milliseconds.

TIP

To ensure end-to-end confidentiality, rawSecret and rawSymKey (or password, which allows to derive them) must remain secret, even from your server.

rawSecret allows you to prove to the Seald server that you have the right to retrieve the encrypted session key, and rawSymKey is the key that decrypts the session key.

You can also specify rights for users of this SymEncKey using the rights argument.

TIP

The default rights for a SymEncKey are { read: true, forward: true, revoke: false }.

The session.addSymEncKey() method returns a string, which is the ID of the created SymEncKey. This ID is not secret and can be transmitted to your server.

Example:

javascript
const crypto = require('node:crypto')

// `rawSecret` can be an arbitrary string, as long as it is hard enough to guess. Here, we use `crypto` for simplicity. A UUIDv4 would also be a good choice.
const rawSecret = crypto.randomBytes(64).toString('base64')
// `rawSymKey` must be a cryptographically secure random buffer of 64 bytes, encoded in base64.
const rawSymKey = crypto.randomBytes(64).toString('base64')

// Creating the `SymEncKey`
const symEncKeyId = await session.addSymEncKey({
  rawSecret,
  rawSymKey,
  rights: { read: true, forward: false, revoke: false }
})
const crypto = require('node:crypto')

// `rawSecret` can be an arbitrary string, as long as it is hard enough to guess. Here, we use `crypto` for simplicity. A UUIDv4 would also be a good choice.
const rawSecret = crypto.randomBytes(64).toString('base64')
// `rawSymKey` must be a cryptographically secure random buffer of 64 bytes, encoded in base64.
const rawSymKey = crypto.randomBytes(64).toString('base64')

// Creating the `SymEncKey`
const symEncKeyId = await session.addSymEncKey({
  rawSecret,
  rawSymKey,
  rights: { read: true, forward: false, revoke: false }
})

Retrieving a session with a SymEncKey ​

To retrieve an EncryptionSession via a SymEncKey, use the sdk.retrieveEncryptionSessionWithSymEncKey() method. This method takes as arguments:

  • the session ID;
  • the SymEncKey ID, which is not secret and can be transmitted via your server;
  • the SymEncKey secret (either a password, or a rawSecret/rawSymKey pair).

TIP

To ensure end-to-end confidentiality, the secret of the SymEncKey (either a password or a rawSecret/rawSymKey pair) must remain secret, even from your server.

How you transmit the secret from the creator to the recipient is up to you, and depends on your use case.

The sdk.retrieveEncryptionSessionWithSymEncKey() method returns an EncryptionSession, which then allows you to encrypt/decrypt messages and files.

TIP

If you access an EncryptionSession via a SymEncKey, you cannot use the access management methods of that session (session.addRecipients(), session.addSymEncKey(), session.revokeRecipients(), session.listRecipients(), ...).

Example:

javascript
// Retrieving a session with a `SymEncKey`
const session = await sdk.retrieveEncryptionSessionWithSymEncKey({
  sessionId, // `sessionId` is not secret, and can be transferred via your server
  symEncKeyId, // `symEncKeyId` is not secret, and can be transferred via your server
  symEncKeyRawSecret, // `symEncKeyRawSecret` is secret, and should never be known by your server
  symEncKeyRawSymKey // `symEncKeyRawSymKey` is secret, and should never be known by your server
})
// Retrieving a session with a `SymEncKey`
const session = await sdk.retrieveEncryptionSessionWithSymEncKey({
  sessionId, // `sessionId` is not secret, and can be transferred via your server
  symEncKeyId, // `symEncKeyId` is not secret, and can be transferred via your server
  symEncKeyRawSecret, // `symEncKeyRawSecret` is secret, and should never be known by your server
  symEncKeyRawSymKey // `symEncKeyRawSymKey` is secret, and should never be known by your server
})

Self-adding to a Session with a SymEncKey ​

If you have access to an EncryptionSession via a SymEncKey, and this SymEncKey has the forward right, you can also use it to add yourself as a "normal" recipient of this session. This allows you, for example, to then transfer this session to other users or to a group. For this, you can use the sdk.selfAddToEncryptionSessionWithSymEncKey() method. This method takes as arguments:

  • the session ID;
  • the SymEncKey ID, which is not secret and can be transmitted via your server;
  • the SymEncKey secret (either a password, or a rawSecret/rawSymKey pair).

You can also specify the rights for yourself as a recipient of this session, within the limit of the rights of the SymEncKey, using the rights argument.

TIP

The default rights for yourself are { read: true, forward: true, revoke: false }.

  • the read right is necessary;
  • the forward right allows you to transfer this session to other recipients via session.addRecipients() and to create new SymEncKeys;
  • the revoke right allows you to revoke recipients from this session and remove SymEncKeys.

For convenience, the method sdk.selfAddToEncryptionSessionWithSymEncKey() also returns the EncryptionSession.

Example:

javascript
// Self-adding to a session with a `SymEncKey`
const session = await sdk.selfAddToEncryptionSessionWithSymEncKey({
  sessionId, // `sessionId` is not secret, and can be transferred via your server
  symEncKeyId, // `symEncKeyId` is not secret, and can be transferred via your server
  symEncKeyRawSecret, // `symEncKeyRawSecret` is secret, and should never be known by your server
  symEncKeyRawSymKey, // `symEncKeyRawSymKey` is secret, and should never be known by your server
  rights: { read: true, forward: false, revoke: false }
})
// Self-adding to a session with a `SymEncKey`
const session = await sdk.selfAddToEncryptionSessionWithSymEncKey({
  sessionId, // `sessionId` is not secret, and can be transferred via your server
  symEncKeyId, // `symEncKeyId` is not secret, and can be transferred via your server
  symEncKeyRawSecret, // `symEncKeyRawSecret` is secret, and should never be known by your server
  symEncKeyRawSymKey, // `symEncKeyRawSymKey` is secret, and should never be known by your server
  rights: { read: true, forward: false, revoke: false }
})

Anonymous Retrieval of a session with a SymEncKey ​

To anonymously retrieve an EncryptionSession via a SymEncKey, you can use the method anonymousSdk.retrieveEncryptionSession(). This method takes the following arguments:

  • the session ID;
  • the SymEncKey ID, which is not secret and can be transmitted via your server;
  • the SymEncKey secret (either a password and appId, or a rawSecret/rawSymKey pair);
  • a JWT retrieveSessionToken, created by your server, which authorizes the session retrieval.

TIP

To ensure end-to-end confidentiality, the secret of the SymEncKey (either a password or a rawSecret/rawSymKey pair) must remain secret, even from your server.

How you transmit the secret from the creator to the recipient is up to you, and depends on your use case.

The method anonymousSdk.retrieveEncryptionSession() returns an AnonymousEncryptionSession, which allows you to then encrypt/decrypt messages and files.

Usage example:

javascript
// Anonymous retrieval of a session with a `SymEncKey`
const session = await anonymousSdk.retrieveEncryptionSession({
  sessionId, // `sessionId` is not secret, and can be transferred via your server
  symEncKeyId, // `symEncKeyId` is not secret, and can be transferred via your server
  symEncKeyRawSecret, // `symEncKeyRawSecret` is secret, and should never be known by your server
  symEncKeyRawSymKey, // `symEncKeyRawSymKey` is secret, and should never be known by your server
  retrieveSessionToken // JWT generated by your server to authorize this anonymous retrieval
})
// Anonymous retrieval of a session with a `SymEncKey`
const session = await anonymousSdk.retrieveEncryptionSession({
  sessionId, // `sessionId` is not secret, and can be transferred via your server
  symEncKeyId, // `symEncKeyId` is not secret, and can be transferred via your server
  symEncKeyRawSecret, // `symEncKeyRawSecret` is secret, and should never be known by your server
  symEncKeyRawSymKey, // `symEncKeyRawSymKey` is secret, and should never be known by your server
  retrieveSessionToken // JWT generated by your server to authorize this anonymous retrieval
})