There is a quick guide, so try that first; this is a more detailed guide.
It is possible to make contact with someone in Deltachat just like in a regular e-mail client, by typing in their e-mail address and sending them a unencrypted message. But this is not possible using the e-mail addresses Deltachat will give you automatically (Chatmail addresses), because they only work for encrypted mail.
Encryption hides your messages from data harvesters, and it’s a good way to stop spam. Encrypted mail contacts need to be introduced to each other before they can send messages.
This guide tells you how to do encryption introductions, which create encrypted contacts. It is made to be read in order, but different sections are aimed at different levels of expertise. This post will be edited in response to feedback, or you may be able to edit it yourself.
If you can meet with your friends
Can you physically meet with your friend? Can two (or more) of you, with devices you have Deltachat installed on, get together in the same room? If so, scanning QR codes is the best way to do an encryption introduction.
- In the client, click on the QR-code icon. You will see a screen with a big QR code on it. Have your friend do the same.
- One of you should click on the “Scan QR code” button, and scan the QR code on your friend’s screen.
Done! You can now use encrypted chat.
Note: This will work with any version of any Deltachat client (except maybe a few very old ones? Older than 1.0?). The clients do not need to match. In fact, this will work using any softwareu which implements the SecureJoin protocol, even if it is not a chat client.
Meeting in person really is the best and easiest method. If you connect less-directly, you need to be careful not to be fooled by a machine-in-the-middle (MITM) attack. In an MITM attack, you think you are talking directly to your friend, and your friend thinks they are talking directly to you, but both of you are talking to a a lying snoop who relays your messages both ways (and can read and rewrite them).
You can double-check that there is no MITM by comparing the fingerprints of your accounts (in a chat with the friend, under “Encryption Info”, you and your friend should have the same codes). Note that you need to compare these in person, or using a secure channel other than DeltaChat. If you use the MITMed channel, the Machine-In-The-Middle can just rewrite the message to give a fake fingerprint!
If you can’t meet with your friends
Do you have some other secure communications channel to your friends? If so, you can use it to send a contact QR code or contact text code (which is in the form of a web URL, starting “https://”).
First, pick your channel! An end-to-end-encrypted (E2EE) messenger, like Signal or Jami, can be used. Some messengers have an E2EE option, like a Whatsapp “private exchange”, or a Telegram “Secret Chat”. Some claims of E2EE have been dodgy; check them with reputable independent information sources. You could even print your QR code and send it by snailmail, if the postal system is secure.
It is not secure to use WeChat, or any messenger controlled by someone who might want to spy on you, or any messenger that an “AI” tool could be listening to (like Gmail).
MITM WARNING! If you use an insecure channel, then you might get tricked into talking via an impersonator when you think you are talking directly. In-person contactmaking is easier and more secure, so use it instead if you can.
How to get the contact code
In the screen with the big QR code, click on the hamburger icon (three horizontal lines) to copy the QR code, or click on the share icon (three circles connected by lines) to copy the text URL.
Now send this contact code, using the secure channel of your choice.
Your friend must paste the QR image or the text URL into the “Scan QR Code” screen. They will then have a contact.
Done! You can now use encrypted chat. But maybe compare fingerprints first.
The text URL (web address) and the QR code are equivalent. The QR code is just a barcode of the URL. If opened in a browser, the text URLs and QR codes both act as links (if delta.chat is not blocked), but if pasted into Deltachat, the web is not used.
You can also copy-paste QR codes or text URLs between two profiles on your own device. This might be useful if you want to swap profiles.
If you have a trusted friend in common
You don’t all have to meet. Everyone who joins an encrypted group chat is automatically introduced to everyone else in the group. You can also send a contact code to another contact as an attachment. So if someone has an encrypted connection with a friend, they can automatically introduce that friend to anyone else they have an encrypted connection with. And then those people can introduce more people.
MITM WARNING! The friend-in-common could lie to you. Separately, if two of your friends suffered an MITM attack, then they think that they are talking to each other when they are actually both talking to a lying snoop who intercepts and forwards their messages. So when the first friend tries to introduce you to the second friend, they actually introduce you to the snoop, because the snoop is pretending to be the second friend. AND now you are also deceived. You think the snoop is your second friend. If you try to introduce a third friend to the second friend, then the second and third friends will also be talking via the lying snoop.
It is safer to meet in person if possible. If not, enquire about how your friends did their encryption introduction. If they did it in person, and you trust them, it should be safe.
Using a public key registry
Deltachat is designed to let people exchange encryption introductions in person. Publishing your contact information is generally avoided in Deltachat. But it is very convenient. You may want to use a gatehouse profile so that strangers cannot spam you on a profile you use for talking to friends.
There exist public-key registries that publish encryption introductions (public keys are the info that must be exchanged in an encryption introduction; never share your private keys). To use a public key registry, you need to start a chat with a key-lookup bot.
MITM warning!! If you add a bot to a chat, then it can read everything in that chat, just like any other contact can. Don’t add it to chats with anyone else in them. The bot must be trustworthy, and the mailserver of the e-mail address for which you want a key must be trustworthy, because both could MITM you (note that the domain name of the bot’s e-mail address is not an endorsement by the domain owner; if the mailserver allows open registration anyone can set up a bot on that domain). There is open-source bot code you can run on your own server if you like.
Here is a key-lookup bot and its source code.
When you have started a chat with the bot, type “/publish” to permanently publish your public key in a public database online. Again, you may want to use a gatehouse profile, since anyone will be able to see what you published.
Now your friend must also start a chat with a key-lookup bot (not necessarily the same one). They can type any e-mail address to get its public key (in contact form). They must type your e-mail address, then click on the message the bot sends them. This adds your contact to their contact list. Now they can start a new chat with you.
You will also be able to look up the keys of many people who do not use Deltachat. But unless they send e-mails that are Autocrypt-compliant, then the standard free accounts generated in Deltachat (Chatmail accounts) will silently drop their replies. So you might want to warn them of that!
Other public channels
If you have an established account on a secure (https, with TLS that is controlled by someone you trust) website, you could post your contact code (QR code or text URL) there. If the post is public anyone could contact you (and maybe claim to be someone they are not). So you and your friend may want to both post codes, and mutually scan, to prevent an MITM.
Click on the QR icon, then the hamburger icon menu, then “reset QR code” to invalidate the posted QR code(s) or contact URLs once you’ve made the connection. This invalidation will stop someone else reusing your published contact code for an MITM attack in which they pretend to be you. This invalidation does not hide the connection between e-mails you send from that profile and the website post, but it will stop people spamming you with contact requests.
If you want to hide the connection you can use a gatehouse profile; post its contact info, switching to another, more private, profile once you have made contact. Chatmail accounts are free, so using an extra profile is reasonable.
At risk of an MITM, you can also both make contact with a public introduction bot. This is essentially a bot which adds everyone contacting it to a public group. Group members are all introduced to one another.
Note that using an introduction bot is essentially trust-on-first-use. If the bot is dishonest, it could MITM you. You also don’t know who the people are. They might have been MITMed by a dishonest introduction bot that then auto-registered them with an honest introduction bot (the dishonest bot could then invisibly edit anything they post). Groups made by an introduction bot are public groups, of people who may not be whom they claim to be, and they may not be saying what they think they are saying in the chat.
Here are some invite bots: List of public bots, Groupsbot, Invitebot, Majordomo (Majordomo also removes stale group members who stop posting).
A contact made through an introduction bot should probably be considered untrusted and insecure, because it could in theory be MITMed.
Using a shared secret
As a last resort, if you and your friend have a pre-shared secret, you can use it either to establish a new secure connection, or to check that a existing connection is not MITMed (by comparing fingerprints).
The shared secret cannot be something any attacker could guess (even using a program that has scanned all your online communications), and you cannot transmit the secret over the unverified Deltachat chat. You can describe it on Deltachat (e.g. “The password is that silly thing you said to the dog on your birthday”, or “The first sentence of the terrible unpublished novel I wrote when I was nine”), as long as no attacker could guess the shared secret from the description. Your version of the shared secret and your friend’s must be exactly identical, not a single character different. It is both easier and more secure to make encryption introductions and compare fingerprints in person, so don’t use this technique unless you have no better options.
- Send a contact code (QR code or text-URL code) to your friend as above, but over an insecure channel that might be surveilled or altered. Only do this if you really can’t use a secure channel.
- Have your friend use the code set up a chat. You are now in contact, but the chat is unverifed and it might have an MITM! Don’t say anything private.
- Leave the unverified chat and enter your “Saved Messages” chat (basically a chat with yourself).
- Add the Cryptotext app to your saved-messages chat as an attachment. Send and open the app.
- Type the shared secret into the “password” field.
- Paste either your fingerprint or your contact code text URL into the “text” field, and press the button to encrypt
- Send the encrypted text to your friend, by copying it and pasting it into the unverified chat with them. The friend uses the same Cryptotext app (in their saved-messages chat) to decrypt the text, typing in the same shared secret as a password.
- If the decrypted text is a fingerprint, your friend should compare the decrypted text you sent to the fingerprint under “Encryption Info” in the unverified chat. If it does not match, there is an MITM.
- If the decrypted text is a contact code, your friend must paste the text URL into the “Scan QR Code” screen. They will then have a contact they can use to start a new chat with you. The old unverified chat should be deleted. It still could have an MITM.
I understand encrypted e-mail, tell me how to make this thing interoperate with my existing setup
When you attach a contact intro and send it to someone? It is in VCard format (see Github standards list, and Chatmail standard)
If you have a VCard with someone’s key, and attach that VCard as a file to a message, and send it, it will become a contact. Now you know how to manually import your friends’ public keys. Note that not all types of key will work. Putting a VCard in a QR code and scanning it does not work if you are using a free autogenerated (Chatmail) address.
If you go into your “Saved Messages” chat (basically a chat with yourself) and add (as an attachment) an open-source app called “.asc to VCard”, and send that app to yourself (this is how you install WebXCD apps, really), and open the app, you can conveniently switch file formats.
If you use Deltachat with an autogenerated Chatmail address, you can export the password and keys for that address under the advanced settings (except on Android, where there are security issues). Alternately, dig into the SQL database to get the keys. You can then also use that address in any mail client that does IMAP and Autocrypt; K9 is known to work. But it might be easier to create the Chatmail address in the other client; Chatmail servers autocreate accounts on first login.
Be warned that Deltachat clients are very atypical mailclients. They do not use mBox or Maildir format for storage; they use an SQLite database (which is compressed in the per-profile backup files and add-device process). There is currently no way to export chats except by copy-pasting each individual message. The expectation is that the messages are mostly ephemeral and will be deleted soon after receipt. Too many saved messages may affect usability. So using another mail client in parallel, for archiving, may be useful.
Importing private keys to Deltachat
Importing private keys isn’t supported anymore, though it may be possible.