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