It is possible to verify a user's identity by setting up and providing a passphrase.

This can be a user-chosen password, a randomly-generated passphrase or even the answer to a security question. Just be sure not to store the passphrase anywhere as it would compromise the user's account security.

Setting up a verification passphrase

Setting up a passphrase is done by using the registerIdentity() method with the passphrase argument.

if (status == Status.IDENTITY_REGISTRATION_NEEDED) {
  // Get the user to input their security passphrase
  String passphrase = passphraseInput();

  // Register the identity with the passphrase as a verification method
  tanker.registerIdentity(new PassphraseVerification(passphrase)).get();
}

if (status == TKRStatusIdentityRegistrationNeeded) {

  // Get the user to input his security passphrase
  NSString* passphrase = [self.app promptUser:@"Enter your passphrase:"];

  // Convert the passphrase into a TKRVerification.
  TKRVerification* verification = [TKRVerification verificationFromPassphrase:passphrase];
  // Register the passphrase as the current identity verification method.
  [self.tanker registerIdentityWithVerification:verification
                              completionHandler:^(NSError* err) {
                                if (err == nil) {
                                  // do something
                                }
                          }];
}

if (status === Tanker.statuses.IDENTITY_REGISTRATION_NEEDED) {
  // Get the user to input their security passphrase
  const passphrase = await app.promptUser('Enter your passphrase:');

  // Register the identity with the passphrase as a verification method
  await tanker.registerIdentity({ passphrase });
}

if status == Tanker::Status::IDENTITY_REGISTRATION_NEEDED
  # Get the user to input their security passphrase
  passphrase = app.prompt_user('Enter your passphrase:')

  # Register the identity with the passphrase as a verification method
  tanker.register_identity(Tanker::PassphraseVerification.new(passphrase))
end

Verifying the identity with the passphrase

To later verify the user's identity using their passphrase, ask the user to input it and pass it to verifyIdentity() after starting the session:

if (status == Status.IDENTITY_VERIFICATION_NEEDED) {
  // Wait for the user to input their passphrase
  String passphrase = passphraseInput();

  // Verify the identity
  tanker.verifyIdentity(new PassphraseVerification(passphrase)).get();
}

if (status == TKRStatusIdentityVerificationNeeded) {
  // Wait for the user to input their passphrase
  NSString* passphrase = [self.app promptUser:@"Enter your passphrase:"];

  // Convert the passphrase into a TKRVerification.
  TKRVerification* verification = [TKRVerification verificationFromPassphrase:passphrase];
  // Verify the identity
  [self.tanker verifyIdentityWithVerification:verification
                            completionHandler:^(NSError* err) {
                              if (err == nil) {
                                // do something
                              }
                        }];
}

if (status === Tanker.statuses.IDENTITY_VERIFICATION_NEEDED) {
  // Wait for the user to input their passphrase
  const passphrase = await app.promptUser('Enter your passphrase:');

  // Verify the identity
  await tanker.verifyIdentity({ passphrase });
}

if status == Tanker::Status::IDENTITY_VERIFICATION_NEEDED
  # Wait for the user to input their passphrase
  passphrase = app.prompt_user('Enter your passphrase:')

  # Verify the identity
  tanker.verify_identity(Tanker::PassphraseVerification.new(passphrase))
end

To change a user's passphrase, just call setVerificationMethod() with the new passphrase.

Note

The Tanker SDK takes care of hashing the passphrase client-side before sending it to the Tanker servers. Server-side, it is then hashed again and salted.

Recovering a lost passphrase

It is not possible to recover a lost passphrase.

However, in case a user forgot their passphrase, you can use any other verification method to verify their identity and then have them update their passphrase.

Using the application password as a passphrase

To avoid a situation in which users have to remember an additional password, you might want to use their application password as the security passphrase.

Warning

Please note that this is not the recommended way of handling identity verification, as it has security implications.

If you still want to do this, you must make sure that you hash the user's application password client-side before sending it to your application servers. The prehashed password must then be hashed again server-side before storage or comparison, using a well-known password hash algorithm (e.g. Argon2i or scrypt). This is very important because anyone (including you) having access to this password in plain text could be able to decrypt any resources shared with the corresponding user.

We provide a prehashPassword function to hash the application password client side before sending it to your application's servers.

app.login(email, Tanker.prehashPassword(password));
// Tanker hashes the passphrase internally, do not call prehashPassword here
tanker.setVerificationMethod(new PassphraseVerification(password)).get();

app.Login(email, core.PrehashPassword(password))
// Tanker hashes the passphrase internally, do not call PrehashPassword here
tanker.SetVerificationMethod(core.PassphraseVerification{password})

NSString* prehashedPassword = [TKRTanker prehashPassword:password];
[self.app loginWithEmail:email password:prehashedPassword];
// Tanker hashes the passphrase internally, do not call prehashPassword here
TKRVerification* verification = [TKRVerification verificationFromPassphrase:password];
[self.tanker setVerificationMethod:verification completionHandler:completion];

const prehashedPassword = await prehashPassword(password);
await app.login(email, prehashedPassword);
// Tanker hashes the passphrase internally, do not call prehashPassword here
await tanker.setVerificationMethod({ passphrase: password });

prehashed_password = Tanker::Core.prehash_password password
app.login(email, prehashed_password)

# Tanker hashes the passphrase internally, do not call prehash_password here
tanker.set_verification_method(Tanker::PassphraseVerification.new(password))