User Authentication

This guide shows how to manage your application user and their Virgil Card, which is associated with a user or device, using Virgil E3Kit.

Be sure to implement the following:

• JWT generation on your server side
• Set up your client side with E3Kit

User registration on the Virgil Cloud consists of the following steps:

1. Developers initialize the client-side SDK (Virgil E3Kit) with the JWT, which is generated on the server side
2. Users use the E3Kit to generate private keys and store them on their devices
3. Users use the E3Kit to create and publish a Virgil Card with the corresponding public key on the Virgil Cloud

The eThree.register function checks whether a user already has a private key saved in local storage, and a published public key on the Virgil Cloud. If the user doesn't have them, the function generates a new keypair for the user, saves the private key locally, and publishes the public key on the Virgil Cloud (for other users to reference). There is no need to use the eThree.register method on the Sign In flow.

Use the eThree.register method during the Sign Up flow in your application:

OnCompleteListener registerListener = new OnCompleteListener() {
    @Override public void onSuccess() {
        // User private key loaded, ready for end-to-end encrypt!
    }

    @Override public void onError(@NotNull final Throwable throwable) {
        // Error handling
    }
};

// Generates new keypair for the user. Saves private key to the device and publishes public key to the Virgil's cloud.
eThree.register().addCallback(registerListener);

When you use the E3Kit to delete a user's Card, you don't fully delete it from the Virgil Cloud, you only deactivate (revoke) the card by updating (replacing) an active Virgil Card with a new one that has an empty public key. A user's Card that is going to be deleted should have the same identity which is used to generate a JWT. All deactivated Cards will still be visible and available to application users while searching the Card by its ID.

Use the eThree.unregister method which will delete the private key from local storage and the public key from Virgil Cloud, reversing the actions of the register function. Note that this method doesn't delete user's key backup.

OnCompleteListener unregisterListener = new OnCompleteListener() {
    @Override public void onSuccess() {
        // Public key (Card) revoked successfully, private key removed successfully.
    }

    @Override public void onError(@NotNull Throwable throwable) {
        // Handle error
    }
};

// Revokes Card from Virgil Cards Service, deletes Private Key from local storage
eThree.unregister().addCallback(unregisterListener);

Cleanup method deletes user's private key from their device in order to prepare it for generating a new key pair (rotate key pair) or to seize the access to user's data from current device.

If you're going to need current private key in future on another device, make sure to make its backup.

To delete user's private key from their device, use the eThree.cleanUp method:

// If you log out user - you should delete her private key
eThree.cleanup();

Resetting a user means generating a new key pair, saving new private key locally, publishing a new public key at Virgil Cloud and marking the old published one as outdated. Use this flow if a user's public key was published, but the private key has been lost (and there is no backup) or stolen (became not valid).

It is necessary to delete the existing private key and delete private key backup (if there is one) before going through this flow.

Use the eThree.rotatePrivateKey method to reset the current user's key pair:

// If the user wants to rotate their keys. For example if they lost all devices.
OnCompleteListener rotateListener = new OnCompleteListener() {
    @Override public void onSuccess() {
        // You're done
    }

    @Override public void onError(@NotNull Throwable throwable) {
        // Error handling
    }
};

eThree.rotatePrivateKey().addCallback(rotateListener);

Note! If a user loses their private key before making a backup, they won't be able to decrypt previously encrypted data.

Explore E3Kit encryption options to start encrypting messages: