How do I set up off-the-record (OTR) end-to-end encryption (E2EE) for my chat boxes?

 

Related info: Looking for more background information in this feature? Please see What does the end-to-end encryption (E2EE) feature for chat do?

To get started, the local LibraryH3lp administrator generates a public key fingerprint for all chat box skins within the admin dashboard (Main, CA, EU, SG) using the "Manage Off the Record Chat (E2EE)" button.

 

If no keys exist, the only available option is to generate new keys.

 

Generate New Keys: Public key fingerprint

When new keys are generated, a public key fingerprint is stored as part of all chat box skins the administrator manages. (If you later create new chat box skins, you'll need to regenerate the keys.) When generated, all chat box skins managed by the administrator share the same public key fingerprint. You don't need to see/view this fingerprint and in order to avoid confusion, it is not displayed.

For many customers, this is all that is needed, so you might be done!  As long as your web pages have chat boxes that reference a skin with a public key fingerprint, then the chats will use OTR. The end-to-end encryption (E2EE) will be negotiated automatically between the guest's web browser and the webclient chat operator's web browser. 

The local administrator can generate new public key fingerprint at any time, and the chat skins will receive it. There is no need to update any of your web pages directly since the fingerprint is stored as part of the skin.

 

Key rotation best-practices

We recommend regenerating the public key fingerprint (and private key if distributed) on a routine schedule as a best practice. Using keys for up to one month is generally considered safe, and the typical recommendation is to regenerate keys weekly.  This requires coordination within the organization.

 

Optional: Private keys for chat operators

 

The local administrator can optionally distribute a matching private key to chat operators.  This allows proof that there is no man-in-the-middle eavesdropping, but it requires additional internal communication between the local administrator and chat operators. If the local administrator generates new keys, and the chat operators do not update the private keys on their end, then there is no way guarantee the absence of no man-in-the-middle eavesdropping.

 

 

You must keep track of your private key

IMPORTANT: The private key is never stored on LibraryH3lp servers since doing so would defeat the purpose of the OTR/E2EE feature. The private key is only visible to the local administrator within that administrator's web browser and while the key generation screen is in view. Once the page refreshes, that particular private key is gone. Forever. It is the local administrator's responsibility to distribute the private key to all operators who answer chats from guests.

When a chat operator receives the private key from the local administrator, the operator pastes it into the preferences page of the webclient and it is again ONLY stored locally in the web browser's storage, never server-side on LibraryH3lp's end. This means that if the webclient operator switches web browsers (such as moving from Firefox to Chrome) then the operator needs to provide the private key again. Or if an operator clears browser cache/storage, the operator will need to enter the private key again. 

It is important to keep track of the current private key on your (the customer's) side since it will never be stored on LibraryH3lp's side. 

 

What happens if my operators do not have the current private key?

If an operator does not have a private key entered as part of their webclient preferences, or if they have an old no-longer-valid key, the operator can still successfully answer OTR chats from guests. However in such cases, we cannot guarantee the absence of man-in-the-middle (MITM) eavesdropping. 

 

If I distribute private keys, what will my webclient operators see?

In the webclient preferences, operators will see a checkbox indicating that their local administrator gave them a private key.

 

If they check the box, then they receive some basic information and a data entry field where they can paste in the key.

 

There is a basic check to see if what is entered looks like a key.  If it does not seem to be a key, then the operator sees an error message.

 

If I distribute private keys, what will my guests see?

Assuming that your chat operators plug in the current private key, the guest will see an informational, "This chat uses end-to-end encryption." feedback message in the chat box as part of the transcript. This message will appear after the chat operator sends their first message and only if the private key matches the public fingerprint stored in the chat skin.

If the chat operator does not have a private key or has a private key that does not match the the public fingerprint in the chat skin, then the feedback message shown above will not appear for the guest.

 

Well, I lost track of the current private key. What can I do?

No worries.  You should generate new keys, which will immediately update your chat skins.  If you want to continue to distribute private keys to your chat operators, make note of it and distribute it to them.  Their old key will not interfere with their ability to chat with guests, but adding the new, current key will provide proof against man-in-the-middle eavesdropping.

FAQ URL: