Hyphenate Docs

Start Chatting with Hyphenate!

Welcome to the Hyphenate docs portal. Here you'll find comprehensive guides and technical documentation to help you integrate Hyphenate In-App Chat.

Get Started

End-to-End Encryption

Overview

End-to-end encryption can be realized using a Certificate Authority (CA). When a user signs in on a device for the first time, the device generates an RSA key pair and sends information to the CA. The key information stored on the CA includes:

  • Username: a unique identifier of the user.
  • Public key: public key of the RSA 1024 key pair generated by the client.
  • Expiration date: expiration date of the public key. Need to obtain a new public key if expired.

The CA stores all users' key information in respect to their username. In order to send a message, the sender must obtain the recipient's key information from the CA and generate a symmetric key for message encryption, then deliver the encrypted message to the recipient.

Key Negotiation Process

  1. Clients generate private and public keys using the RSA algorithm on client devices and publish public keys to the CA that associates the keys with clients’ usernames.
  2. Client A uses Client B's username to obtain the key info from the CA.
  3. Client A checks the validity of Client B's public key and proceeds with the valid key.
  4. Client A generates an AES 128-bit true random number as a symmetric key.
  5. Client A encrypts the symmetric key using Client B's public key.
  6. Client A computes the hash value of the symmetric key using SHA-256 algorithm and signs the hash value with its own private key as a signature.
  7. Encrypted symmetric key (step 5) and signature (step 6) are attached to the message extension and sent from Client A to Client B.
  8. Upon receiving messages from Client A, Client B reaches CA to obtain Client A's public key in respect to Client A’s username.
  9. Client B checks the validity of Client A's public key and proceeds with the valid key.
  10. Client B extracts the encrypted symmetric key and signature from the message received.
  11. Client B decrypts the encrypted symmetric key using its local private key.
  12. Client B computes the hash value of the symmetric key using SHA-256 algorithm.
  13. Client B uses the hash value and Client A's public key to verify the signature to see if it was signed by Client A.
  14. Client B decrypts the message using the symmetric key.
Figure 1. the key negotiation process

Figure 1. the key negotiation process

Message Encryption

  1. After a successful key negotiation, the encrypted message will be sent and carry the encrypted symmetric key and signature to the recipient.
  2. The recipient verifies the signature and uses the symmetric key to encrypt messages. The sender encrypts the message using the recipient’s public key.
  3. Clients can save the symmetric key to the local database to decrypt messages in the future.
  4. Client can generate new symmetric keys by following the key negotiation rules, but remember to send a message with the updated symmetric key to the peer client.

CA Key Info Renewal

Users can utilize the strategy of key info updates to maximize the security of the key. The following steps demonstrate the key renewal and update process:

  1. The client generates a new RSA key pair (public and private keys).
  2. The client computes the hash value of the new public key by using SHA-1 algorithm.
  3. The client obtains the signature by signing the hash value with its old private key.
  4. The client uploads the new public key, the signature (step 3), and the expiration date of new private key to CA.
  5. The CA computes the hash value of the new public key by using SHA-1 algorithm.
  6. The CA uses the hash value obtained earlier and the old public key to verify the signature and confirms that the client uploaded the data (step 4) is the same client in the record.
  7. The CA updates the key information if the verification is successful.
  8. The client can now use the new RSA key pair as its local authentication identifier. However, keep the old RSA key pair until the negotiation process is completed to avoid the potential encryption key issue while CA is updating the key information during the key negotiation process.
Figure 2. CA key info renewal

Figure 2. CA key info renewal

Unread offline message decryption

The encryption approach described cannot be applied to decrypting unread offline messages if the user switches to a new device, since the RSA key pair is tied to an individual device.

Next Section: Chatbot Integration

End-to-End Encryption


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.