Virgil Security Ratchet Java/Kotlin SDK

Introduction

Virgil Security provides a set of services and open source libraries for adding security to any application. If you're developing a chat application, you'll understand the need for a high level of data protection to ensure confidentiality and data integrity.

You may have heard of our e3kit which offers a high level of end-to-end encription, but if you need maximum protection with your application, Virgil Security presents the Double Ratchet SDK – an implementation of the Double Ratchet Algorithm. With the powerful tools in this SDK, you can protect encrypted data, even if user messages or a private key has been stolen. The Double Ratchet SDK not only assigns a private encryption key with each chat session, but also allows the developer to limit the lifecycle of these keys. In the event an active key is stolen, it will expire according to the predetermined lifecycle you had set in your application.

Ratchet SDK interacts with the PFS service to publish and manage one-time keys (OTK), long-term keys (LTK), and interacts with Virgil Cards service to retrieve the user identity cards the OTK and LTK are based on. The Ratchet SDK issues chat participants new keys for every chat session. As a result new session keys cannot be used to compromise past session keys.

SDK Features

communicate with Virgil PFS Service
manage users' one-time keys (OTK) and long-term keys (LTK)
enable group or peer-to-peer chat encryption
uses the Virgil crypto library and Virgil Core SDK

Installation

You can easily add Ratchet SDK dependency to your project with:

Maven

<dependencies>
    <dependency>
        <groupId>com.virgilsecurity</groupId>
        <artifactId>ratchet</artifactId>
        <version><latest-version></version>
    </dependency>
</dependencies>

Gradle

Add jcenter() repository if missing, then update gradle dependencies:

    implementation "com.virgilsecurity:ratchet:<latest-version>"

The <latest-version> of the Ratchet SDK can be found in the Maven Central Repository or in the header of current readme.

Register Users

Make sure you have registered with the Virgil Dashboard and have created an E2EE V5 application.

Besides registering on your own server, users must also be registered on the Virgil Cloud. If they already are, you can skip this step and proceed to the next one.

Every Virgil user has a Virgil Card with an unlimited life-time on their device. The card contains a Private Key, Public Key, and the user's identity.

To register users on the Virgil Cloud (i.e. create and publish their Identity Cards), follow these steps:

Set up your backend to generate a JWT to provide your service and users with access to the Virgil Cloud.
Set up the client side for authenticating users on the Virgil Cloud.
Set up the Cards Manager on your client side to generate and publish Virgil Card with Virgil Cards Service.

If you've already installed the Virgil Ratchet SDK or don't need to install the Virgil SDK or Virgil Crypto, you can use this guide for the steps described above.

Initialize SDK

To begin communicating with the PFS service and establish a secure session, each user must run the initialization. To do that, you need the Receiver's public key (identity card) from Virgil Cloud and the sender's private key from their local storage:

val rotateKeysListener = object : OnResultListener<RotationLog> {
    override fun onSuccess(result: RotationLog) {
        // Keys were rotated
    }

    override fun onError(throwable: Throwable) {
        // Error handling
    }
}

val context = SecureChatContext(identityCard = card,
                                identityKeyPair = keyPair,
                                accessTokenProvider = provider)

val secureChat = SecureChat(context = context)

secureChat.rotateKeys().addCallback(rotateKeysListener)

During the initialization process, using Identity Cards and the rotateKeys method we generate special keys that have their own life-time:

One-time Key (OTK) - each time chat participants want to create a session, a single one-time key is obtained and discarded from the server.
Long-term Key (LTK) - rotated periodically based on the developer's security considerations and is signed with the Identity Private Key.

Peer-to-peer Chat Example

In this section you'll find out how to build a peer-to-peer chat using the Virgil Ratchet SDK.

Send initial encrypted message

Let's assume Alice wants to start communicating with Bob and wants to send the first message:

first, Alice has to create a new chat session by running the startNewSessionAsSender function and specify Bob's Identity Card
then, Alice encrypts the initial message using the encrypt SDK function
finally, The Ratchet SDK doesn't store and update sessions itself. Alice has to store the generated session locally with the storeSession SDK function.

// prepare a message
val messageToEncrypt = "Hello, Bob!"

val startNewSessionAsSenderListener = object : OnResultListener<SecureSession> {
    override fun onSuccess(session: SecureSession) {
        val ratchetMessage = session.encrypt(messageToEncrypt)
        secureChat.storeSession(session)
        val encryptedMessage ratchetMessage.serialize()
    }

    override fun onError(throwable: Throwable) {
        // Error handling
    }
}

// start new secure session with Bob
secureChat.startNewSessionAsSender(receiverCard = bobCard).addCallback(startNewSessionAsSenderListener)

Important: You need to store the session after operations that change the session's state (encrypt, decrypt), therefore if the session already exists in storage, it will be overwritten

Decrypt the initial message

After Alice generates and stores the chat session, Bob also has to:

start the chat session by running the startNewSessionAsReceiver function
decrypt the encrypted message using the decrypt SDK function

val ratchetMessage = RatchetMessage.deserialize(encryptedMessage)

val secureSession = secureChat.startNewSessionAsReceiver(senderCard = aliceCard, ratchetMessage = ratchetMessage)

val decryptedMessage = secureSession.decryptString(ratchetMessage)

secureChat.storeSession(session)

Important: You need to store sessions after operations that change the session's state (encrypt, decrypt). If the session already exists in storage, it will be overwritten

Encrypt and decrypt messages

Encrypting messages

To encrypt future messages, use the encrypt function. This function allows you to encrypt data and strings.

You also need to use message serialization to transfer encrypted messages between users. And do not forget to update sessions in storage as their state changes with every encryption operation!

Use the following code-snippets to encrypt strings:

val session = secureChat.existingSession(participantIdentity = bobCard.identity)

val message = session.encrypt("Hello, Bob!")

secureChat.storeSession(session)

val messageData = message.serialize()
// Send messageData to Bob

Use the following code-snippets to encrypt data:

val session = secureChat.existingSession(participantIdentity = bobCard.identity)

val message = session.encrypt(data)

secureChat.storeSession(session)

val messageData = message.serialize()
// Send messageData to Bob

Decrypting Messages

To decrypt messages, use the decrypt function. This function allows you to decrypt data and strings.

You also need to use message serialization to transfer encrypted messages between users. And do not forget to update sessions in storage as their state changes with every decryption operation!

Use the following code-snippets to decrypt strings:

val session = secureChat.existingSession(participantIdentity = aliceCard.identity)

val ratchetMessage = RatchetMessage.deserialize(messageData)

val decryptedMessage = session.decryptString(ratchetMessage)

secureChat.storeSession(session)

Use the following code-snippets to decrypt data:

val session = secureChat.existingSession(participantIdentity = aliceCard.identity)

val ratchetMessage = RatchetMessage.deserialize(messageData)

val decryptedMessage = session.decryptData(ratchetMessage)

secureChat.storeSession(session)

Group Chat Example

In this section, you'll find out how to build a group chat using the Virgil Ratchet SDK.

Create Group Chat Ticket

Let's assume Alice wants to start a group chat with Bob and Carol. First, create a new group session ticket by running the startNewGroupSession method. This ticket holds a shared root key for future group encryption. Therefore, it should be encrypted and then transmitted to other group participants. Every group chat should have a unique 32-byte session identifier. We recommend tying this identifier to your unique transport channel id. If your channel id is not 32-bytes you can use SHA-256 to derive a session id from it.

// Create transport channel according to your app logic and get session id from it
val sessionId = ConvertionUtils.hexToBytes("7f4f96cedbbd192ddeb08fbf3a0f5db0da14310c287f630a551364c54864c7fb")

val ticket = secureChat.startNewGroupSession(sessionId)

Start Group Chat Session

Now, start the group session by running the startGroupSession function. This function requires specifying the group chat session ID, the receivers' Virgil Cards and tickets.

val receiverCards = cardManager.searchCards(listOf("Bob", "Carol"))

val groupSession = secureChat.startGroupSession(receiverCards, sessionId, ticket)

Store the Group Session

The Ratchet SDK doesn't store and update the group chat session itself. Use the storeGroupSession SDK function to store the chat sessions.

Also, store existing session after operations that change the session's state (encrypt, decrypt, setParticipants, updateParticipants). If the session already exists in storage, it will be overwritten

secureChat.storeGroupSession(groupSession)

Send the Group Ticket

Next, provide the group chat ticket to other members.

First, serialize the ticket

val ticketData = ticket.serialize()

For security reasons, we can't send the unprotected ticket because it contains an unencrypted symmetric key. Therefore, we have to encrypt the serialized ticket for the receivers. The only secure way to do this is to use peer-to-peer Double Ratchet sessions with each participant to send the ticket.

receiverCards.forEach { card ->
    val session = secureChat.existingSession(participantIdentity = card.identity) ?:
    // If you don't have session, see Peer-to-peer Chat Example on how to create it as Sender.
    return


    val encryptedTicket = session.encrypt(ticketData).serialize()

    secureChat.storeGroupSession(groupSession)

    // Send ticket to receiver
}

Next, use your application's business logic to share the encrypted ticket with the group chat participants.

Join the Group Chat

Now, when we have the group chat created, other participants can join the chat using the group chat ticket.

First, we have to decrypt the encrypted ticket

val session = secureChat.existingSession(participantIdentity = "Alice") ?:
// If you don't have a session, see the peer-to-peer chat example on how to create it as a receiver.
return

val encryptedTicketMessage = RatchetMessage.deserialize(encryptedTicket)

val ticketData = session.decryptData(encryptedTicketMessage)

Then, use the deserialize function to deserialize the session ticket.

val ticket = RatchetGroupMessage.deserialize(ticketData)

Join the group chat by running the startGroupSession function and store the session.

val receiverCards = cardManager.searchCards(listOf("Alice", "Bob"))

val groupSession = secureChat.startGroupSession(receiverCards, sessionId, ticket)

secureChat.storeGroupSession(groupSession)

Encrypt and decrypt messages

Encrypting messages

In order to encrypt messages for the group chat, use the encrypt function. This function allows you to encrypt data and strings. You still need to use message serialization to transfer encrypted messages between users. And do not forget to update sessions in storage as their state is changed with every encryption operation!

Use the following code-snippets to encrypt strings:

val message = groupSession.encrypt("Hello, Alice and Bob!")

secureChat.storeGroupSession(groupSession)

val messageData = message.serialize()
// Send messageData to receivers

Use the following code-snippets to encrypt data:

val message = groupSession.encrypt(data)

secureChat.storeGroupSession(groupSession)

val messageData = message.serialize()
// Send messageData to receivers

Decrypting Messages

To decrypt messages, use the decrypt function. This function allows you to decrypt data and strings. Do not forget to update sessions in storage as their state changes with every encryption operation!

Use the following code-snippets to decrypt strings:

val message = RatchetGroupMessage.deserialize(messageData)

val carolCard = receiversCard.first { it.identity == "Carol" }

val decryptedMessage = groupSession.decryptString(message, senderCardId = carolCard.identifier)

secureChat.storeGroupSession(groupSession)

Use the following code-snippets to decrypt data:

val message = RatchetGroupMessage.deserialize(messageData)

val carolCard = receiversCard.first { it.identity == "Carol" }

val data = groupSession.decryptData(message, senderCardId = carolCard.identifier)

secureChat.storeGroupSession(groupSession)

License

This library is released under the 3-clause BSD License.

Support

Our developer support team is here to help you. Find out more information at our Help Center.

You can find us on Twitter or send us an email at support@VirgilSecurity.com.

Also, get extra help from our support team on Slack.

VirgilSecurity/virgil-ratchet-kotlin

Virgil Security Ratchet Java/Kotlin SDK

Introduction

SDK Features

Installation

Maven

Gradle

Register Users

Initialize SDK

Peer-to-peer Chat Example

Send initial encrypted message

Decrypt the initial message

Encrypt and decrypt messages

Encrypting messages

Decrypting Messages

Group Chat Example

Create Group Chat Ticket

Start Group Chat Session

Store the Group Session

Send the Group Ticket

Join the Group Chat

Encrypt and decrypt messages

Encrypting messages

Decrypting Messages

License

Support