This guide shows how to use the Tanker encryption session to encrypt multiple resources with a reduced number of keys.

It makes sense in a context where multiple resources are linked to each other and will be shared with the same recipients. For example: A document in edition, i.e. having multiple revisions (shared with the same recipients) A form with multiple fields of heterogenous format. * A real time exchange of text or data.

Opening a session and encrypting a ressource

To encrypt a ressource, you need to create the encryption session with createEncryptionSession() and then call its encrypt() member function.

By default, an encryption session's data can only be accessed by the user who created the session. No one else can decrypt the data encrypted inside the session. You can specify additional recipients by providing their Tanker public identity to createEncryptionSession()'s options:

String[] publicIdentities = app.getPublicIdentities(new String[]{"bob-id", "charlie-id"});
SharingOptions options = new SharingOptions().shareWithUsers(publicIdentities);
EncryptionSession encryptionSession = tanker.createEncryptionSession(options).get();

byte[] clearData = myData;
byte[] encryptedData = encryptionSession.encrypt(clearData).get();

NSArray<NSString*>* identities = [self.app getPublicIdentities:@[@"bob-id", @"charlie-id"]];

TKRSharingOptions* sharingOptions = [TKRSharingOptions options];
sharingOptions.shareWithUsers = identities;

[self.tanker createEncryptionSessionWithCompletionHandler:^(TKREncryptionSession* encryptionSession, NSError* err) {
  NSData* clearData = myData;
  [encryptionSession encryptData:clearData
    completionHandler:^(NSData* encryptedData, NSError* err) {
                        if (err == nil) {
                          // handle encrypted data
                        }
                      }];}
                      sharingOptions:options
];

// Ask the application server for Bob and Charlie's public identities
const publicIdentities = await app.getPublicIdentities(['bob-id', 'charlie-id']);
const encryptionSession = await tanker.createEncryptionSession({ shareWithUsers: publicIdentities });

const clearText = "This is a secret message";
const encryptedData = await encryptionSession.encrypt(clearText);

public_identities = app.fetch_public_identities(['bob-id', 'charlie-id'])
sharing_options = Tanker::SharingOptions.new(share_with_users: public_identities)
encryption_session = tanker.create_encryption_session(sharing_options)

clear_text = 'Secret message'
encrypted_text = encryption_session.encrypt_utf8(clear_text)

Note

Please note that Tanker does not transfer nor store the encrypted data. For it to be available to your users later and across devices, you need to store and distribute it yourself.

Tanker does not expose encryption keys. They will automatically be made accessible to the users the session was created by or shared with.

Postponing the share operation

First, you have to retrieve the resource id of the encryption session:

byte[] clearData = myData;
byte[] encryptedData = encryptionSession.encrypt(clearData).get();
String resourceId = encryptionSession.getResourceId();

NSData* clearData = myData;
[encryptionSession encryptData:clearData
                 options:encryptOptions
       completionHandler:^(NSData* encryptedData, NSError* err) {

   NSString* resourceID = encryptionSession.getResourceID;

   }
}];

const encryptedData = await encryptionSession.encrypt(clearText);
const resourceId = encryptionSession.resourceId;

clear_text = 'Secret message'
encrypted_text = encryption_session.encrypt_utf8(clear_text)
resource_id = encryption_session.resource_id

Once you have the resource id of the encryption session, you can call share() with a list of resource IDs and a list of recipients. More details are available in the related section of the encryption guide.

Decrypting

You can use decrypt() to decrypt resources shared with or without an encryption session. You can find more details in the related section of the encryption guide.

Encrypting and decrypting binary data with an encryption session

The encryption of binary resources with encryption session is similar to the encryption of binary resources without encryption sessions. More details are available on the dedicated guide on the subject.