2021-10-26 Backing up WhatsApp data through the multi-device web client

Systematically backing up WhatsApp messages and media in an open format is impractical. However the multi-device beta makes the WhatsApp web client an almost first-class WhatsApp client. I describe how the web client stores messages and media, and a proof of concept program, wadump, which can extract and display them.

After I wrote the tool and the post, I realized that somebody had already reverse engineered the WhatsApp web client protocol. Some of the information in this post (especially regarding media encryption) is explained more completely in that project.

As you might have noticed from some of my other blog posts, I care about controlling my data. This is not out of privacy concerns, but because I want to be sure that I will never lose access to it. This fear is not abstract: I did lose access to a lot of my data a long time ago, and never got over it 🙃.

Disclaimer & Limitations #

I am not affiliated with Facebook or WhatsApp, and this investigation was done purely to preserve my personal data better. I don’t know if backing up your data this way breaches WhatsApp’s terms of service. Use at your own risk!

This information is useful at the time of writing, but it could very well not be in the near future if the web client changes the way it stores its data.

Finally, wadump currently cannot reliably extract all media.

How multi-device WhatsApp works #

This is explained well in the Facebook Engineering blog post about the multi-device beta, but the key concept is simple.

Before the multi-device web app, the web client relied on the phone to send and receive messages, deferring all E2EE with our contacts to the phone:

The multi-device beta changes this, so that many devices (up to 4) can send and receive messages directly. If we have more than one device, say a laptop and a phone, our contacts will encrypt their messages once per device, and similarly when we send a message from one of our devices we will route it both to the recipient and to our other devices:

How data is stored by the WhatsApp client #

The data stored by the web client can be divided in three parts:

• Metadata stored as cleartext in IndexedDB;
• Encrypted text chat content, also stored in IndexedDB;
• Encrypted media files, stored in WhatsApp’s CDN, and cached locally.

IndexedDB is a persistent storage facility for web applications — think of an in-browser key-value store. Web applications can create databases and tables (which IndexedDB calls “object stores”), and store JavaScript objects indexed by some key in them.

The cleartext metadata includes a lot of information, mostly stored in the model-storage database, including:

• Our contact list, including names and phone numbers, in object store contact;
• The list of groups we’re in, in object store group-metadata;
• Information about the messages we’ve sent and received, including senders and recipients, their time, and in which chat they appeared, in object stores message and chat.

You can check this data out for yourself in the “IndexedDB” section of the “Application” tab of the Chrome dev tools.

The cleartext data can be saved by just dumping the relevant object stores. Retrieving the actual contents of the messages, wether text or media, is trickier.

Decrypting text chats #

Messages are stored as JSON objects in the message object store. For text messages, the content of the message is encrypted using AES-CBC, as implemented by the SubtleCrypto API:

{
  id: ...,
  t: 1517917600, // seconds epoch
  from: ...,
  to: ...,
  msgRowOpaqueData: { 
    // An identifier telling us which key to use to decrypt this message
    _keyId: 1,
    // The initialization vector to be used by AES-CBC decryption, see
    // <https://developer.mozilla.org/en-US/docs/Web/API/AesCbcParams>
    iv: ArrayBuffer(16),
    // The actual encrypted data
    _data: ArrayBuffer(80), 
  },
  ... omitted fields ...
}

AES-CBC is a symmetric encryption scheme — the same key is used to encrypt and decrypt messages. But where does this key come from?

Storing, retrieving, and deriving keys #

The keys that we are interested in are in keys object store in the wawc_db_enc IndexedDB database. Each object in this object store looks like this:

{
  id: number,          // the key id, as referenced from the messages
  key: CryptoKey,
  _expiration: number, // milliseconds epoch
}

In my case I have only one key, with id 1.

Deriving the right key #

The keys in IndexedDB are not used directly to encrypt and decrypt messages. Rather they are be used to derive an AES-CBC key for message encryption, using the HKDF key derivation function. Key derivation functions are used to turn some secret (maybe a passphrase or, like in our case, another key) into a key suitable for the task at hand.

HKDF in particular lets us integrate other bits of information (the “salt” and the “info”), and allows us to specify the length of the output key.

WhatsApp web uses the deriveKey function from SubtleCrypto to turn our “master” key into an AES-CBC key suitable for local symmetric encryption of our text messages. It looks like this:

// https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/deriveKey
crypto.subtle.deriveKey(
  // The algorithm used to derive the key (HKDF with SHA256 as hash
  // function), together with its parameters -- the salt and the info.
  // We'll see below where these come from.
  {
    name: "HKDF",
    hash: "SHA-256",
    salt,
    info,
  }
  // The key stored in `wawc_db_enc`
  key,
  // The specification of the derived key
  { name: "AES-CBC", length: 128 },
  // Whether the key can be extracted (e.g. whether we can dump its contents
  // with `crypto.subtle.exportKey`)
  false,
  // What we'll use the key for -- in this case we'll perform symmetric
  // encryption with it, to store and retrieve our text messages
  [ "encrypt", "decrypt" ],
);

Given the code above, all we need to generate the appropriate key is the salt and the info parameters to the HKDF function. The salt is non-secret data which gives HKDF some desirable properties, while the info parameter is used to “bind” the key for a certain application.

Typically the salt is generated at random, while the info contains some info on where the key is used, such as protocol number, user identity, and so on.

Finding the info and salt #

Retrieving the derived key by monkey patching #

WhatsApp web uses crypto.subtle.decrypt to decrypt messages. Luckily, crypto.subtle.decrypt is not a read-only property, and we can replace it with a function which waits until it is called with arguments which are capable of decoding messages.

It looks like this:

• We read a message from the message object store;
• We replace crypto.subtle.decrypt with a function which tries to decode the message above with the arguments passed to decrypt;
• Once we’ve found a key that works, we store it in a global variable, restore the original function, and start decoding the messages in bulk.

This relies on the same key working for all messages, which is the case for me.

Using this method we avoid having to derive the key ourselves, at the cost of requiring some user interaction to trigger message decryption in the web client.

Decoding the content of the messages #

Once msgRowOpaqueData._data is decrypted, the resulting cleartext is a Protocol Buffer message with this schema:

message WhatsAppMessage {
  string body = 1;
  string caption = 2;
  string loc = 4;
  double lng = 5;
  double lat = 7;
  int32 paymentAmount1000 = 8;
  string paymentNoteMsgBody = 9;
  string canonicalUrl = 10;
  string matchedText = 11;
  string title = 12;
  string description = 13;
  bytes futureproofBuffer = 14;
}

message FullWhatsAppMessage {
  WhatsAppMessage currentMsg = 1;
  WhatsAppMessage quotedMsg = 1;
}

The quotedMsg contains the message we’re replying to, if any. To decode the protobuf messages without depending on external code, wadump contains a minimal protobuf decoder.

Downloading and decrypting media #

Now that we’ve covered text chats, let’s talk about media.

Media (audio messages, images, videos, documents) is predictably not stored inline in the protobuf message above. Rather, it is encrypted and stored in WhatsApp’s CDNs, and retrieved and decrypted when needed. A media message looks like this in the message object store:

{
  id: ...,
  t: 1627663880, // seconds epoch
  from: ...,
  to: ...,
  // Might be "video", "audio", etc.
  type: "image",
  mimetype: "image/jpeg",
  // base64 encoded SHA256 hash of the decrypted message
  filehash: "dzBnGb+PQVMhdlkuoUkXB+3xMWEJsCadLRJ9JVOdTeQ=",
  // base64 encoded key used to decrypt the message
  mediaKey: "e4Q1drkxa4ST0+Ac9Ug86W0etx3WbDaZ0IGRs/3ZVI4=",
  // CDN path to the encrypted message
  directPath: "/v/t62.7118-24/35487369_1391679344547224_9081397384390117319_n.enc?ccb=11-4&oh=a8323bff0917bdc1827929420adec846&oe=61287211&_nc_hot=1627663880",
  // Image metadata...
  size: 165863,
  height: 1281,
  width: 1600,
  ... omitted fields ...
}

The main CDN domain for WhatsApp seems to be https://mmg.whatsapp.net. Appending the directPath to it will give us the URL to hit to download the encrypted file. Once that is done, we need to decrypt it.

Deriving the media encryption keys #

AES-CBC is used to also decrypt media files. Like with messages, HKDF with SHA256 as hash function is used to derive the key. This time the parameters to HKDF are:

• The key is the 32 bytes of data encoded in base64 in the mediaKey field of the message object.
• The info is derived from the type of the message. For "image" it is "WhatsApp Image Keys", for "video" it is "WhatsApp Video Keys", and so on.
• The salt is not used, in which case HKDF just uses a dummy salt filled with 0s.
• The output key length is 112 bytes.

In this case HKDF is performed directly on the raw data from mediaKey, without going through crypto.subtle.importKey and crypto.subtle.deriveKey.

Once the 112 bytes long key is generated, it is chopped up to get the initialization vector and key for AES-CBC decryption:

const mediaKeys = {
  iv: key.slice(0, 16),
  encKey: key.slice(16, 48),
  // Other keys, unused for our purposes
  macKey: key.slice(48, 80),
  refKey: key.slice(80, 112)
}

Note how in this case, unlike with text messages, we only need cleartext data to decrypt media files.

Once we have the data above, we can go ahead and use it to decrypt the encrypted bytes:

const key = await crypto.subtle.importKey("raw", mediaKeys.encKey, "AES-CBC", false, ["decrypt"]);
// the last 10 bytes contain the mac
bytes = bytes.slice(0, -10);
const cleartext = await crypto.subtle.decrypt({ name: "AES-CBC", iv: mediaKeys.iv }, key, bytes);

Media caching #

The web client caches decrypted media files in the "lru-media-array-buffer-cache" cache, through the CacheStorage API.

When looking for media files, wadump looks there first, and stores downloaded files in the cache after download, as the web client would. This is to avoid sending off thousands of CDN requests each time we want to dump the media messages.

Media troubles #

While the method above works for recent media files, it seems that the WhatsApp CDN does not store media forever. In those cases requesting the file results in a 410 or 404. When that happens the web client re-requests the media file from the phone and gets a new link from the WebSocket channel.

I have not studied in detail the protocol that is used on the WebSocket channel, and I have not experimented with using it independently from the web client. Therefore wadump can currently only retrieve relatively recent or cached media messages.

Another mystery is how the encrypted msgRowOpaqueData is used for for media messages, since it is still present. It might be used to request the missing files above, but again, I have not figured that out yet.

Wrapping up the dump, and browsing it #

Once wadump has collected all the information that it can find, it stores everything in a tarball, which it then offers for download.

The tarball contains the following files:

message.json
chat.json
contact.json
group-metadata.json
media/<filehash>

The chat.json/contact.json/group-metadata.json files simply contain a dump of the respective object stores. message.json contains a dump of the message object store, but with the msgRowOpaqueData field replaced by a msgRow field with the decrypted text message.

The media folder contains all the media files we could retrieve, named with their filehash.

wadump also contains a small utility to easily browse the contents of the tarball archive — head to the README for more information.

Closing thoughts & future work #

Acknowledgements #

Thanks to Alexandru Scvorţov and Alex Appetiti for reading drafts of this article.