dm3 Protocol

The dm3 protocol enables decentralized, open, and secure messaging using established web3 services. In this post I will explain the technical specification of the dm3 protocol.

The protocol is composed of the following specifications:

• Delivery Flow & API
• Sign-In
• Key Management
• User Storage
• Profile Registry

📨 Delivery Flow & API

The following example depicts how the delivery would work if Alice sent a message to Bob.

1. Alice types her message for Bob into the dm3 app and submits it.
2. The dm3 app asks on-chain for Bob’s dm3 profile. To do so, the app queries the eth.dm3.profile text record linked to his ENS name. The profile contains Bob’s public encryption key, his public signing key, and the URL to the delivery service he uses.
3. The message content is signed using Alice’s private signing key and encrypted using Bob’s public encryption key. After the message is encrypted, it is sent to the delivery service used by Bob via its WebSocket API.
4. The delivery service pushes the message to Bob’s instance of the dm3 app. The app decrypts the message using Bob’s private encryption key.
5. The app queries Alice’s dm3 profile and uses it to check whether the message signature is valid.
6. If the signature is valid, Bob is able to read the message

There is no central delivery service. Alice and Bob can change their delivery service by changing the delivery service URL in their profile. They could, for example, run a delivery service instance on their DAppNode at home.

🔐 Key Management

The aim of the key management is to give the owner of the key, who controls the corresponding ENS name, complete control over the dm3 identity. No one who does not have access to this key is able to read messages, send messages, or change profile settings.

The following types of keys exist:

• Ethereum Account Key: The private key of the Ethereum account that owns your ENS name.
• Storage Encryption Key: The symmetric key used to encrypt the user storage. This key is generated by signing a message including a salt with the Ethereum Account Key.
  Storage_Encryption_Key = keccak256( personal_sign( salt ) )
• Message Encryption Key Pair: The key pair used to encrypt/decrypt messages.
• Signing Key Pair: The key pair used to sign/verify messages.

✍️ Sign-In Flow

The dm3 app requires users to sign in using their Ethereum account. The initial sign-in consists of the following steps:

1. Connect an Ethereum account: The dm3 app connects to an Ethereum Account which is injected by a wallet (e.g., MetaMask).
2. Storage Encryption Key creation: A message containing a salt (randomly generated characters) is created and signed with the user’s Ethereum Account Key. The hash of the signature serves as Storage Encryption Key. The salt is stored unencrypted in the user storage.
3. dm3 Profile creation: The app generates a new Message Encryption Key Pair and Signing Key Pair and stores the private keys in the encrypted part of the User Storage. The public keys and the delivery service URL constitute the dm3 profile. The profile is then signed using the connected Ethereum account. Next, the app sends the profile to the Delivery Service, which returns an authentication token if the profile’s signature is a valid signature of the connected Ethereum account. Finally, the app uses the authentication token to connect to the delivery service.

After the initial sign-in, the user can interact with all users connected to the same delivery service. To connect with users of other delivery services, the user must publish the URL pointing to theirdm3 Profile as ENS text record.

Any subsequent sign-in consists of two steps:

1. Connect an Ethereum account
2. Decryption of the User Storage: The app retrieves the user storage from the selected storage location. The user storage contains the unencrypted salt message and signs it using the Ethereum account to recreate the Storage Encryption Key. This key’s purpose is to decrypt the encrypted part of the user storage.

🔏 Profile Registry

For the protocol to work, there needs to be one registry where the dm3 app can look up dm3 profiles of other users. dm3 uses ENS text records for this purpose. The text record named eth.dm3.profile contains a URL to the actual profile. It is essential to verify the integrity of the profile entry. For example, if the eth.dm3.profile text record contains a simple HTTP-URL, it would be possible to hijack the server and change the profile entry. Therefore, the URL must be an IPFS-URL or an URL containing a hash of the entry.

Example eth.dm3.profile text record entry:

http://delivery.dm3.network/profile/0xbcd6de065fd7e889e3ec86aa2d2780d7553ab3cc?dm3Hash=0x84f89a7...278ca03e421ab50c8

Example Profile Entry:

{
  "profileRegistryEntry": {
    "publicKeys": {
      "publicMessagingKey": "rF5wuvHX6...J6Eip2KG3lQ=",
      "publicSigningKey": "l11foFzMl1J.../btdg9oSdDU="
    },
    "deliveryServiceUrl": "http://delivery.dm3.network"
  },
  "signature": "0x9b2ba...a82abf1b"
}

💾 Storage Management

During delivery, the messages are encrypted with the recipient’s Encryption Public Key. However, the delivery service deletes the messages after they are delivered. To access past messages, the dm3 app stores the messages in the encrypted part of the user storage. The user storage is a JSON file.

The separation of delivery and storage of messages allows the users to decide on the storage location of their sent and received messages. Possible storage locations are:

• Browser storage
• A local file
• The dm3 Storage Service
• Web3 Storage (IPFS)
• Google Drive

Wherever the storage is located, only the user who owns the corresponding Ethereum account key is able to decrypt it.

Further Use Case

The first use case of the dm3 protocol is to send signed and end-to-end encrypted messages between two ENS name owners. However, the protocol can also be used to create public message feeds for ENS name owners (“decentralized Twitter”).

We believe that dm3 can provide a better way for people to communicate and we want to offer it to the world. Christoph Jentzsch, our CEO, has written an article about dm3 and its principles. We encourage you to read it and learn more.

Give dm3 a try today. If you have any questions, our team is always available to help. You can reach us at help.dm3.eth or hello@dm3.network. For the latest news and updates about dm3, be sure to follow us on Twitter.

dm3 — decentralized messaging for web3