import { Tanker } from '@tanker/client-browser';
// or...
const { Tanker } = require('@tanker/client-browser');

Note

This documentation uses flow type annotations.
The custom b64string type represents binary data encoded in a base 64 string.

@import Tanker;
import io.tanker.api.Tanker;

Error handling

import { errors } from '@tanker/client-browser';

try {
  await tanker.start(...);
} catch(e) {
  if (e instanceof errors.InvalidArgument) {
    /* specific Tanker error handling */
  } else if (e instanceof errors.TankerError) {
    /* generic Tanker error handling */
  } else {
    /* generic non-Tanker error handling */
  }
}

All errors thrown by Tanker extend the same TankerError base class and have the following fields:

Field Description
name the name of the (sub)class as a string
message additional details about the error

Here is the list of possible errors:

Error Description
DecryptionFailed A decryption operation failed
ExpiredVerification The identity verification is expired
GroupTooBig The group would exceed the maximum member limit (1000)
InternalError Tanker internal error, thrown as a last resort
InvalidArgument Developer error, one of the function's argument is invalid
InvalidVerification An invalid identity verification was provided
NetworkError Network error, e.g. connection lost or the Tanker server is not reachable
OperationCanceled An asynchronous operation was canceled when Tanker stopped
PreconditionFailed Developer error, a function's precondition was violated
TooManyAttempts An operation was attempted too many times, please try again later

Errors are reported with NSError, with the TKRErrorDomain domain, and a TKRError code.

NSString* identity = /* ... */;
[tanker startWithIdentity:identity completionHandler:
  ^(NSError* err)
  {
    if (err != nil) {
      NSLog(@"An error occurred: %@", [err localizedDescription]);
      if (err.code == TKRErrorInvalidArgument) {
        /* ... */
      }
    }
  }
];

Here is the list of possible errors:

TKRError Description
TKRErrorInvalidArgument Developer error, one of the function's argument is invalid
TKRErrorNetworkError Network error, e.g. connection lost or the Tanker server is not reachable
TKRErrorPreconditionFailed Developer error, a function's precondition was violated
TKRErrorOperationCanceled An asynchronous operation was canceled when Tanker stopped
TKRErrorDecryptionFailed A decryption operation failed
TKRErrorGroupTooBig The group would exceed the maximum member limit (1000)
TKRErrorInvalidVerification An invalid identity verification was provided
TKRErrorTooManyAttempts An operation was attempted too many times, please try again later
TKRErrorExpiredVerification The identity verification is expired
TKRErrorInternalError Tanker internal error, thrown as a last resort
private static final String TAG = "YourActivity";

TankerFuture<Unit> future = tanker.open(...);
future.then((future) -> {
    try {
        future.get();
    } catch (TankerException e) {
        if (e.getErrorCode() == TankerErrorCode.INVALID_ARGUMENT)
            Log.e(TAG, "An error occurred", e);
    }
});

All errors thrown from Tanker use the TankerException class, which contains an error code and a message. Here is the list of possible errors:

Error Description
INVALID_ARGUMENT Developer error, one of the function's argument is invalid
INTERNAL_ERROR Tanker internal error, thrown as a last resort
NETWORK_ERROR Network error, e.g. connection lost or the Tanker server is not reachable
PRECONDITION_FAILED Developer error, a function's precondition was violated
OPERATION_CANCELED An asynchronous operation was canceled when Tanker stopped
DECRYPTION_FAILED A decryption operation failed
INVALID_GROUP_TOO_BIG The group would exceed the maximum member limit (1000)
INVALID_VERIFICATION An invalid identity verification was provided
TOO_MANY_ATTEMPTS An operation was attempted too many times, please try again later
EXPIRED_VERIFICATION The identity verification is expired

Constructor

const config = { appId: 'your-app-id' };
const tanker = new Tanker(config);
Parameters Description
config: Object The configuration of this Tanker instance, containing:
config.appId: b64string The app ID
TKRTankerOptions *opts = [TKRTankerOptions options];
opts.appID = @"your-app-id";
opts.writablePath = @"/some/writable/path";

TKRTanker* tanker = [TKRTanker tankerWithOptions:opts];
Options
writablePath: NSString* The path where persistent data will be stored
appID: NSString* The app ID
String writablePath = getApplicationContext().getFilesDir().getAbsolutePath();
TankerOptions options = new TankerOptions();
options.setAppId("your-app-id")
        .setWritablePath(writablePath);
Tanker tanker = new Tanker(options);
Options
writablePath: String The path where persistent data will be stored
appID: String The app ID

Session methods

The methods below allow you to start and stop a Tanker session, and check its current status. To find out more, please refer to the guide.

start

Starts a Tanker session and returns a status. See the guide for more information on treating the status.

The Tanker status must be STOPPED.

function start(identity: b64string): Promise<number>

The returned promise resolves in a value in Tanker.statuses.

Parameters
identity: string The Tanker identity
Returns
Promise<READY> The session is ready and fully operational
Promise<IDENTITY_REGISTRATION_NEEDED> First use of the identity. registerIdentity() must be called.
Promise<IDENTITY_VERIFICATION_NEEDED> New device for this identity. verifyIdentity() must be called.
Throws Description
InvalidArgument The provided identity is invalid
PreconditionFailed The status is not STOPPED
NetworkError Network error, e.g. connection lost or the Tanker server is not reachable
typedef void (^TKRStartHandler)(TKRStatus _Nullable status,
                                NSError* _Nullable err);

- (void)startWithIdentity:(nonnull NSString*)identity
        completionHandler:(nonnull TKRStartHandler)handler;
Parameters
identity: NSString* The Tanker identity
Handler return value Description
TKRStatusReady The session is ready and fully operational
TKRStatusIdentityRegistrationNeeded First use of the identity. registerIdentity must be called.
TKRStatusIdentityVerificationNeeded New device for this identity. verifyIdentityWithVerification must be called.
Errors Description
TKRErrorInvalidArgument The identity is invalid
TKRErrorPreconditionFailed The status is not TKRStatusStopped

The Tanker status must be STOPPED.

@NotNull
public TankerFuture<Status> start(@NotNull String identity)
Parameters
identity: String The Tanker identity
Returns
TankerFuture<READY> The session is ready and fully operational
TankerFuture<IDENTITY_REGISTRATION_NEEDED> First use of the identity. registerIdentity() must be called.
TankerFuture<IDENTITY_VERIFICATION_NEEDED> New device for this identity. verifyIdentity() must be called.
Errors Description
INVALID_ARGUMENT An argument is ill-formed
PRECONDITION_FAILED The session is not STOPPED

stop

Stops the current Tanker session.

function stop(): Promise<void>
Returns
Promise The promise is fulfilled once the stop operation is done
typedef void (^TKRErrorHandler)(NSError* _Nullable err);

- (void)stopWithCompletionHandler:(nonnull TKRErrorHandler)handler;
@NotNull
public TankerFuture<Unit> stop()
Returns
TankerFuture<Unit> The future is fulfilled once the stop operation is done

status

The status of a Tanker session is available as the status property:

const status = tanker.status;

Possible status values are defined in Tanker.statuses:

Status Description
Tanker.statuses.STOPPED The session is stopped. start() can be called on it.
Tanker.statuses.READY The session is ready and fully operational
Tanker.statuses.IDENTITY_VERIFICATION_NEEDED The session needs the identity to be verified to become READY
Tanker.statuses.IDENTITY_REGISTRATION_NEEDED This identity is not associated with any verification method. One must be registered.

To monitor status changes in your application, listen to the statusChange event.

@property(readonly) TKRStatus status;

The following constants are available to check the status value:

Status Description
TKRStatusStopped The session is stopped. start() can be called on it.
TKRStatusReady The session is ready and fully operational
TKRStatusIdentityVerificationNeeded The session needs the identity to be verified to become TKRStatusReady
TKRStatusIdentityRegistrationNeeded This identity is not associated with any verification method. One must be registered.

The following constants are available to check the status value:

Status Description
Status.STOPPED The session is stopped. start() can be called on it.
Status.READY The session is ready and fully operational
Status.IDENTITY_VERIFICATION_NEEDED The session needs the identity to be verified to become Status.READY
Status.IDENTITY_REGISTRATION_NEEDED This identity is not associated with any verification method. One must be registered.

You can read the status of the Tanker session using:

@NotNull
public Status getStatus()

Identity verification

Verification

The Verification object is a plain-data object that must match one of the following formats:

{ email: string, verificationCode: string }
{ oidcIdToken: string }
{ passphrase: string }
{ verificationKey: string }

A Verification object is typically used to perform an identity verification, or to register a new identity verification method.

The TKRVerification class is an opaque type providing the following class methods:

+ (instancetype)verificationFromVerificationKey:(nonnull TKRVerificationKey*)key;
+ (instancetype)verificationFromEmail:(nonnull NSString*)email
                     verificationCode:(nonnull NSString*)code;
+ (instancetype)verificationFromPassphrase:(nonnull NSString*)passphrase;
+ (instancetype)verificationFromOIDCIDToken:(nonnull NSString*)oidcIDToken;

A TKRVerification object is typically used to perform an identity verification, or to register a new identity verification method.

The Verification abstract class can be instantiated by the classes with these constructors:

public PassphraseVerification(@NotNull String passphrase)
public VerificationKeyVerification(@NotNull String verificationKey)
public EmailVerification(@NotNull String email, @NotNull String verificationCode)
public OIDCIDTokenVerificationMethod(@NotNull String oidcIDToken)

A Verification object is typically used to perform an identity verification, or to register a new identity verification method.

Verification Method

The VerificationMethod object is a plain-data object that must match one of the following formats:

{ type: 'email', email: string }
{ type: 'oidcIdToken' }
{ type: 'passphrase' }
{ type: 'verificationKey' }

VerificationMethod objects are returned by functions that list verification methods available for an upcoming identity verification, e.g. getVerificationMethods() and attachProvisionalIdentity().

The TKRVerificationMethod class is a read-only type, returned by the verificationMethodsWithCompletionHandler function.

@property(readonly) TKRVerificationMethodType type;

// nil when type != TKRVerificationMethodTypeEmail
@property(readonly) NSString* email;

TKRVerificationMethod objects will be returned by functions that list identity verification methods available for an upcoming identity verification, such as getVerificationMethods() or attachProvisionalIdentity().

The VerificationMethod abstract class provides information about available verification methods through the following concrete types:

public class PassphraseVerificationMethod extends VerificationMethod { }
public class VerificationKeyVerificationMethod extends VerificationMethod { }
public class EmailVerificationMethod extends VerificationMethod {
    @NotNull
    public String getEmail()
}

These objects are returned by functions that list verification methods available for an upcoming identity verification, e.g. getVerificationMethods() and attachProvisionalIdentity().

registerIdentity

Registers the user's identity with which start() has been called, and starts the session.

The Tanker status must be IDENTITY_REGISTRATION_NEEDED.

function registerIdentity(verification: Verification): Promise<void>

The Tanker status must be TKRStatusIdentityRegistrationNeeded.

- (void)registerIdentityWithVerification:(nonnull TKRVerification*)verification
                       completionHandler:(nonnull TKRErrorHandler)handler;

The Tanker status must be IDENTITY_REGISTRATION_NEEDED.

@NotNull
public TankerFuture<Unit> registerIdentity(@NotNull Verification verification)

It must be called once, when the user has started a Tanker session for the first time. It will register the user's identity and associate a first identity verification method to it.

Note

In case the user wishes to use a verificationKey , call generateVerificationKey() instead.

Parameters
verification: Verification The verification to use for identity registration
Returns
Promise The promise is fulfilled once the registration is done
Throws Description
InvalidArgument The verification is ill-formed or incomplete
PreconditionFailed The status is not IDENTITY_REGISTRATION_NEEDED
ExpiredVerification The verification expired
InvalidVerification The verification is invalid
TooManyAttempts Too many verification attempts occurred. Please retry later.
NetworkError Network error, e.g. connection lost or the Tanker server is not reachable
Parameters Description
verification: TKRVerification* The verification required to register the identity
Errors Description
TKRErrorPreconditionFailed Status is not TKRStatusIdentityRegistrationNeeded
TKRErrorExpiredVerification The verification expired
TKRErrorInvalidVerification The verification is invalid
TKRErrorTooManyAttempts Too many verification attempts occurred. Please retry later.
Parameters
verification: Verification The verification to use for identity registration
Returns
TankerFuture<Unit> Resolves when the registration is done
Errors Description
PRECONDITION_FAILED The status is not IDENTITY_REGISTRATION_NEEDED
EXPIRED_VERIFICATION The verification expired
INVALID_VERIFICATION The verification is invalid
TOO_MANY_ATTEMPTS Too many verification attempts occurred. Please retry later.

verifyIdentity

Verifies the user's identity with which start has been called, and starts the session.

The Tanker status must be IDENTITY_VERIFICATION_NEEDED.

function verifyIdentity(verification: Verification): Promise<void>

The Tanker status must be TKRStatusIdentityVerificationNeeded.

- (void)verifyIdentityWithVerification:(nonnull TKRVerification*)verification
                     completionHandler:(nonnull TKRErrorHandler)handler;

The Tanker status must be IDENTITY_VERIFICATION_NEEDED.

@NotNull
public TankerFuture<Unit> verifyIdentity(@NotNull Verification verification)

This function verifies the user's identity based on the provided verification. It must be called when the user has started a Tanker session on a new device.

Parameters
verification: Verification The verification to use
Returns
Promise The promise is fulfilled once the verification is complete
Throws Description
InvalidArgument The verification is ill-formed or incomplete
PreconditionFailed The status is not IDENTITY_VERIFICATION_NEEDED
ExpiredVerification The verification expired
InvalidVerification The verification is invalid
TooManyAttempts Too many verification attempts occurred. Please retry later.
NetworkError Network error, e.g. connection lost or the Tanker server is not reachable
Parameters Description
verification: TKRVerification* The verification required to verify the identity
Errors Description
TKRErrorPreconditionFailed Status is not TKRStatusIdentityVerificationNeeded
TKRErrorExpiredVerification The verification expired
TKRErrorInvalidVerification The verification is invalid
TKRErrorTooManyAttempts Too many verification attempts occurred. Please retry later.
Parameters
verification: Verification The verification to use
Returns
TankerFuture<Unit> Resolves once the verification is complete
Errors Description
PRECONDITION_FAILED The status is not IDENTITY_VERIFICATION_NEEDED
EXPIRED_VERIFICATION The verification expired
INVALID_VERIFICATION The verification is invalid
TOO_MANY_ATTEMPTS Too many verification attempts occurred. Please retry later.

setVerificationMethod

Adds or overrides a verification method.

The Tanker status must be READY.

function setVerificationMethod(verification: Verification): Promise<void>

The Tanker status must be TKRStatusReady.

- (void)setVerificationMethod:(nonnull TKRVerification*)verification
            completionHandler:(nonnull TKRErrorHandler*)handler;

The Tanker status must be READY.

@NotNull
public TankerFuture<Unit> setVerificationMethod(@NotNull Verification verification)

Note that you must prove your identity with a Verification when calling this function. The corresponding VerificationMethod will then be associated with your identity and listed in future getVerificationMethods() result.

Parameters Description
verification: Verification The verification to use
Returns
Promise The promise is fulfilled when the verification method has been set or updated
Throws Description
InvalidArgument The verification is ill-formed or incomplete
ExpiredVerification The verification expired
InvalidVerification The verification is invalid
PreconditionFailed The status is not READY
TooManyAttempts Too many verification attempts occurred. Please retry later.
NetworkError Network error, e.g. connection lost or the Tanker server is not reachable
Parameters Description
verification: TKRVerification* The verification to use
Errors Description
TKRErrorExpiredVerification The verification expired
TKRErrorInvalidVerification The verification is invalid.
TKRErrorPreconditionFailed Status is not TKRStatusReady
TKRErrorTooManyAttempts Too many verification attempts occurred. Please retry later.
Parameters
verification: Verification The verification to use
Returns
TankerFuture<Unit> Resolves once the verification method has been set or updated
Errors Description
EXPIRED_VERIFICATION The verification expired
INVALID_VERIFICATION The verification is invalid
PRECONDITION_FAILED The status is not READY
TOO_MANY_ATTEMPTS Too many verification attempts occurred. Please retry later.

getVerificationMethods

Returns the list of registered verification methods.

The Tanker status must be either IDENTITY_VERIFICATION_NEEDED or READY.

function getVerificationMethods(): Promise<Array<VerificationMethod>>

The Tanker status must be TKRStatusReady.

typedef void (^TKRVerificationMethodsHandler)(
    NSArray<TKRVerificationMethod*>* _Nullable methods, NSError* _Nullable err);

- (void)verificationMethodsWithCompletionHandler:(nonnull TKRVerificationMethodsHandler)handler;

The Tanker status must be either IDENTITY_VERIFICATION_NEEDED or READY.

@NotNull
public TankerFuture<List<VerificationMethod>> getVerificationMethods()
Returns
Promise<Array<VerificationMethod>> The list of VerificationMethods already set
Throws Description
PreconditionFailed The status is neither IDENTITY_VERIFICATION_NEEDED nor READY
NetworkError Network error, e.g. connection lost or the Tanker server is not reachable
Handler return value Description
methods A non-null array of verification methods
Errors Description
TKRErrorPreconditionFailed The status is neither TKRStatusIdentityVerificationNeeded nor TKRStatusReady
Returns
TankerFuture<List<VerificationMethod>> The list of VerificationMethods already set
Errors Description
PRECONDITION_FAILED The status is neither IDENTITY_VERIFICATION_NEEDED nor READY

generateVerificationKey

Generates a verification key, registers its public part on Tanker's servers, and returns its private part, which is required to verify the user's identity.

The Tanker status must be IDENTITY_REGISTRATION_NEEDED.

function generateVerificationKey(): Promise<string>

The Tanker status must be TKRStatusIdentityRegistrationNeeded.

typedef void (^TKRVerificationKeyHandler)(TKRVerificationKey* _Nullable key,
                                          NSError* _Nullable err);

- (void)generateVerificationKeyWithCompletionHandler:(nonnull TKRVerificationKeyHandler)handler;

The Tanker status must be IDENTITY_REGISTRATION_NEEDED.

@NotNull
public TankerFuture<String> generateVerificationKey()

Once the verification key has been generated, it is not possible to set up high-level verification methods (e.g. email/passphrase).

The opposite is also true: no high-level verification method must have been set up before calling this function.

It is NOT possible to generate several verification keys.

Warning

This is a low level function for specific use-cases only, as it can have severe security implications. Use it only if high-level identity verification doesn't fit your needs, and you fully understand how it works. Don't hesitate to contact us for help.

Returns
Promise<string> The generated verification key
Throws Description
PreconditionFailed The status is not IDENTITY_REGISTRATION_NEEDED
NetworkError Network error, e.g. connection lost or the Tanker server is not reachable
Returns
TankerFuture<String> The generated verification key
Errors Description
PRECONDITION_FAILED The session is not in the IDENTITY_REGISTRATION_NEEDED state
Handler return value Description
TKRVerificationKey* The verification key's private part
Errors Description
TKRErrorPreconditionFailed The status is not TKRStatusIdentityRegistrationNeeded

Device management

deviceId

A property containing the current device's ID.

The Tanker status must be READY.

get deviceId(): b64string;
Contains
b64string The current device's ID
Throws Description
PreconditionFailed The status is not READY

Retrieves the current device's ID.

The Tanker status must be TKRStatusReady.

typedef void (^TKRDeviceIDHandler)(NSString* _Nullable deviceID,
                                   NSError* _Nullable err);

- (void)deviceIDWithCompletionHandler:(nonnull TKRDeviceIDHandler)handler;
Handler return value Description
NSString* The device ID
Errors Description
TKRErrorPreconditionFailed The status is not TKRStatusReady

Retrieves the current device's ID.

@NotNull
public TankerFuture<String> getDeviceId()

Each device has its own ID and can be identified as such.

Returns
TankerFuture<String> Resolves with the current device's ID
Errors Description
PRECONDITION_FAILED The status is not READY

getDeviceList

Retrieves the user's devices list.

The Tanker status must be READY.

function getDeviceList(): Promise<Array<Device>>

Warning

Not implemented yet for iOS.

The Tanker status must be READY.

@NotNull
public TankerFuture<List<DeviceInfo>> getDeviceList()
Returns
Promise<Array<Device>> An array of devices

Each Device is an object describing a device, with the following properties:

Fields Description
id: b64string The device ID of the device
isRevoked: boolean true if the device has been revoked
Throws Description
PreconditionFailed The status is not READY
NetworkError Network error, e.g. connection lost or the Tanker server is not reachable
Returns
TankerFuture<List<DeviceInfo>> The list of devices

Each DeviceInfo is an object describing a device, with the following methods:

Method Description
String getDeviceId() The device ID of the device
Boolean isRevoked() true if the device has been revoked
Errors Description
PRECONDITION_FAILED The status is not READY

revokeDevice

Revokes one of the user's devices.

The Tanker status must be READY.

function revokeDevice(deviceId: b64string): Promise<void>
@NotNull
public TankerFuture<Unit> revokeDevice(@NotNull String deviceId)

The status must be TKRStatusReady.

- (void)revokeDevice:(nonnull NSString*)deviceId
   completionHandler:(nonnull TKRErrorHandler)handler;
Parameters
deviceId: b64string The device ID of the device to be revoked
Throws Description
InvalidArgument The device ID is not one of the users'
PreconditionFailed The status is not READY
NetworkError Network error, e.g. connection lost or the Tanker server is not reachable
Parameters
deviceId: NSString The device ID of the device to revoke
Errors Description
TKRErrorPreconditionFailed The status is not TKRStatusReady
TKRErrorInvalidArgument The device ID is not one of the users'
Parameters
deviceId: String The device ID of the device to be revoked
Returns
TankerFuture<Unit> Resolves when the revocation operation completes
Errors Description
PRECONDITION_FAILED The status is not READY
INVALID_ARGUMENT The specified device was not found
INVALID_ARGUMENT Cannot revoke another user's device

Encryption methods

Encryption

encrypt

Encrypts a string and returns the result as an ArrayBuffer, Buffer, Blob, File or Uint8Array (default). The resulting encrypted resource will be shared with either or both individual users and groups specified in the EncryptionOptions.

The Tanker status must be READY.

type Data = ArrayBuffer | Buffer | Blob | File | Uint8Array;

function encrypt(clearText: string, options?: EncryptionOptions): Promise<Data>

Note

The clearText string is UTF-8 encoded prior to encryption.

Parameters
clearText: string The clear text to be encrypted
options?: EncryptionOptions Encryption and sharing options (optional)
Returns
Promise<Uint8Array> The encrypted data
Throws Description
InvalidArgument Some recipients (groups or users) have not been found
PreconditionFailed The status is not READY
NetworkError Network error, e.g. connection lost or the Tanker server is not reachable

encryptData

Encrypts raw bytes passed as an ArrayBuffer, Buffer, Blob, File or Uint8Array and returns the resulting encrypted resource in the same format as the input by default. Additional output options are available in EncryptionOptions.

The Tanker status must be READY.

type Data = ArrayBuffer | Buffer | Blob | File | Uint8Array;

function encryptData(clearData: Data, options?: EncryptionOptions): Promise<Data>

The resource will be shared with either or both individual users and groups specified in the EncryptionOptions.

Parameters
(Browsers) clearData: Data The clear data to encrypt as an ArrayBuffer, Blob, File or Uint8Array
(Node.js) clearData: Data The clear data to encrypt as an ArrayBuffer, Buffer or Uint8Array
options?: EncryptionOptions Encryption and sharing options (optional)
Returns
Promise<Data> The encrypted data in the specified type format, or in the same format as the input otherwise
Throws Description
InvalidArgument Some recipients (groups or users) have not been found
PreconditionFailed The status is not READY
NetworkError Network error, e.g. connection lost or the Tanker server is not reachable

encryptString

typedef void (^TKREncryptedDataHandler)(NSData* _Nullable encryptedData,
                                        NSError* _Nullable err);

- (void)encryptString:(nonnull NSString*)clearText
    completionHandler:(nonnull TKREncryptedDataHandler)handler;

- (void)encryptString:(nonnull NSString*)clearText
              options:(nonnull TKREncryptionOptions*)encryptionOptions
    completionHandler:(nonnull TKREncryptedDataHandler)handler;

Encrypts and shares a string.

The resulting encrypted resource will be shared with users and groups specified in the TKREncryptionOptions.

Note

The clearText string is UTF-8 encoded prior to encryption.

Parameters
clearText: NSString* The clear string to be encrypted
options: TKREncryptionOptions* Encryption options (optional)
Errors Description
TKRErrorInvalidArgument One of the provided user public identities or group IDs is invalid
TKRErrorPreconditionFailed The status is not TKRStatusReady

encryptData

- (void)encryptData:(nonnull NSData*)clearData
  completionHandler:(nonnull TKREncryptedDataHandler)handler;

- (void)encryptData:(nonnull NSData*)clearData
            options:(nonnull TKREncryptionOptions*)encryptionOptions
  completionHandler:(nonnull TKREncryptedDataHandler)handler;

Encrypts and shares binary data.

The resulting encrypted resource will be shared with users and groups specified in the TKREncryptionOptions.

Parameters
clearData: NSData* The clear data to be encrypted
options: TKREncryptionOptions* Encryption options (optional)
Errors Description
TKRErrorInvalidArgument Some of the provided user public identities or group IDs are invalid
TKRErrorPreconditionFailed The status is not TKRStatusReady

encryptStream

typedef void (^TKRInputStreamHandler)(NSInputStream* _Nullable stream,
                                      NSError* _Nullable err);

- (void)encryptStream:(nonnull NSInputStream*)clearStream
    completionHandler:(nonnull TKRInputStreamHandler)handler;

- (void)encryptStream:(nonnull NSInputStream*)clearStream
              options:(nonnull TKREncryptionOptions*)encryptionOptions
    completionHandler:(nonnull TKRInputStreamHandler)handler;

Creates an encryption stream wrapping clearStream.

The resource produced by the stream will be shared with either or both individual users and groups specified using the TKREncryptionOptions.

Warning

After calling this function, clearStream must not be used!

Parameters
clearStream: NSInputStream* The stream containing data to encrypt
options: TKREncryptionOptions* Encryption options (optional)
Errors Description
TKRErrorInvalidArgument One of the provided user public identities or group IDs is invalid
TKRErrorInvalidArgument clearStream status is not NSStreamStatusNotOpen
TKRErrorPreconditionFailed The status is not TKRStatusReady

encrypt

@NotNull
public TankerFuture<byte[]> encrypt(
  @NotNull byte[] data,
  @Nullable EncryptOptions encryptionOptions
)

Encrypts a byte[] of raw data and returns the result in a future. The resulting encrypted resource will be shared with either or both individual users and groups specified using the EncryptOptions.

Parameters
data: byte[] The clear data to be encrypted. Can be either a java byte[] or a Kotlin ByteArray.
options: EncryptOptions Encryption and sharing options (optional)
Returns
TankerFuture<byte[]> The encrypted data
Errors Description
INVALID_ARGUMENT A recipient (user or group) was not found
PRECONDITION_FAILED The status is not READY

encrypt (channels)

@NotNull
public TankerFuture<TankerAsynchronousByteChannel> encrypt(
  @NotNull TankerAsynchronousByteChannel clearChannel,
  @Nullable EncryptOptions encryptionOptions
)

Constructs an encryption channel wrapping clearChannel, and returns it in a future.

The resource produced by the channel will be shared with either or both individual users and groups specified using the EncryptOptions.

Warning

After calling this function, clearChannel must not be used!

Parameters
clearChannel: TankerAsynchronousByteChannel The channel to be encrypted
options: EncryptOptions Encryption and sharing options (optional)
Returns
TankerFuture The encryption channel
Errors Description
INVALID_ARGUMENT A recipient (user or group) was not found
PRECONDITION_FAILED The status is not READY

EncryptionOptions

The shareWithUsers and shareWithGroups options allow you to specify who will be able to decrypt the resource. If none is provided, only the resource creator will be able to decrypt it.

In general, if you need to share a resource with multiple users, it is advised to create groups and use shareWithGroups.

Fields Default Description
shareWithUsers: Array<string> [] User PublicTankerIdentities to share with (the current user's identity will be automatically appended)
shareWithGroups: Array<string> [] Group IDs to share with

Additional options are available to define the output of encryption methods:

Fields Default Description
(Browsers) type: Class (same class as input) Output format among ArrayBuffer, Blob, File and Uint8Array
(Node.js) type: Class (same class as input) Output format among ArrayBuffer, Buffer and Uint8Array
mime: string application/octet-stream Output MIME type (Blob & File types only)
name: string '' Output file name (File type only)
onProgress: Function (none) A handler function to track progress. It will be called several times with a single argument in the following format: { currentBytes: number, totalBytes: number }

EncryptOptions

The EncryptOptions allows you to specify who will be able to decrypt the resource through the shareWithUsers() and shareWithGroups() methods.

If neither are specified, only the resource creator will be able to decrypt it.

In general, if you need to share a resource with multiple users, it is advised to create groups and use shareWithGroups().

Method Default value Description
shareWithUsers(String[] publicIdentities) new String[]{} User public identities to share with (the current user's identity will be automatically appended)
shareWithGroups(String[] groupIDs) new String[]{} Group IDs to share with

TKREncryptionOptions

The TKREncryptionOptions allows you to specify who will be able to decrypt the resource through the shareWithUsers and shareWithGroups properties.

If neither are specified, only the resource creator will be able to decrypt it.

In general, if you need to share a resource with multiple users, it is advised to create groups and use shareWithGroups.

Fields Default value Description
shareWithUsers: NSArray<NSString*>* @[] User public identities to share with (the current user is automatically included)
shareWithGroups: NSArray<NSString*>* @[] Group IDs to share with

Decryption

decrypt

type Data = ArrayBuffer | Buffer | Blob | File | Uint8Array;

function decrypt(encryptedData: Data, options?: DecryptionOptions): Promise<string>

Decrypts a resource passed as an ArrayBuffer, Buffer, Blob, File or Uint8Array, decodes it from UTF-8 to a DOM string, and returns it.

Parameters
encryptedData: Uint8Array The encrypted data to be decrypted
options?: DecryptionOptions Decryption options: only onProgress is available (optional)
Returns
Promise<string> The decrypted string
Throws Description
DecryptionFailed The encrypted data is either corrupted or the current user has no right to decrypt it
PreconditionFailed The status is not READY
NetworkError Network error, e.g. connection lost or the Tanker server is not reachable, and the key is not locally available

decryptStringFromData

Decrypts an encrypted resource and UTF-8 decodes the result into a string.

The Tanker status must be TKRStatusReady.

typedef void (^TKRDecryptedStringHandler)(NSString* _Nullable decryptedString,
                                          NSError* _Nullable err);

- (void)decryptStringFromData:(nonnull NSData*)encryptedData
            completionHandler:(nonnull TKRDecryptedStringHandler)handler;
Parameters Description
encryptedData: NSData* The data to decrypt
Errors Description
TKRErrorDecryptionFailed The data could not be decrypted
TKRErrorPreconditionFailed The status is not TKRStatusReady

decryptData

Decrypts an encrypted resource into binary data.

The Tanker status must be TKRStatusReady.

typedef void (^TKRDecryptedDataHandler)(NSData* _Nullable decryptedData,
                                        NSError* _Nullable err);

- (void)decryptData:(nonnull NSData*)encryptedData
  completionHandler:(nonnull TKRDecryptedDataHandler)handler;

Decrypts a resource and returns the original raw bytes.

Parameters Description
encryptedData: NSData* The data to decrypt
Errors Description
TKRErrorDecryptionFailed The data could not be decrypted
TKRErrorPreconditionFailed The status is not TKRStatusReady

decryptStream

- (void)decryptStream:(nonnull NSInputStream*)encryptedStream
    completionHandler:(nonnull TKRInputStreamHandler)handler;

Creates a decryption stream wrapping encryptedStream.

Note

encryptedStream's content must have been encrypted by an encryption stream

Warning

After calling this function, encryptedStream must not be used!

Parameters
encryptedStream: NSInputStream* The stream containing data to decrypt
Errors Description
TKRErrorInvalidArgument encryptedStream status is not NSStreamStatusNotOpen
TKRErrorPreconditionFailed The status is not TKRStatusReady
TKRErrorDecryptionFailed The encrypted data is corrupted

decrypt

@NotNull
public TankerFuture<byte[]> decrypt(@NotNull byte[] data)

Decrypts a resource and returns the original clear data.

Parameters
data: byte[] The encrypted data to be decrypted
Returns
TankerFuture<byte[]> The decrypted data
Errors Description
PRECONDITION_FAILED The status is not READY
DECRYPTION_FAILED The encrypted data is corrupted

decrypt (channels)

@NotNull
public TankerFuture<TankerAsynchronousByteChannel> decrypt(
  @NotNull TankerAsynchronousByteChannel encryptedChannel
)

Constructs a decryption channel wrapping encryptedChannel, and returns it in a future.

Note

encryptedChannel's content must have been encrypted by an encryption channel

Warning

After calling this function, encryptedChannel must not be used!

Parameters
encryptedChannel: TankerAsynchronousByteChannel The channel containing data to decrypt
Returns
TankerFuture<TankerAsynchronousByteChannel> The decryption channel
Errors Description
PRECONDITION_FAILED The status is not READY
DECRYPTION_FAILED The encrypted data is corrupted

decryptData

type Data = Uint8Array | ArrayBuffer | Buffer | Blob | File;

function decryptData(encryptedData: Data, options?: DecryptionOptions): Promise<Data>

Decrypts a resource passed as an ArrayBuffer, Buffer, Blob, File or Uint8Array and returns the original raw bytes resource in the same format as the input by default. Additional output options are available in DecryptionOptions.

Parameters
(Browsers) encryptedData: Data The encrypted data to decrypt as an ArrayBuffer, Blob, File or Uint8Array
(Node.js) encryptedData: Data The encrypted data to decrypt as an ArrayBuffer, Buffer or Uint8Array
options?: DecryptionOptions Decryption options (optional)
Returns
Promise<Data> The decrypted data in the specified type format, or in the same format as the input otherwise
Throws Description
DecryptionFailed The encrypted data is either corrupted or the current user has no right to decrypt it
PreconditionFailed The status is not READY
NetworkError Network error, e.g. connection lost or the Tanker server is not reachable, and the key is not locally available

DecryptionOptions

In the context of a decryptData() call only, the following options are available:

Fields Default Description
(Browsers) type: Class (same class as input) Output format among ArrayBuffer, Blob and File
(Node.js) type: Class (same class as input) Output format among ArrayBuffer, Buffer and Uint8Array
mime: string application/octet-stream Output MIME type (Blob & File types only)
name: string '' Output file name (File type only)
onProgress: Function (none) A handler function to track progress. It will be called several times with a single argument in the following format: { currentBytes: number, totalBytes: number }

Group methods

Creating a Group

Creates a group with users' public identities, and returns its ID.

The Tanker status must be READY.

function createGroup(publicIdentities: Array<string>): Promise<b64string>
@NotNull
public TankerFuture<String> createGroup(@NotNull String[] publicIdentities)

The Tanker status must be TKRStatusReady.

typedef void (^TKRGroupIDHandler)(NSString* _Nullable groupID,
                                  NSError* _Nullable err);

- (void)createGroupWithPublicIdentities:(nonnull NSArray<NSString*>*)publicIdentities
                      completionHandler:(nonnull TKRGroupIDHandler)handler;

Note

The maximum number of users per group is 1000.

Parameters
publicIdentities: Array<string> Group members' public identities
Returns
Promise<b64string> The newly created group's ID
Throws Description
InvalidArgument Some recipients (groups or users) have not been found. The whole operation is canceled.
PreconditionFailed The status is not READY
NetworkError Network error, e.g. connection lost or the Tanker server is not reachable
Parameters
publicIdentities: Array<String> Group members' public identities
Returns
TankerFuture<String> A future of the newly created group's ID
Errors Description
INVALID_ARGUMENT Some recipients (groups or users) have not been found. The whole operation is canceled.
PRECONDITION_FAILED The status is not READY
Parameters Description
publicIdentities: NSArray<NSString*>* The users' public identities to add to the new group
Errors Description
TKRErrorInvalidArgument One of the public identities is invalid
TKRErrorPreconditionFailed The status is not TKRStatusReady

Updating a group

Add members to an existing group.

The Tanker status must be READY.

function updateGroupMembers(groupId: string, { usersToAdd: Array<string> }): Promise<void>;
@NotNull
public TankerFuture<Unit> updateGroupMembers(@NotNull String groupId, @NotNull String[] usersToAdd)
- (void)updateMembersOfGroup:(nonnull NSString*)groupId
                  usersToAdd:(nonnull NSArray<NSString*>*)users
           completionHandler:(nonnull TKRErrorHandler)handler;

The new group members will automatically get access to all resources previously shared with the group.

Parameters
groupId: string Group ID to modify
usersToAdd: Array<string> Public identities of users to add to the group
Returns
Promise The promise is fulfilled once the operation is done
Throws Description
InvalidArgument Some recipients (groups or users) have not been found. The whole operation is canceled.
PreconditionFailed The status is not READY
NetworkError Network error, e.g. connection lost or the Tanker server is not reachable
Parameters Description
groupId: NSString* The ID of the group to update
usersToAdd: NSArray<NSString*>* The user identities to add to the group
Errors Description
TKRErrorInvalidArgument One of the arguments is ill-formed
TKRErrorPreconditionFailed The status is not TKRStatusReady
Parameters
groupId: string Group ID to modify
usersToAdd: Array<String> Public identities of users to add to the group
Returns
TankerFuture<Unit> A future that resolves when the operation completes
Errors Description
INVALID_ARGUMENT One of the arguments is ill-formed
PRECONDITION_FAILED The status is not READY

Sharing methods

Sharing a resource is usually done during encryption, using the encryption options.

The share function below should only be used in the following circumstances:

  • If a resource is already shared with a group, and you want to share it with an additional group
  • If a resource is already shared with a group, and you want to share it with an additional user without adding them to the group
  • If for some reason you're not using groups and want to add another individual user to the list of recipients

In most cases, adding members to a group with updateGroupMembers() will be the prefered way to go.

getResourceId

Retrieves an encrypted resource's ID.

type Data = Uint8Array | ArrayBuffer | Buffer | Blob | File;

function getResourceId(encryptedData: Data): Promise<b64string>
- (nullable NSString*)resourceIDOfEncryptedData:(nonnull NSData*)encryptedData
                                          error:(NSError* _Nullable* _Nonnull)error;
@NotNull
public String getResourceID(@NotNull byte[] encryptedData)

The resource ID can then be used to call share.

Note

This function does not have any requirement on Tanker's status.

Parameters
(Browsers) encryptedData: Data The encrypted resource of which you want the ID as an ArrayBuffer, Blob, File or Uint8Array
(Node.js) encryptedData: Data The encrypted resource of which you want the ID as an ArrayBuffer, Buffer or Uint8Array
Returns
Promise<b64string> The ID of the given encrypted resource
Throws Description
InvalidArgument The argument is an invalid resource
PreconditionFailed The status is not READY
Parameters Description
encryptedData: NSData* The resource from which to retrieve the ID
error: NSError** Will be set if an error occurs
Returns Description
NSString* The ID of the resource, or nil if an error occurs
Errors Description
TKRErrorInvalidArgument The argument is an invalid resource
Parameters
encryptedData: byte[] The encrypted resource from which you want the ID
Returns
String The ID of the given encrypted resource
Errors Description
INVALID_ARGUMENT The argument is an invalid resource

share

Shares resources with users and groups.

The Tanker status must be READY.

type SharingOptions = { shareWithUsers?: Array<string>, shareWithGroups?: Array<string> };

function share(resourceIds: Array<b64string>, options: SharingOptions): Promise<void>

The status must be TKRStatusReady.

- (void)shareResourceIDs:(nonnull NSArray<NSString*>*)resourceIDs
                 options:(nonnull TKRShareOptions*)shareOptions
       completionHandler:(nonnull TKRErrorHandler)handler;
@NotNull
public TankerFuture<Unit> share(
  @NotNull String[] resourceIDs,
  @NotNull ShareOptions shareOptions
)

This function either fully succeeds or fails. In this case, it does not share with any recipient.

Parameters
resourceIds: Array<b64string> Resource IDs to share
options: SharingOptions Object defining the recipients of the sharing operation
Returns
Promise The promise is fulfilled once the operation is done
Throws Description
PreconditionFailed The status is not READY
InvalidArgument Some recipients (groups or users) have not been found
InvalidArgument Some resource IDs have not been found
NetworkError Network error, e.g. connection lost or the Tanker server is not reachable
Parameters Description
resourceIDs: NSArray<NSString*>* Resource IDs to share
options: TKRShareOptions* Sharing options
Errors Description
TKRErrorPreconditionFailed The status is not TKRStatusReady
TKRErrorInvalidArgument Some recipients (groups or users) have not been found
TKRErrorInvalidArgument Some resource IDs have not been found
Parameters
resourceIds: Array<String> Resource IDs to share
options: ShareOptions Sharing options
Returns
TankerFuture<Unit> A future that resolves when the data has been shared
Errors Description
PRECONDITION_FAILED The status is not READY
INVALID_ARGUMENT Some recipients (groups or users) have not been found
INVALID_ARGUMENT Some resource IDs have not been found

SharingOptions

The shareWithUsers and shareWithGroups options allow you to specify who will be able to decrypt the resource.

In general, if you need to share a resource with multiple users, it is advised to create groups and use shareWithGroups.

Fields Default Description
shareWithUsers: Array<string> [] Public tanker identities of users to share with (the current user's identity will be automatically appended)
shareWithGroups: Array<string> [] Group IDs to share with

ShareOptions

The ShareOptions class allows you to specify who will be able to decrypt the resource through the shareWithUsers() and shareWithGroups() methods.

In general, if you need to share a resource with multiple users, it is advised to create groups and use shareWithGroups().

Method Default value Description
shareWithUsers(String[] publicIdentities) new String[]{} Public tanker identities of users to share with (the current user's identity will be automatically appended)
shareWithGroups(String[] groupIDs) new String[]{} Group IDs to share with

TKRShareOptions

The TKRShareOptions allows you to specify who will be able to decrypt the resource through the shareWithUsers and shareWithGroups properties.

In general, if you need to share a resource with multiple users, it is advised to create groups and use shareWithGroups.

Fields Default value Description
shareWithUsers: NSArray<NSString*>* @[] Public tanker identities of users to share with (the current user's identity will be automatically appended)
shareWithGroups: NSArray<NSString*>* @[] Group IDs to share with

Pre-registration sharing

attachProvisionalIdentity

Attaches a provisional identity to the user.

The Tanker status must be READY.

function attachProvisionalIdentity(provisionalIdentity: string): Promise<AttachResult>

The Tanker status must be TKRStatusReady.

typedef void (^TKRAttachResultHandler)(TKRAttachResult* _Nullable result,
                                       NSError* _Nullable err);

- (void)attachProvisionalIdentity:(nonnull NSString*)provisionalIdentity
                completionHandler:(nonnull TKRAttachResultHandler)handler;
@NotNull
public TankerFuture<AttachResult> attachProvisionalIdentity(@NotNull String provisionalIdentity)

Depending on the result, verifying the provisional identity with verifyProvisionalIdentity might be necessary.

Parameters
provisionalIdentity: string A provisional identity
Returns
Promise<AttachResult> An AttachResult
Throws Description
InvalidArgument The provided provisional identity is invalid
PreconditionFailed The status is not READY
NetworkError Network error, e.g. connection lost or the Tanker server is not reachable
Parameters Description
provisionalIdentity: NSString* A provisional identity
Errors Description
TKRErrorInvalidArgument The provisional identity is invalid
TKRErrorPreconditionFailed The status is not TKRStatusReady
Parameters
provisionalIdentity: String A provisional identity
Returns
TankerFuture<AttachResult> An AttachResult
Errors Description
INVALID_ARGUMENT The provided provisional identity is invalid
PRECONDITION_FAILED The status is not READY

AttachResult

The attachProvisionalIdentity function returns a type with the following properties:

Field Description
status: Status The provisional identity's status. Either READY or IDENTITY_VERIFICATION_NEEDED
verificationMethod: VerificationMethod A verification method containing the email matching the created provisional identity
Property Description
status: TKRStatus The provisional identity's status. Either TKRStatusReady or TKRStatusIdentityVerificationNeeded
method: TKRVerificationMethod* A verification method containing the email matching the created provisional identity
Method Description
Status getStatus() The provisional identity's status. Either READY or IDENTITY_VERIFICATION_NEEDED
VerificationMethod getMethod() A verification method containing the email matching the created provisional identity

verifyProvisionalIdentity

Verifies an attached provisional identity.

To be called when the status returned by attachProvisionalIdentity is IDENTITY_VERIFICATION_NEEDED.

function verifyProvisionalIdentity(verification: Verification): Promise<void>

To be called when the status returned by attachProvisionalIdentity is TKRStatusIdentityVerificationNeeded.

- (void)verifyProvisionalIdentityWithVerification:(nonnull TKRVerification*)verification
                                completionHandler:(nonnull TKRErrorHandler)handler;
@NotNull
public TankerFuture<Unit> verifyProvisionalIdentity(@NotNull Verification verification)

Once the provisional identity is verified, every resource shared with it can now be decrypted by the user, who also joins every group in which the provisional identity was a member.

Parameters
verification: Verification A verification containing the provisional identity's email, and the verification code
Returns
Promise The promise is fulfilled once the verification is done
Throws
InvalidArgument The verification is ill-formed or incomplete
PreconditionFailed The status of the current session is not READY
PreconditionFailed The status of the attach result is not IDENTITY_VERIFICATION_NEEDED
ExpiredVerification The verification expired
InvalidVerification The verification is invalid
TooManyAttempts Too many verification attempts occurred. Please retry later.
NetworkError Network error, e.g. connection lost or the Tanker server is not reachable
Parameters Description
verification: TKRVerification* A verification containing the provisional identity's email, and the verification code
Errors Description
TKRErrorPreconditionFailed The status of the current session is not TKRStatusReady
TKRErrorPreconditionFailed The status of the attach result is not TKRStatusIdentityVerificationNeeded
TKRErrorExpiredVerification The verification expired
TKRErrorInvalidVerification The verification is invalid
TKRErrorTooManyAttempts Too many verification attempts occurred. Please retry later.
Parameters
verification: Verification A verification containing the provisional identity's email, and the verification code
Returns
TankerFuture<Unit> A future that resolves when the verification is done
Errors
PRECONDITION_FAILED The status of the current session is not READY
PRECONDITION_FAILED The status of the attach result is not IDENTITY_VERIFICATION_NEEDED
EXPIRED_VERIFICATION The verification expired
INVALID_VERIFICATION The verification is invalid
TOO_MANY_ATTEMPTS Too many verification attempts occurred. Please retry later.

File uploading and downloading

The methods below allow you to upload and download files. These files are encrypted before the upload and decrypted after the download.

Upload

Encrypt and upload a file.

type FileId = string;
type Data = ArrayBuffer | Buffer | Blob | File | Uint8Array;

function upload(clearData: Data, options?: EncryptionOptions): Promise<FileId>
Parameters Description
clearData: Data The data of the file to upload
options: EncryptionOptions Encryption and sharing options. See the related section.
Returns
Promise The fileId of the uploaded file
Throws Description
InvalidArgument Some recipients have not been found, or clearData is not a valid input
PreconditionFailed Tanker session has not been started
NetworkError Network error, e.g. connection lost or the Tanker server is not reachable

Not implemented yet in Android.

Not implemented yet in iOS.

Download

Download and decrypt a file.

function download(fileId: FileId, options?: DecryptionOptions): Promise<Data>
Parameters Description
fileId: string The fileId of the file to download
options?: DecryptionOptions Decryption options (optional)
Returns
Promise<Data> The decrypted data in the specified type format, or in the File format by default
Throws Description
InvalidArgument The fileId provided does not match with any file uploaded with Tanker
PreconditionFailed Tanker session has not been started
NetworkError Network error, e.g. connection lost or the Tanker server is not reachable

Events

Tanker uses EventEmitter to emit events.

You can subscribe to events using on and unsubscribe using removeListener. Please refer to the EventEmitter documentation for more information.

Tanker defines a set of functions and callback handlers to handle events. Call connect${eventName}Handler() with your callback to subscribe to the event. Event registration is asynchronous.

Tanker defines a set of functions and callback handlers to handle events. Call connect${eventName}Handler() with your callback to subscribe to the event.

You can unsubscribe from the event by calling disconnectHandler with your callback.

TankerDeviceRevokedHandler handler = () -> {
    // Handle event
};
TankerConnection connection = tanker.connectHandler(handler);

//...

tanker.disconnectHandler(handler);

statusChange

Emitted when the session status changes. The event takes the new status as a parameter.

tanker.on('statusChange', newStatus => console.log(`Tanker status has changed: ${newStatus}`));

Warning

Not implemented yet for iOS.

Warning

Not implemented yet for Android.

deviceRevoked

Emitted when the current device has been revoked. The revocation can be initiated on any device the user has registered, including the current device.

tanker.on('deviceRevoked', () => console.log('One of my devices has been revoked'));
[tanker connectDeviceRevokedHandler:^{ NSLog(@"Current device has been revoked."); }];
@NotNull
public TankerConnection connectDeviceRevokedHandler(@NotNull TankerDeviceRevokedHandler eventHandler)