Skip to content
Markus Ottela edited this page Feb 2, 2020 · 35 revisions

11. Pre-shared keys (PSK)

When to use PSKs

Use of PSKs provides post-quantum security and is recommended in cases where the users know and trust each other and where they can meet to exchange the keys. PSKs should never be exchanged with strangers or contacts who might be malicious.

The PSK Key exchange

1. Exchange TFC accounts

The TFC accounts should be exchanged using some authenticated channel. An authenticated (and preferrably confidential) channel such as an end-to-end encrypted Signal-call should also be used to agree on the date and location for exchanging the PSK file.

2. Select the key exchange

Enter the contact's TFC account, nick and select PSK as the key exchange method.

Selecting PSK as the key exchange


3. Create a password for the PSK

PSK needs to be protected during transit, so Transmitter Program prompts the user to enter and confirm a password that needs to be delivered to the contact through some secret channel (e.g., during/after key exchange meeting).

The password should be strong to ensure an attacker who manages to make a copy of the encrypted PSK cannot access it. Next, the user must select the directory for removable media to store the PSK in.

Enter and confirm password that protects the PSK


4. Select location for the PSK file

For this step, the user needs a removable media that is entered into their Source Computer. To protect the user, this removable media must come from a sealed packaging. The user must then choose the removable media as the directory for the PSK in the GUI prompt.

Note: It is unsafe for contact to return the removable media so do not expect to get it back.

Choose a removable media for the PSK


5. Enter confirmation code for keys exported to Destination Computer

The Transmitter Program will then export a copy of the keys to the Receiver Program on destination Computer. Enter the confirmation code for the keys.

Confirmation code prompt for Tx-keys

At this point of the key exchange the Transmitter Program's contact list displays a (No contact key) message next to the key exchange method. This tells the user they have not yet imported the PSK from contact that allows the user to decrypt incoming messages. The next step is to physically exchange the keys.

Transmitter Program displays notification about missing contact key


6. Exchange PSKs

The users must then meet in person, and exchange the PSK transmission media. During transport extreme care must be taken to ensure no adversary gains access to the PSK transmission media.


7. Insert the removable media to Destination Computer.

After the meeting, the user must insert the removable media of the contact to their Destination Computer (the one that runs Receiver Program).

WARNING! If the user accidentally connects the contact's PSK transmission media to their Source Computer instead of their Destination Computer, all security of their TFC endpoint should be assumed to have been lost permanently.
WARNING! If the PSK transmission media contains e.g. a covert transmitter, it might leak data on Destination Computer in real time. The user should never trust PSKs from contacts they don't personally know and trust. Always use X448 in such situations.

8. Import PSK to Receiver Program

To import the PSK, the user must first select the contact, and then enter the command /psk to their Transmitter Program. The command will open a file selection prompt on Receiver Program. They must select the protected PSK file from the contacts transmission media.

Receiver Progam's prompt for PSK file


9. Enter the password

The user must then enter the password given to them by their contact to decrypt the contact's PSK.

Enter and confirm password that protects the PSK


10. Enter the confirmation code

Once Receiver Program has decrypted the PSK file, it will copy the keys to its key database and overwrite the encrypted PSK file. The Receiver Program will then display the user a confirmation code that must be written to the Transmitter Program's prompt.

Enter confirmation code

This code is verifies the user has indeed imported the PSK, so Transmitter Program knows to remove the trailing (No contact key) label from the key exchange type (PSK) when viewing contact details with /names.

Warning about missing contact key has been removed

The key exchange is now complete, but there's one more thing to do:


11. Destroy the PSK transmission media

WARNING! Do not skip this step

Always assume the PSK transmission media received from contact steals sensitive data from Destination Computer. Never give the media back to the contact. It is the responsibility of the contact to know they cannot have their device back. As the Receiver Program's warning instructs, destroy the transmission media to ensure no data escapes the Destination Computer.

Receiver Program overwrites the PSK file on the removable device after keys have been imported. This is however not a strong guarantee. Would and adversary succeed in recovering the PSK file and guessing the password, they could decrypt all messages trivially, as the PSK is the root key from which the forward secret keys are generated.

To guarantee such attacks do not happen, physically destroy the removable media by hammering/drilling/angle grinding the memory chips, The Guardian style.

Clone this wiki locally