If you need to regularly share data with several people, you might want to create a group. Groups provide much better performance than user-to-user sharing by sharing less keys and allowing applications to avoid specifying the same list of users multiple times. They come, however, at the cost of increased complexity because you'll need to keep the members of the Tanker groups in sync with the groups of people in your own application.

Creating a group

The first step is to create a group with several users in it. This is done using createGroup():

// Retrieve Bob's and Charlie's public identities from the application server
const publicIdentities = await app.getPublicIdentities(['bob-id', 'charlie-id']);

// Create a group containing Bob and Charlie
const groupId = await tanker.createGroup(publicIdentities);
NSArray<NSString*>* identities = [self.app getPublicIdentities:@[@"bob-id", @"charlie-id"]];
[self.tanker createGroupWithIdentities:identities
                     completionHandler:^(NSString* groupID, NSError* err) {
                       if (err == nil) {
                         // do something
                       }
                     }];
// Retrieve Bob's and Charlie's public identities from the application server
String[] publicIdentities = app.getPublicIdentities(new String[]{"bob-id", "charlie-id"});

// Create a group containing Bob and Charlie
String groupId = tanker.createGroup(publicIdentities).get();

Note

If the group creator wants to be part of the group, they must explicitly add themselves to it.

The group ID must be stored on your application's server, along with any group meta-data. When a user needs to share with a group, the application front-end must query the application server to fetch the group ID and give it to Tanker.

The maximum number of users per group is 1000.

Sharing data with a group

Sharing with a group is similar to sharing with a user. Both encrypt() and share() support group IDs, as well as user IDs.

const options = { shareWithGroups: [groupId] };
const encryptedData = await tanker.encrypt(message, options);

// OR
const options = { shareWithGroups: [groupId] };
await tanker.share([resourceId], options);
TankerEncryptOptions encryptionOptions = new TankerEncryptOptions()
      .shareWithGroups(new String[]{groupId});

byte[] encryptedData = tanker.encrypt(message.getBytes(), encryptionOptions).get();

// OR

TankerShareOptions shareOptions = new TankerShareOptions()
      .shareWithGroups(new String[]{groupId});

tanker.share(new String[]{resourceId}, shareOptions).get();
TKREncryptionOptions* encryptionOptions = [TKREncryptionOptions options];
encryptionOptions.shareWithGroups = @[groupID];

[self.tanker encryptString:message
                   options:encryptionOptions
         completionHandler:^(NSData* encryptedData, NSError* err) {
           if (err == nil) {
             // do something with encryptedData
           }
         }];

// OR

TKRShareOptions* shareOptions = [TKRShareOptions options];
shareOptions.shareWithGroups = @[groupID];

[self.tanker shareResourcesIDs:@[resourceID]
                       options:shareOptions
             completionHandler:^(NSError* err) {
               if (err == nil) {
                 // do something
               }
             }];

If a user is a member of a group, they can decrypt() data shared with the group.

Updating a group

Once it has been created with createGroup(), a group can be updated by adding members to it. The new members will automatically get access to all resources previously shared with this group.

This is done using updateGroupMembers().

Note

The option to remove users from a group is currently in the making and will be available soon.

// Retrieve Charlie's public identity from the application server
const publicIdentities = await app.getPublicIdentities(['charlie-id']);

// Add Charlie to the group
await tanker.updateGroupMembers(groupId, { usersToAdd: publicIdentities });
NSArray<NSString*>* identities = [self.app getPublicIdentities:@["charlie-id"]];
[self.tanker updateMembersOfGroup:groupId
                       usersToAdd:identities
                completionHandler:^(NSError* err) {
                  if (err == nil) {
                    // do something
                  }
                }];
// Retrieve Charlie's public identity from the application server
String[] publicIdentities = app.getPublicIdentities(new String[]{"charlie-id"});

// Add Charlie to the group
tanker.updateGroupMembers(groupId, publicIdentities).get();