# Encryption Sessions

When you intend to encrypt many messages in a row, for example in an instant chat, you can use an Encryption Session. An Encryption Session uses the same key to encrypt all messages in the session.

The advantages are that your integration code can be simpler, that it decreases the number of network requests related to retrieving decryption keys, and that you decrease the total number of keys used (opens new window).

The downside is that you lose the granularity offered by encrypting each message independently: you cannot add / revoke a recipient on a single message of the session, but only on the session as a whole.

# Creating an encryption session

You can create a session with the function sealdSDK.createEncryptionSession.

Upon creation, two elements must be defined:

  • userIds : an array of user IDs in your application that will be allowed for this encryption session;
  • metadata : an optional argument declaring a non-encrypted metadata to the Seald API. It can be used in the administration of a Seald account.

The session created is of type EncryptionSession. It has a sessionId property, and several methods.

The person who creates a session is the administrator: only this user will be able to revoke the whole session.

# Encrypting messages

With the EncryptionSession object, we can then encrypt messages, which will be readable by all recipients of the session.

This will result in a string of the form:

'{"sessionId":"0000000000000000000000","data":"8RwaOppCD3uIJVFv2LoP3XGXpomj0xsMv4qmMVy30Vdqor2w0+DVCXu3j13PEyN2KfJm6SiSrWDRMDziiiOUjQ=="}'

This contains the sessionId which is the identifier of the encryption session and data which is the encrypted data.

# Retrieving a session

Once a session has been created and a message encrypted, it must be possible to retrieve the session afterwards, including by the sender himself.

For this, there are two possibilities:

  • from the sessionId, but this requires storing it in a separate field in the application;
  • from an encrypted message with this session directly, which has the advantage of being simpler.

In both cases, we use the sealdSDK.retrieveEncryptionSession method, either with the argument named sessionId if we know it, or with the argument named encryptedMessage:

# Decrypting messages

Once the session is retrieved, we can use it to decrypt a message:

# Add / revoke session recipients

Any recipient of the session can add other recipients to it, using the method session.addRecipients.

On the other hand, to revoke a recipient of the session with the session.revokeRecipients method, only the person who added this recipient (directly or indirectly), or the creator of the session, can do so.

Let's imagine a case where user1 added user2 into the session, and user2 added user3.

  • user3 cannot revoke anyone
  • user2 can revoke user3 (because he added him), but cannot revoke user1
  • user1 can revoke user2 (because he added him) and user3 (because he was added by someone added by him)

The session creator can also use the session.revoke method to revoke the entire session and all its content.

# Encrypt & decrypt files

An EncryptionSession also exposes two methods encryptFile and decryptFile for using this encryption session to encrypt files.

As explained in the dedicated file encryption guide, these methods support different types (string, Buffer, Blob in the browser only, ReadableStream of Web Streams (opens new window), and Readable of Node.JS Streams (opens new window)).

# Difference with SDK#encryptFile and SDK#decryptFile

By using an EncryptionSession to encrypt/decrypt files, one can reuse the session encryption key on different files/messages, and one manages the recipients at the encryption session level.

Thus the encryptFile method of an EncryptionSession does not take the recipients argument, and only has the following arguments:

  • clearFile: same as SDK#encryptFile;
  • filename: in this case it is not used as the metadata, but only as the file name in the encrypted tar (see the format of an encrypted file);
  • options: the options object of which only the fileSize property is used, and is only necessary when clearFile is of type Readable or ReadableStream.

# Encryption

Here is an example of encryption (with the Buffer type):

# Decryption

To decrypt a file encrypted with a session, we must use the same EncryptionSession (previously retrieved with SDK#retrieveEncryptionSession):

One can also directly use SDK#decryptFile which will automatically retrieve the associated EncryptionSession (the EncryptionSession ID is always included in the result of a file encryption):

WARNING

Using the decryptFile method of an EncryptionSession on file encrypted with another session will not work.

TIP

For examples with other types, refer to the examples section of the file encryption guide. You will just have to take into account the above-mentioned differences.