Seald: documentation

English

Français

English

Français

Groups ​

Seald supports groups. You can create a group which contains multiple users, so that you can easily encrypt data for all members of the group.

You can also easily add or remove members of the group. Of course, when you add members to a group, they immediately have access to data previously encrypted for the group; conversely, when you remove members from a group, they lose access to all the data encrypted for the group.

Creating a group ​

In order to create a group, you must use the method SealdSDK.createGroup.

javascript
const group = await seald.createGroup({
  groupName: 'My super group', // will be displayed in the administration dashboard. This is just to help you locate the group. You can for example put the ID that your back-end has assigned to this group.
  members: {
    sealdIds: [mySealdId, otherUserSealdId] // all members of the group: the users who will be able to read the messages intended for the group. Must contain the user who is creating the group.
  },
  admins: {
    sealdIds: [mySealdId] // the group administrators: the users who will be able to add/remove members to the group. Must contain the user who is creating the group.
  }
})

// `group` is then `{ groupName: string, id: string }`.
// `group.groupName` is what you just assigned when creating the group, here `My super group`.
// `group.id` is the ID you can use in order to encrypt data for this group. It is a `sealdId`
const group = await seald.createGroup({
  groupName: 'My super group', // will be displayed in the administration dashboard. This is just to help you locate the group. You can for example put the ID that your back-end has assigned to this group.
  members: {
    sealdIds: [mySealdId, otherUserSealdId] // all members of the group: the users who will be able to read the messages intended for the group. Must contain the user who is creating the group.
  },
  admins: {
    sealdIds: [mySealdId] // the group administrators: the users who will be able to add/remove members to the group. Must contain the user who is creating the group.
  }
})

// `group` is then `{ groupName: string, id: string }`.
// `group.groupName` is what you just assigned when creating the group, here `My super group`.
// `group.id` is the ID you can use in order to encrypt data for this group. It is a `sealdId`

TIP

To accelerate the creation of groups, you can pre-generate the private keys by calling the seald.preGenerateIdentityKeys() function in advance.

Encrypting for a group ​

When a user encrypts data for a group, all members of the group can decrypt it.

javascript
const encryptedForGroup = await sealdSender.encryptFile( // a user encrypts for the group
  'Secret file content',
  'my_secret_file.txt',
  { sealdIds: [groupId] }
)

const decrypted = await sealdGroupMember.decryptFile(encryptedForGroup) // another SDK user, who is a member of the group, decrypts the data encrypted for the group

// Here, the user has decrypted the data, and we do have as expected `decrypted === 'Secret file content'`
const encryptedForGroup = await sealdSender.encryptFile( // a user encrypts for the group
  'Secret file content',
  'my_secret_file.txt',
  { sealdIds: [groupId] }
)

const decrypted = await sealdGroupMember.decryptFile(encryptedForGroup) // another SDK user, who is a member of the group, decrypts the data encrypted for the group

// Here, the user has decrypted the data, and we do have as expected `decrypted === 'Secret file content'`

TIP

If you are encrypting for a group of which the user is a member, you can use the optional argumentencryptForSelf: false so that you do not encrypt directly for their own identities. The user will still be able to decrypt the data thanks to their group membership. This can allow you to improve the performance of the encryption.

Adding /removing group members ​

Group administrators can add and remove members to the group.

When a member is added to the group, they can then decrypt the data previously encrypted for that group.

javascript
await sealdGroupAdmin.addGroupMembers(groupId, { sealdIds: [newMemberSealdId] }) // only a group administrator can add members

const decrypted = await sealdNewMember.decryptFile(encryptedForGroup) // the newly added user can then decrypt the data previously encrypted for that group
await sealdGroupAdmin.addGroupMembers(groupId, { sealdIds: [newMemberSealdId] }) // only a group administrator can add members

const decrypted = await sealdNewMember.decryptFile(encryptedForGroup) // the newly added user can then decrypt the data previously encrypted for that group

Conversely, when a member is removed from the group, they can no longer decrypt the data encrypted for that group.

In this case, and for more security, it is advisable to renew the group keys.

javascript
const decrypted = await sealdGroupMember.decryptFile(encryptedForGroup) // a group member can decrypt data encrypted for the group

await sealdGroupAdmin.removeGroupMembers(groupId, { sealdIds: [groupMemberToRemoveSealdId] }) // only a group administrator can remove members

await sealdGroupMember.decryptFile(encryptedForGroup) // Throws an error: the user newly removed from the group cannot decrypt data encrypted for the group anymore

await sealdGroupAdmin.renewGroupKey(groupId) // a group administrator can then renew the group keys for more security
const decrypted = await sealdGroupMember.decryptFile(encryptedForGroup) // a group member can decrypt data encrypted for the group

await sealdGroupAdmin.removeGroupMembers(groupId, { sealdIds: [groupMemberToRemoveSealdId] }) // only a group administrator can remove members

await sealdGroupMember.decryptFile(encryptedForGroup) // Throws an error: the user newly removed from the group cannot decrypt data encrypted for the group anymore

await sealdGroupAdmin.renewGroupKey(groupId) // a group administrator can then renew the group keys for more security

A group administrator can also add and remove administrators to the group.

javascript
await sealdGroupAdmin.setGroupAdmin(groupId, { sealdIds: [newAdminSealdId] }, true) // newAdmin is the administratorr

await sealdGroupAdmin.setGroupAdmin(groupId, { sealdIds: [oldAdminSealdId] }, false) // oldAdmin is no longer administrator
await sealdGroupAdmin.setGroupAdmin(groupId, { sealdIds: [newAdminSealdId] }, true) // newAdmin is the administratorr

await sealdGroupAdmin.setGroupAdmin(groupId, { sealdIds: [oldAdminSealdId] }, false) // oldAdmin is no longer administrator