CMYK / .eps

Facebook “f ” Logo

CMYK / .eps

Messenger Secret Conversations
Technical Whitepaper

Version 2.0
May 18, 2017

Version History:
2.0 — May 18, 2017
1.0 — Jul 8, 2016©2017 Facebook, Inc. All rights reservedmessenger secret conversations technical whitepaper

Contents

4

Introduction

Transport Protocol Overview
Abuse Reporting

11

Message Storage

13

Conclusion

15

5

3

messenger secret conversations technical whitepaper

Introduction
In this document we provide a brief technical overview of Secret
Conversations — a specialized conversation mode within Facebook Messenger. Secret Conversations provides end-to-end
encryption for messages using keys that are only available on users’
devices.
Secret Conversations is a distinct conversation mode inside
Facebook Messenger. Individual secret conversations are displayed
as separate threads in Messenger and share many UX elements withregular Messenger conversations. However, Secret Conversations uses a different transport protocol, specialised on-device storage and separate back-end infrastructure.
The Secret Conversations threat model considers the compromise of server and networking infrastructure used by Messenger— Facebook’s included. Attempts to obtain message plaintext or falsify messages by Facebook or network providers result in explicit
warnings to the user. We assume however that clients are working as
designed, e.g. that they are not infected with malware.
Secret Conversations relies upon the Signal Protocol. Messenger uses Signal Protocol’s implementation as available in the opensource libsignal-protocol-java and libsignal-protocol-c libraries for Android
and iOS respectively. Secret Conversations also incorporates
abuse-reporting features which are not present in other platforms
which use the Signal Protocol.
In this document we describe Secret Conversations, startingwith the transport protocol. We then cover abuse reporting and closewith how we handle on-device storage.

4

messenger secret conversations technical whitepaper

Transport Protocol Overview
Secret Conversations is a device-to-device conversation mode.
Messages are only accessible from the devices which participate in aconversation when the conversation occurs. This differs from regular
Messenger conversations which are stored server-side and are accessible from any device connected to the participating Facebook accounts; including present and future devices and browser instances.
Instead, to use Secret Conversations users enable some subset
of devices, such as their mobile phone and a tablet, upon which only
their future secret conversations will be available.

Device Management
A user can enable or disable a device for Secret Conversations at
any point, and can disable other devices remotely from any currently
enabled device. Secret Conversations may also be enabled or
disabled automatically. When a user logs into a compatible version of
Messenger, the new device gets enabled for use with Secret Conversations. Facebook disables devices after they have been offline
for a period of at least 30 days. Upon enabling a new device existing
Secret Conversations messages and cryptographic keys are nottransferred to the new device.
Whenever the list of devices on which Secret Conversations isenabled changes for an account, Messenger displays a warning that
this occurred. When a user’s own set of enabled devices changes, allof their other devices enabled for Secret Conversations proactively receive an update. People with pre-existing secret conversations with the user who changed their list of enabled devices receive
the same warning when they return to these pre-existing conversations.
Facebook bounces messages sent to an incorrect list of participants, and includes the correct device list within that bounce. Messenger does not automatically resend bounced messages when newdevices are added to a secret conversation – an explicit resend action
from the user is required. Messenger, however, may automatically5messenger secret conversations technical whitepaper

resend messages without user interaction in case of device removal,
as no device will receive the message that the sender has not been
notified about.

Keys
Each device manages various cryptographic keys. All keys are generated or derived on-device. Private keys are never sent to Facebook.
Public keys All public key operations use Curve25519. Each device
uses the following public-secret keypairs:• The Identity Key keypair (IK pk , IKsk ). This is a long-term keypair
which is generated the first time Messenger runs.
• The Signed Pre-Key keypair (SPK pk , SPKsk ). This is a medium-term
keypair which is rotated periodically. It is signed by IKsk .
• The One-Time Pre-Key keypairs (OTPK pk , OTPKsk ). These keypairs
are generated in batches by clients. They facilitate asynchronous
conversation initiation.1• The Ephemeral Key keypairs (EK pk , EKsk ). A new ephemeral keypair
is generated for each round of communication within a secretconversation and is subsequently discarded.
Pairwise Session keys When starting a pairwise cryptographic channel the participating devices derive symmetric session keys. Theseare:• The Root Key (RK) is a 256-bit key which is used to derive Chain
Keys in the Signal Protocol ratchets.
• Chain Keys (CK) are each 256-bit values which are used to derive
Message Keys.
• Message Keys (MK) are each 640-bit values which consist of 256 bits
for an AES-256 key, 256 bits for an HMAC·SHA256 key, and 128 bits
for an Initialization Vector (IV) for AES-CBC encryption.
Multicast Session keys In Secret Conversations involving morethan 2 devices each device uses session keys for sending messages.
These are:• Sender Chain Keys (SCK) are 256-bit values used to derive SenderMessage Keys.

1

The client also generates a single
Last-Resort Pre-Key. This is used likea One-Time Pre-Key, but is simply
provided when the server has no OneTime Pre-Keys available for a given
device.

6messenger secret conversations technical whitepaper• Sender Message Keys (SMK) are 384-bit values consisting of 256 bits
for an AES-256 key, and 128 bits for an Initialization Vector (IV) for
AES-CBC encryption.
• Sender Signing Keys (SSK) are key pairs used to sign multicast
messages.
When Messenger initialises Secret Conversations it generates
and then uploads to Facebook its permanent IK pk and the current
SPK pk . It generates a batch of one-time pre-key keypairs and uploads
their public parts to Facebook on demand.

Pairwise Channel Initiation
Each device in a secret conversation must have a pairwise channel
with each other device before it can send messages. Each pairwise
channel consists of two devices: one Initiator device and one Responder device (I and R respectively). Let HKDF be a secure hash-based
key derivation function, and ECDH indicate the elliptic curve DiffieHellman function applied to a secret and public key. To create a new
pairwise channel:
1. The Initiator obtains from Facebook IKRpk , SPKRpk and OTPKRpk for
an one-time pre-key keypair generated by the Responder device.
2. Facebook deletes OTPKRpk from the Responder’s list of available
one-time pre-keys, so long as it is not the last-resort.
I
3. The Initiator generates a fresh ephemeral keypair (EK Ipk , EKsk).

4. The Initiator now computes the first root key RK as follows:I
a = ECDH(IKsk, SPKRpk ),I
c = ECDH(EKsk, SPKRpk ),I
b = ECDH(EKsk, IKRpk )I
d = ECDH(EKsk, OTPKRpk )RK = HKDF( a||b||c||d)Using the RK the Initiator can calculate the first CK and MK (asdescribed next) and use those to start sending messages.
5. The Initiator sends the first encrypted message to the Responder,
including the fresh EK Ipk it generated previously.
Upon receiving the first encrypted message the Responder:
1. Recomputes RK as above by performing the four ECDH operations
using the other part of the same keypairs available locally.
2. Recomputes the first CK and MK, and decrypts the message.
R
3. Deletes (OTPKRpk ,OTPKsk) from its local storage.

7

messenger secret conversations technical whitepaper

Pairwise Message Exchange
Each pairwise message is encrypted with AES·CBC and authenticatedusing HMAC·SHA256. The unique MK is derived from the current CK
and RK. Their first value is:
CK = RKMK = HKDF(CK)
In each message exchange, the sender generates a fresh ephemeral
keypair (EKsender, EKsender) and includes the public part in the outpk
sk
going message. The recipient calculates the current MK value using
EKsenderand can decrypt the message. It too then generates a freshpk

ephemeral keypair (EKreceiver, EKreceiver) and derives new keys RK0 ,
pk
sk
0
0
CK and MK for use with the next response by updating the previous
symmetric key values as follows:
RK0 , CK0 = HKDF(ECDH(EKreceiver, EKsender))skpk
MK0 = HKDF(CK0 )If a second message is sent before the opposing party responds, thesender uses a new chain key CK00 = HKDF(CK) and a corresponding
MK00 = HKDF(CK00 ).
When a secret conversation contains just two devices, we use thepairwise channel for transmitting messages directly. The Signal
Protocol’s implementation is open-source and available at https://github.com/whispersystems/libsignal-protocol-java/.

Multi-device Message Exchange
Secret conversations with more than two devices use the Signal Protocol’s Group Messaging protocol.
All messages have a Sender and at least two Receivers. Prior tosending to a multi-device conversation Sender must have a pairwise
channel with every Receiver. Sender also generates a SCK and SSK,and sends them along its pairwise channel to each Receiver.
Each multi-device message is encrypted with AES·CBC and signedby the SSK. The unique SMK is derived from the SCK similarly to thepairwise channel:
SMK = HKDF(SCK)
For subsequent messages the Sender ratchets the SCK using HKDF
SCK0 = HKDF(SCK)8messenger secret conversations technical whitepaper

9

and uses each subsequent SCK0 key to derive SMK and SSK. Thisapproach provides forward secrecy, as earlier SCKs and SMKs cannot
be calculated from the current state.
When a new device is added to a secret conversation, each otherdevice will send the new device their latest SCK upon sending theirnext message. When a device is removed however, each device will
generate a new SCK. This ensures that the necessary key material isrestricted to the devices within the thread.

Attachments
If a message includes attachments, such as images or videos, they
are encrypted and uploaded to Facebook. For each attachment, thesender:1. Generates a pseudorandom 256-bit AES key K and a 96-bit pseudorandom Initialization Vector IV.
2. Encrypts the attachment using AES-GCM2 encryption using K
and IV. The IV is placed into the header (Associated Data) of the
GCM encryption. The IV and the GCM authentication tag are
attached to the resulting ciphertext to form the encrypted file.
3. Computes a SHA256 hash H of the resulting encrypted file anduploads the file to Facebook. The sender obtains a unique identifier for future retrieval.
4. Encodes the unique identifier, K, H, attachment metadata, and an
optional thumbnail into a message. The message is encrypted andsent to the recipient who downloads the content, verifies the hashH, and decrypts the file using K.

Stickers
Stickers are images chosen from a set of collections hosted by Facebook. Each sticker is referenced by a unique identifier. The senderchooses a sticker to attach in a conversation from a set of sticker previews available in the message composer. The sender then sends thecorresponding sticker identifier as an encrypted message to the recipient. Unless the sticker file is available locally, both the sender andthe receiver submit the sticker identifier to Facebook and download
the corresponding sticker file. Facebook may infer the use of individual stickers when they are first used on a device but devices cache
sticker files and avoid repeat fetches if a sticker is later reused.

2

Messenger uses the AES-GCM implementation provided by OpenSSL. On
Android, Messenger employs Conceal.
Conceal is open-source and available athttps://facebook.github.io/conceal/messenger secret conversations technical whitepaper

Conversation Metadata
During a secret conversation, devices generate metadata such as delivery and read receipts to indicate successful message transmission
and display, respectively. Conversation metadata such as delivery
and read receipts do not contain message plaintext and are not endto-end encrypted.

Key Verification
For every secret conversation Messenger exposes in its interface theidentity keys (i.e. IK pk ) for every participating device. Users may
optionally verify these keys in order to ensure no man-in-the- middle attack is compromising their secret conversations. Messenger
displays the 256-bit IK pk values in hexadecimal format.

10

messenger secret conversations technical whitepaper

Abuse Reporting
A participant in a secret conversation may voluntarily notify Facebook of abusive content. Facebook uses such reports to identify users
who violate Facebook’s terms of service.
The ability to report abuse does not represent a relaxation of theend-to-end encryption guarantees of Secret Conversations. Facebook will never have access to plaintext messages unless one participant in a secret conversation voluntarily reports the conversation.
Secret Conversations includes a mechanism to perform“franking” of messages sent through Facebook. This mechanism isanalogous to placing a cryptographic stamp on the message, without
learning the message content.

Franking
The franking mechanism must satisfy three main guarantees: authenticity, confidentiality and third-party deniability. The authenticity
property ensures that if a user submits a report then the message
must have legitimately originated from the sender’s device. The confidentiality property ensures that no outside party — including Facebook — should learn the content of a message unless a participant
in a secret conversation voluntarily shares that information. Finally,
the third-party deniability property ensures that no party outside ofFacebook can cryptographically determine the validity of a report.
Franking tag Authenticity for messages in a secret conversation isprovided by the Franking tag TF . Senders must send the Franking
tag along with each encrypted message. To compute TF , the senderfirst generates a 256-bit random nonce NF . NF is added to the unencrypted message being transmitted. Next, the entire data structure isserialized into a string M, and TF is computed as:
TF = HMAC·SHA256(NF , M)
NF remains within the serialised, encrypted data sent to the recipient.
The sender destroys any other copies of NF after transmission. TF is

11messenger secret conversations technical whitepapertransmitted to Facebook along with each encrypted message.
Franking messages When Facebook receives TF , it uses a Facebook
key KF to compute the Reporting tag RF over TF and conversation
context (e.g., sender and recipient identifiers, timestamp) as:
RF = HMAC·SHA256(KF , TF kcontext)
Both TF and RF are sent to the recipient along with the encrypted
message. The recipient decrypts the ciphertext, parses the resulting
plaintext to obtain NF , and verifies the structure of TF prior to displaying the message. If TF is not verified then the recipient discards
the message without displaying it. The recipient stores the message
M, NF , TF , RF and context in its local storage.
Reporting abuse To report abuse, the recipient of a message submits
to Facebook the full serialized message plaintext, RF , NF , and context.
Upon receiving this message Facebook first recomputes TF and thenvalidates RF using the provided information as well as its internal
key KF .
Security and Privacy The authenticity properties of the franking
mechanism are based on reasonable assumptions about the collisionresistance of the SHA256 hash function and the unforgeability of
HMAC·SHA256.
Authenticity In order to “forge” invalid content M0 , a user must
either ( a) produce a forged HMAC tag under Facebook’s key KF ,or (b), identify a collision NF 0 , M0 , context0 such that the HMAC ofthese values is equal to the HMAC of a different valid message M
sent through Facebook.
Confidentiality Similarly, under reasonable assumptions about
HMAC·SHA256, the resulting tag reveals no information about
the message to Facebook or to eavesdroppers.
Third-party deniability The guarantee holds under the assumptionthat HMAC·SHA256 is a pseudorandom function and that KF isnever publicly revealed. Facebook rotates KF periodically.

12

messenger secret conversations technical whitepaper

Message Storage
Secret Conversations plaintext messages are stored permanently
only on the devices that participate in each conversation. Plaintext
messages are protected using on-device symmetric-key encryption
and optional Disappearing Messages functionality.
On-device encryption ensures that messages stored permanently
on a particular device are only accessible while a user is authenticated to Facebook. Messenger allows users to switch accounts. Whilea second user is logged in to a particular device messages of the firstuser should not be accessible. However, when the first user returns tothe same device they should find their messages intact.
To fulfill these requirements, clients employ two encryption keys:
Klocal and Kremote . Both these keys are used for AES-GCM encryption. Klocal is generated on-device and never leaves the device it was
generated on. It is used to encrypt plaintext messages before theseare stored permanently on a device. Kremote is a long-term, userspecific key held on Facebook and delivered to the device when auser authenticates. It is used to encrypt Klocal in local storage. When
Messenger switches accounts the device persists an encrypted versionof Klocal and erases Kremote . Upon successful reauthentication the device obtains Kremote from Facebook, uses it to decrypt Klocal and gains
access to messages.
On iOS, database files are protected using the filesystem protectionlevel FileProtectionComplete. This ensures that database files canno longer be accessed shortly after the user locks their device. The
key used for local storage, i.e. Klocal , is stored in keychain using thekSecAttrAccessibleWhenUnlockedThisDeviceOnly attribute.
Disappearing Messages ensures that messages are no longer
visible within a selected time after they are sent or received. In Disappearing Messages a timeout value is added to the message data
structure before serialisation and encryption. Both devices automatically hide messages that specify a timeout once the message timeout
has elapsed. The actual deletion of message plaintext from local storage occurs shortly after each message has expired in order to enableabuse reporting in the interim.

13messenger secret conversations technical whitepaper

Video Attachments on iOS
As with other attachment types on iOS, video attachments are stored
on-device encrypted. To play videos however, Messenger’s video
player on iOS must access them via a URL. As memory cannot be
addressed by URL, this prevents videos from being playable directlyfrom an in-memory decrypt. Messenger decrypts videos and storesthem in a session-based least-recently-used filesystem cache when
they need to be viewed. This cache is cleared when a user logs out.
When a secret conversation is deleted, any associated decrypted
video attachments in the cache are deleted.

14messenger secret conversations technical whitepaper

Conclusion
Secret Conversations is a specialised conversation mode in Messenger. Messages in Secret Conversations are encrypted end-toend between the sender and the recipient using the Signal Protocol
and its open-source implementations. Third parties — Facebook included — do not have access to message plaintext and messages canonly be decrypted by their intended recipient. Users may inspect theidentity keys used for end-to-end encryption and verify the confidentiality and authenticity of their communications. Decrypted messages
do not leave the devices that participate in the conversation. Users
retain the ability to report abusive content to Facebook.

15