Welcome to SecureDrop’s documentation!¶
SecureDrop is an open-source whistleblower submission system that media organizations can use to securely accept documents from and communicate with anonymous sources.
Source Guide¶
Choose who to submit to¶
Each SecureDrop instance is totally independent, and submissions to that instance are only available to journalists associated with that organization.
All organizations have a landing page that provides their own organization-specific recommendations for using SecureDrop. We encourage you to consider an organization’s landing page before submitting to them.
Most organizations make their landing page prominently accessible from their main website’s homepage. You can also find an incomplete list of organizations accepting submissions through SecureDrop on the SecureDrop Directory maintained by Freedom of the Press Foundation.
Get the Tor Browser¶
Each SecureDrop instance has a publicly available Source Interface: a website where sources can create anonymous accounts, submit files and messages, and check back for replies.
Each Source Interface is only available as a Tor Hidden Service, which is a special type of website with an address ending in “.onion” that is only accessible through Tor. Tor is an anonymizing network that makes it difficult for anybody observing the network to associate a user’s identity (e.g. their computer’s IP address) with their activity (e.g. uploading information to SecureDrop).
The easiest and most secure way to use Tor is to download the Tor Browser from the Tor Project website. The Tor Browser is a modified version of the Firefox web browser designed to protect your security and anonymity while using Tor.
Once you have the Tor Browser, launch it and enter the “.onion” address for the Source Interface of the organization that you wish to submit to. You can find this address on the organization’s landing page, or listed on the SecureDrop Directory.
While using the Tor Browser on your personal computer helps hide your activity on the network, it leaves traces (of its own installation) on your local machine. For even more deniability, we recommend booting into a live system such as Tails for a higher level of security. Tails is specifically designed to run on your computer without leaving traces of your activity, and automatically routes all of your Internet browsing through Tor so you can easily access SecureDrop safely.
Making your First Submission¶
Open the Tor Browser and navigate to the .onion address for the SecureDrop Source Interface you wish to make a submission to. The page should look similar to the screenshot below, although it will probably have a logo specific to the organization you are submitting to.
If this is the first time you’re using the Tor browser, it’s likely that you have Javascript enabled and that the Security Slider that Tor browser provides is set to “Low”. If you do, there will be a purple warning banner at the top of the page that encourages you to disable Javascript and turn up the Security Slider to “High”:
Click the Learn how to set it to high link in the warning banner and a message bubble will pop up explaining how to disable Javascript and turn up the Slider:
Follow the instructions and the page should refresh automatically. Note that this will change the slider and disable Javascript for every page in your Tor Browser, and this setting will persist across browser sessions.
The page should look similar to the screenshot below. If this is the first time you are using SecureDrop, click the Submit Documents button.
You should now see a screen that shows the unique codename that SecureDrop has generated for you. Note that your codename will not be the same as the codename shown in the image below. It is extremely important that you both remember this code and keep it secret. After submitting documents, you will need to provide this code to log back in and check for responses.
The best way to protect your codename is to memorize it. If you cannot memorize it right away, we recommend writing it down and keeping it in a safe place at first, and gradually working to memorize it over time. Once you have memorized it, you should destroy the written copy.
Tip
For detailed recommendations on best practices for managing your passphrase, check out Passphrase Best Practices.
Once you have generated a codename and put it somewhere safe, click Continue.
You will next be brought to the submission interface, where you may upload a document, enter a message to send to journalists, or both. You can only submit one document at a time, so you may want to combine several files into a zip archive if necessary. The maximum submission size is currently 500MB. If the files you wish to upload are over that limit, we recommend that you send a message to the journalist explaining this, so that they can set up another method for transferring the documents.
When your submission is ready, click Submit.
After clicking Submit, a confirmation page should appear, showing that your message and/or documents have been sent successfully. On this page you can make another submission or view responses to your previous messages.
Once you are finished submitting documents, be certain you have saved your secret codename and then click the Exit button:
The final step to clearing your session is to restart Tor Browser for optimal security. You can either close the browser entirely or follow the notification: click on the Tor onion in the toolbar, click New Identity and then click Yes in the dialog box that appears to confirm you’d like to restart Tor Browser:
Continuing the Conversation¶
If you have already submitted a document and would like to check for responses, click the Check for a Response button on the media organization’s SecureDrop homepage.
The next page will ask for your secret codename. Enter it and click Continue.
If a journalist has responded, their message will appear on the next page. This page also allows you to upload another document or send another message to the journalist. Before leaving the page, you should delete any replies. In the unlikely event that someone learns your codename, this will keep your identity secret as no one will be able to see the previous correspondences you had with journalists.
After you delete the message from the journalist, make sure you see the below message.
If the server experiences a large number of new sources signing up at once and is overloaded with submissions, the journalist will flag your message on their end and you will see the message below. They can’t write a reply to you until you’ve seen this message for security reasons. This will only happen the first time a journalist replies and with subsequent replies you will skip this step. Click Refresh or log in again to see if a journalist has responded.
Repeat these steps to continue communicating with the journalist.
Journalist Guide¶
This guide presents an overview of the SecureDrop system for a journalist. It covers the core functions necessary to start working with the platform: logging in securely, viewing documents, editing documents, and interacting with sources.
Creating a GPG Key¶
Each journalist needs a personal GPG key for encrypting files. A GPG key has two parts: a public key and a private key. The private key, used for decryption, stays on the Journalist Workstation. The public key, used for encryption, is copied to the Secure Viewing Station.
If you do not yet have a GPG key, follow the instructions for your operating system to set one up:
Connecting to the Journalist Interface¶
Journalists viewing documents on SecureDrop must connect to the Journalist Interface using the Tails operating system on a USB drive. Your administrator can help provide you with a Tails drive.
Important
See our guide on setting up Tails for the Admin and Journalist Workstation before continuing.
Note
The Tails OS makes using SecureDrop very different from other computing experiences. The added layers of security mean extra steps each time you want to login. With practice, you will become increasingly comfortable with the process.
Each journalist has an authenticated Tor hidden service URL for logging in to the Journalist Interface. This must be done using the Tails operating system. Click the Journalist Interface icon on the desktop. This will open Tor Browser to a “.onion” page. Log in with your username, passphrase, and two-factor authentication token, as shown in the first screenshot below. (See Using YubiKey with the Journalist Interface.)
Interacting With Sources¶
If any sources have uploaded documents or sent messages, they will be listed on the homepage by codename.
Note
Codenames that journalists see are different than the codenames visible to sources.
Click on a codename to see the dedicated page for that source. You will see all of the messages that they have written and documents that they have uploaded. If the name of a source is difficult to say or remember, you can rename a source using the Change codename button next to their current codename.
Tip
You can also Star interesting or promising sources to easily return to them later.
If you want to reply to the source, write your message in the text field and click Submit.
Once your reply has been successfully submitted, you will be returned to the source page and see a message confirming that the reply was stored. The source will see your reply the next time they log in with their unique codename. To minimize sensitive data retention, the source interface encourages the source to delete the reply after reading it. If you notice one or more replies disappear from the list of documents, you may infer that the source read and deleted them. You may also delete replies if you change your mind after sending them.
Documents and messages are encrypted to the SecureDrop installation’s GPG public key. In order to read the messages or look at the documents you will need to transfer them to the Secure Viewing Station.
Flag for reply¶
If the server experiences a large number of new sources signing up at once and is overloaded with submissions, you will need to flag sources for reply before you can communicate with them. Click the Flag this source for reply button.
After clicking the Flag this source for reply button, you will see this confirmation page. Click through to get back to the page that displays that source’s documents and replies.
You will not be able to reply until after the source logs in again and sees that you would like to talk to him or her. So you may have to sit and wait. After the source sees that you’d like to reply, a GPG key pair will automatically be generated and you can log back in and send a reply.
Moving Documents to the Secure Viewing Station¶
Documents sent by sources can only be viewed on the Secure Viewing Station. After clicking on an individual source, you will see the page below with any messages that source has sent you. Click on a document or message name to save it, or select a number of documents and save them all at once by clicking Download Selected.
A dialog box will appear asking if you want to Open or Save the file. Select Save File:
In order to protect you from malware, the browser in Tails will only
allow you to download documents to a special persistent folder located
at /home/amnesia/Tor Browser.
Tip
The special folder mentioned here is called Tor Browser, not “Persistent.” Attempting to download directly into the Persistent folder will only lead to frustration.
Once downloaded to this folder, move the document to the designated USB stick you intend to use to transfer the documents from your Journalist Workstation to the Secure Viewing Station. This storage device will be known as your Transfer Device.
Eject the Transfer Device from the Journalist Workstation.
Next, boot up the Secure Viewing Station using Tails and enter the passphrase for the Secure Viewing Station persistent volume. Once you have logged in, plug in the Transfer Device.
Note
The Secure Viewing Station and Journalist Workstation are on separate Tails USB drives.
Click on the computer icon on your desktop, then on the Transfer Device. Drag and drop the file into your Persistent folder.
Important
Copy these documents to the Persistent folder before decrypting them. Otherwise you might accidentally decrypt the documents on the USB stick, and they could be recoverable in the future.
After successfully copying, erase the files from your Transfer Device by returning to the Transfer Device folder. Right click on the files that need removal and click “Wipe” to securely delete the files from your device.
Decrypting on the Secure Viewing Station¶
To decrypt documents, return to your Persistent folder and double-click on the zipped file folder. After you extract the files, click on each file individually. A prompt will ask you for the application PGP key passphrase to decrypt the document.
When you decrypt the file it will have the same filename, but without “.gpg” at the end.
You can now double-click on the decrypted file to open it in its default application.
If the default application does not work, you can right-click on the document and choose Open with Other Application… to try opening the document with OpenOffice Writer, or Document Viewer. You might also need to right-click on a file and choose Rename… to rename a document with a proper file extension (for example, “.jpg” instead of “.jpeg”).
Working with Documents¶
This section describes how to handle unusual file formats, safely research submissions, remove metadata, and mitigate risks from submitted malware.
Handling File Formats¶
SecureDrop accepts submissions of any file type. Tails comes with pre-installed applications for securely working with documents, including the Tor Browser, an office suite, graphics tools, desktop publishing tools, audio tools, and printing and scanning tools.
Pre-Encrypted Submissions¶
SecureDrop sources can optionally encrypt prior to submitting to SecureDrop. This means that once you decrypt the document as you usually do by double clicking the document in the file navigator, there will be another layer of encryption.
Most often, the file will be encrypted to the SecureDrop key. If the file is encrypted to your SecureDrop key, you should be able to double click the file as usual once more in the SVS and it should decrypt.
However, it’s also possible the file is encrypted to another key, potentially
your personal key. If this occurs, you will get an error message in Tails that
reads “Decryption failed. You probably do not have the decryption key”.
To determine which key was used, if you are comfortable at the command line, you
can open the Terminal, navigate to the file, and use:
gpg --decrypt NAME_OF_FILE
replacing NAME_OF_FILE with the name of the file you wish to decrypt. This
command will tell you what key was used to encrypt the file. If you are not
comfortable at the command line, contact your SecureDrop administrator or
Freedom of the Press Foundation for assistance.
Warning
You should not transfer source material off the SVS for decryption, and should instead transfer cryptographic keys to the device for decryption and metadata removal.
Researching Submissions¶
Journalists should take care to research submissions using the Tor Browser, ideally in a new Tails session for highly sensitive submissions. For more information, visit the Tails guide to working with sensitive documents.
Removing Metadata¶
Tails also comes with the Metadata Anonymisation Toolkit (MAT) that is used to help strip metadata from a variety of types of files, including png, jpg, OpenOffice/LibreOffice documents, Microsoft Office documents, pdf, tar, tar.bz2, tar.gz, zip, mp3, mp2, mp1, mpa, ogg, and flac. You can open MAT by clicking Applications in the top left corner, Accessories, Metadata Anonymisation Toolkit.
We recommend always doing as much work as possible inside of Tails before copying documents back to your Journalist Workstation. This includes stripping metadata with MAT.
When you no longer need documents, you can right-click on them and choose Wipe to delete them.
Risks From Malware¶
As long as you are using the latest version of Tails, you should be able to open submitted documents with a low risk of malicious files compromising the Secure Viewing Station. However, even if a compromise does occur, Tails is designed so that the next time you reboot, the malware will be gone.
Never scan QR codes from the Secure Viewing Station using a network connected device. These QR codes can contain links that your connected device will automatically visit. In general, you should take care when opening any links provided in a SecureDrop submission, as this can leak information to third parties. If you are unsure if a link is safe to click, you should consult your digital security staff or Freedom of the Press Foundation for assistance.
Encrypting and Moving Documents to the Journalist Workstation¶
Before moving documents back to the Transfer Device to copy them to your workstation, encrypt them to your personal GPG key that you imported when setting up the Secure Viewing Station.
To do this, right-click on the document you want to encrypt and choose Encrypt….
Then choose your public key (and, if you choose, any additional keys, such as an editor’s) and click OK.
When you are done encrypting, you will have another document with the same filename but ending in “.gpg”. This file is encrypted to the GPG keys you selected. You can safely copy these encrypted files to the Transfer Device to transfer them to your workstation.
Decrypting and Preparing to Publish¶
Plug the Transfer Device into your workstation computer and copy over the encrypted documents. Decrypt them with GPG.
You are now ready to write articles and blog posts, edit video and audio, and begin publishing important, high-impact work!
Tip
Check out our SecureDrop Promotion Guide to read about encouraging sources to use SecureDrop.
Admin Guide¶
You (the admin) should have your own username and password, plus two-factor authentication through either the Google Authenticator app on your smartphone or a YubiKey.
Responsibilities¶
The SecureDrop architecture contains multiple hardened servers, and while we have automated many of the installation and maintenance tasks, a skilled Linux admin and some manual intervention is required to responsibly run the system.
This section outlines the tasks the admin is responsible for in order to ensure that the SecureDrop server continues to be a safe place for sources to talk to journalists.
Keep your SecureDrop Server Updated¶
You should maintain awareness of SecureDrop updates and take any required manual action if requested in the SecureDrop Release Blog. We recommend subscribing to the SecureDrop RSS Feed to stay apprised of new updates.
Most often, the SecureDrop server will automatically update via apt. However, occasionally you will need to run the Ansible playbooks. We will inform you in the release blog when this is the case. If you are onboarded to our SecureDrop Support Portal, we will let you know in advance of major releases if manual intervention will be required.
Keep your Network Firewall Updated¶
Given all traffic first hits the network firewall as it faces the non-Tor public network, you will want to ensure that critical security patches are applied.
Be informed of potential updates to your network firewall. If you’re using the suggested network firewall by FPF you can subscribe to the Netgate RSS Feed to be alerted when releases occur. If critical security updates need to be applied, you can do so through the firewall’s pfSense WebGUI. Refer to our Keeping pfSense up to date documentation or the official pfSense Upgrade Docs for further details on how to update the suggested firewall.
Keep your Tails Drives Updated¶
You should apply updates to your Tails drives as they are released, as they can contain critical security fixes. Subscribe to the Tails RSS Feed to be alerted of new releases. The online Tails drives, once booted and connected to Tor, will alert you if upgrades are available. Follow the Tails Upgrade Documentation on how to upgrade the drives.
Monitor OSSEC alerts for Unusual Activity¶
You should decrypt and read your OSSEC alerts. Report any suspicious events to FPF through the SecureDrop Support Portal. See the OSSEC Guide for more information on common OSSEC alerts.
Warning
Do not post logs or alerts to public forums without first carefully examining and redacting any sensitive information.
Adding Users¶
Now you can add new logins for the journalists at your news organization who will be checking the system for submissions. Make sure the journalist is physically in the same room as you when you do this, as they will have to scan a barcode for their two-factor authentication. Since you’re logged in, this is the screen you should see now:
In the top right corner click the “Admin” link, which should bring you to this page:
Once there, click ‘Add User’ button, which will take you to this page:
Here, you will hand the keyboard over to the journalist so they can create their own username. Once they’re done entering a username for themselves, have them write down their pre-generated diceware passphrase. Then, you will select whether you would like them to also be an admin (this allows them to add or delete other journalist accounts), and whether they will be using Google Authenticator or a YubiKey for two-factor authentication.
Tip
Consider using the alternative FreeOTP application for mobile two-factor authentication.
Google Authenticator¶
If they are using Google Authenticator for their two-factor, they can just proceed to the next page:
At this point, the journalist should make sure they have downloaded the Google Authenticator app to their smartphone. It can be installed from the Apple Store for an iPhone or from the Google Play store for an Android phone. Once you download it and open it, the app does not require setup. It should prompt you to scan a barcode. The journalist should use their phone’s camera to scan the barcode on the screen.
If they have difficulty scanning the barcode, they can use the “Manual Entry” option and use their phone’s keyboard to input the random characters that are highlighted in yellow.
Inside the Google Authenticator app, a new entry for this account will appear on the main screen, with a six digit number that recycles to a new number every thirty seconds. Enter the six digit number under “Verification code” at the bottom of the screen, and hit enter.
If Google Authenticator was set up correctly, you will be redirected back to the Admin Interface and will see a flashed message that says “Two factor token successfully verified for user new username!”.
YubiKey¶
If the journalist wishes to use a YubiKey for two-factor authentication, check the box next to “I’m using a YubiKey”. You will then need to enter the OATH-HOTP Secret Key that your YubiKey is configured with. For more information, read the YubiKey Setup Guide.
Once you’ve configured your YubiKey and entered the Secret Key, click Add user. On the next page, enter a code from your YubiKey by inserting it into the workstation and pressing the button.
If everything was set up correctly, you will be redirected back to the Admin Interface, where you should see a flashed message that says “Two factor token successfully verified for user new username!”.
Congratulations! You have successfully set up a journalist on SecureDrop. Make sure the journalist remembers their username and password and always has their 2 factor authentication device in their possession when they attempt to log in to SecureDrop.
Updating the Servers¶
Sometimes you will want to update the system configuration on the SecureDrop servers. For example, to customize the logo on the source interface, or change the PGP key that OSSEC alerts are encrypted to. You can do this from your Admin Workstation by following the procedure described in this section.
Updating system configuration¶
The server configuration is stored on the Admin Workstation in
~/Persistent/securedrop/install_files/ansible-base/group_vars/all/site-specific.
If you want to update the system configuration, there are two options:
- Manually edit the
site-specificfile to make the desired modifications. - From
~/Persistent/securedrop, run./securedrop-admin sdconfig --force, which will require you to retype each variable insite-specific.
Once you have edited the site-specific server configuration file, you will
need to apply the changes to the servers. From ~/Persistent/securedrop:
./securedrop-admin install
Note
If you see an error running ./securedrop-admin install, and
believe it may be an intermittent issue (for example, due to losing
network connectivity to the servers), it is safe to run the
./securedrop-admin install command again. If you see the same
issue consistently, then you will need to troubleshoot it.
Once the install command has successfully completed, the changes are applied. Read the next section if you have multiple admins.
Managing site-specific updates on teams with multiple admins¶
Organizations with multiple admins should establish a protocol to communicate
any changes one admin makes to the site-specific configuration file on the server.
Currently, when one admin pushes changes in site-specific to the server, the
changes will not sync to the local site-specific file on the remaining admin workstations.
Without being aware of changes made to site-specific, admins run the risk of pushing old
information to the servers. This can affect the receipt of OSSEC alerts, viability of the
Submission Key, among other critical components of the SecureDrop environment.
There are multiple ways to avoid pushing out-of-date information to the servers.
We recommend admins establish a secure communication pipeline to alert fellow admins
of any changes made to site-specific on the server. That clues every admin in on
changes in real time, providing all team members with a reminder to manually update
all site-specific files.
In addition to secure group communications, admins can learn of updates to the server by monitoring OSSEC alerts. (Please note that while an OSSEC alert can notify you of the occurrence of an update to the server, it may not reveal the content of the change.) Another management option would be SSHing into the server and manually inspecting the configuration to identify any discrepancies.
Passphrase Best Practices¶
All SecureDrop users—Sources, Journalists, and Admins—are required to memorize at least one passphrase. This document describes best practices for passphrase management in the context of SecureDrop.
General Best Practices¶
Do memorize your passphrase.
If necessary, do write your passphrase down temporarily while you memorize it.
Caution
Do store your written passphrase in a safe place, such as a safe at home or on a piece of paper in your wallet. Do destroy the paper as soon as you feel comfortable that you have the passphrase memorized. Do not store your passphrase on any digital device, such as your computer or mobile phone.
Do review your passphrase regularly. It’s easy to forget a long or complex passphrase if you only use it infrequently.
Tip
We recommend reviewing your passphrase (e.g. by ensuring that you can log in to your SecureDrop account) on at least a monthly basis.
Do not use your passphrase anywhere else.
If you use your SecureDrop passphrase on another system, a compromise of that system could theoretically be used to compromise SecureDrop. You should avoid reusing passwords in general, but it is especially important to avoid doing so in the context of SecureDrop.
For Sources¶
Your passphrase is associated with your pseudononymous account and all of your activity on the SecureDrop server. In order to preserve your anonymity, you should avoid creating physical or digital associations between yourself and your passphrase as much as possible.
For Journalists/Admins¶
While Sources only have one passphrase that they are required to manage, Journalists and Admins unfortunately have to manage a veritable menagerie of credentials.
We have tried to minimize the number of credentials that Journalists and
admins actually have to remember by automating the storage and entry
of credentials on the Tails workstations wherever possible. For example,
shortcut icons are created on the Desktop of each Tails workstation to make it
easy to access the Tor Hidden Services without having to look up their
.onion addresses every time.
Ideally, each admin would only have to:
- Keep track of their Admin Workstation Tails USB.
- Remember the passphrase to unlock the persistent storage on that Tails USB.
And each Journalist would only have to:
- Keep track of their Journalist Workstation Tails USB.
- Keep track of their Secure Viewing Station Tails USB (and the associated Secure Viewing Station computer).
- Remember the passphrases to unlock the persistent storage on both of these Tails USBs.
Memorizing further passwords beyond the ones listed above is counterproductive: an attacker with access to any of those environments would be able to pivot to anything they wish to access, and increasing the burden of keeping track of additional credentials is unpleasant for journalists and admins and increases the risk that they will either forget their credentials, compromising the availability of the system, or compensate for the difficulty by using weak or reused credentials, potentially compromising the security of the system.
There is a detailed list of the credentials that must be managed by each end user role in Passphrases. We recommended using the KeePassX password manager included in Tails to store your credentials and minimize the passphrases that you need to memorize to just the passphrases for the persistent storage on your Tails USBs.
Overview¶
SecureDrop is an open-source whistleblower submission system that media organizations can use to securely accept documents from and communicate with anonymous sources. It was originally created by the late Aaron Swartz and is currently managed by Freedom of the Press Foundation.
Tip
Check out What makes SecureDrop Unique to read more about SecureDrop’s approach to keeping sources safe.
Technical Summary¶
SecureDrop is a tool for sources to communicate securely with journalists. The SecureDrop application environment consists of three dedicated computers:
- Secure Viewing Station: An air-gapped laptop running the
- Tails operating system from a USB stick that journalists use to decrypt and view submitted documents.
- Application Server: Ubuntu server running two segmented Tor hidden
- services. The source connects to the Source Interface, a public-facing Tor hidden service, to send messages and documents to the journalist. The journalist connects to the Journalist Interface, an authenticated Tor hidden service, to download encrypted documents and respond to sources.
- Monitor Server: Ubuntu server that monitors the Application Server
- with OSSEC and sends email alerts.
In addition to these dedicated computers, the journalist will also use their normal workstation computer:
- Journalist Workstation: The every-day laptop that the journalist uses for
- their work. The journalist will use this computer to connect to the Application Server to download encrypted documents that they will transfer to the Secure Viewing Station. The Journalist Workstation is also used to respond to sources via the Journalist Interface.
Depending on the news organization’s threat model, it is recommended that journalists always use the Tails operating system on their Journalist Workstation when connecting to the Application Server. Alternatively, this can also be its own dedicated computer.
These computers should all physically be in your organization’s office.
Infrastructure¶
There are four main components of SecureDrop: the servers, the admins, the sources, and the journalists.
Servers¶
At SecureDrop’s heart is a pair of severs: the Application (“App”) Server, which runs the core SecureDrop software, and the Monitor (“Mon”) Server, which keeps track of the Application Server and sends out alerts if there’s a problem. These two servers run on dedicated hardware connected to a dedicated firewall appliance. They are typically located physically inside the newsroom.
Admins¶
The SecureDrop servers are managed by a systems admin; for larger newsrooms, there may be a team of systems admins. The admin uses a dedicated Admin Workstation running Tails and connects to the Application and Monitor Servers over authenticated Tor Hidden Services and manages them using Ansible.
Sources¶
A source submits documents and messages by using Tor Browser (or Tails) to access the Source Interface: a public Tor Hidden Service. Submissions are encrypted in place on the Application Server as they are uploaded.
Journalists¶
Journalists working in the newsroom use two machines to interact with SecureDrop. First, they use a Journalist Workstation running Tails to connect to the Journalist Interface, an authenticated Tor Hidden Service. Journalists download GPG-encrypted submissions and copy them to a Transfer Device (a thumb drive or DVD). Those submissions are then connected to the airgapped Secure Viewing Station (SVS) which holds the key to decrypt them. Journalists can then use the SVS to read, print, and otherwise prepare documents for publication. Apart from those deliberately published, decrypted documents are never accessed on an Internet-connected computer.
Note
The terms in italics are terms of art specific to SecureDrop. The Terminology Guide provides more-precise definitions of these and other terms. SecureDrop is designed against a comprehensive Threat Model, and has a specific notion of the roles that are involved in its operation.
Operation¶
Planning & Preparation¶
Setting up SecureDrop is a multi-step process. Before getting started, you should make sure that you’re prepared to operate and maintain it. You’ll need a systems admin who’s familiar with Linux, the GNU utilities, and the Bash shell. You’ll need the hardware on which SecureDrop runs — this will normally cost $2000-$3000 dollars. The journalists in your organization will need to be trained in the operation of SecureDrop, and you’ll need to publish and promote your new SecureDrop instance afterwards — using your existing websites, mailing lists, and social media.
It is recommended that you have all of this planned out before you get started. If you need help, contact the Freedom of the Press Foundation who will be glad to help walk you through the process and make sure that you’re ready to proceed.
Technical Setup¶
Once you are familiar with the architecture and have all the hardware, setting up SecureDrop will take at least a day’s work for your admin. We recommend that you set aside at least a week to complete and test your setup.
Provisioning & Training¶
Once SecureDrop is installed, journalists will need to be provided with accounts, two-factor tokens, workstations, and so on — and then trained to use these tools safely and reliably. You will probably also need to train additional backup admins so that you can be sure that your SecureDrop setup keeps running even when your main admin is on holiday.
Introducing staff to SecureDrop takes half a day. Training a group to use SecureDrop proficiently takes at least a day — and a single trainer can only work with so many people at once. You will probably need to run several training sessions to instruct an entire newsroom. Depending on staff availability, training and provisioning may take a week or more. If you have multiple offices, training will need to happen at each location. Again, the Freedom of the Press Foundation are happy to help you plan and train your team.
Going Public¶
Once you have a SecureDrop instance and your team knows how to use it, you should test it thoroughly and then tell the world. The Freedom of the Press Foundation are happy to help you check that your SecureDrop setup is up-to-code and properly grounded. After that you’ll want to check out the best practices for your SecureDrop landing page and our guide to promoting your SecureDrop instance.
Terminology¶
A number of terms used in this guide, and in the SecureDrop workflow diagram, are specific to SecureDrop. The list below attempts to enumerate and define these terms.
Source¶
The Source is the person who submits documents to SecureDrop, and may use SecureDrop to communicate with a Journalist. A Source will always access SecureDrop through the Source Interface, and must do so using Tor.
Instructions for using SecureDrop as a Source are available in our Source Guide.
Journalist¶
The Journalist uses SecureDrop to communicate with and download documents submitted by the Source. Journalists do this by using the Journalist Workstation to connect to the Journalist Interface over Tor.
The Journalist also uses a Transfer Device to move documents to the Secure Viewing Station. If a Journalist chooses to release any of these documents, they can be prepared for publication on the Secure Viewing Station before being transferred to an Internet-connected computer.
Instructions for using SecureDrop as a Journalist are available in our Journalist Guide.
Application Server¶
The Application Server runs the SecureDrop application. This server hosts both the website that sources access (the Source Interface) and the website that journalists access (the Journalist Interface). Sources, journalists, and admins may only connect to this server using Tor.
Monitor Server¶
The Monitor Server keeps track of the Application Server and sends out an email alert if something seems wrong. Only system admins connect to this server, and they may only do so using Tor.
Source Interface¶
The Source Interface is the website that sources will access to submit documents and communicate with journalists. This site is hosted on the Application Server and can only be accessed over Tor.
Instructions for using the Source Interface are available in our Source Guide.
Journalist Interface¶
The Journalist Interface is the website that journalists access to download new documents and communicate with sources. This site is hosted on the Application Server and can only be accessed over Tor. In previous releases, this was called the Document Interface, but we have renamed it to avoid ambiguity.
Instructions for using the Journalist Interface are available in our Journalist Guide.
Journalist Workstation¶
The Journalist Workstation is a machine that is online and used together with the Tails operating system on the online USB stick. This machine will be used to connect to the Journalist Interface, download documents, and move them to the Secure Viewing Station using the Transfer Device.
Instructions for using the Journalist Workstation are available in our Journalist Guide.
Admin Workstation¶
The Admin Workstation is a machine that the system admin can use to connect to the Application Server and the Monitor Server using Tor and SSH. The admin will also need to have an Android or iOS device with the Google Authenticator app installed.
Secure Viewing Station¶
The Secure Viewing Station (or SVS for short) is a machine that is kept offline and only ever used together with the Tails operating system on the offline USB stick. This machine will be used to generate GPG keys for all journalists with access to SecureDrop, as well as to decrypt and view submitted documents.
Since this machine will never touch the Internet or run an operating system other than Tails on a USB, it does not need a hard drive or network device. We recommend physically removing the drive and any networking cards (wireless, Bluetooth, etc.) from this machine.
This is also referred to as the “airgapped computer,” meaning there is a gap between it and a computer connected to the Internet.
Two-Factor Authenticator¶
There are several places in the SecureDrop architecture where two-factor authentication is used to protect access to sensitive information or systems. These instances use the standard TOTP and/or HOTP algorithms, and so a variety of devices can be used to provide two-factor authentication for devices. We recommend using one of:
- An Android or iOS device with Google Authenticator installed
- A YubiKey
Transfer Device¶
The Transfer Device is the physical media used to transfer encrypted documents from the Journalist Workstation to the Secure Viewing Station. Examples: a dedicated USB stick, CD-R, DVD-R, or SD card.
If you use a USB stick for the Transfer Device, we recommend using a small one (4GB or less). It will be necessary to securely wipe the entire device at times, and this process takes longer for larger devices.
Depending on your threat model, you may wish to only use one-time use media (such as CD-R or DVD-R) for transferring files to and from the SVS. While doing so is cumbersome, it reduces the risk of malware (that could be run simply by opening a malicious submission) exfiltrating sensitive data, such as the private key used to decrypt submissions or the content of decrypted submissions.
When we use the phrase “sneakernet” we mean physically moving documents with the Transfer Device from one computer to another.
Passphrases¶
Each individual with a role (admin or journalist) at a given SecureDrop instance must generate and retain a number of strong, unique passphrases. The document is an overview of the passphrases, keys, two-factor secrets, and other credentials that are required for each role in a SecureDrop installation.
Note
We encourage each end user to use KeePassX, an easy-to-use password manager included in Tails, to generate and retain strong and unique passphrases. We have created a template password database that you can use to get started. For more information, see the Tails Guide.
Tip
For best practices on managing passphrases, see Passphrase Best Practices.
Admin¶
The admin will be using the Admin Workstation with Tails to connect to the Application Server and the Monitor Server using Tor and SSH. The tasks performed by the admin will require the following set of passphrases:
- A password for the persistent volume on the Admin Live USB.
- A master password for the KeePassX password manager, which unlocks
passphrases to:
- The Application Server and the Monitor Server (required to be the same).
- The network firewall.
- The SSH private key and, if set, the key’s passphrase.
- The GPG key that OSSEC will encrypt alerts to.
- The admin’s personal GPG key.
- The credentials for the email account that OSSEC will send alerts to.
- The Hidden Services values required to connect to the App and Monitor Server.
The admin will also need to have an Android or iOS device with the Google Authenticator app installed. This means the admin will also have the following two credentials:
- The secret code for the Application Server’s two-factor authentication.
- The secret code for the Monitor Server’s two-factor authentication.
Journalist¶
The journalist will be using the Journalist Workstation with Tails to connect to the Journalist Interface. The tasks performed by the journalist will require the following set of passphrases:
- A master password for the persistent volume on the Tails device.
- A master password for the KeePassX password manager, which unlocks
passphrases to:
- The Hidden Service value required to connect to the Journalist Interface.
- The Journalist Interface.
- The journalist’s personal GPG key.
The journalist will also need to have a two-factor authenticator, such as an Android or iOS device with Google Authenticator installed, or a YubiKey. This means the journalist will also have the following credential:
- The secret code for the Journalist Interface’s two-factor authentication.
Secure Viewing Station¶
The journalist will be using the Secure Viewing Station with Tails to decrypt and view submitted documents. The tasks performed by the journalist will require the following passphrases:
- A master password for the persistent volume on the Tails device.
The backup that is created during the installation of SecureDrop is also encrypted with the application’s GPG key. The backup is stored on the persistent volume of the Admin Live USB.
Hardware¶
This document outlines the required hardware components necessary to successfully install and operate a SecureDrop instance, and recommends some specific components that we have found to work well. If you have any questions, please email securedrop@freedom.press.
Hardware Overview¶
For an installation of SecureDrop, you must acquire:
- 2 computers with memory and hard drives to use as the SecureDrop servers.
- Mouse, keyboard, monitor (and necessary dongle or adapter) for installing the servers.
- Dedicated physical computers for the Admin, Journalist, and Secure Viewing Station that can boot to Tails. At minimum this is 2 computers.
- Dedicated airgapped hardware for the mouse, keyboard, and monitor (only if you are using a desktop for the Secure Viewing Station).
- Network firewall.
- At least 3 ethernet cables.
- Plenty of USB sticks: 1 drive for the master Tails stick, 1 drive for each Secure Viewing Station, 1 drive for each Transfer drive, and 1 drive for each admin and journalist.
In the sections that follow, we provide additional details on each item.
Required Hardware¶
Servers¶
These are the core components of a SecureDrop instance.
- Application Server: 1 physical server to run the SecureDrop web services.
- Monitor Server: 1 physical server which monitors activity on the Application Server and sends email notifications to an admin.
- Network Firewall: 1 physical computer that is used as a dedicated firewall for the SecureDrop servers.
We are often asked if it is acceptable to run SecureDrop on cloud servers (e.g. Amazon EC2, DigitalOcean, etc.) or on dedicated servers in third party datacenters instead of on dedicated hardware hosted in the organization. This request is generally motivated by a desire for cost savings and/or convenience. However: we consider it critical to have dedicated physical machines hosted within the organization for both technical and legal reasons:
- While the documents are stored encrypted at rest (via PGP) on the SecureDrop Application Server, the documents hit server memory unencrypted (unless the source used the GPG key provided to encrypt the documents first before submitting), and are then encrypted in server memory before being written to disk. If the machines are compromised then the security of source material uploaded from that point on cannot be assured. The machines are hardened to prevent compromise for this reason. However, if an attacker has physical access to the servers either because the dedicated servers are located in a datacenter or because the servers are not dedicated and may have another virtual machine co-located on the same server, then the attacker may be able to compromise the machines. In addition, cloud servers are trivially accessible and manipulable by the provider that operates them. In the context of SecureDrop, this means that the provider could access extremely sensitive information, such as the plaintext of submissions or the encryption keys used to identify and access the Tor Hidden Services.
- In addition, attackers with legal authority such as law enforcement agencies may (depending on the jurisdiction) be able to compel physical access, potentially with a gag order attached, meaning that the 3rd party hosting your servers or VMs may be legally unable to tell you that law enforcement has been given access to your SecureDrop servers.
One of the core goals of SecureDrop is to avoid the potential compromise of sources through the compromise of third party communications providers. Therefore, we consider the use of virtualization for production instances of SecureDrop to be an unacceptable compromise and do not support it. Instead, dedicated servers should be hosted in a physically secure location in the organization itself. While it is technically possible to modify SecureDrop’s automated installation process to work on virtualized servers (for example, we do so to support our CI pipeline), doing so in order to run it on cloud servers is at your own risk and without our support or consent.
Workstations¶
Note
SecureDrop depends on the Tails operating system for its bootable USB drives. Since the release of Tails 3.0, 32-bit computers are no longer supported.
To see if you have a 64-bit machine, run uname -m from a terminal. If you
see x86_64, then Tails should work on your current machine. If, on the
other hand, you see i686, your current machine will not work with Tails
3.0 or greater. For more details, see the Tails website.
These components are necessary to do the initial installation of SecureDrop and to process submissions using the airgapped workflow.
Secure Viewing Station (SVS)¶
1 physical computer used as an airgap to decrypt and view submissions retrieved from the Application Server.
The chosen hardware should be solely used for this purpose and should have any wireless networking hardware removed before use.
Admin/Journalist Workstation(s)¶
At least 1 physical computer that is used as a workstation for SecureDrop admins and/or journalists.
Each Admin and Journalist will have their own bootable Tails USB with an encrypted persistent partition that they will use to access SecureDrop. You will need at least one workstation to boot the Tails USBs, and may need more depending on: the number of admins/journalists you wish to grant access to SecureDrop, whether they can share the same workstation due to availability requirements, geographic distribution, etc.
USB drive(s)¶
At least 2 USB drives to use as a bootable Tails USB for the SVS and the Admin Tails/Journalist Tails.
If only one person is maintaining the system, you may use the same Tails instance as both the Admin Tails and the Journalist Tails; otherwise, we recommend buying 1 drive for each admin and each journalist.
We also recommend buying two additional USBs to use as bootable backups of the SVS and Admin Tails.
Two-factor authenticator: Two-factor authentication is used when connecting to different parts of the SecureDrop system. Each admin and each journalist needs a two-factor authenticator. We currently support two options for two-factor authentication:
- Your existing smartphone with an app that computes TOTP codes (e.g. Google Authenticator).
- A dedicated hardware dongle that computes HOTP codes (e.g. a YubiKey).
Transfer Device(s): You need a mechanism to transfer encrypted submissions from the Journalist Workstation to the SVS to decrypt and view them. The most common transfer devices are DVD/CD-R discs and USB drives.
From a security perspective, it is preferable to use write-once media such as DVD/CD-R discs because it eliminates the risk of exfiltration by malware that persists on the Transfer Device (e.g. BadUSB).
On the other hand, using write-once media to transfer data is typically inconvenient and time-consuming. You should consider your threat model and choose your transfer device accordingly.
Monitor, Keyboard, Mouse: You will need these to do the initial installation of Ubuntu on the Application and Monitor Servers.
Depending on your setup, you may also need these to work on the SVS.
Note
If you cannot afford to purchase new hardware for your SecureDrop instance, we encourage you to consider re-purposing existing hardware to use with SecureDrop. If you are comfortable working with hardware, this is a great way to set up a SecureDrop instance for cheap.
Since SecureDrop’s throughput is significantly limited by the use of Tor for all connections, there is no need to use top of the line hardware for any of the servers or the firewall. In our experience, relatively recent recycled Dell desktops or servers are adequate for the SecureDrop servers, and recycled ThinkPad laptops work well for the Admin/Journalist workstations.
If you choose to use recycled hardware, you should of course consider whether or not it is trustworthy; making that determination is outside the scope of this document.
Optional Hardware¶
This hardware is not required to run a SecureDrop instance, but most of it is still recommended.
Offline Printer¶
It is often useful to print submissions from the Secure Viewing Station for review and annotation.
Warning
To maintain the integrity of the airgap, this printer should be dedicated to use with the Secure Viewing Station, connected via a wired connection, and should not have any wireless communication capabilities.
Offline Storage¶
The SVS is booted from a Tails USB drive, which has an encrypted persistent volume but typically has a fairly limited storage capacity since it’s just a USB drive. For installations that expect to receive a large volume of submissions, we recommend buying an external hard drive that can be encrypted and used to store submissions that have been transferred from the Application Server to the SVS.
Backup Storage¶
It’s useful to run periodic backups of the servers in case of failure. We recommend buying an external hard drive that can be encrypted and used to store server backups.
Warning
Since this drive will be connected to the Admin Workstation to perform backups, it should not be the same drive used for Offline Storage.
Network Switch¶
If your firewall has fewer than four NICs, you will need an additional Ethernet switch to perform installation and maintenance tasks with the Admin Workstation. This switch is generally useful because it allows you to connect the Admin Workstation to your firewall’s LAN port without taking down either of the SecureDrop servers.
Labeling Equipment¶
As you have probably noticed by now, a SecureDrop installation has a plethora of components. Some of these components can be hard to tell apart; for example, if you buy 3 of the same brand of USB sticks to use for the Admin Workstation, Journalist Workstation, and Secure Viewing Station, they will be indistinguishable from each other unless you label them. We recommend buying some labeling equipment up front so you can label each component as you provision it during the installation process.
There is a multitude of options for labeling equipment. We’ve had good results with small portable labelmakers, such as the Brother P-Touch PT-210 or the Epson LabelWorks LW-300. We like them because they produce crisp, easy-to-read labels, and it’s easy to customize the size of the label’s text, which is great for clearly labeling both large components (like computers) and small components (like USB sticks).
If you do not have a label maker available but have an inkjet printer available to you, it may also be possible to print and cut out labels using adhesive-backed paper and some scissors. These are some labels designed by our team which may be used for labeling:
Specific Hardware Recommendations¶
Application and Monitor Servers¶
We currently recommend the Gigabyte BRIX, Intel NUC, or Mac Mini for SecureDrop servers.
Note
If using non-recommended hardware, ensure you remove as much extraneous hardware as physically possible from your servers. This could include: speakers, cameras, microphones, fingerprint readers, wireless, and Bluetooth cards.
Gigabyte BRIX¶
The Gigabyte BRIX series is an inexpensive, quiet, low-power device that can be used for SecureDrop servers. There are a variety of models to choose from; we recommend the GB-BXi5-5575. It has a mid-range CPU (the 5th generation Intel i5), a full-size HDMI port for a monitor, and four USB 2 ports. If you select a different model series (such as the GB-BSi5H) carefully verify that it uses the 5th generation Intel i5. Newer generation CPUs will not work with SecureDrop.
The GB-BXi5-5575 supports wireless and Bluetooth through a removable card. This removable card is preferable, since you want neither WiFi nor Bluetooth. You can open the BRIX by removing the screws from the underside of the computer; the wireless card has one small screw you need to remove and two small connectors.
The BRIXs come as kits, and some assembly is required. You will need to purchase the RAM and hard drive separately for each BRIX and insert both into the machine before it can be used. We recommend:
- 2x 240 GB SSDs (2.5”)
- 1x memory kit of 2x4GB sticks (DIMM DDR3 1866MHz) - You can put one 4GB memory stick in each of the servers.
Intel NUC¶
The Intel NUC (Next Unit of Computing) is an inexpensive, quiet, low-power device that can be used for the SecureDrop servers. There are a variety of models to choose from. We recommend the NUC5i5MYHE because it has a mid-range CPU (the 5th generation Intel i5), a Mini DisplayPort port for a monitor, and two USB 3.0 ports for faster OS installation and data transfer.
The NUC5i5MYHE supports wireless through optionally-purchased expansion cards. This means the wireless components aren’t soldered on which would make them nearly impossible to remove without inflicting damage to the NUC. This optional support is preferable, since you want neither WiFi nor Bluetooth.
The NUCs come as kits, and some assembly is required. You will need to purchase the RAM and hard drive separately for each NUC and insert both into the NUC before it can be used. We recommend:
- 2x 240 GB SSDs (2.5”)
- 1x memory kit of 2x4GB sticks - You can put one 4GB memory stick in each of the servers.
Note
The D54250WYK we previously recommended has now entered End of Life and End of Interactive Support statuses. If you’re currently using this model for your SecureDrop setup, and need hardware support, you’ll need to consult the support community forum.
Note
If you encounter issues booting Ubuntu on the NUCs, try updating the BIOS according to these instructions.
Caution
Some older NUC BIOS versions will cause the server to brick itself if the device attempts to suspend. This has since been fixed in a BIOS update. See these release notes (PDF) for more details.
Mac Minis¶
Other than the NUCs we also recommend the 2014 Apple Mac Minis (part number MGEM2) for installing SecureDrop. Mac Minis have removable wireless cards that you should remove. This requires a screwdriver for non-standard TR6 Torx security screws.
However, on the first install of Ubuntu Server the Mac Minis will not boot: this is a known and documented issue. The workaround requires a one-time modification after you install Ubuntu but before you move on to install SecureDrop. After Ubuntu is installed, for each Mac Mini you should:
Connect your Ubuntu installation media (USB drive or CD)
Boot your Mac Mini while holding down the Option key.
Select EFI Boot and select Rescue a broken system at the Ubuntu install screen.
Accept the default options for the install steps until you get to Device to use as root file system.
At the Device to use as root file system prompt, select
/dev/mon-vg/rootor/dev/app-vg/rootfor the monitor and application servers respectively.Select to mount the separate
/bootpartition.Select Execute a shell in
/dev/mon-vg/root(or/dev/app-vg/root) and select Continue.You should now be at a rescue Linux shell. Type
efibootmgr, and you should see the following:BootCurrent: 0000 Timeout: 5 seconds BootOrder: 0080 Boot0000* ubuntu Boot0080* Mac OS X BootFFFF*
Type
efibootmgr -o 00.Again type
efibootmgr. This time you should see the following:BootCurrent: 0000 Timeout: 5 seconds BootOrder: 0000 Boot0000* ubuntu Boot0080* Mac OS X BootFFFF*
Type
exit.Select Reboot the system and remove the installation media. Your server should now boot to Ubuntu by default.
Secure Viewing Station (SVS)¶
The Secure Viewing Station is a machine that is kept offline and only ever used together with the Tails operating system. This machine will be used to generate the GPG keys used by SecureDrop to encrypt submissions, as well as decrypt and view submissions. Since this machine will never touch the Internet or run an operating system other than Tails, it does not need a hard drive or network device; in fact, we recommend removing these components if they are already present.
One option is to buy a Linux-compatible laptop such as a Lenovo ThinkPad; we’ve tested the T420 and successfully removed the wireless components with ease. It’s possible to repurpose old laptops from other manufacturers, as long as the wireless components are removable.
Just as with the servers, you can also use an Intel NUC for the SVS. As noted before, NUCs do not ship with a hard drive, and can be configured without any wireless components, so you’ll save time by not having to remove these, since they won’t be present. However, NUCs do contain an IR receiver, which we recommend taping over with opaque masking tape.
If you choose to use an Intel NUC that differs from our recommended model, make sure you use one that offers wireless as an option. If the model is advertised as having “integrated wireless”, such as the NUC5i5RYK, this could mean it’s built into the motherboard, making it physically irremovable, and attempting to do so would risk damaging the unit; instead, look for attributes like M.2 22×30 slot and wireless antenna pre-assembled (for wireless card support), as advertised by the NUC5i5MYHE that we recommend.
Tails USBs¶
Note
Tails no longer supports 32-bit computers. Please see the note in the Workstations section for more details.
We strongly recommend getting USB 3.0-compatible drives to run Tails from. The transfer speeds are significantly faster than USB 2.0, which means a live operating system booting from one will be much faster and more responsive.
You will need at least an 8GB drive to run Tails with an encrypted persistent partition. We recommend getting something in the 16-64GB range so you can handle large amounts of submissions without hassle. Anything more than that is probably overkill.
Transfer Device¶
If you are using USBs for the transfer device, the same general recommendations for the Tails USBs also apply. One thing to consider is that you are going to have a lot of USB drives to keep track of, so you should consider how you will label or identify them and buy drives accordingly. Drives that are physically larger are often easier to label (e.g. with tape, printed sticker or a label from a labelmaker).
If you are using DVD/CD-R’s for the transfer device, you will need two DVD/CD writers: one for burning DVDs from the Journalist Workstation, and one for reading the burned DVDs on the SVS. We recommend using two separate drives instead of sharing the same drive to avoid the potential risk of malware exfiltrating data by compromising the drive’s firmware. We’ve found the DVD/CD writers from Samsung and LG to work reasonably well, you can find some examples here.
Finally, you will need a stack of blank DVD/CD-R’s, which you can buy anywhere.
Network Firewall¶
We recommend the pfSense SG-2440.
Network Switch¶
This is optional, for people who are using a firewall with less than 4 ports (the recommended firewall has 4 ports). Any old switch with more than 3 ports will do, such as the 5-port Netgear ProSafe Ethernet Switch.
Printers¶
Careful consideration should be given to the printer used with the SVS. Most printers today have wireless functionality (WiFi or Bluetooth connectivity) which should be avoided because it could be used to compromise the airgap.
Unfortunately, it is difficult to find printers that work with Tails, and it is increasingly difficult to find non-wireless printers at all. To assist you, we have compiled the following partial list of airgap-safe printers that have been tested and are known to work with Tails:
| Printer Model | Testing Date | Tails Versions | Printer Type |
|---|---|---|---|
| HP DeskJet F4200 | 06/2017 | 3.0 | Color Inkjet |
| HP DeskJet 1112 | 06/2017 | 3.0 | Color Inkjet |
| HP DeskJet 1110 | 08/2017 | 3.1 | Color Inkjet |
| HP LaserJet 400 M401n | 06/2015 | 1.4 | Monochrome Laser |
| HP DeskJet 6940 | 04/2015 | 1.3.2 | Monochrome Injket |
Note
We’ve documented both the HP DeskJet F4200 and HP LaserJet 400 M401n with screenshots of the installation process, in our section on Setting up a Printer in Tails. While the F4200 installed automatically, the 400 M401n required that we set “Make and model” to “HP LaserJet 400 CUPS+Gutenprint v5.2.9” when manually configuring the drivers.
If you know of another model of printer that fits our requirements and works with Tails, please submit a pull request to add it to this list.
Monitor, Keyboard, Mouse¶
We don’t have anything specific to recommend when it comes to displays. You should make sure you know what monitor cable you need for the servers, since you will need to connect them to a monitor to do the initial Ubuntu installation.
You should use a wired (USB) keyboard and mouse, not wireless.
Before you begin¶
Before you get started, you should familiarize yourself with the Overview, Terminology, and the Passphrases involved in SecureDrop’s operations. You may wish to leave these documents open in other tabs for reference as you work.
SecureDrop is a technical tool. It is designed to protect journalists and sources, but no tool can guarantee safety. This guide will instruct you in installing and configuring SecureDrop, but it does not explain how to use it safely and effectively. Put another way: at the end of this guide, you will have built a car; you will not know how to drive. Make sure to review the Deployment Guide to review best practices for SecureDrop deployments.
Installing SecureDrop is an extended manual process which requires a bunch of preparation and equipment. You should probably set aside a day to complete the install process. A successful install requires an admin with at-least basic familiarity with Linux, the GNU core utilities and Bash shell. If you are not proficient in these areas, it is strongly recommended that you contact the Freedom of the Press Foundation for installation assistance.
Before you begin, you will need to assemble all the hardware that you are going to use.
To better assist in the installation process, you can organize your work using the SecureDrop Installation Worksheet. It is critical you destroy this worksheet when your installation is complete and all of your passphrases have been safely stored in a password manager.
When running commands or editing configuration files that include filenames, version numbers, usernames, and hostnames or IP addresses, make sure you use the appropriate values for your instance.
Once you’re familiar with SecureDrop, you’ve made your plan, your organization is ready to follow-through and you have the required hardware assembled before you, you’re ready to begin.
Create Tails USBs¶
Tails is a privacy-enhancing live operating system that runs on removable media, such as a DVD or a USB stick. It sends all your Internet traffic through Tor, does not touch your computer’s hard drive, and securely wipes unsaved work on shutdown.
Most of the work of installing, administering, and using SecureDrop is done from computers using Tails, so the first thing you need to do is set up several USB drives with the Tails operating system. To get started, you’ll need two Tails drives: one for the Admin Workstation and one for the Secure Viewing Station. Later, you’ll set up a bunch more Tails drives for your journalists and backups, but for now you just need two.
As soon as you create a new Tails drive, label it immediately. USB drives all look alike and you’re going to be juggling a whole bunch of them throughout this installation. Label immediately. Always.
Install Tails¶
We recommend creating an initial Tails Live DVD or USB, and then using that to create additional Tails drives with the Tails Installer, a special program that is only available from inside Tails. All of your Tails drives will need persistence: a way of safely saving files and so on between reboots. It is only possible to set up persistence on USB drives which were created via the Tails Installer.
The Tails website has detailed and up-to-date instructions on how to download and verify Tails, and how to create a bootable Tails USB drive. Follow the instructions at these links and then return to this page:
You will need to create 3 Tails USBs to perform the SecureDrop installation:
- A “master” Tails USB, which you will create by copying a Tails .iso onto a USB drive, using one of the techniques outlined in the Tails documentation. This Tails USB is only used for creating other Tails USBs with the Tails Installer.
- The Secure Viewing Station Tails USB.
- The Admin Workstation Tails USB.
Tip
This process will take some time, most of which will be spent waiting around. Once you have the “master” copy of Tails, you have to boot it, create another Tails drive with the Tails Installer, shut down, and boot into the new Tails USB to complete the next step of setting up the persistence - for each additional Tails USB.
Note
Tails doesn’t always completely shut down and reboot properly when you click “restart”, so if you notice a significant delay, you may have to manually power off and restart your computer for it to work properly.
Enable Persistent Storage¶
Creating an encrypted persistent volume will allow you to securely save information and settings in the free space that is left on your Tails drive. This information will remain available to you even if you reboot Tails. (Tails securely erases all other data on every shutdown.)
You will need to create a persistent storage on each Tails drive, with a unique password for each.
Please use the instructions on the Tails website to make the persistent volume on each Tails drive you create. When creating the persistence volume, you will be asked to select from a list of features, such as ‘Personal Data’. You should enable all features by selecting each item in the list.
Some other things to keep in mind:
- Right now, you need to create a persistent volume on both the Admin Workstation Tails drive and the Secure Viewing Station Tails drive.
- Each Tails persistent volume should have an unique and complex passphrase that’s easy to write down or remember. We recommend using Diceware passphrases.
- Each journalist will need their own Tails drive with their own persistent volume secured with their own passphrase — but that comes later.
- Journalists and admins will eventually need to remember these passphrases. We recommend using spaced-repetition to memorize Diceware passphrases.
Warning
Make sure that you never use the Secure Viewing Station Tails drive on a computer connected to the Internet or a local network. This Tails drive will only be used on the air-gapped Secure Viewing Station.
Set up the Secure Viewing Station¶
The Secure Viewing Station is the computer where journalists read and respond to SecureDrop submissions. Once submissions are encrypted on the Application Server, only the Secure Viewing Station has the key to decrypt them. The Secure Viewing Station is never connected to the internet or a local network, and only ever runs from a dedicated Tails drive. Journalists download encrypted submissions using their Journalist Workstation, copy them to a Transfer Device (a USB drive or a DVD) and physically transfer the Transfer Device to the Secure Viewing Station.
Since the Secure Viewing Station never uses a network connection or an internal hard drive, we recommend that you physically remove any internal storage devices or networking hardware such as wireless cards or Bluetooth adapters. If the machine has network ports you can’t physically remove, you should clearly cover these ports with labels noting not to use them. For an even safer approach, fill a port with epoxy to physically disable it. We also recommend you remove the speakers from the device (or just cut the audio cables if that’s easier). This is to prevent exfiltration of data from the airgap via ultrasonic audio, which cannot be heard by humans. If you have questions about repurposing hardware for the Secure Viewing Station, contact the Freedom of the Press Foundation.
You should have a Tails drive clearly labeled “SecureDrop Secure Viewing Station”. If it’s not labeled, label it right now, then boot it on the Secure Viewing Station. After it loads, you should see a “Welcome to Tails” screen with two options. Select Yes to enable the persistent volume and enter your password, but do NOT click Login yet. Under ‘More Options,’ select Yes and click Forward.
Enter an Administration password for use with this specific Tails session and click Login.
Note
The Administration password is a one-time password. It is reset every time you shut down Tails.
Set up the Transfer Device¶
Journalists copy submissions from their Journalist Workstation to the Secure Viewing Station using the Transfer Device which can be a DVD or a USB drive.
Select DVDs or USBs¶
Using DVDs as the Transfer Device provides some protection against certain kinds of esoteric USB-based attacks on the Secure Viewing Station, but requires that you have blank DVDs, a dedicated DVD drive for the Secure Viewing Station, DVD drives for use with Journalist Workstations, and a shredder capable of destroying DVDs. Unless you are certain that you need to use DVDs as the Transfer Device, you should use USB drives instead. If you have chosen to use DVDs instead, there is nothing to set up now — just make sure that you have all the hardware on hand.
USB Transfer Device Configuration¶
The easiest and recommended option for a Transfer Device is a USB drive. If you have a large team of journalists you may want to create several of these. Here we’ll just walk through making one Transfer Device [1].
Create a USB Transfer Device¶
Note
This process will destroy all data currently on the drive.
First, label your USB drive “SecureDrop Transfer Device”.
On the Secure Viewing Station, open the
Applications menu in the top left corner and select
Utilities then 
Disks:
Connect your Transfer Device then pick your device in the menu on the left. Since we’re going to destroy all the data on this drive, it’s important that you pick the right drive. It should be named something that sounds similar to the manufacturer’s label on the outside of the drive, and it will only appear after you plug it in. Double check that you have clicked on the correct drive:
Once you’re sure you have the right drive, click the interlocking gears, then Format Partition….
Note
If there are multiple existing partitions on the drive, you should first click the “-” icon on the left of the interlocking gears icon to delete each partition, and then create another partition that fills all free space with the options as shown below.
Give the partition on your Transfer Device a descriptive name like “Transfer Device” and select the options as in the following screenshot:
You won’t need to memorize this passphrase or type it more than a few times, so feel free to make a good long one. Then click Format to continue. The Disks utility will ask you if you are sure: click Format to continue. After a few seconds, your new Transfer Device should be ready for use. If you haven’t already, make sure to label it.
Set up the USB Transfer Device on each workstation¶
On each Journalist Workstation and Secure Viewing Station you’d like to use the Transfer Device you will securely save the passphrase on the persistent volume. This ensures that you will only have to type in the passphrase once during initial set up and it will be automatic thereafter:
- Insert the Transfer Device
- Go to Places ▸ Computer and click the USB drive in the left column.
- Type in the passphrase and click “Remember Password”:
Remember to first do this on the Secure Viewing Station you just used to create the device!
After you’ve done this on each computer you wish to use the Transfer Device with, you’re good to go!
| [1] | Tails screenshots were taken on Tails 3.0.1. Please make an issue on GitHub if you are using the most recent version of Tails and the interface is different from what you see here. |
Generate the SecureDrop Submission Key¶
When a document or message is submitted to SecureDrop by a source, it is automatically encrypted with the SecureDrop Submission Key. The private part of this key is only stored on the Secure Viewing Station which is never connected to the Internet. SecureDrop submissions can only be decrypted and read on the Secure Viewing Station.
We will now prepare the Secure Viewing Station and generate the SecureDrop Submission Key.
Ensure Filenames are Preserved¶
In order to preserve filenames when you decrypt submissions, on each Secure Viewing Station, you should open a Terminal and type the following commands:
cd /live/persistence/TailsData_unlocked/dotfiles
echo "/usr/bin/dconf write /org/gnome/nautilus/preferences/automatic-decompression false" > .xsessionrc
Note
This only needs to be done once on each Secure Viewing Station. After a reboot it will persist.
Correct the system time¶
After booting up Tails on the Secure Viewing Station, you will need to manually set the system time before you create the SecureDrop Submission Key. Be sure to enable admin privileges before you do this. In Tails 3.x, you enable admin privileges by clicking the + button under Additional Settings, then navigating to Administration Password. Enter an administration password and then click Start Tails.
To set the system time:
- Click the upper right down arrow in the menu bar and select the wrench icon:
- Then click Date & Time.
- Click Unlock. Type in the admin password you set when you started up Tails.
- Set the correct time, region and city.
- Click Lock, exit Settings and wait for the system time to update in the top panel.
Once that’s done, follow the steps below to create the key.
Create the key¶
Navigate to Applications ▸ Terminal to open a terminal
.In the terminal, run
gpg --full-generate-key:
When it says Please select what kind of key you want, choose “(1) RSA and RSA (default)”.
When it asks What keysize do you want?, type
4096.When it asks Key is valid for?, press Enter. This means your key does not expire.
It will let you know that this means the key does not expire at all and ask for confirmation. Type y and hit Enter to confirm.
- Next it will prompt you for user ID setup. Use the following options:
- Real name: “SecureDrop”
- Email address: leave this field blank
- Comment:
[Your Organization's Name] SecureDrop Submission Key
GPG will confirm these options. Verify that everything is written correctly. Then type
Ofor(O)kayand hit enter to continue:
A box will pop up (twice) asking you to type a passphrase. Since the key is protected by the encryption on the Tails persistent volume, it is safe to simply click OK without entering a passphrase.
The software will ask you if you are sure. Click Yes, protection is not needed.
Wait for the key to finish generating.
Export the public key¶
To manage GPG keys using the graphical interface (a program called Seahorse),
click the clipboard icon 
in the top right corner and select
“Manage Keys”. Click “GnuPG keys” and you should see the key that you just
generated.
- Select the key you just generated and click “File” then “Export”.
- Save the key to the Transfer Device as
SecureDrop.asc, and make sure you change the file type from “PGP keys” to “Armored PGP keys” which can be switched at the bottom of the Save window. Click the ‘Export’ button after switching to armored keys.
Note
This is the public key only.
You’ll need to provide the fingerprint of this new key during the installation. Double-click on the newly generated key and change to the Details tab. Write down the 40 hexadecimal digits under Fingerprint.
Note
Your fingerprint will be different from the one in the example screenshot.
At this point, you are done with the Secure Viewing Station for now. You can shut down Tails, grab the admin Tails USB and move over to your regular workstation.
Set up the Admin Workstation¶
Earlier, you should have created the admin Tails USB along with a persistence volume for it. Now, we are going to add a couple more features to the admin Tails USB to facilitate SecureDrop’s setup.
If you have not switched to and booted the admin Tails USB on your regular workstation, do so now.
Start Tails with Persistence Enabled¶
After you boot the admin Tails USB on your normal workstation, you should see a Welcome to Tails screen with Encrypted Persistent Storage. Enter your password and click Unlock. Do NOT click Start Tails yet. Under Additional Settings click the plus sign.
Click Administration password, enter a password for use with this specific Tails session and click Add. And finally click Start Tails.
Note
The Administration password is a one-time password. It will reset every time you shut down Tails.
After Tails finishes booting, make sure you’re connected to the Internet
and that the Tor status onion icon is not crossed out
, consulting the icons in the upper right corner of the
screen.
Download the SecureDrop repository¶
The rest of the SecureDrop-specific configuration is assisted by files
stored in the SecureDrop Git repository. We’re going to be using this
again once SecureDrop is installed, but you should download it now. To
get started, open a terminal . You will use this Terminal
throughout the rest of the install process.
Start by running the following commands to download the git repository.
cd ~/Persistent
git clone https://github.com/freedomofpress/securedrop.git
Note
Since the repository is fairly large and Tor can be slow, this may take a few minutes.
Verify the Release Tag¶
First, download and verify the SecureDrop Release Signing Key.
gpg --recv-key "2224 5C81 E3BA EB41 38B3 6061 310F 5612 00F4 AD77"
Note
It is important you type this out correctly. If you are not copy-pasting this command, we recommend you double-check you have entered it correctly before pressing enter.
Tip
If the --recv-key command fails, first double-check that
Tails is connected to Tor.
Once you’ve confirmed that you’re successfully connected to Tor, try
re-running the --recv-key command a few times. The default GPG
configuration on Tails uses a keyserver pool, which may occasionally return
a malfunctioning keyserver, causing the --recv-key command to fail.
If the command is consistently failing after a few tries, it could
indicate that the default GPG key servers are down or unreachable. As a
workaround, another keyserver can be specified by adding the --keyserver
option to the gpg --recv-key command. In our experience, the SKS HKPS
keyserver pool is usually a reliable alternative, so try:
gpg --keyserver hkps://hkps.pool.sks-keyservers.net --recv-key "2224 5C81 E3BA EB41 38B3 6061 310F 5612 00F4 AD77"
Again, this is a keyserver pool, so you may need to retry the command a couple of times before it succeeds.
When passing the full public key fingerprint to the --recv-key command, GPG
will implicitly verify that the fingerprint of the key received matches the
argument passed.
Caution
If GPG warns you that the fingerprint of the key received does not match the one requested do not proceed with the installation. If this happens, please email us at securedrop@freedom.press.
Verify that the current release tag was signed with the release signing key:
cd ~/Persistent/securedrop/
git checkout 0.5
git tag -v 0.5
You should see Good signature from "SecureDrop Release Signing Key" in the
output of that last command.
Caution
If you do not, signature verification has failed and you should not proceed with the installation. If this happens, please contact us at securedrop@freedom.press.
Create the Admin Passphrase Database¶
We provide a KeePassX password database template to make it easier for admins and journalists to generate strong, unique passphrases and store them securely. Once you have set up Tails with persistence and have cloned the repo, you can set up your personal password database using this template.
You can find the template in tails_files/securedrop-keepassx.kdbx
in the SecureDrop repository that you just cloned.
To use the template:
- Open the KeePassX program
which is already installed on
Tails - Select Database, Open database, and navigate to the location of securedrop-keepassx.kdbx, select it, and click Open
- Check the password box and hit OK
- Click Database and Save Database As
- Save the database in the Persistent folder
Tip
If you would like to add a master password, navigate to Database and Change master key. Note that since each KeePassX database is stored on the encrypted persistent volume, this additional passphrase is not necessary.
Warning
You will not be able to access your passwords if you forget the master password or the location of the key file used to protect the database.
In case you wish to manually create a database, the suggested password fields in the admin template are:
Administrator:
- Admin account username
- App Server SSH Onion URL
- Email account for sending OSSEC alerts
- Monitor Server SSH Onion URL
- Network Firewall Admin Credentials
- OSSEC GPG Key
- SecureDrop Login Credentials
Journalist:
- Auth Value: Journalist Interface
- Onion URL: Journalist Interface
- Personal GPG Key
- SecureDrop Login Credentials
Secure Viewing Station:
- SecureDrop GPG Key
Backup:
- This section contains clones of the above entries in case a user accidentally overwrites an entry.
Set up the Network Firewall¶
Now that you’ve set up your password manager, you can move on to setting up the Network Firewall. You should stay logged in to your admin Tails USB to access the Network Firewall’s web interface for configuration.
Unfortunately, due to the wide variety of firewalls that may be used, we do not provide specific instructions to cover every type or variation in software or hardware. This guide is based on pfSense, and assumes your firewall hardware has at least three interfaces: WAN, LAN, and OPT1. For hardware, you can build your own network firewall (not covered in this guide) and install pfSense on it. For most installations, we recommend buying a dedicated firewall appliance with pfSense pre-installed, such as the one recommended in the Hardware Guide.
We currently recommend the pfSense SG-2440, which has 4 interfaces: WAN, LAN, OPT1, and OPT2. If your firewall only has 3 NICs (WAN, LAN, and OPT1), you will need to use a switch on the OPT1 interface to connect the Admin Workstation for the initial installation.
If you are new to pfSense or firewall management in general, we recommend the following resources:
- Official pfSense Wiki
- pfSense: The Definitive
Guide
- Note: This guide is now slightly out of date, although we found it to be a useful reference in the past. To get the latest version of this book, you need to become a pfSense Gold Member.
If you’re using the recommended SG-2440 firewall, then you may find the following resources useful:
Before you begin¶
First, consider how the firewall will be connected to the Internet. You will need to provision several unique subnets, which should not conflict with the network configuration on the WAN interface. If you are unsure, consult your local sysadmin.
Many firewalls, including the recommended Netgate pfSense,
automatically set up the LAN interface on 192.168.1.1/24. This
particular private network is also a very common choice for home and
office routers. If you are connecting the firewall to a router with the
same subnet (common in a small office, home, or testing environment),
you will probably be unable to connect to the network at first. However,
you will be able to connect from the LAN to the pfSense WebGUI
configuration wizard, and from there you will be able to configure the
network so it is working correctly.
Configuring your firewall¶
If your firewall has 4 NICs, as the SG-2440 does, we will refer to the ports as WAN, LAN, OPT1, and OPT2. In this case, we can now use a dedicated port on the network firewall for each component of SecureDrop (Application Server, Monitor Server, and Admin Workstation), so you do not need a switch like you do for a 3-NIC configuration.
Depending on your network configuration, you should define the following values before continuing. For the examples in this guide, we have chosen:
- Admin Subnet:
10.20.1.0/24 - Admin Gateway:
10.20.1.1 - Admin Workstation:
10.20.1.2
- Application Subnet:
10.20.2.0/24 - Application Gateway:
10.20.2.1 - Application Server (OPT1):
10.20.2.2
- Monitor Subnet:
10.20.3.0/24 - Monitor Gateway:
10.20.3.1 - Monitor Server (OPT2) :
10.20.3.2
Initial Configuration¶
Unpack the firewall, connect the power, and power on the device.
We will use the pfSense WebGUI to do the initial configuration of the network firewall. [1]
Connect to the pfSense WebGUI¶
Boot the Admin Workstation into Tails from the Admin Live USB.
Connect the Admin Workstation to the LAN interface. You should see a popup notification in Tails that says “Connection Established”. If you click on the network icon in the upper right of the Tails Desktop, you should see “Wired Connected”:
Warning
Make sure your only active connection is the one you just established with the network firewall. If you are connected to another network at the same time (e.g. a wireless network), you may encounter problems trying to connect the pfSense WebGUI.
Launch the Unsafe Browser from the menu bar: Applications ▸ Internet ▸ Unsafe Browser.
Note
The Unsafe Browser is, as the name suggests, unsafe (its traffic is not routed through Tor). However, it is the only option because Tails intentionally disables LAN access in the Tor Browser.
A dialog will ask “Do you really want to launch the Unsafe Browser?”. Click Launch.
You will see a pop-up notification that says “Starting the Unsafe Browser…”
After a few seconds, the Unsafe Browser should launch. The window has a bright red border to remind you to be careful when using it. You should close it once you’re done configuring the firewall and use the Tor Browser for any other web browsing you might do on the Admin Workstation.
Navigate to the pfSense WebGUI in the Unsafe Browser:
https://192.168.1.1Note
If you have trouble connecting, go to your network settings and make sure that you have an IPv4 address in the
192.168.1.1/24range. You may need to turn on DHCP, else you can manually configure a static IPv4 address of192.168.1.xwith a subnet mask of255.255.255.0. However, make sure not to configure your Tails device to have the same IP as the firewall (192.168.1.1).The firewall uses a self-signed certificate, so you will see a “This Connection Is Untrusted” warning when you connect. This is expected. You can safely continue by clicking Advanced, Add Exception…, and Confirm Security Exception.
You should see the login page for the pfSense GUI. Log in with the default username and password (
admin/pfsense).
Setup Wizard¶
If you’re setting up a brand new (or recently factory reset) router, logging in to the pfSense WebGUI will automatically start the Setup Wizard. Click Next, then Next again. Don’t sign up for a pfSense Gold subscription (unless you want to).
On the “General Information” page, we recommend leaving your hostname as the default (pfSense). There is no relevant domain for SecureDrop, so we recommend setting this to
securedrop.localor something similar. Use your preferred DNS servers. If you don’t know what DNS servers to use, we recommend using Google’s DNS servers:8.8.8.8and8.8.4.4. Click Next.
Leave the defaults for “Time Server Information”. Click Next.
On “Configure WAN Interface”, enter the appropriate configuration for your network. Consult your local sysadmin if you are unsure what to enter here. For many environments, the default of DHCP will work and the rest of the fields can be left blank. Click Next.
For “Configure LAN Interface”, use the IP address of the Admin Gateway (
10.20.1.1) and the subnet mask (/24) of the Admin Subnet. Click Next.
Set a strong admin password. We recommend generating a strong password with KeePassX, and saving it in the Tails Persistent folder using the provided KeePassX database template. Click Next.
Click Reload. Once the reload completes and the web page refreshes, click the corresponding “here” link to “continue on to the pfSense webConfigurator”.
At this point, since you (probably) changed the LAN subnet settings from
their defaults, you will no longer be able to connect after reloading
the firewall and the next request will probably time out. This is not an
error - the firewall has reloaded and is working correctly. To connect
to the new LAN interface, unplug and reconnect your network cable to get
a new network address assigned via DHCP. Note that if you used a subnet
with fewer addresses than /24, the default DHCP configuration in
pfSense may not work. In this case, you should assign the Admin
Workstation a static IP address that is known to be in the subnet to
continue.
Now the WebGUI will be available on the Admin Gateway address. Navigate
to https://<Admin Gateway IP> in the Unsafe Browser, and login as
before except with the new passphrase you just set for the pfSense WebGUI.
Once you’ve logged in to the WebGUI, you are ready to continue configuring
the firewall.
Connect Interfaces and Test¶
Now that the initial configuration is completed, you can connect the WAN port without potentially conflicting with the default LAN settings (as explained earlier). Connect the WAN port to the external network. You can watch the WAN entry in the Interfaces table on the pfSense WebGUI homepage to see as it changes from down (red arrow pointing down) to up (green arrow pointing up). This usually takes several seconds. The WAN’s IP address will be shown once it comes up.
Finally, test connectivity to make sure you are able to connect to the
Internet through the WAN. The easiest way to do this is to use ping
(Diagnostics → Ping in the WebGUI). Enter an external hostname or IP
that you expect to be up (e.g. google.com) and click “Ping”.
Disable DHCP on the LAN¶
pfSense runs a DHCP server on the LAN interface by default. At this stage in the documentation, the Admin Workstation likely has an IP address assigned via that DHCP server.
In order to tighten the firewall rules as much as possible, we recommend disabling the DHCP server and assigning a static IP address to the Admin Workstation instead.
Disable DHCP Server On the Firewall¶
To disable DHCP, navigate to Services ▸ DHCP Server in the pfSense WebGUI. Uncheck the box labeled Enable DHCP server on LAN interface, scroll down, and click the Save button.
Assign a static IP address to the Admin Workstation¶
Now you will need to assign a static IP to the Admin Workstation.
You can easily check your current IP address by clicking the top right of the menu bar, clicking on the Wired Connection and then clicking Wired Settings.
From here you can click on the cog in the lower right of the panel:
This will take you to the network settings, where you can click IPv4 to see whether or not the Automatic (DHCP) or Manual (static IP) setting is turned on.
Change to the IPv4 Settings tab. Change Addresses from Automatic (DHCP) to Manual (if it isn’t already).
Fill in the static networking information for the Admin Workstation:
- Address:
10.20.1.2 - Netmask:
255.255.255.0 - Gateway :
10.20.1.1
Note
The Unsafe Browser will not launch when using a manual network configuration if it does not have DNS servers configured. This is technically unnecessary for our use case because we are only using it to access IP addresses on the LAN, and do not need to resolve anything with DNS. Nonetheless, you should configure some DNS servers here so you can continue to use the Unsafe Browser to access the WebGUI in future sessions.
We recommend keeping it simple and using the same DNS servers that you used for the network firewall in the setup wizard.
Click Apply. If the network does not come up within 15 seconds or so, try disconnecting and reconnecting your network cable to trigger the change. You will need you have succeeded in connecting with your new static IP when you see a pop-up notification that says “Tor is ready. You can now access the Internet”.
Troubleshooting: DNS servers and the Unsafe Browser¶
After saving the new network configuration, you may still encounter the “No DNS servers configured” error when trying to launch the Unsafe Browser. If you encounter this issue, you can resolve it by disconnecting from the network and then reconnecting, which causes the network configuration to be reloaded.
To do this, click the network icon in the system toolbar, and click Disconnect under the name of the currently active network connection, which is displayed in bold. After it disconnects, click the network icon again and click the name of the connection to reconnect. You should see a popup notification that says “Connection Established”, followed several seconds later by the “Tor is ready” popup notification.
For the next step, SecureDrop Configuration, you will manually configure the firewall for SecureDrop, using screenshots or XML templates as a reference.
SecureDrop Configuration¶
SecureDrop uses the firewall to achieve two primary goals:
- Isolating SecureDrop from the existing network, which may be compromised (especially if it is a venerable network in a large organization like a newsroom).
- Isolating the Application Server and the Monitor Server from each other as much as possible, to reduce attack surface.
In order to use the firewall to isolate the Application Server and the Monitor Server from each other, we need to connect them to separate interfaces, and then set up firewall rules that allow them to communicate.
Set up OPT1¶
We set up the LAN interface during the initial configuration. We now need to set up the OPT1 interface for the Application Server. Start by connecting the Application Server to the OPT1 port. Then use the WebGUI to configure the OPT1 interface. Go to Interfaces ▸ OPT1, and check the box to Enable Interface. Use these settings:
- IPv4 Configuration Type: Static IPv4
- IPv4 Address:
10.20.2.1(Application Gateway IP)
Make sure that the CIDR routing prefix is correct (/24). Leave everything else
as the default. Save and Apply Changes.
Set up OPT2¶
Next, you will have to enable the OPT2 interface. Go to Interfaces ▸ OPT2, and check the box to Enable Interface. OPT2 interface is set up similarly to how we set up OPT1 in the previous section. Use these settings:
- IPv4 Configuration Type: Static IPv4
- IPv4 Address:
10.20.3.1(Monitor Gateway IP)
Make sure that the CIDR routing prefix is correct (/24). Leave everything else
as the default. Save and Apply Changes.
Set up the Firewall Rules¶
Since there are a variety of firewalls with different configuration interfaces and underlying sets of software, we cannot provide a set of network firewall rules to match every use case.
The easiest way to set up your firewall rules is to look at the screenshots of a correctly configured firewall and edit the interfaces, aliases, and firewall rules on your firewall to match them.
Use Screenshots of Firewall Configuration¶
Here are some example screenshots of a working pfSense firewall configuration. You will add the firewall rules until they match what is shown on the screenshots.
First, we will configure IP and port aliases. Navigate to Firewall ▸ Aliases and you should see a screen with no currently defined IP aliases:
Next you will click Add to add each IP alias. You should leave the Type as Host. Make aliases for the following:
admin_workstation:10.20.1.2app_server:10.20.2.2external_dns_servers:8.8.8.8, 8.8.4.4monitor_server:10.20.3.2local_servers:app_server, monitor_server
Click Save to add the alias.
Keep adding aliases until the screenshot matches what is shown here:
Finally, click Apply Changes. This will save your changes. You should see a message “The changes have been applied successfully”:
Next click “Ports” for the port aliases, and add the following ports:
- OSSEC:
1514 - ossec_agent_auth:
1515
Your configuration should match this screenshot:
Next we will configure firewall rules for each interface. Navigate to Firewall ▸ Rules to add firewall rules for the LAN, OPT1, and OPT2 interfaces.
Warning
Be sure not to delete the Anti-Lockout Rule on the LAN interface. Deleting this rule will lock you out of the pfSense WebGUI.
Add or remove rules until they match the following screenshots by clicking Add to add a rule.
LAN interface:
OPT1 interface:
OPT2 interface:
Once you’ve set up the firewall, exit the Unsafe Browser, and continue with the “Keeping pfSense up to date” section below.
Configuration Reference Templates¶
As an alternative to the provided screenshots, you can examine the provided
.xml templates as a reference:
- Interfaces config:
install_files/network_firewall/interfaces-config-pfSense.xml - Aliases:
install_files/network_firewall/aliases-config-pfSense.xml - Firewall rules:
install_files/network_firewall/filter-config-pfSense.xml
Note
These will not load using pfSense Restore and are here as a reference only. See GitHub #2282 for more info.
Tips for setting up pfSense Firewall Rules¶
Here are some general tips for setting up pfSense firewall rules:
- Create aliases for the repeated values (IPs and ports).
- pfSense is a stateful firewall, which means that you don’t need
corresponding rules to allow incoming traffic in response to outgoing
traffic (like you would in, e.g. iptables with
--state ESTABLISHED,RELATED). pfSense does this for you automatically. - You should create the rules on the interface where the traffic originates.
- Make sure you delete the default “allow all” rule on the LAN interface. Leave the “Anti-Lockout” rule enabled.
- Any traffic that is not explicitly passed is logged and dropped by
default in pfSense, so you don’t need to add explicit rules (iptables
LOGNDROP) for that. - Since some of the rules are almost identical except for whether they allow traffic from the Application Server or the Monitor Server, you can use the “add a new rule based on this one” button to save time creating a copy of the rule on the other interface.
- If you are troubleshooting connectivity, the firewall logs can be very helpful. You can find them in the WebGUI in Status → System Logs → Firewall.
Keeping pfSense up to date¶
Periodically, the pfSense project maintainers release an update to the pfSense software running on your firewall. You will be notified by the appearance of text saying that there is a new version in the Version section of the “Status: Dashboard” page (the home page of the WebGUI).
If you see that an update is available, we recommend installing it. Most of these updates are for minor bugfixes, but occasionally they can contain important security fixes. You should keep apprised of updates yourself by checking the pfSense Blog posts with the “releases” tag.
Note
Protip: Subscribe to the RSS feed.
To install the update, click the Download icon next to the update then click the “Confirm” button:
You will see a page with a progress bar while pfSense performs the upgrade:
Note
This may take a while, so be patient!
Once it is complete, you will see a notification of successful upgrade:
| [1] | Tails screenshots were taken on Tails 3.0~beta4. Please make an issue on GitHub if you are using the most recent version of Tails and the interface is different from what you see here. |
Set up the Servers¶
Now that the firewall is set up, you can plug the Application Server and the Monitor Server into the firewall. If you are using a setup where there is a switch on the LAN port, plug the Application Server into the switch and plug the Monitor Server into the OPT1 port.
Install Ubuntu¶
Note
Installing Ubuntu is simple and may even be something you are very familiar with, but we strongly encourage you to read and follow this documentation exactly as there are some “gotchas” that may cause your SecureDrop set up to break.
The SecureDrop Application Server and Monitor Server run Ubuntu Server 14.04.5 LTS (Trusty Tahr). To install Ubuntu on the servers, you must first download and verify the Ubuntu installation media. You should use the Admin Workstation to download and verify the Ubuntu installation media.
Download the Ubuntu installation media¶
The installation media and the files required to verify it are available on the Ubuntu Releases page. You will need to download the following files:
If you’re reading this documentation in the Tor Browser on the Admin
Workstation, you can just click the links above and follow the prompts to save
them to your Admin Workstation. We recommend saving them to the
/home/amnesia/Persistent/Tor Browser directory on the Admin Workstation,
because it can be useful to have a copy of the installation media readily
available.
Alternatively, you can use the command line:
cd ~/Persistent
torify curl -OOO http://releases.ubuntu.com/14.04.5/{ubuntu-14.04.5-server-amd64.iso,SHA256SUMS{,.gpg}}
Note
Downloading Ubuntu on the Admin Workstation can take a while because Tails does everything over Tor, and Tor is typically slow relative to the speed of your upstream Internet conenction.
Verify the Ubuntu installation media¶
You should verify the Ubuntu image you downloaded hasn’t been modified by a malicious attacker or otherwise corrupted. We can do so by checking its integrity with cryptographic signatures and hashes.
First, we will download Ubuntu Image Signing Key and verify its fingerprint.
gpg --recv-key "C598 6B4F 1257 FFA8 6632 CBA7 4618 1433 FBB7 5451"
Note
It is important you type this out correctly. If you are not copy-pasting this command, we recommend you double-check you have entered it correctly before pressing enter.
Again, when passing the full public key fingerprint to the --recv-key command, GPG
will implicitly verify that the fingerprint of the key received matches the
argument passed.
Caution
If GPG warns you that the fingerprint of the key received does not match the one requested do not proceed with the installation. If this happens, please email us at securedrop@freedom.press.
Verify the SHA256SUMS file and move on to the next step if you see
“Good Signature” in the output.
gpg --verify SHA256SUMS.gpg SHA256SUMS
The next and final step is to verify the Ubuntu image.
sha256sum -c <(grep ubuntu-14.04.5-server-amd64.iso SHA256SUMS)
If the final verification step is successful, you should see the following output in your terminal.
ubuntu-14.04.5-server-amd64.iso: OK
Caution
If you do not see the line above it is not safe to proceed with the installation. If this happens, please contact us at securedrop@freedom.press.
Create the Ubuntu installation media¶
To create the Ubuntu installation media, you can either burn the ISO image to a
CD-R or create a bootable USB stick. As a reliable method we recommend using
the dd command to copy the hybrid ISO directly to a USB drive rather than a
utility like UNetbootin which can result in errors. Once you have a CD or USB
with an ISO image of Ubuntu on it, you may begin the Ubuntu installation on both
SecureDrop servers.
To use dd you first need to find where the USB device you wish to install
Tails on has been mapped. Simply running the command lsblk in the terminal
will give you a list of your block storage device mappings (this includes hard
drives and USB). If the USB you are writing the Ubuntu installer to is of a
different size or brand than the USB you are running Tails from, it should be
easy to identify which USB has which sdX identifier. If you are unsure, try
running lsblk before and after plugging in the USB you are using for the
Ubuntu installer.
If your USB is mapped to /dev/sdX and you are currently in the directory that contains the Ubuntu ISO, you would use dd like so:
sudo dd conv=fdatasync if=ubuntu-14.04.5-server-amd64.iso of=/dev/sdX
Perform the Installation¶
The steps below are the same for both the Application Server and the Monitor Server.
Start by inserting the Ubuntu installation media into the server. Boot or reboot the server with the installation media inserted, and enter the boot menu. To enter the boot menu, you need to press a key as soon as you turn the server on. This key varies depending on server model, but common choices are Esc, F2, F10, and F12. Often, the server will briefly display a message on boot that shows which key should be pressed to enter the boot menu. Once you’ve entered the boot menu, select the installation media (USB or CD) and press Enter to boot it.
After booting the Ubuntu image, select Install Ubuntu Server.
Follow the steps to select your language, country and keyboard settings. Once that’s done, let the installation process continue.
Configure the network manually¶
The Ubuntu installer will try to autoconfigure networking for the server you are setting up; however, SecureDrop requires manual network configuration. You can hit Cancel at any point during network autoconfiguration to be given the choice to Configure the network manually.
If network autoconfiguration completes before you can do this, the next window will ask for your hostname. To get back to the choice of configuring the network manually, Cancel the step that asks you to set a hostname and choose the menu option that says Configure the network manually instead.
For a production install with a pfSense network firewall in place, the Application Server and the Monitor Server are on separate networks. You may choose your own network settings at this point, but make sure the settings you choose are unique on the firewall’s network and remember to propagate your choices through the rest of the installation process.
Below are the configurations you should enter, assuming you used the network settings from the network firewall guide for the recommended 4 NIC firewall. If you did not, adjust these settings accordingly.
- Application Server:
- Server IP address: 10.20.2.2
- Netmask (default is fine): 255.255.255.0
- Gateway: 10.20.2.1
- For DNS, use Google’s name servers: 8.8.8.8 and 8.8.4.4
- Hostname: app
- Domain name should be left blank
- Monitor Server:
- Server IP address: 10.20.3.2
- Netmask (default is fine): 255.255.255.0
- Gateway: 10.20.3.1
- For DNS, use Google’s name servers: 8.8.8.8 and 8.8.4.4
- Hostname: mon
- Domain name should be left blank
Continue the installation¶
You can choose whatever username and password you would like. To make things easier later you should use the same username and same password on both servers (but not the same password as username). Make sure to save this password in your admin KeePassX database afterwards.
Click ‘no’ when asked to encrypt the home directory. Then configure your time zone.
Partition the disks¶
Before setting up the server’s disk partitions and filesystems in the next step, you will need to decide if you would like to enable *Full Disk Encryption (FDE)*. If the servers are ever powered down, FDE will ensure all of the information on them stays private in case they are seized or stolen.
Warning
The Ansible playbooks for SecureDrop will enable nightly reboots
after the cron-apt task runs for automatic updates. Using FDE
would therefore require manual intervention every morning.
Consequently we strongly discourage the use of FDE.
While FDE can be useful in some cases, we currently do not recommend that you enable it because there are not many scenarios where it will be a net security benefit for SecureDrop operators. Doing so will introduce the need for more passwords and add even more responsibility on the admin of the system (see this GitHub issue for more information).
If you wish to proceed without FDE as recommended, choose the installation option that says Guided - use entire disk and set up LVM.
However, if you decide to go ahead and enable FDE, please note that doing so means SecureDrop will become unreachable after an automatic reboot. An admin will need to be on hand to enter the password in order to decrypt the disks and complete the startup process, which will occur anytime there is an automatic software update, and also several times during SecureDrop’s installation. We recommend that the servers be integrated with a monitoring solution that so that you receive an alert when the system becomes unavailable.
To enable FDE, select Guided - use entire disk and set up encrypted LVM during the disk partitioning step and write the changes to disk. Follow the recommendations as to choosing a strong password. As the admin, you will be responsible for keeping this passphrase safe. Write it down somewhere and memorize it if you can. If inadvertently lost it could result in total loss of the SecureDrop system.
After selecting either of those options you may be asked a few questions about overwriting anything currently on the server you are using. Select yes. You do not need an HTTP proxy, so when asked, you can just click continue.
Finish the installation¶
Wait for the base system to finish installing. When you get to the Configure tasksel screen, choose No automatic updates. The subsequent SecureDrop installation will include a task that handles regular software updates.
Note
The Ansible playbooks for SecureDrop will configure automatic
updates via cron-apt. As part of the automatic update process,
the servers will reboot nightly. See the
OSSEC guide for example notifications
generated by the reboots.
When you get to the software selection screen, only choose OpenSSH server by hitting the space bar.
Caution
Hitting enter before the space bar will force you to start the installation process over.
Once OpenSSH Server is selected, hit Continue.
You will then have to wait for the packages to finish installing.
When the packages are finished installing, Ubuntu will automatically install the bootloader (GRUB). If it asks to install the bootloader to the Master Boot Record, choose Yes. When everything is done, reboot.
Save the Configurations¶
When you are done, make sure you save the following information:
- The IP address of the Application Server
- The IP address of the Monitor Server
- The non-root user’s name and password for the servers.
Test Connectivity¶
Now that both the network firewall and the servers are connected and configured, you should make sure you can connect from the Admin Workstation to both of the servers before continuing with the installation.
In a terminal, verify that you can SSH into both servers, authenticating with your password:
$ ssh <username>@<App IP address> hostname
app
$ ssh <username>@<Monitor IP address> hostname
mon
Tip
If you cannot connect, check the network firewall logs for clues.
Set up SSH keys¶
Ubuntu’s default SSH configuration authenticates users with their passwords; however, public key authentication is more secure, and once it’s set up it is also easier to use. In this section, we will create a new SSH key for authenticating to both servers. Since the Admin Live USB was set up with SSH Client Persistence, this key will be saved on the Admin Live USB and can be used in the future to authenticate to the servers in order to perform administrative tasks.
First, generate the new SSH keypair:
ssh-keygen -t rsa -b 4096
You’ll be asked to “Enter file in which to save the key” Type Enter to use the default location.
Given that this key is on the encrypted persistence of a Tails USB, you do not need to add an additional passphrase to protect the key. If you do elect to use a passphrase, note that you will need to manually type it (Tails’ pinentry will not allow you to copy and paste a passphrase).
Once the key has finished generating, you need to copy the public key
to both servers. Use ssh-copy-id to copy the public key to each
server, authenticating with your password:
ssh-copy-id <username>@<App IP address>
ssh-copy-id <username>@<Mon IP address>
Verify that you are able to authenticate to both servers by running the below commands. You should not be prompted for a passphrase (unless you chose to passphrase-protect the key you just created).
$ ssh <username>@<App IP address> hostname
app
$ ssh <username>@<Monitor IP address> hostname
mon
Minor Admin Tasks¶
DNS¶
The network firewall rules are set up to disable DNS traffic to the gateway,
so if your system has not set nameservers, DNS queries will fail. You can
test this by running host freedom.press. If the host isn’t found,
or there is some other sort of failure, check the pfSense logs. You may see
UDP traffic to the gateway on port 53 being blocked.
If this is the case, you need add the following lines to /etc/resolvconf/resolv.conf.d/tail
nameserver 8.8.8.8
nameserver 8.8.4.4
Then run sudo dpkg-reconfigure resolvconf. This will update /etc/resolv.conf
to include the new name servers. Verify that host freedom.press succeeds.
System Date¶
The ansible playbooks you will run later depend on the system clock
being set accurately, so run sudo ntpdate ntp.ubuntu.com on both servers.
Install SecureDrop¶
Install Prerequisites¶
SecureDrop has some dependencies that need to be loaded onto the Admin Workstation prior to the installation of the server.
To load these dependencies, from the base of the SecureDrop repository
(~/Persistent/securedrop/) run the following commands:
./securedrop-admin setup
The package installation will complete in approximately 10 minutes, depending on network speed and computing power.
Note
Occasionally this command times out due to network latency issues. You should be able to re-run the command and complete the setup. If you run into a problem, try removing the
~/Persistent/securedrop/.venv/directory and running the command again. The command should only be run as theamnesiauser.
Localization of the source and journalist interfaces¶
The source and journalist interface are translated in the following languages:
- German (de_DE)
- Spanish (es_ES)
- French (fr_FR)
- Norwegian (nb_NO)
- Dutch (nl)
- Portuguese, Brasil (pt_BR)
During the installation you will be given the opportunity to choose the list of supported languages to display, using the code shown in parentheses. When the source interface is displayed in French (for instance), people submitting documents will expect a journalist fluent in French is available to read them and followup.
Configure the Installation¶
Make sure you have the following information and files before continuing:
- The Application Server IP address
- The Monitor Server IP address
- The SecureDrop Submission Key (from the Transfer Device)
- The SecureDrop Submission Key fingerprint
- The email address that will receive alerts from OSSEC
- The GPG public key and fingerprint for the email address that will receive the alerts
- Connection information for the SMTP relay that handles OSSEC alerts. For more information, see the OSSEC Alerts Guide.
- The first username of a journalist who will be using SecureDrop (you can add more later)
- The username of the system admin
- (Optional) An image to replace the SecureDrop logo on the Source
Interface and Journalist Interface
- Recommended size:
500px x 450px - Recommended format: PNG
- Recommended size:
You will have to copy the following required files to
install_files/ansible-base:
- SecureDrop Submission Key public key file
- Admin GPG public key file (for encrypting OSSEC alerts)
- (Optional) Custom header image file
The SecureDrop Submission Key should be located on your Transfer Device from earlier. It will depend on the location where the USB stick is mounted, but for example, if you are already at the root of the SecureDrop repository, you can just run:
cp /media/[USB folder]/SecureDrop.asc install_files/ansible-base
Or you may use the copy and paste capabilities of the file manager. Repeat this step for the Admin GPG key and custom header image.
Run the configuration playbook and answer the prompts with values that match your environment:
./securedrop-admin sdconfig
The script will automatically validate the answers you provided, and display
error messages if any problems were detected. The answers you provided will be
written to the file install_files/ansible-base/group_vars/all/site-specific,
which you can edit in case of errors such as typos before rerunning the script.
You can also run ./securedrop-admin sdconfig --force to remove your entire
configuration file and start over.
When you’re done, save the file and quit the editor.
Install SecureDrop Servers¶
Now you are ready to install! This process will configure the servers and install SecureDrop and all of its dependencies on the remote servers.
./securedrop-admin install
You will be prompted to enter the sudo password for the Application and Monitor Servers (which should be the same).
The install process will take some time, and it will return the terminal to you when it is complete.
If an error occurs while running the install, please check all of the details of the error output.
Note
If you see an error running ./securedrop-admin install, and
believe it may be an intermittent issue (for example, due to losing
network connectivity to the servers), it is safe to run the
./securedrop-admin install command again. If you see the same
issue consistently, then you will need to troubleshoot it.
If needed, make edits to the file located at
install_files/ansible-base/group_vars/all/site-specific
as described above. If you continue to have issues please submit a detailed GitHub
issue or
send an email to securedrop@freedom.press.
Note
The SecureDrop install process configures a custom Linux kernel hardened with the grsecurity patch set. Only binary images are hosted in the apt repo. For source packages, see the Source Offer.
Once the installation is complete, the addresses for each Tor Hidden
Service will be available in the following files under
install_files/ansible-base:
app-source-ths: This is the .onion address of the Source Interfaceapp-journalist-aths: This is theHidServAuthconfiguration line for the Journalist Interface. During a later step, this will be automatically added to your Tor configuration file in order to exclusively connect to the hidden service.app-ssh-aths: Same as above, for SSH access to the Application Server.mon-ssh-aths: Same as above, for SSH access to the Monitor Server.
The dynamic inventory file will automatically read the Onion URLs for SSH
from the app-ssh-aths and mon-ssh-aths files, and use them to connect
to the servers during subsequent playbook runs.
Configure the Admin Workstation Post-Install¶
Set up two-factor authentication for the Admin¶
The SecureDrop servers should always be accessed over SSH from the Admin Workstation. In the event of a connectivity problem, Admins can log in directly to the servers by attaching a keyboard and a display. In order to do so, you will need to configure 2FA TOTP access.
Create an admin account on the Journalist Interface¶
In order for any user (admin or journalist) to access the Journalist Interface, they need:
- The
auth-cookiefor the Journalist Interface’s ATHS - An account on the Journalist Interface, which requires the following
credentials to log in:
- Username
- Password
- Two-factor authentication code
You should create a separate account on the Journalist Interface for each user who needs access. This makes it easy to enable or disable access to the Journalist Interface on an individual basis, so you can grant access to new users or revoke access for users who have left the organization or should no longer be allowed to access the Journalist Interface.
There are two types of accounts on the Journalist Interface: admin accounts and normal accounts. Admins accounts are like normal accounts, but they are additionally allowed to manage (add, change, delete) other user accounts through the web interface.
You must create the first admin account on the Journalist Interface by running a command on the Application Server. After that, the Journalist Interface admin can create additional accounts through the web interface.
To create the first admin account, SSH to the Application Server, then:
sudo su
cd /var/www/securedrop
./manage.py add-admin
Follow the prompts.
A secure diceware passphrase will be generated by manage.py. You will see output like this:
This journalist's password is: delivery propose requisite stunner dragonfly unstamped stowaway
Passphrases include the spaces between the words, but not leading or trailing whitespace. Be sure to save this passphrase in the appropriate KeePassX database.
Once that’s done, you should open the Tor Browser 
and
navigate to the Journalist Interface’s .onion address. Verify that you
can log in to the Journalist Interface with the admin account you just
created.
For adding more user accounts, please refer now to our Admin Interface Guide.
Test the Installation¶
Test connectivity¶
SSH to both servers over Tor¶
On the Admin Workstation, you should be able to SSH to the App Server and the Monitor Server.
ssh app
ssh mon
The SSH aliases should have been configured automatically by running
the ./securedrop-admin tailsconfig tool. If you’re unable to connect via aliases,
try using the verbose command format to troubleshoot:
ssh <username>@<app .onion>
ssh <username>@<mon .onion>
Tip
You can find the Onion URLs for SSH in app-ssh-aths and
mon-ssh-aths inside the install_files/ansible-base directory.
Log in to both servers via TTY¶
All access to the SecureDrop servers should be performed over SSH from the Admin Workstation. To aid in troubleshooting, physical logins via TTY are supported, but require 2FA to be configured. See the 2FA setup guide for information how to enable console logins.
Test the 2FA functionality by connecting a keyboard and display to each server, then login with the Admin username. You will need:
- sudo password for the Admin username
- TOTP code from a 2FA app such as Google Authenticator or FreeOTP
Confirm that logging in via TTY prompts for a 2FA code, and that the code generated by your smartphone app permits logging in to an interactive shell.
Sanity-check the install¶
On each server:
- Check that you can execute privileged commands by running
sudo su. - Verify that you are booted into a grsec kernel: run
uname -rand verify that the name of the running kernel ends with-grsec. - Check the current applied iptables rules with
iptables-save. It should output approximately 50 lines. - You should have received an email alert from OSSEC when it first started. If not, review our OSSEC Alerts Guide.
On the Application Server:
- Check the AppArmor status with
sudo aa-status. On a production instance all profiles should be in enforce mode.
Test the web interfaces¶
- Make sure the Source Interface is available, and that you can make a
submission.
- Do this by opening the Tor Browser and navigating to the onion
URL from
app-source-ths. Proceed through the codename generation (copy this down somewhere) and you can submit a message or attach any random unimportant file. - Usage of the Source Interface is covered by our Source User Manual.
- Do this by opening the Tor Browser and navigating to the onion
URL from
- Test that you can access the Journalist Interface, and that you can log
in as the admin user you just created.
- Open the Tor Browser and navigate to the onion URL from app-journalist-aths. Enter your password and two-factor authentication code to log in.
- If you have problems logging in to the Admin/Journalist Interface,
SSH to the Application Server and restart the ntp daemon to synchronize
the time:
sudo service ntp restart. Also check that your smartphone’s time is accurate and set to network time in its device settings.
- Test replying to the test submission.
- While logged in as an admin, you can send a reply to the test source submission you made earlier.
- Usage of the Journalist Interface is covered by our Journalist User Manual.
- Test that the source received the reply.
- Within Tor Browser, navigate back to the app-source-ths URL and use your previous test source codename to log in (or reload the page if it’s still open) and check that the reply you just made is present.
- We highly recommend that you create persistent bookmarks for the Source and Journalist Interface addresses within Tor Browser.
- Remove the test submissions you made prior to putting SecureDrop to real use. On the main Journalist Interface page, select all sources and click ‘Delete selected’.
Once you’ve tested the installation and verified that everything is working, see How to Use SecureDrop.
Onboard Journalists¶
Congratulations! You’ve successfully installed SecureDrop.
At this point, the only person who has access to the system is the admin. In order to grant access to journalists, you will need to do some additional setup for each individual journalist.
In order to use SecureDrop, each journalist needs two things:
A Journalist Tails USB.
The Journalist Interface is only accessible as an authenticated Tor Hidden Service (ATHS). For ease of configuration and security, we require journalists to set up a Tails USB with persistence that they are required to use to access the Journalist Interface.
Access to the Secure Viewing Station.
The Journalist Interface allows journalists to download submissions from sources, but they are encrypted to the offline private key that is stored on the Secure Viewing Station Tails USB. In order for the journalist to decrypt and view submissions, they need access to a Secure Viewing Station.
Determine access protocol for the Secure Viewing Station¶
Currently, SecureDrop only supports encrypting submissions to a single public/private key pair - the SecureDrop Submission Key. As a result, each journalist needs a way to access the Secure Viewing Station with a Tails USB that includes the submission private key.
The access protocol for the Secure Viewing Station depends on the structure and distribution of your organization. If your organization is centralized and there are only a few journalists with access to SecureDrop, they should be fine with sharing a single Secure Viewing Station. On the other hand, if your organization is distributed, or if you have a lot of journalists who wish to access SecureDrop concurrently, you will need to provision multiple Secure Viewing Stations.
Create a Journalist Tails USB¶
Each journalist will need a Journalist Tails USB and a Journalist Workstation, which is the computer they use to boot their Tails USB.
To create a Journalist Tails USB, just follow the same procedure you used to create a Tails USB with persistence for the Admin Tails USB, as documented in the Tails Setup Guide.
Once you’re done, boot into the new Journalist Tails USB on the Journalist Workstation. Enable persistence and set an admin password before continuing with the next section.
Set up automatic access to the Journalist Interface¶
Since the Journalist Interface is an ATHS, we need to set up the Journalist Tails USB to auto-configure Tor just as we did with the Admin Tails USB. The procedure is essentially identical, except the SSH configuration will be skipped, since only admins need to access the servers over SSH.
Tip
Copy the files app-journalist-aths and app-source-ths from
the Admin Workstation via the Transfer Device. Place these files
in ~/Persistent/securedrop/install_files/ansible-base on the
Journalist Workstation, and the ./securedrop-admin tailsconfig
tool will automatically use them.
Warning
Do not copy the files app-ssh-aths and mon-ssh-aths
to the Journalist Workstation. Those files grant access via SSH,
and only the Admin Workstation should have shell access to the
servers.
Since you need will the Tails setup scripts (securedrop/tails_files) that
you used to Configure the *Admin Workstation* Post-Install, clone (and verify) the SecureDrop
repository on the Journalist Workstation, just like you did for the Admin
Workstation. Refer to the docs for cloning the SecureDrop
repository, then return here to
continue setting up the Journalist Workstation.
Once you’ve done this, run the install script to configure the shortcuts for the Source and Journalist Interfaces:
./securedrop-admin tailsconfig
If you did not copy over the app-source-ths and app-journalist-aths
files from the Admin Workstation, the script will prompt for the information.
Make sure to type the information carefully, as any typos will break access
for the Journalist Workstation.
Once the script is finished, you should be able to access the Journalist Interface. Open the Tor Browser and navigate to the .onion address for the Journalist Interface. You should be able to connect, and will be automatically taken to a login page.
Add an account on the Journalist Interface¶
Finally, you need to add an account on the Journalist Interface so the journalist can log in and access submissions. See the section on Adding Users in the admin Guide.
Import GPG keys for journalists with access to SecureDrop to the SVS¶
While working on a story, journalists may need to transfer some documents or notes from the Secure Viewing Station to the journalist’s work computer on the corporate network. To do this, the journalist should re-encrypt them with their own keys. If a journalist does not already have a personal GPG key, they can follow the same steps above to create one. The journalist should store the private key somewhere safe; the public key should be stored on the Secure Viewing Station.
If the journalist does have a key, transfer their public key from wherever it
is located to the Secure Viewing Station, using the Transfer Device. Open
the file manager 
and double-click on the public key to import it.
Verify Journalist Setup¶
Once the journalist device and account have been provisioned, then the admin should run through the following steps with each journalist to verify the journalist is set up for SecureDrop.
The journalist should verify that they:
- Have their own Journalist Tails USB that they have verified they are able to boot on the Journalist Workstation.
Note
It is important that they test on the same Journalist Tails USB and the same Journalist Workstation they will be using on a day to day basis. Issues may arise due to differences in USB drives or laptop models.
- Verify they are able to decrypt the persistent volume on the Journalist Tails USB.
- Ensure that they can connect to and login to the Journalist Interface.
- Ensure that they have a Data Transfer Device with a saved passphrase.
- Verify they have access to the Secure Viewing Station they will be using by plugging in the SVS USB, booting, and verifying they can decrypt the persistent volume.
Note
Again, it is important that they test on the same SVS Tails USB and the same Secure Viewing Station they will be using on a day to day basis.
- Verify the submission private key is present in the Secure Viewing Station
persistent volume by clicking the clipboard icon in the top right
corner of the Tails desktop and selecting “Manage Keys”. When clicking
“GnuPG keys” the key should be present.
Tip
The journalist should have all the credentials used in this checklist saved in the KeePassX database stored in the persistent volume of the Journalist Workstation.
At this point, the journalist has verified they have the devices and credentials they need and can proceed to a walkthrough of the entire SecureDrop workflow.
Overview¶
SecureDrop is only as secure as the environment that surrounds it. To keep sources safe, the news organization’s website must employ a set of basic security best practices or else you risk losing any source protection provided by SecureDrop.
While SecureDrop itself is located on a Tor hidden service, news organizations also need to create a SecureDrop landing page that will explain how SecureDrop works, give sources instructions on how to access the Tor hidden service, and disclose the risks. We recommend to also include a privacy policy (see our Sample SecureDrop Privacy Policy) that describes what data is collected and how it will be used by your organization.
It is important to keep in mind that implementing SecureDrop will bring more attention to your organization by security researchers, hackers, and other like-minded people. If the landing page minimum requirements are not implemented, these people will be sure to loudly point this out on Twitter and other blogs as a #SecurityFail. This will discourage potential sources from using your instance of SecureDrop. However, it can easily be avoided by following the below best practices.
Freedom of the Press Foundation eventually plans to list all of those SecureDrop onion URLs as “verified” on its website that meet the minimum requirements for deployment best practices. If your organization cannot follow the minimum guidelines we cannot recommend to users that your SecureDrop instance is safe to use.
In addition to implementing the below best practices, it is strongly recommended that you have a reputable security firm perform a security review of your organization’s public website prior to launching an instance of SecureDrop. Upon request, we can help put you in touch with a few security firms if you need more assistance.
Landing Page¶
URL and location¶
Ideally you would not use a separate subdomain, but would use a path at your top-level domain, e.g. organization.com/securedrop. This is because TLS does not encrypt the hostname, so a SecureDrop user whose connection is being monitored would be trivially discovered.
If the landing page is deployed on the same domain as another site, you might consider having some specific configuration (such as the security headers below) apply only to the /securedrop request URI. This can be done in Apache by the encapsulating these settings within a <Location> block, which can be defined similarly in nginx by using the location {} directive.
HTTPS only (no mixed content)¶
Most news organizations, in fact almost all, do not use HTTPS encryption by default. This is the number one minimum requirement for the SecureDrop landing page on your website. Without HTTPS, a source can easily be exposed as a visitor to your site.
This may be difficult if your website serves advertisements or utilizes a legacy content delivery network. You should make sure the SecureDrop landing page does not serve ads of any kind, even if the rest of your site does.
If you do not serve ads on any of your site, you should also consider switching your whole site over to HTTPS by default immediately. If you do serve ads, consider pressuring your ad networks to enable you to switch to HTTPS for your entire website in the future.
If your website needs to operate in both HTTPS and HTTP mode, use protocol-relative URLs for resources such as images, CSS and JavaScript in common templates to ensure your page does not end up in a mixed HTTPS/HTTP state.
Consider submitting your domain to be included in the Chrome HSTS preload list if you can meet all of the requirements. This will tell web browsers that the site is only ever to be reached over HTTPS.
Perfect Forward Secrecy¶
Perfect Forward Secrecy (PFS) is a property of encryption protocols that ensures each SSL session has a unique key, meaning that if the key is compromised in the future it can’t be used to decrypt previously recorded SSL sessions. You may need to talk to your CA (certificate authority) and CDN (content delivery network) for this, although our recommended configuration below provides forward secrecy.
SSL certificate recommendations¶
Regardless of where you choose to purchase your SSL cert and which CA issues it, you’ll often be asked to generate the private key and a CSR (certificate signing request).
When you do this, it’s imperative that you use SHA-2 as the hashing algorithm instead of SHA-1, which is being phased out. You should also choose a key size of at least 2048 bits. These parameters will help ensure that the encryption used on your landing page is sufficiently strong. The following example OpenSSL command will create a private key and CSR with a 4096-bit key length and a SHA-256 signature:
openssl req -new -newkey rsa:4096 -nodes -sha256 -keyout domain.com.key -out domain.com.csr
Don’t load any resources (scripts, web fonts, etc.) from 3rd parties (e.g. Google Web Fonts)
This will potentially leak information about sources to third parties, which can more easily be accessed by law enforcement agencies. Simply copy them to your server and serve them yourself to avoid this problem.
Don’t use 3rd party analytics, tracking, or advertising¶
Most news websites, even those that are non-profits, use 3rd-party analytics tools or tracking bugs on their websites. It is vital that these are disabled for the SecureDrop landing page.
In the past, some news organizations were heavily criticized when launching their SecureDrop instances because their landing page contained trackers. They claimed they were going to great lengths to protect sources’ anonymity, but by having trackers on their landing page, this also opened up multiple avenues for third parties to collect information on those sources. This information can potentially be accessed by law enforcement or intelligence agencies and could unduly expose a source.
Similarly, consider avoiding the use of Cloudflare (and other CDNs: Akamai, StackPath, Incapsula, Amazon CloudFront, etc.) for the SecureDrop landing page. These services intercept requests between a potential source and the SecureDrop landing page and can be used to track or collect information on sources.
Apply applicable security headers¶
Security headers give instructions to the web browser on how to handle requests from the web application. These headers set strict rules for the browser and help mitigate against potential attacks. Given the browser is a main avenue for attack, it is important these headers are as strict as possible.
You can use the site securityheaders.com to easily test your website’s security headers.
If you use Apache, you can use these:
Header set Cache-Control "max-age=0, no-cache, no-store, must-revalidate"
Header edit Set-Cookie ^(.*)$ $;HttpOnly
Header set Pragma "no-cache"
Header set Expires "-1"
Header always append X-Frame-Options: DENY
Header set X-XSS-Protection: "1; mode=block"
Header set X-Content-Type-Options: nosniff
Header set X-Download-Options: noopen
Header set X-Permitted-Cross-Domain-Policies: master-only
Header set Content-Security-Policy: "default-src 'self'"
If you intend to run nginx as your webserver instead, this will work:
add_header Cache-Control "max-age=0, no-cache, no-store, must-revalidate";
add_header Pragma no-cache;
add_header Expires -1;
add_header X-Frame-Options DENY;
add_header X-XSS-Protection "1; mode=block";
add_header X-Content-Type-Options nosniff;
add_header Content-Security-Policy "default-src 'self'";
add_header X-Download-Options: noopen;
add_header X-Permitted-Cross-Domain-Policies master-only;
Additional Apache configuration¶
To enforce HTTPS/SSL always, you need to set up redirection within the HTTP (port 80) virtual host:
RewriteEngine On
RewriteCond %{HTTPS} off
RewriteRule (.*) https://%{HTTP_HOST}%{REQUEST_URI}
The same thing can be achieved in nginx with a single line:
return 301 https://$server_name$request_uri;
In your SSL (port 443) virtual host, set up HSTS and use these settings to give preference to the most secure cipher suites:
Header set Strict-Transport-Security "max-age=16070400;"
SSLProtocol all -SSLv2 -SSLv3
SSLHonorCipherOrder on
SSLCompression off
SSLCipherSuite EECDH+AESGCM:EDH+AESGCM:AES256+EECDH:AES256+EDH
Here’s a similar example for nginx:
add_header Strict-Transport-Security max-age=16070400;
ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
ssl_prefer_server_ciphers on;
ssl_ciphers "EECDH+AESGCM:EDH+AESGCM:AES256+EECDH:AES256+EDH";
Note
We have prioritized security in selecting these cipher suites, so if you choose to use them then your site might not be compatible with legacy or outdated browsers and operating systems. For a good reference check out Cipherli.st.
You’ll need to run a2enmod headers ssl rewrite for all these to
work. You should also set ServerSignature Off and
ServerTokens Prod, typically in /etc/apache2/conf.d/security. For nginx,
use server_tokens off; so that the webserver doesn’t leak extra information.
If you use nginx, you can follow this link and use the configuration example provided by ProPublica.
Change detection monitoring for the web application configuration and landing page content
OSSEC is a free and open source host-based intrusion detection suite that includes a file integrity monitor. More information can be found here.
Don’t log access to the landing page in the webserver
Here’s an Apache example that would exclude the landing page from logging:
SetEnvIf Request_URI "^/securedrop$" dontlog
CustomLog logs/access_log common env=!dontlog
In nginx, logging can be disabled like so:
access_log off;
error_log off;
Security suggestions
To guard your landing page against being modified by an attacker and directing sources to a rogue SecureDrop instance, you will need good security practices applying to the machine where it is hosted. Whether it’s a VPS in the cloud or dedicated server in your office, you should consider the following:
- Brute force login protection (see sshguard or fail2ban)
- Disable root SSH login
- Use SSH keys instead of passwords
- Use long, random and complex passwords
- Firewall rules to restrict accessible ports (see iptables or ufw)
- AppArmor, grsecurity, SELINUX, modsecurity
- Intrusion and/or integrity monitoring (see Logwatch, OSSEC, Snort, rkhunter, chkrootkit)
- Downtime alerts (Nagios or Pingdom)
- Two-factor authentication (see libpam-google-authenticator, libpam-yubico)
It’s preferable for the landing page to have its own segmented environment instead of hosting it alongside other sites running potentially vulnerable software or content management systems. Check that user and group file permissions are locked down and that modules or gateway interfaces for dynamic scripting languages are not enabled. You don’t want any unnecessary code or services running as this increases the attack surface.
Minimum requirements for the SecureDrop environment¶
- The Application and Monitor Servers should be dedicated physical machines, not virtual machines.
- A trusted location to host the servers. The servers should be hosted in a location that is owned or occupied by the organization to ensure that their legal department can not be bypassed with gag orders.
- The SecureDrop servers should be on a separate internet connection or completely segmented from corporate network.
- All traffic from the corporate network should be blocked at the SecureDrop’s point of demarcation.
- Video monitoring should be recorded of the server area and the organizations safe.
- Journalists should ensure that while using the air-gapped viewing station they are in an area without video cameras.
- An established monitoring plan and incident response plan. Who will receive the OSSEC alerts and what will their response plan be? These should cover technical outages and a compromised environment plan.
Whole Site Changes¶
Ideally, some or all of the following changes are made to improve the overall security of the path to the landing page and obfuscate traffic analysis.
- Make your entire site available through HTTPS.
- That way, visits to your landing page won’t stand out as the only encrypted traffic to your site.
- Include an iframe for all (or a random subset of) visitors, loading
this particular URL (hidden).
- By artificially generating traffic to the endpoint it will be harder to distinguish these from other, ‘real’ requests.
- Use a random delay for adding the iframe (otherwise the ‘pairing’ with the initial HTTP request may distinguish this traffic).
- Print the link, URL and info block on the dead trees (the paper), as others have suggested.
- Add HSTS headers.
Suggested¶
- For publicly advertised SecureDrop instances display the Source Interface’s hidden service onion address on all of the organization public pages.
- Mirror the Tor Browser and Tails so sources do not have to visit torproject.org to download it.
Sample SecureDrop Privacy Policy¶
[DATE]
SecureDrop strives to create a more secure environment for whistleblowers to give information to journalists. It was installed at [MEDIA ORG] with the help of Freedom of the Press Foundation.
Please read this privacy policy carefully. It explains what information what type of information SecureDrop does and does not collect, and why.
Collection of Information From Sources¶
- We don’t ask or require you to provide any personally identifying information when you submit materials through SecureDrop.
- The system does not record your IP address, information about your browser, computer, or operating system. Furthermore, the SecureDrop pages do not embed third-party content or deliver persistent cookies to your browser.
- The server will only store the date and time of the newest message sent from each source. Once you send a new message, the time and date of your previous message is automatically deleted.
- Journalists decrypt and read each message offline. They are encouraged to delete messages from the server on a regular basis. The date and time of any message will be securely deleted from the server when the message is deleted.
- Please keep in mind that the actual messages you send and receive through SecureDrop may include personally identifying information. For this reason, once you read a journalist’s message, we recommend you delete it. It will then be securely deleted from the file system.
Also please note that when you submit certain types of files through SecureDrop, you may be sending us metadata associated with that file.
For example, if you submit a photo through SecureDrop in JPEG format, the file may include information about the date, time, and the GPS location of where it was taken, and the type of device used to take the photo. Similarly, if you submit a Word file (.doc or .docx) through SecureDrop, it may include the identity of the document’s author, the author’s operating system, GPS data about the author’s location, and the date and time when the document was created.
Our policy is to scrub metadata from the files we receive through SecureDrop before publication. If you don’t want to send us metadata, please use the Metadata Anonymization Toolkit to scrub the file before you submit it.
Collection of Information About Journalists’ Use of SecureDrop¶
[MEDIA ORG] collects information about journalists’ use of SecureDrop for security monitoring and to make sure the system works properly.
This information we collect about journalists includes details about the device, browser, and operating system journalists use when accessing the system, and the date and time of each session.
We retain these access logs for [___] days, and then delete them.
Data Security¶
[MEDIA ORG] works diligently to protect the identities of our sources and keep the information they give us confidential.
SecureDrop servers are under the physical control of [MEDIA ORG] and do not share common elements of the [MEDIA ORG’S] other infrastructure.
However, no one can truly guarantee 100% security of any system. Like all software, SecureDrop may contain bugs. Ultimately, you use the SecureDrop service at your own risk.
Children Under 13¶
The Children’s Online Privacy Protection Act restricts our ability to collect personal information from children under 13. This site is not directed to children 12 or younger.
Changes to This Policy¶
We may revise this Privacy Policy from time to time. The most current version of the policy will govern our collection and use of personal information and will always be at [LINK]. If we make changes that we believe are material, we will prominently display a notice on our site [___] days before we make those changes.
Contact¶
[MEDIA ORG] welcomes questions, concerns, and feedback about this policy. If you have suggestions for us, feel free to let us know at [EMAIL ADDRESS].
Pre-Install Hardware Checklist¶
This is the minimum hardware that must be acquired to install SecureDrop:
- 2 computers with memory and hard drives to use as the SecureDrop servers.
- Mouse, keyboard, monitor (and necessary dongle or adapter) for installing the servers.
- Dedicated physical computers for the Admin, Journalist, and Secure Viewing Station that can boot to Tails. At minimum this is 2 computers.
- Dedicated airgapped hardware for the mouse, keyboard, and monitor (only if you are using a desktop for the Secure Viewing Station).
- Network firewall.
- At least 3 ethernet cables.
- Plenty of USB sticks: 1 drive for the master Tails stick, 1 drive for each Secure Viewing Station, 1 drive for each Transfer drive, and 1 drive for each admin and journalist.
Note
For additional details, please read the full document on Required Hardware for SecureDrop.
Promoting Your SecureDrop Instance¶
At Freedom of the Press Foundation, we’ve found news organizations that get the most out of SecureDrop are those who promote it regularly and effectively. SecureDrop will only be used by sources if they know it exists, so it’s best to promote its use in a variety of ways so that a wide swath of people will see it.
So here are a few tips used by some of the news outlets that have seen the most success with SecureDrop.
Make a High Profile Announcement¶
Anytime you launch a SecureDrop, you’ll want to write an accompanying news story along with it to alert your readers and potential sources where to submit information. Almost every news organization already does this, but some good recent examples come from USA Today, The Guardian, and Wired. You can also write a companion Q & A like the Washington Post did.
However, a launch announcement is really just a small piece of the puzzle. It’s important to regularly remind readers and potential sources that your SecureDrop exists, because only a tiny fraction will likely see the launch announcement and it will quickly be buried in other news after a couple of days.
Provide a Clear Link on Your Homepage¶
Making your SecureDrop or secure tips page easy to find is one of the most important things you can do to ensure that potential sources use it. The best way you can do this is providing a clear link on your home page, so that every time a user goes to your website, they can quickly see where they need to go.
For example, the Intercept has a “become a source” link in its main menu:
The Washington Post has a link on their front page for “how to share a tip securely”:
Other news organizations put a little link in their footer, however, we’ve found that this is not as effective as putting it in a more prominent on your front page.
Provide Links at the Bottom of Your Articles¶
Another great way to remind potential sources know that they can use SecureDrop is to put a link at the bottom of each article. For example, Gizmodo Media Group, uses a message like this:
Create an Instructional Video on How to Access and Use Your SecureDrop¶
To better help potential sources visualize how SecureDrop works, several organizations have made short instructional videos walking through all the steps. Some good examples include the Toronto Globe and Mail, The Intercept, and Lucy Parsons Labs.
Regularly Share Your SecureDrop Landing Page on Social Media¶
The majority of adults in the United States now get their news from Facebook or other social media sites like Twitter, so it’s important to regularly remind people via social media posts that SecureDrop is the safest way they can contact your journalists if they have a sensitive tip to share. If there’s specific stories you are looking for tips on that may already be in the news, this is a great way of getting added attention to your SecureDrop.
Target Potential Whistleblowers with Advertising¶
Facebook and Twitter also allow for targeted advertising to users in specific locations, attributes, and sometimes even specific users. Gizmodo Media Group recently targeted online advertisements for their secure tips page at DC residents imploring them to tell on trump. At Freedom of the Press Foundation, we ran a proof of concept Twitter advertisement aimed at EPA and NOAA employees to show how it can be done. You can read about how you can do the same thing here.
Put an Advertisement in Your Physical Paper¶
Obviously this tip only applies to news outlets that also print a physical newspaper, but putting an ad or in the paper to tell readers where to go to access SecureDrop can be extremely effective.
The New York Times took out a full page ad in their own paper when they launched SecureDrop and other secure communications tools for their tips line:
And the Toronto Globe and Mail regularly puts a note in their physical paper reminding potential sources where they can go:
What Makes SecureDrop Unique¶
SecureDrop attempts to solve or mitigate several problems journalists and sources have faced in recent legal investigations, attacks from state actors, and other threats to the confidentiality of communications.
No third parties that can secretly be subpoenaed¶
For decades, there were very few leak prosecutions in the United States in large part because the government would have to subpoena reporters to testify against a source to get a conviction. That proved incredibly difficult, if not impossible, when reporters regularly refused to testify and threatened to go to jail rather than betray a source.
More recently, there have been a record number of leak prosecutions largely because the government has learned they don’t need reporters to testify against their sources anymore. Instead, they can just secretly subpoena third party services like Google or AT&T or Verizon or Facebook and get a treasure trove of digital information on reporters and sources’ communications. For example, the Associated Press had twenty of their phone lines subpoenaed without their knowledge in order to identify a source. The government also got a warrant for Fox News reporter James Rosen’s Gmail account without him knowing. In both cases, their alleged sources were prosecuted, even though journalists never directly divulged their sources.
SecureDrop completely eliminates third parties from the equation and puts the power to challenge such cases back in the hands of reporters. The journalist and source communicate exclusively through one server that the news organization owns and sits on their property, so any legal order for information must go directly to the news organization rather than Google or AT&T. The news organization again has the power to contest the order or refuse to comply if they so wish.
Limits the metadata trail as much as possible¶
In many leak cases, the metadata of a journalist’s communications—where you’re located, who you’re talking to, when you’re talking to them, and how often—can lead to trouble just as much as the actual content of your conversations.
Even if a government serves a court order directly to a news organization to compel the disclosure of information, SecureDrop logs much less information than email providers or phone companies do.
The source can only log into SecureDrop through the Tor Browser, which masks the source’s IP address to begin with, so there is no indication who the source is (unless they disclose it) and where they are sending information from. The Tor IP address, the computer, and the browser type that the source is using is not logged either.
For each source, only the time and date of each submission is logged on the server. When a source sends a new message, the time and date of the last message is overwritten. This means that there won’t be a trail of metadata showing exactly when the source and journalist were talking.
In addition, sources cannot create a custom username that could reveal information about them. Instead, SecureDrop automatically generates two random codenames, one to show to the source and another to the journalists using the system.
Encrypted and air-gapped¶
Communications through SecureDrop are both encrypted in transit, so messages cannot be easily intercepted and read while they are traversing the Internet and are also encrypted on the server so if any attacker manages to break into the server, they would not be able to read past messages.
In addition, the decryption key for SecureDrop submissions sits on an air-gapped computer (not connected to the Internet). This air-gapped computer is the only place SecureDrop submissions are decrypted and read so that they are much harder for an attacker to access.
Protecting against hackers¶
A 2014 study showed that 20 of the top 25 news organization had, at one time or another, their networks compromised by state sponsored hackers.
Because of this threat, SecureDrop completely segments its traffic from a news organization’s normal network. Submissions are accessed and downloaded using the Tails operating system, which boots off of a USB, does not touch your computer’s hard drive, and routes all its Internet traffic through Tor.
Submissions are decrypted on an air-gapped computer also using Tails. This mitigates against the risk that an attacker could send malware through SecureDrop in an attempt to infect the news organization’s normal network as well.
The SecureDrop servers also undergo significant system hardening in order to make it as difficult as possible for hackers to break in.
The SecureDrop servers also undergo significant system hardening in order to make it as difficult as possible for hackers to break in. By doing so, SecureDrop protects sources against networks that are already compromised, as well as a news organization’s normal network from attacks that could potentially come through SecureDrop.
Free and open source software¶
100% of SecureDrop’s code is free and open source. Not only does this mean anyone can install SecureDrop themselves, but the code is available online for security experts to test for vulnerabilities.
SecureDrop has gone through four audits by third party penetration testing firms and will continue to go through audits when major changes are made to the code base in the future. We always publish these audits publicly so everyone can be assured that SecureDrop is as safe to use as possible.
Google Authenticator¶
As part of the SecureDrop installation process, you will need to set up two factor authentication using the Google Authenticator app for both the Application and Monitor Servers.
Connect to each of the servers using ssh and run google-authenticator.
Follow the prompts, saying “yes” when prompted for a “yes/no” response. When
you’ve finished, open the Google Authenticator app on your smartphone and
follow the steps below for either iOS or Android. Once you’ve properly set up
the first server, repeat these steps again on the other.
iOS¶
- Select the pencil in the top-right corner
- Select the plus sign at the bottom to add a new entry
- Select Scan Barcode
- Scan the barcode using your phone’s camera
A new entry will automatically be added to the list. If you wish to edit this entry and give it a new name, do the following:
- Select the pencil in the top-right corner
- Select the pencil next to the entry you wish to edit
- Select the checkmark in the top-right corner to save
To complete the setup process, say y to each prompt presented by
google-authenticator.
Android¶
- Select the menu bar in the top-right corner
- Select Set up account
- Select Scan a barcode
- Scan the barcode using your phone’s camera
A new entry will automatically be added to the list. If you wish to edit this entry and give it a new name, do the following:
- Highlight the entry with a long press
- Select the pencil in the top-right corner
- Edit the entry’s name and press Save
To complete the setup process, say y to each prompt presented by
google-authenticator.
Useful Logs¶
Both servers¶
- AppArmor and grsec errors:
/var/log/kern.log - iptables:
/var/log/syslog
Application Server¶
- Apache:
/var/log/apache2/*
If an error is triggered it’s in the SecureDrop application logs:
/var/log/apache2/source-error.log and
/var/log/apache2/journalist-error.log
Monitor Server¶
OSSEC
/var/ossec/logs/ossec.log /var/ossec/logs/alerts/alerts.log
Postfix/Procmail
/var/log/mail.log /var/log/procmail.log
OSSEC Guide¶
Setting up OSSEC alerts¶
OSSEC is an open source host-based intrusion detection system (IDS) that we use to perform log analysis, file integrity checking, policy monitoring, rootkit detection and real-time alerting. It is installed on the Monitor Server and constitutes that machine’s main function. OSSEC works in a server-agent scheme, that is, the OSSEC server extends its existing functions to the Application Server through an agent installed on that server, covering monitoring for both machines.
In order to receive email alerts from OSSEC, you need to supply several
settings to Ansible in the playbook for your environment. If you don’t
already have a working mail server or don’t know what to do, then see
the section below about using Gmail as a fallback option. We assume that
you’re working out of the ‘securedrop’ directory you cloned the code
into, and editing install_files/ansible-base/group_vars/all/site-specific
prior to installing SecureDrop.
What you need:
- The GPG key that OSSEC will encrypt alerts to
- The email address that will receive alerts from OSSEC
- Information for your SMTP server or relay (hostname, port)
- Credentials for the email address that OSSEC will send alerts from
Receiving email alerts from OSSEC requires that you have an SMTP relay to route the emails. You can use an SMTP relay hosted internally, if one is available to you, or you can use a third-party SMTP relay such as Gmail. The SMTP relay does not have to be on the same domain as the destination email address, i.e. smtp.gmail.com can be the SMTP relay and the destination address can be securedrop@freedom.press.
While there are risks involved with receiving these alerts, such as information leakage through metadata, we feel the benefit of knowing how the SecureDrop servers are functioning is worth it. If a third-party SMTP relay is used, that relay will be able to learn information such as the IP address the alerts were sent from, the subject of the alerts, and the destination email address the alerts were sent to. Only the body of an alert email is encrypted with the recipient’s GPG key. A third-party SMTP relay could also prevent you from receiving any or specific alerts.
The SMTP relay that you use should support SASL authentication and SMTP TLS protocols TLSv1.2, TLSv1.1, and TLSv1. Most enterprise email solutions should be able to meet those requirements.
Below are the values you must specify in to configure OSSEC correctly.
For first-time installs, you can use the
configuration playbook, or edit
install_files/ansible-base/group_vars/all/site-specific manually.
- GPG public key used to encrypt OSSEC alerts:
ossec_alert_gpg_public_key - Fingerprint of key used when encrypting OSSEC alerts:
ossec_gpg_fpr - The email address that will receive alerts from OSSEC:
ossec_alert_email - The reachable hostname of your SMTP relay:
smtp_relay - The secure SMTP port of your SMTP relay:
smtp_relay_port(typically 25, 587, or 465. must support TLS encryption) - Email username to authenticate to the SMTP relay:
sasl_username - Domain name of the email used to send OSSEC alerts:
sasl_domain - Password of the email used to send OSSEC alerts:
sasl_password
If you don’t know what value to enter for one of these, please ask your
organization’s email admin for the full configuration before
proceeding. It is better to get these right the first time rather than
changing them after SecureDrop is installed. If you’re not sure of the
correct smtp_relay_port number, you can use a simple mail client
such as Thunderbird to test different settings or a port scanning tool
such as nmap to see what’s open. You could also use telnet to make sure
you can connect to an SMTP server, which will always transmit a reply
code of 220 meaning “Service ready” upon a successful connection.
The smtp_relay mail server hostname is often, but not always,
different from the sasl_domain, e.g. smtp.gmail.com and gmail.com.
In some cases, authentication or transport encryption mechanisms will vary and you may require later edits to the Postfix configuration (mainly /etc/postfix/main.cf) on the Monitor Server in order to get alerts to work. You can consult Postfix’s official documentation for help, although we’ve described some common scenarios in the troubleshooting section.
If you have your GPG public key handy, copy it to
install_files/ansible-base and then specify the filename, e.g.
ossec.pub, in the ossec_alert_gpg_public_key line of
group_vars/all/site-specific.
If you don’t have your GPG key ready, you can run GnuPG on the command line in
order to find, import, and export your public key. It’s best to copy the key
from a trusted and verified source, but you can also request it from keyservers
using the known fingerprint. Looking it up by email address or a shorter key ID
format could cause you to obtain a wrong, malicious, or expired key. Instead, we
recommend you type out your fingerprint in groups of four (just like GPG prints
it) enclosed by double quotes. The reason we suggest this formatting for the
fingerprint is simply because it’s easiest to type and verify correctly. In the
code below simply replace <fingerprint> with your full, space-separated
fingerprint:
Download your key and import it into the local keyring:
gpg --recv-key "<fingerprint>"
Note
It is important you type this out correctly. If you are not copy-pasting this command, we recommend you double-check you have entered it correctly before pressing enter.
Again, when passing the full public key fingerprint to the --recv-key command, GPG
will implicitly verify that the fingerprint of the key received matches the
argument passed.
Caution
If GPG warns you that the fingerprint of the key received does not match the one requested do not proceed with the installation. If this happens, please email us at securedrop@freedom.press.
Next we export the key to a local file.
gpg --export -a "<fingerprint>" > ossec.pub
Copy the key to a directory where it’s accessible by the SecureDrop installation:
cp ossec.pub install_files/ansible-base/
The fingerprint is a unique identifier for an encryption (public) key. The
short and long key ids correspond to the last 8 and 16 hexadecimal digits of the
fingerprint, respectively, and are thus a subset of the fingerprint. The value
for ossec_gpg_fpr must be the full 40 hexadecimal digit GPG fingerprint for
this same key, with all capital letters and no spaces. The following command
will retrieve and format the fingerprint per our requirements:
gpg --with-colons --fingerprint "<fingerprint>" | grep "^fpr" | cut -d: -f10
Next you specify the e-mail that you’ll be sending alerts to, as
ossec_alert_email. This could be your work email, or an alias for a
group of IT admins at your organization. It helps for your mail
client to have the ability to filter the numerous messages from OSSEC
into a separate folder.
Now you can move on to the SMTP and SASL settings, which are
straightforward. These correspond to the outgoing e-mail address used to
send the alerts instead of where you’re receiving them. If that e-mail
is ossec@news-org.com, the sasl_username would be ossec and
sasl_domain would be news-org.com.
The Postfix configuration enforces certificate verification, and
requires both a valid certificate and STARTTLS support on the SMTP
relay. By default the system CAs will be used for validating the relay
certificate. If you need to provide a custom CA to perform the
validation, copy the cert file to install_files/ansible-base add a
new variable to group_vars/all/site-specific:
smtp_relay_cert_override_file: MyOrg.crt
where MyOrg.crt is the filename. The file will be copied to the
server in /etc/ssl/certs_local and the system CAs will be ignored
when validating the SMTP relay TLS certificate.
Save group_vars/all/site-specific, exit the editor and proceed with
the installation by running the playbooks.
Using Gmail for OSSEC alerts¶
It’s easy to get SecureDrop to use Google’s servers to deliver the alerts, but it’s not ideal from a security perspective. This option should be regarded as a backup plan. Keep in mind that you’re leaking metadata about the timing of alerts to a third party — the alerts are encrypted and only readable to you, however that timing may prove useful to an attacker.
First you should sign up for a new
account. While it’s
technically possible to use an existing Gmail account, it’s best to
compartmentalize these alerts from any of your other activities. Choose
a strong and random passphrase for the new account. Skip the creation of
a Google+ profile and continue straight to Gmail. Next, enable Google’s
2-Step Verification. With
2-Step Verification enabled, you won’t use the normal account password
in this configuration — it will not work; instead you must navigate
(using the settings in the top right) to Account > Signing in > App
passwords, and generate a new App password which you will use as the
sasl_passwd.
Once the account is created you can log out and provide the values for
sasl_username as your new Gmail username (without the domain),
sasl_domain, which is typically gmail.com (or your custom Google
Apps domain), and sasl_passwd. Remember to use the App password
generated from the 2-step config for sasl_passwd, as the primary
account password won’t work. The smtp_relay is smtp.gmail.com and
the smtp_relay_port is 587.
Configuring fingerprint verification¶
If you run your own mail server, you may wish to increase the security
level used by Postfix for sending mail to fingerprint, rather than
secure. Doing so will require an exact match for the fingerprint of
TLS certificate on the SMTP relay. The advantage to fingerprint
verification is additional security, but the disadvantage is potential
maintenance cost if the fingerprint changes often. If you manage the
mail server and handle the certificate rotation, you should update the
SecureDrop configuration whenever the certificate changes, so that OSSEC
alerts continue to send. Using fingerprint verification does not work
well for popular mail relays such as smtp.gmail.com, as those
fingerprints can change frequently, due to load balancing or other
factors.
You can retrieve the fingerprint of your SMTP relay by running the
command below (all on one line). Please note that you will need to
replace smtp.gmail.com and 587 with the correct domain and port
for your SMTP relay.
openssl s_client -connect smtp.gmail.com:587 -starttls smtp < /dev/null 2>/dev/null |
openssl x509 -fingerprint -noout -in /dev/stdin | cut -d'=' -f2
If you are using Tails, you will not be able to connect directly with
openssl s_client due to the default firewall rules. To get around
this, proxy the requests over Tor by adding torify at the beginning
of the command. The output of the command above should look like the
following:
6D:87:EE:CB:D0:37:2F:88:B8:29:06:FB:35:F4:65:00:7F:FD:84:29
Finally, add a new variable to group_vars/all/site-specific as
smtp_relay_fingerprint, like so:
smtp_relay_fingerprint: "6D:87:EE:CB:D0:37:2F:88:B8:29:06:FB:35:F4:65:00:7F:FD:84:29"
Specifying the fingerprint will configure Postfix to use it for
verification on the next playbook run. (To disable fingerprint
verification, simply delete the variable line you added, and rerun the
playbooks.) Save group_vars/all/site-specific, exit the editor and
proceed with the installation by running the
playbooks.
Troubleshooting¶
Some OSSEC alerts should begin to arrive as soon as the installation has finished.
The easiest way to test that OSSEC is working is to SSH to the Monitor
Server and run service ossec restart. This will trigger an Alert
level 3 saying: “Ossec server started.”
So you’ve finished installing SecureDrop, but you haven’t received any OSSEC alerts. First, check your spam/junk folder. If they’re not in there, then most likely there is a problem with the email configuration. In order to find out what’s wrong, you’ll have to SSH to the Monitor Server and take a look at the logs. To examine the mail log created by Postfix, run the following command:
tail /var/log/mail.log
The output will show you attempts to send the alerts and provide hints as to what went wrong. Here’s a few possibilities and how to fix them:
| Problem | Solution |
|---|---|
| Connection timed out | Check that the hostname and port is correct
in the relayhost line of
/etc/postfix/main.cf |
| Server certificate not verified | Check that the relay certificate is valid
(for more detailed help, see Troubleshooting
SMTP TLS).
Consider adding
smtp_relay_cert_override_fileto
prod_specific.yml as described above. |
| Authentication failure | Edit
/etc/postfix/sasl_passwd and make
sure the username, domain and password are
correct. Run postmap /etc/postfix/sasl_passwdto update when finished.
|
After making changes to the Postfix configuration, you should run
service postfix reload and test the new settings by restarting the
OSSEC service.
Tip
If you change the SMTP relay port after installation for any
reason, you must update the smtp_relay_port variable in the
group_vars/all/site-specific file, then rerun the Ansible playbook.
As a general best practice, we recommend modifying and
rerunning the Ansible playbook instead of manually editing
the files live on the servers, since values like smtp_relay_port
are used in several locations throughout the config.
Useful log files for OSSEC¶
Other log files that may contain useful information:
- /var/log/procmail.log
- Includes lines for sending mail containing OSSEC alerts.
- /var/log/syslog
- Messages related to grsecurity, AppArmor and iptables.
- /var/ossec/logs/ossec.log
- OSSEC’s general operation is covered here.
- /var/ossec/logs/alerts/alerts.log
- Contains details of every recent OSSEC alert.
Tip
Remember to encrypt any log files before sending via email, for example to securedrop@freedom.press, in order to protect security-related information about your organization’s SecureDrop instance.
Not receiving emails¶
Some mail servers require that the sending email address match the account
that authenticated to send mail. By default the Monitor Server will use
ossec@ossec.server for the from line, but your mail provider may not support
the mismatch between the domain of that value and your real mail host.
If the Admin email address (configured as ossec_alert_email in
group_vars/all/site-specific) does not start receiving OSSEC alerts updates shortly
after the first playbook run, try setting ossec_from_address in
group_vars/all/site-specific to the full email address used for sending the alerts,
then run the playbook again.
Message failed to encrypt¶
If OSSEC cannot encrypt the alert to the GPG public key for the Admin
email address (configured as ossec_alert_email in group_vars/all/site-specific),
the system will send a static message instead of the scheduled alert:
Failed to encrypt OSSEC alert. Investigate the mailing configuration on the Monitor Server.
Check the GPG configuration vars in group_vars/all/site-specific. In particular,
make sure the GPG fingerprint matches that of the public key file you
exported.
Troubleshooting SMTP TLS¶
Your choice of SMTP relay server must support STARTTLS and have a valid
server certificate. By default, the Monitor Server’s Postfix
configuration will try to validate the server certificate using the
default root store (in Ubuntu, this is maintained in the
ca-certificates package). You can override this by setting
smtp_relay_cert_override_file as described earlier in this document.
In either situation, it can be helpful to use the openssl command
line tool to verify that you can successfully connect to your chosen
SMTP relay securely. We recommend doing this before running the
playbook, but it can also be useful as part of troubleshooting OSSEC
email send failures.
In either case, start by attempting to make a STARTTLS connection to
your chosen smtp_relay:smtp_relay_port (get the values from your
group_vars/all/site-specific file). On a machine running Ubuntu, run the
following openssl command, replacing smtp_relay and
smtp_relay_port with your specific values:
openssl s_client -showcerts -starttls smtp -connect smtp_relay:smtp_relay_port < /dev/null 2> /dev/null
Note that you will not be able to run this command on the Application Server because of the firewall rules. You can run it on the Monitor Server, but you will need to run it as the Postfix user (again, due to the firewall rules):
sudo -u postfix openssl s_client -showcerts -starttls smtp -connect smtp.gmail.com:587 < /dev/null 2> /dev/null
If the command fails with “Could not connect” or a similar message, then
this mail server does not support STARTTLS. Verify that the values you
are using for smtp_relay and smtp_relay_port are correct. If
they are, you should contact the admin of that relay and talk to them
about supporting STARTTLS, or consider using another relay that already
has support.
If the command succeeds, the first line of the output should be
“CONNECTED” followed by a lot of diagnostic information about the
connection. You should look for the line that starts with “Verify return
code”, which is usually one of the last lines of the output. Since we
did not give openssl any information about how to verify
certificates in the previous command, it should be a non-zero value
(indicating verification failed). In my case, it is
Verify return code: 20 (unable to get local issuer certificate),
which indicates that openssl does not know how to build the certificate
chain to a trusted root.
If you are using the default verification setup, you can check whether
your cert is verifiable by the default root store with -CApath:
openssl s_client -CApath /etc/ssl/certs -showcerts -starttls smtp -connect smtp_relay:smtp_relay_port < /dev/null 2> /dev/null
For example, if I’m testing Gmail as my SMTP relay
(smtp.gmail.com:587), running the openssl with the default root
store results in Verify return code: 0 (ok) because their
certificate is valid and signed by one of the roots in the default
store. This indicates that can be successfully used to securely relay
email in the default configuration of the Monitor Server.
If your SMTP relay server does not successfully verify, you should use the return code and its text description to help you diagnose the cause. Your cert may be expired, in which case you should renew it. It may not be signed by a trusted CA, in which case you should obtain a signature from a trusted CA and install it on the mail server. It may not have the right hostnames in the Common Name or Subject Alternative Names, in which case you will need to generate a new CSR with the correct hostnames and then obtain a new certificate and install it. Etc., etc.
If you are not using the the default verification setup, and
intentionally do not want to use a certificate signed by one of the
default CA’s in Ubuntu, you can still use openssl to test whether
you can successfully negotiate a secure connection. Begin by copying
your certificate file (smtp_relay_cert_override_file from
group_vars/all/site-specific) to the computer you are using for testing. You
can use -CAfile to test if your connection will succeed using your
custom root certificate:
openssl s_client -CAfile /path/to/smtp_relay_cert_override_file -showcerts -starttls smtp -connect smtp_relay:smtp_relay_port < /dev/null 2> /dev/null
Finally, if you have a specific server in mind but are not sure what
certificate you need to verify the connection, you can use the output of
openssl s_client to figure it out. Since we have -showcerts
turned on, openssl prints the entire certificate chain it receives
from the server. A properly configured server will provide all of the
certificates in the chain up to the root cert, which needs to be
identified as “trusted” for the verification to succeed. To see the
chain, find the part of the output that start with
Certificate chain. It will look something like this (example from
smtp.gmail.com, with certificate contents snipped for brevity):
---
Certificate chain
0 s:/C=US/ST=California/L=Mountain View/O=Google Inc/CN=smtp.gmail.com
i:/C=US/O=Google Inc/CN=Google Internet Authority G2
-----BEGIN CERTIFICATE-----
<snip>
-----END CERTIFICATE-----
1 s:/C=US/O=Google Inc/CN=Google Internet Authority G2
i:/C=US/O=GeoTrust Inc./CN=GeoTrust Global CA
-----BEGIN CERTIFICATE-----
<snip>
-----END CERTIFICATE-----
2 s:/C=US/O=GeoTrust Inc./CN=GeoTrust Global CA
i:/C=US/O=Equifax/OU=Equifax Secure Certificate Authority
-----BEGIN CERTIFICATE-----
<snip>
-----END CERTIFICATE-----
---
The certificates are in reverse order from leaf to root. openssl
handily prints the Subject (s:) and Issuer (i:) information for
each cert. In order to find the root certificate, look at the Issuer of
the last certificate. In this case, that’s
Equifax Secure Certificate Authority. This is the root certificate
that issued the first certificate in the chain, and it is what you need
to tell Postfix to use in order to trust the whole connection.
Actually obtaining this certificate and establishing trust in it is beyond the scope of this document. Typically, if you are using your own SMTP relay with a custom CA, you will be able to obtain this certificate from an intranet portal or someone on your IT staff. For a well-known global CA, you can obtain it from the CA’s website. For example, a quick search for “Equifax Secure Certificate Authority” finds the web page of GeoTrust’s Root Certificates, which have accompanying background information and are available for download.
Once you have the root certificate file, you can use -CAfile to test
that it will successfully verify the connection.
Analyzing the Alerts¶
Understanding the contents of the OSSEC alerts requires a background and knowledge in Linux systems administration. They may be confusing, and at first it will be hard to tell between a genuine problem and a fluke. You should examine these alerts regularly to ensure that the SecureDrop environment has not been compromised in any way, and follow up on any particularly concerning messages with direct investigation.
Common OSSEC Alerts¶
The SecureDrop Application and Monitor Servers reboot every night, as part of the unattended upgrades process. When the servers come back up, OSSEC will start again and report the change in status. Therefore you should receive an email alert every morning containing text similar to:
Received From: mon->ossec-monitord
Rule: 502 fired (level 3) -> "Ossec server started."
Portion of the log(s):
ossec: Ossec started.
This is a normal alert, and informs you that the system is working as expected.
Similarly, your SecureDrop Application and Monitoring Servers will
check for application updates on your servers. Should your servers require
updates, OSSEC will alarm because the packages binaries will have changed
Below is a sample alert, but you may see any number of these records in the
logs. This will happen in batches so these emails might be longer than the
below alert. You should also see them in an email named Daily Report:
File Changes. To verify this activity matches the package history, you
can review the logs in /var/log/apt/history.log.
Received From: (app)
Rule: 2902 fired (level 7) -> "New (Debian Package) installed."
Portion of the log(s):
status installed <package name> <version>
This is a normal alert, it tells you your system is up-to-date and patched.
Occasionally your SecureDrop Servers will send an alert for failing to connect to Tor relays. Since SecureDrop runs as a Tor Onion Service, it is possible for Tor connections to timeout or become overloaded.
Received From: (app)
Rule: 1002 fired (level 2) -> "Unknown problem somewhere in the system."
Portion of the log(s):
[warn] Your Guard <name> ($fingerprint) is failing a very large amount of
circuits. Most likely this means the Tor network is overloaded, but it
could also mean an attack against you or potentially the guard itself.
This alert is common but if you see them for sustained periods of time (several times a day), please contact us at the SecureDrop Support Portal or at securedrop@freedom.press for help.
Uncommon OSSEC Alerts¶
If you believe that the system is behaving abnormally, you should contact us at the SecureDrop Support Portal or securedrop@freedom.press for help.
Tails Guide¶
To log-in SecureDrop and retreived messages sent by sources, the journalist must be using the Tails operating system. The admin must also use Tails to access the Journalist Interface and create new users.
If you followed the SecureDrop Installation instructions correctly, you should have already created a journalist Tails USB and an admin Tails USB and enabled the persistence volume on each. If you have not, or need to create another journalist Tails USB for a second journalist, follow the steps below.
If you already know how to boot the admin Tails USB or the journalist Tails USB with persistence, you can skip down to the step ‘download the repository’.
Note that for all of these instructions to work, you should have already installed the main SecureDrop application. It is also required that you use Tails version 2.x or greater.
Installing Tails on USB sticks¶
Tails is a live operating system that is run from removable media, such as a DVD or a USB stick. For SecureDrop, you’ll need to install Tails onto USB sticks and enable persistent storage.
We recommend creating an initial Tails Live USB or DVD, and then using that to create additional Tails Live USBs with the Tails Installer, a special program that is only available from inside Tails. You will only be able to create persistent volumes on USB sticks that had Tails installed via the Tails Installer.
The Tails website has detailed and up-to-date instructions on how to download and verify Tails, and how to create a Tails USB stick. Here are some links to help you out:
- Download and verify the Tails .iso
- Install onto a USB stick or SD card
- Create & configure the persistent volume
Note for Mac OS X users manually installing Tails¶
The Tails documentation for manually installing Tails onto a USB device
on Mac OS X describes how to copy the downloaded .iso image to a USB stick in
Section 4, “Do the copy”. This section includes the following dd invocation
to copy the .iso to the USB:
dd if=[tails.iso] of=/dev/diskX
This command is very slow. In our testing, it took about 18 minutes to copy
the .iso to a USB 2.0 drive. You can speed it up by changing the arguments to
dd like so:
dd if=[tails.iso] of=/dev/rdiskX bs=1m
Note the change from diskX to rdiskX. This reduced the copy time to 3
minutes for us.
Configure Tails for use with SecureDrop¶
Persistence¶
Creating an encrypted persistent volume will allow you to securely save information in the free space that is left on the Transfer Device. This information will remain available to you even if you reboot Tails. Instructions on how to create and use this volume can be found on the Tails website. You will be asked to select from a list of persistence features, such as personal data. We require that you enable all features.
Start Tails and enable the persistent volume¶
When starting Tails, you should see a “Welcome to Tails” screen with two options. Select Yes to enable the persistent volume and enter your password. Select Yes to show more options and click Forward. Enter an Administration password for use with this specific Tails session and click Login.
Download the repository¶
The rest of the SecureDrop-specific configuration is assisted by files stored in the SecureDrop git repository. To get started, open a terminal and run the following commands to download the git repository. Note that since the repository is fairly large and Tor can be slow, this may take a few minutes.
cd ~/Persistent
git clone https://github.com/freedomofpress/securedrop.git
Passphrase Database¶
We provide a KeePassX password database template to make it easier for admins and journalists to generate strong, unique passphrases and store them securely. Once you have set up Tails with persistence and have cloned the repo, you can set up your personal password database using this template.
You can find the template in tails_files/securedrop-keepassx.kdbx
in the SecureDrop repository that you just cloned.
To use the template:
- Open the KeePassX program which is already installed on
Tails
- Select Database, Open database, and navigate to the location of securedrop-keepassx.kdbx, select it, and click Open
- Check the password box and hit OK
- Click Database and Save Database As
- Save the database in the Persistent folder
Tip
If you would like to add a master password, navigate to Database and Change master key. Note that since each KeePassX database is stored on the encrypted persistent volume, this additional passphrase is not necessary.
Warning
You will not be able to access your passwords if you forget the master password or the location of the key file used to protect the database.
Set up easy access to the Journalist Interface¶
To complete setup of the Admin Workstation or Journalist Workstation, we
recommend using the scripts in tails_files to easily configure Tor to
access the Journalist Interface.
Navigate to the directory with the setup scripts and begin the installation by typing these commands into the terminal:
./securedrop-admin tailsconfig
Type the administration password that you selected when starting Tails and hit enter. This installation script does the following:
- Downloads additional software
- Installs a program that automatically and persistently configures Tor to
access the SecureDrop servers and interfaces, by adding
HidServAuthvalues to/etc/tor/torrc. - Sets up desktop and main menu shortcuts for the Journalist Interface and Source Interface
- Sets up SSH host aliases for
monandapp - Makes it so that Tails installs Ansible at the beginning of every session
If you are missing any files, the script will exit with an error. If you’re running this script as an admin, the entire setup should be automatic.
If you’re running the script as a journalist, you will need the .onion addresses for each interface, provided to you by the admin.
We use an “authenticated” Tor Hidden Service so that adversaries cannot access the Journalist Interface, providing a layer of defense-in-depth which protects the Journalist Interface even if there is a security vulnerability in the web application, or if the journalist’s username, password, and two-factor token are stolen. The extra configuration that is required is handled by this script.
Our ./securedrop-admin tailsconfig tool sets up Tails to work with SecureDrop
every time you login. As long as Tails is booted with the persistent volume enabled
then you can open the Tor Browser and connect to the Journalist Interface as normal.
Create bookmarks for Source and Journalist Interfaces¶
If you want, you can open the browser and create bookmarks for the Source and Journalist Interfaces. Navigate to the site you wish to bookmark, select Bookmarks and Bookmark This Page, give the site a useful name (e.g. Source Interface), and click Done. Tails will remember the bookmarks even if you reboot.
Setting up a Printer in Tails¶
Because Tails is supposed to be as “amnesiac” as possible, you want to shield your Tails stick from any extra inputs from, and outputs to, a potentially untrusted network. This is why we strongly recommend using a printer that does not have WiFi or Bluetooth, and hooking up to it using a regular USB cable to print.
Finding a printer that works with Tails can be challenging because Tails is based on the Linux operating system, which often has second-class hardware support in comparison to operating systems such as Windows or macOS.
We maintain a list of printers that we have personally tested and gotten to work with Tails, in the Hardware guide; if possible, we recommend using one of those printers. The Linux Foundation also maintains the OpenPrinting database, which documents the compatibility, or lack thereof, of numerous printers from most every manufacturer.
Note
The latest generations of printers might or might not be represented by the OpenPrinting database; also, the database does not document whether or not a printer is wireless, so this will involve manually checking models of interest, if you wish to use this resource as a guide for purchasing a non-wireless printer suitable for use with SecureDrop.
With that in mind, this database is arguably the best resource for researching the compatibility of printers with Linux. As a tip for narrowing down your search, look for printers that are compatible with Debian, or Debian-based distributions like Ubuntu, since Tails itself is also Debian-based. This might increase the chances for a seamless installation experience in Tails.
In any case, this document outlines the usual set of steps that we follow when attempting to use a new printer with Tails, and provides some troubleshooting tips that you may find useful if you are trying to use a different printer.
Note
While, as of Tails 3, it’s no longer necessary to have admin privileges in order to install or configure printers, we recommend that you set an admin passphrase along with enabling persistence; this ensures that the printer’s installation and configuration settings persist after every reboot, so you don’t have to reinstall it each time you start Tails.
Installing and Printing via the Tails GUI¶
Let’s look at Tails 3.0’s typical flow for installing a USB-connected printer. If you’ve enabled persistence, boot with your persistent volume, and set an admin passphrase. Connect the printer to your Tails-booted computer via USB, then turn the printer on.
Now, you’ll want to single-click your way through Applications ▸ System Tools ▸ Settings ▸ Printers.
In this example, we’ll assume that this is the first time we’ve tried to install a printer, which will show the following:
Click “Add a Printer”. By doing so, you’ll now get a list of printers that Tails has auto-detected. You should now see this:
In this example, we’ve connected an HP DeskJet F4200. Clicking on this printer will select it for installation, which, if successful, will display the following:
This indicates the Tails is attempting to install the USB printer; assuming you receive no errors in this process, you will then see the following screen, which indicates that the printer is “ready” for printing.
Troubleshooting¶
For instances where your printer does not work out of the box, most difficulties stem from not selecting the right driver (extra software needed for the printer and computer to communicate). Luckily, Tails has a large number of drivers for just about any popularly manufactured printer on hand, without even having to download new drivers from the web.
Just as before, if you’ve enabled persistence, boot with your persistent volume, and set an admin passphrase.
Make sure your computer is NOT connected to the Internet. This will make sure that your printer set-up is never influenced by a network connection.
Plug in your printer and navigate to Printing. Applications ▸ System Tools ▸ Settings ▸ Printing.
Click Add.
Immediately, Tails will recognize the plugged-in printer, and make the best suggestion from its on-board database of printer drivers.
Tails will guide you through a default set-up, suggesting the best match for the printer you have. These choices come from Tails’ pre-installed driver database.
The recommended driver does not always match the actual make and model of your printer, but starting with the recommendations is a good idea. Sometimes you get lucky, and Tails suggests a perfect match. Click Forward, and Apply your settings.
You’ll notice that the printer is now listed in your Printing Configurations in your persistent storage.
The only way to be sure you have the right driver is by doing a test print. Right-click on your new printer config and select Properties to open its settings, then click Print Test Page.
In this initial test, the recommended driver was wrong! My test page came out garbled, and my printer gave me a warning that I had to manually clear before the page printed.
Don’t worry if this happens to you; you can edit the printer configuration to point it to the correct driver for your model. Select Properties again and choose Change… next to the “Make and Model” directive.
To fix this problem, I selected the CUPS + Gutenprint driver, even though it wasn’t recommended. Click Forward to save your changes.
Do another test print, checking your printer for indicators that it’s working or not. This time, printing works perfectly. If you still experience garbled text, try another driver from your selections. It is a process of trial-and-error.
Printing from the Command Line¶
You can also easily print from the command line using the lp command; if
you haven’t already set your installed printer as default in the GUI, you can
quickly do so by adding this line to your ~/.bashrc file, or entering this
directly into the terminal:
export PRINTER=Printer-Name-Here
If you need to find the name of the printer, you can use lpstat to get a
list of installed printers, as such:
lpstat -a
Once you’ve set your default printer, you can easily print from the terminal by using the following syntax:
lp filename.extension
While printing from the GUI is much easier, once you’ve got everything set up, it’s equally straightforward from the command line, if you prefer that environment.
HTTPS on the Source Interface¶
The SecureDrop Source Interface is served over a Tor Hidden Service,
requiring a *.onion URL to access it. While Tor Hidden Services provide
end-to-end encryption by default, as well as strong anonymity, there are
several reasons why you might want to consider deploying an additional layer of
encryption and authentication via HTTPS:
Extended Validation (EV) certificates, which are currently the only type of certificates that may be issued for
*.onionaddresses, are intended to attest to the identity of the organization running a service. This provides an additional measure of authenticity (in addition to the organization’s Landing Page and the SecureDrop Directory) to help assure sources that they are communicating with the intended organization when they access a given Source Interface.The cryptographic primitives used by Tor Hidden Services are considered to be outdated, and while there are no known compromises of the security of Tor Hidden Services due to this issue, you may wish to provide an additional layer of transport encryption using stronger cryptographic primitives, which is most easily achieved by setting up HTTPS on the Source Interface.
Note
This issue is being addressed by the Tor Project with their Next Generation Onion Services design, but the implementation of the new design is still a work in progress and is not expected to be deployed until December 2017 at the earliest.
Obtaining an HTTPS certificate for Onion URLs¶
DigiCert is currently the only Certificate Authority (CA) that issues HTTPS
certificates for .onion sites. DigiCert requires organizations to follow
the Extended Validation (EV) process in order to obtain a certificate for an
Onion URL, so you should start by reviewing DigiCert’s documentation for
obtaining a .onion certificate.
The EV certificates display in browsers with a green trust bar, including information about the organization:
The additional information about the organization, such as name and geographic location, are checked by the CA during the EV process. A Source can use this information to confirm the authenticity of a SecureDrop instance, beyond the verification already available in the SecureDrop Directory.
In order to obtain an HTTPS certificate for your SecureDrop instance, contact DigiCert directly. As part of the Extended Validation, you will be required both to confirm your affiliation with the organization, and to demonstrate control over the Onion URL for your Source Interface.
In order for you to demonstrate control over the Onion URL for your Source
Interface, DigiCert will provide you with some text and ask you to make it
available at a specific URL: <onion_url>/.well-known/pki-validation.html.
We have support for this workflow:
# From the Admin Workstation, SSH to the Application Server
$ ssh app
# Edit the validation file with content the CA provides
# Note that the filename can be anything as long as it ends
# with .htm or .html
$ sudo vi /var/www/securedrop/.well-known/pki-validation.html
While the CAB forum has specified that .onion certificates may have a
maximum lifetime of 15 months, we have heard that some folks have run into
issues with such certificates, and currently it seems safest to give the
certificate a validity period of 12 months.
Tip
Be patient! HTTPS certificates for .onions are a recent and fairly
niche development, so you may run into various issues while trying to obtain
the certificate.
Warning
As part of the process for obtaining an HTTPS certificate, you
will need to generate a private key. This is usually stored in a file with a
.key extension. It is critical that you protect this key from
unauthorized access. We recommend doing this entire process on the Admin
Workstation, and avoiding copying the .key to any insecure removable
media or other computers.
Activating HTTPS in SecureDrop¶
Make sure you have installed SecureDrop already.
First, on the Admin Workstation:
cd ~/Persistent/securedrop
Make note of the Source Interface Onion URL. Edit the site-specific variables
for your organization in
install_files/ansible-base/group_vars/all/site-specific to include the
following:
securedrop_app_https_on_source_interface: yes
securedrop_app_https_certificate_cert_src: sd.crt
securedrop_app_https_certificate_key_src: sd.key
securedrop_app_https_certificate_chain_src: ca.crt
The filenames should match the names of the files provided to you by DigiCert,
and should be saved inside the install_files/ansible-base/ directory. Then rerun
the configuration:
./securedrop-admin install
The webserver configuration will be updated to apply the HTTPS settings.
Confirm that you can access the Source Interface at
https://<onion_url>, and also that the HTTP URL
http://<onion_url> redirects automatically to HTTPS.
Note
By default, Tor Browser will send an OCSP request to a Certificate Authority (CA) to check if the Source Interface certificate has been revoked. Fortunately, this occurs through Tor. However, this means that a CA or anyone along the path can learn the time that a Tor user visited the SecureDrop Source Interface. Future versions of SecureDrop will add OCSP stapling support to remove this request. See OCSP discussion for the full discussion.
SecureDrop On-Site Training Schedule¶
This is a high level schedule for what happens for the 2 days during an on-site install.
Day 1: Preparation and Install¶
Setup and Introductions¶
Time: 30min
Participants: all
Required: projector, WiFi access, pre-configured demo SecureDrop instance and 2 laptops to act as the Journalist Workstation and SVS
- The demo instance has multiple sources to try and give a feel of what it will look like at 2 weeks past being public with sources in different states of the reply process
Overview of SecureDrop¶
Time: 2 hours
Participants: journalists, editors, SecureDrop admins, OSSEC alert recipients and anyone else interested
- Go over the SecureDrop FAQs
- Go over the SecureDrop environment diagrams
- Importance of the landing page security and Twitter feedback
- Demo the source submission process
- Demo the journalist’s processes for checking the Journalist Interface
- Demo the journalist’s processes for replies
- Demo working with submissions on the SVS
- Discuss scrubbing submitted documents prior to publication
- Options for distributing with other news organizations
- Show example of an OSSEC alert, briefly cover what it does
- Show example of ‘is it up?’ Nagios monitoring alerts for Source Interface
- Explain why the Journalist Interface does not have ‘is it up?’ monitoring
- Discuss vanity onion URLs with Shallot and Scallion
- How to brand the Source and Journalist Interface
- Physical security of servers and SVS
- How to securely publicize the organization’s Source Interface Tor URL
- Distribute important info:
- Third-party security mailing lists to subscribe to
- https://freedom.press/about/staff
- https://securedrop.org
- https://docs.securedrop.org
- Hardware for SecureDrop
- Overview guidelines
- Source Best Practice Guide
- Journalist Best Practice Guide
- Admin Best Practice Guide
- Answering the client vs. server side crypto debate
- Link to security audits
Questions¶
Time: 30 min
Day 2: Journalist and Admin Training¶
Journalist Training¶
Time: 2 separate sessions, about 2 hours each
Participants: journalists and admins
- Check access to previously created Tails USB
- Generate personnel GPG keys
- Setup KeyPassX manager (one for SVS, one for personnel Tails)
- Options between YubiKey/Google Authenticator app for 2FA (SSH, Journalist Interface, FDE and password managers)
- Secure-deleting and difference between wipe and erase free space on Tails, and when to use each
- Disaster recovery for 2FA and password manager, personnel GPG keys
- Updating Tails
- Backing up the SVS
- If needed, process for distributing the Application’s private GPG key to a distant journalist’s air-gapped SVS
- Do complete journalist process walk through twice, either on different days or between morning/afternoon sessions
- Using MAT (Metadata Anonymisation Toolkit)
- What to do for unsupported formats
Admin training¶
Time: 2 hours
Participants: admins
- Check access to previously created Tails USB
- Generate personnel GPG keys
- Setup KeyPassX manager (one for SVS, one for personnel Tails)
- Options between YubiKey/Google Authenticator app for 2FA (SSH, Journalist Interface, FDE and password managers)
- Secure-deleting and difference between wipe and erase free space on Tails, and when to use each
- Disaster recovery for 2FA and password manager, personnel GPG keys
- Updating Tails
- Setting up SSH aliases for the admin Tails workstation
- How to use screen or tmux to help prevent being locked out of the system
- Adding packages to Tails
- Go over common OSSEC alerts for security updates and daily reports
- Disaster recovery for application, remote access and SVS
- Common admin actions
- Adding/removing users
- Enabling logging
- Sending logs to FPF
- Generating new Tor hidden services
- Updating application’s GPG key
- Re-IP’ing
- Backups
- Disk space monitoring
- Updating SMTP and OSSEC alert configs
- Changing passwords (for FDE, persistent volumes, 2FA, KeePassX managers…)
- What will happen to local modifications to prod system after updates
- Updating SecureDrop Application
- Unattended upgrades
- Upgrades that require admin intervention
Using a YubiKey with the Journalist Interface¶
This guide describes in detail how to set up a YubiKey for two-factor authentication on the Journalist Interface. This setup is performed once per journalist to create a secure log-in method. The process requires some configuration steps using a separate software tool.
Note
You will do all of these steps from within the Tails operating system.
What is a YubiKey?¶
A YubiKey is a physical token used for two-factor authentication. They are made by a company called Yubico and are commercially available.
Download and Launch the YubiKey Personalization Tool¶
- Start Tails. At the log in-screen, choose the option to allow an administrator password.
- Open a terminal and enter
sudo apt-get update;
sudo apt-get install yubikey-personalization-gui
- Once you have downloaded and installed the personalization program, open a Root Terminal by choosing Applications ▸ System Tools ▸ Root Terminal.
- Open the YubiKey personalization tool by entering
yubikey-personalization-gui
Setting Up Hardware-Based Codes¶
After opening the personalization tool, click the heading OATH-HOTP. This will bring you to a window called Program in OATH-HTOP mode.
Click on the Quick button.
Under Configuration Slot, click Configuration Slot 1.
Note
If you are already using this YubiKey for something else, you should choose Configuration Slot 2. You will have to press and hold for several seconds to use the token from Slot 2 instead of the one in Slot 1. See the YubiKey manual for more information.
In the section titled OATH-HOTP parameters, uncheck the box for OATH Token Identifier (6 bytes). Next, uncheck the box for Hide secret. This will display the Secret Key (20 bytes Hex) field.
Important
Make a note somewhere safe of the Secret Key (20 bytes Hex) value.
When ready, click the Write Configuration button.
Click through the warning about overwriting the configuration slot and choose a location to save the log file. When the configuration is done, you should see green text saying YubiKey configured at the top of the window.
Adding Users¶
When adding new users, a SecureDrop administrator will need the Secret Key value described above. She will enter it after selecting the I’m Using a YubiKey option while adding users.
Using Your YubiKey¶
When using a Yubikey to log-in to the Journalist Interface, insert the Yubikey into the USB port and enter your username and passphrase. Then click the Two-factor Code field to focus the cursor there. Quickly press the lighted button on your YubiKey. This will insert the 6-digit code that you will need to log in.
Note
When using Configuration Slot 2, be sure to press and hold the YubiKey button for approximately 3 seconds.
Backup and Restore SecureDrop¶
There are a number of reasons why you might want to backup and restore your SecureDrop. You may want to move an existing SecureDrop installation to new hardware. Performing such a migration consists of:
- Backup the existing installation.
- Do a new install of the same version of SecureDrop on the new hardware.
- Restore the backup to the new installation.
Maintaining periodic backups are generally a good practice to guard against data loss. In the event of hardware failure on the SecureDrop servers, having a recent backup will enable you to redeploy the system without changing Onion URLs, recreating Journalist accounts, or losing historical submissions from sources.
Note
Currently only the Application Server is backed up and restored, including historical submissions and Source and Journalist Interface URLs. The Monitor Server will be configured from scratch in the event of a hardware migration.
Minimizing disk space¶
Since the backup and restore operations both involve transferring all of your SecureDrop’s stored submissions over Tor, the process can take a long time. To save time and improve reliability for the transfers, take a moment to clean up older submissions in the Journalist Interface. As a general practice, you should encourage your Journalists to delete submissions from the Journalist Interface regularly.
Tip
The throughput of a Tor Hidden Service seems to average around 150 kB/s, or roughly 4 hours for 2GB. Plan your backup and restore accordingly.
You can use the following command to determine the volume of submissions
currently on the Application Server by SSHing in and running
sudo du -sh /var/lib/securedrop/store.
Note
Submissions are deleted asynchronously and one at a time, so if you
delete a lot of submissions through the Journalist Interface, it may
take a while for all of the submissions to actually be deleted. This
is especially true because SecureDrop uses srm to securely erase
file submissions, which takes significantly more time than normal file
deletion. You can monitor the progress of queued deletion jobs with
sudo tail -f /var/log/securedrop_worker/err.log.
If you find you cannot perform a backup or restore due to this constraint, and have already deleted old submissions from the Journalist Interface, contact us through the SecureDrop Support Portal.
Backing Up¶
Open a Terminal on the Admin Workstation and cd to your clone of the
SecureDrop git repository (usually ~/Persistent/securedrop). Ensure you have
SecureDrop version 0.4 or later checked out (you can run git describe
--exact-match to see what Git tag you’ve checked out).
Note
The backups are stored in the Admin Workstation’s persistent volume. You should verify that you have enough space to store the backups before running the backup command.
You can use the du command described earlier to get the
approximate size of the backup file (since the majority of the backup
archive is the stored submissions), and you can use Tails’ Disks
utility to see how much free space you have on your persistent volume.
Check connectivity¶
First, verify that your Admin Workstation is able to run Ansible and connect to the SecureDrop servers.
ssh app uptime
If this command fails (usually with an error like “SSH Error: data could not be sent to the remote host. Make sure this host can be reached over ssh”), you need to debug your connectivity before proceeding further. Make sure:
- Ansible is installed. If it is not, see Configure the Admin Workstation Post-Install for detailed instructions.
- The Admin Workstation is connected to the Internet.
- Tor started successfully.
- The
HidServAuthvalues fromapp-ssh-athsandmon-ssh-athsare in Tails’/etc/tor/torrc. If they are not, again, see Configure the Admin Workstation Post-Install for detailed instructions.
Create the backup¶
Run:
./securedrop-admin backup
The backup action will display itemized progress as the backup is created. Run time will vary depending on the number of submissions saved on the Application Server.
When the backup action is complete, the backup will be stored as a tar archive in
install_files/ansible-base. The filename will start with sd-backup, have
a timestamp of when the backup was initiated, and end with .tar.gz. You can
find the full path to the backup archive in the output of backup action.
Warning
The backup file contains sensitive information! It should only be stored on the Admin Workstation, or on a dedicated encrypted backup USB.
Restoring¶
Prerequisites¶
The process for restoring a backup is very similar to the process of creating
one. As before, to get started, boot the Admin Workstation, cd to the
SecureDrop repository, and ensure that you have SecureDrop 0.4 or later
checked out.
The restore role expects to find a .tar.gz backup archive in
install_files/ansible-base under the SecureDrop repository root directory.
If you are using the same Admin Workstation to do a restore from a previous
backup, it should already be there because it was placed there by the backup
role. Otherwise, you should copy the backup archive that you wish to restore to
install_files/ansible-base.
Note
The backup strategy used for SecureDrop versions prior to 0.3.7
created encrypted archives with the extension .zip.gpg.
You can safely remove those files once you’ve created the .tar.gz
backup archive described in this guide.
Restoring from a backup file¶
To perform a restore, you must already have a backup archive. Provide its filename in the following command:
./securedrop-admin restore sd-backup-2017-07-22--01-06-25.tar.gz
Make sure to replace sd-backup-2017-07-22--01-06-25.tar.gz with the filename
for your backup archive. The backup archives are located in
install_files/ansible-base.
Once the restore is done, the Application Server will use the original Source and Journalist Interface Onion URLs. You will need to update the corresponding files on the Admin Workstation:
app-source-thsapp-journalist-athsapp-ssh-aths
Then rerun ./securedrop-admin tailsconfig to update the Admin Workstation
to use the restored Onion URLs again. See Configure the Admin Workstation Post-Install
for detailed instructions.
Backup the Workstations¶
Now that you have set up the Secure Viewing Station, the Admin Workstation, and your Journalist Workstations, it is important you make a backup. Your USB drive may wear out, a journalist might lose their backup drive, or something completely unexpected may happen.
In all these cases, it is useful to have a backup of your data for each device.
What you need¶
- Your existing SecureDrop Tails USB sticks (Admin Workstation, Journalist Workstation, and Secure Viewing Station).
- An airgapped machine to perform the Tails upgrades. The Secure Viewing Station may be used for this task.
- Your “master” Tails USB, which we will use to perform the backups.
- At least one USB drive to backup the data on your current SecureDrop Tails USB sticks.
Warning
An airgapped machine (such as the Secure Viewing Station) is required in order to perform these backups safely. By isolating the machine from all network access, you reduce the exposure of sensitive data to networked computers, thereby reducing the threat of compromise by adversaries who wish to gain access to your SecureDrop instance.
The airgapped machine should have 3 USB ports, so you can plug in the Tails drive you wish to upgrade, the master Tails USB drive, and the backup drive at the same time. If you don’t have 3 USB ports available, you can use a USB hub, which may reduce transfer speeds.
Note
The steps in this section should be performed for each Secure Viewing Station, Journalist Workstation, and Admin Workstation USB drive in your organization.
Preparing the Backup Device¶
Navigate to Applications ▸ Utilities ▸ Disks.
Insert the USB drive you wish to use as a backup drive.
Select the drive from the list of drives in the left column.
Click the button with the two cogs and click Format Partition…
Fill out the form as follows:
- Erase: Don’t overwrite existing data (Quick)
- Type: Encrypted, compatible with Linux systems (LUKS + Ext4)
- Name: Backup
Warning
Since this will serve as a long-term backup, make sure to use a strong passphrase.
Click Format.
A dialog box will appear asking you Are you sure you want to format the volume? appears, click Format.
Once completed, you will see two partitions appear:
Now that you made the backup device, plug in the device you want to backup. Then, browse to Places ▸ Computer:
Click on the disk on the left side column. Fill in the passphrase you usually use when you enable Persistence on that device:
You should now have both the Backup and TailsData partition to be backed up mounted and ready to access.
Open a Nautilus window with admin privileges by going to Applications ▸ System Tools ▸ Terminal.
Type gksu nautilus at the terminal prompt and hit enter. You’ll need to type
your admin password.
Note
When you run gksu nautilus, you may run into an error where Nautilus
complains that it can’t create a required folder. If that happens, just click
OK and continue normally.
If a Nautilus window doesn’t come up, it might be because an admin password wasn’t set. If that’s the case, you’ll need to restart and set an admin password before continuing.
Warning
Make sure you use keep the Terminal window open while you perform the backups. Otherwise, the Nautilus window will close.
Make sure you create a directory on the backup drive to store the data from the drive you are backing up:
Copy over everything in the TailsData partition to the relevant folder on the Backup drive. You can simply drag to select all the files and then copy and paste them to the relevant folder on the Backup drive.
In particular, ensure gnupg and Persistent have been successfully
copied over. These files are critical for decrypting submissions.
Once complete, unmount the TailsData partition.
Repeat these steps for every device, making a new folder on the backup device for each device you backup.
Finally, once you have completed the steps described in this section for each USB drive, unmount the Backup partition and store the drive somewhere safely.
Upgrade from 0.4.x to 0.5.x¶
Note
First follow the instructions in the 0.3 to 0.4 migration document if you have not yet updated your Admin Workstation to 0.4.
Beginning with SecureDrop 0.5, the source and journalist interfaces are localized. After an unattended upgrade of the application server, these translations are available but are not activated by default.
Note
See the installation documenation for a list of supported languages.
The steps below should be performed on the Admin Workstation associated with your SecureDrop instance.
Pull the latest release¶
Open a Terminal and navigate to your SecureDrop directory.
cd ~/Persistent/securedrop
Fetch the latest code, and verify the tag for the latest release (0.5):
git fetch
git tag -v 0.5
The output of the above commands should include Good signature from
"SecureDrop Release Signing Key". If it does
not, please contact us immediately at support@freedom.press.
Note
You may also see output from GPG warning you that the key is not certified
with a trusted signature. This means that there is not a trust path to the
release signing key. As long as you see the fingerprint 2224 5C81 E3BA EB41
38B3 6061 310F 5612 00F4 AD77 displayed and the signature verifies as
described above then you can proceed safely.
Once you’ve verified the latest release, check it out:
git checkout 0.5
Choose the list of supported languages¶
You need to run the ./securedrop-admin sdconfig command again,
following the same instructions as during the first installation. This will not modify the existing configuration but
you will be asked for a list of supported languages because this
option did not exist before. You should decide which languages you
prefer as explained in the installation documenation.
You should then proceed to update the application server with:
./securedrop-admin install
Note
If you see an error running ./securedrop-admin install, and
believe it may be an intermittent issue (for example, due to losing
network connectivity to the servers), it is safe to run the
./securedrop-admin install command again. If you see the same
issue consistently, then you will need to troubleshoot it.
Verify the source interface displays the selected languages¶
The source and journalist interfaces will display the current language with a flag and clicking on the flag will show a menu with all supported languages.
Upgrade from 0.3.x to 0.4.x¶
Beginning with SecureDrop 0.4, the use of Tails 3 is required. SecureDrop 0.4 included substantial changes to the Admin tooling used for managing the configuration for the Application and Monitor Servers, and modifies the location of the configuration on Admin Workstation to prevent conflicts in the future.
Note
All Admin and Journalist Workstations must be upgraded to Tails 3 for use with SecureDrop 0.4.x. Follow the Upgrade Tails from 2.x to 3.x guide for detailed instructions on upgrading if you have not already done so.
The steps below should be performed on both the Admin and all Journalist Workstations associated with your SecureDrop instance. You do not need to run these steps on the Secure Viewing Station.
Pull the latest release¶
Open a Terminal and navigate to your SecureDrop directory.
cd ~/Persistent/securedrop
Stash your local configuration, fetch the latest code, and verify the tag for the latest release (0.4.1):
git stash save "site specific configs"
git fetch
git tag -v 0.4.1
The output of the above commands should include Good signature from
"SecureDrop Release Signing Key". If it does
not, please contact us immediately at support@freedom.press.
Note
You may also see output from GPG warning you that the key is not certified
with a trusted signature. This means that there is not a trust path to the
release signing key. As long as you see the fingerprint 2224 5C81 E3BA EB41
38B3 6061 310F 5612 00F4 AD77 displayed and the signature verifies as
described above then you can proceed safely.
Once you’ve verified the latest release, check it out, then pop your local configuration back into place:
git checkout 0.4.1
git stash pop
Upgrade the Tails Persistence Configuration¶
SecureDrop 0.4.x provides more convenient tooling for configuring the ATHS info required to access the Journalist Interface. Run the following commands to install the required packages and set up the access to your SecureDrop instance.
./securedrop-admin setup
./securedrop-admin tailsconfig
Clean up old version-controlled site config¶
The tailsconfig task copied the site-specific configuration for your
SecureDrop instance to a new location: install_files/ansible-base/group_vars/all/site-specific.
Beginning with 0.4, manual edits to the inventory are no longer required, as the ATHS
information is read automatically from the app-ssh-aths and
mon-ssh-aths files. Therefore you should permanently store any
site-specific modifications:
git stash save "old site-specific configs"
During subsequent upgrades to the SecureDrop Admin configuration, you will no
longer need to perform git stash and git pop as described above.
Verify the Upgrades¶
Verify the Journalist Workstation and SVS USB Drives Are Successfully Updated¶
After you upgrade your Journalist Workstation and Secure Viewing Station, do the following to make sure they were upgraded successfully.
- Submit a test document to the source interface.
- Log in to the journalist interface.
- Download the test document.
- Transfer the test document over to the SVS.
- Decrypt the test document.
- Delete the submission.
If you are able to successfully download and decrypt your test submission, then your upgrade was successful!
Verify the Admin Workstation USB Drive Was Successfully Updated¶
After you upgrade your Admin Workstation, ensure that you are able to SSH into both servers. Remember you can use the following shortcuts:
ssh mon
ssh app
Upgrade Tails from 1.x to 2.x¶
Starting with SecureDrop version 0.3.7, SecureDrop’s Tails integration leverages improvements to the Tails OS since the introduction of Tails 2.0. It is critical to upgrade all of your Tails USBs to the latest version of Tails before upgrading SecureDrop to 0.3.7 or later.
Warning
Tails 1.x is no longer receiving updates, and is therefore vulnerable to a growing list of security vulnerabilities. We strongly encourage you to upgrade all of your Tails USBs to the latest version of Tails as soon as possible.
Upgrading Tails from 1.x to 2.x must be done manually. Please follow this guide to updating each Tails USB stick used in your SecureDrop instance. Be sure to use the Secure Viewing Station computer so you benefit from its airgap while transferring sensitive data.
Note
You will need:
- A master Tails USB running the most recent version of Tails (at least v2.3).
- A backup device, a separate, encrypted USB drive used to store backups of the old Tails sticks.
- Your existing SecureDrop Tails USB sticks (Admin, Journalist, and Secure Viewing Station).
- An airgapped machine to perform the Tails upgrades. It is ok to reuse the Secure Viewing Station for this task.
An airgapped machine (such as the SVS) is required in order to perform these upgrades safely. By isolating the machine from all network access, you reduce the exposure of sensitive data to networked computers, thereby reducing the threat of compromise by adversaries who wish to gain access to your SecureDrop instance.
The airgapped machine should have 3 USB ports, so you can plug in all 3 devices at the same time. If you don’t have 3 USB ports available, you can use a USB hub, which may reduce transfer speeds.
Upgrade each Tails device¶
1. Prepare the master Tails USB¶
Because Tails 2.x is incompatible with older versions, you must create a new “master” Tails USB stick for subsequent installations and upgrades to the USB sticks already in-use by your organization. To create this brand-new master Tails, follow the same directions for provisioning the first USB sticks on another networked computer.
Once you’ve created a new Tails 2.x USB, boot into it from your airgapped computer to perform the next steps. At the Tails Greeter screen, be sure to enable admin privileges.
2. Prepare the Backup Device¶
We will use the Tails Installer to upgrade your Tails 1.x USB to Tails 2.x. While this usually works without any issues, we’re going to start by making backups of the important data on your current Tails USBs, so you can use them for recovery in case something goes wrong.
Tip
While it’s recommended to use a fresh USB stick for any backup operation, to cut down on cost, clutter, and/or waste, you may also repurpose old USB sticks to function as Backup Devices. Note that this process will permanently erase any data stored on the Backup Device.
After logging into the master Tails device, open the Disks Utility by navigating to Applications ▸ Utilities ▸ Disks. Insert the Backup Device into a USB port. It will appear in the list of disks in the left column. Select it.
Click the button with the interlocking gears icon and choose Format….
Fill out the Format Volume settings as shown in the screenshot below. There’s no need to overwrite existing data, and doing so can take a long time. You should use a strong passphrase to encrypt the drive.
Note
If you plan on using this USB stick as a permanent backup, you will be responsible for retaining this passphrase for the long-haul. If you only want to use this USB as an intermediary backup, and plan on discarding the data after a successful migration, you may discard the passphrase once all steps are completed.
Click Format…. A dialog box will ask: “Are you sure you want to format the volume?”. Click Format.
While the drive is being formatted, you will see a spinning progress indicator next to the drive’s name in the left column. Wait until it is done. When it is done, you will see the partition layout has two nested partitions (LUKS and ext4), like this:
You’re ready to start backing up your current Tails USBs.
3. Backup a Tails USB¶
Insert the Tails USB (that you want to back up) into a free USB port.
Mount it by navigating to Places ▸ Computer, and clicking on the encrypted disk. You will be prompted to enter the passphrase to unlock the disk (the same passphrase you normally use to log into Tails on that USB stick).
Open a Nautilus window with admin privileges by navigating to Applications
▸ System Tools ▸ Root Terminal. At the terminal prompt, simply type
nautilus.
The Nautilus window should show both the Backup Device and the TailsData partition as mounted.
Copy the all data from the TailsData partition onto the Backup Device except:
persistence.conf- In older versions of Tails, this file might have slightly different directives in it that could temporarily brick a Tails 2.x USB.
claws-mail- Claws Mail is no longer included in Tails. The OS uses Icebird instead. Some users might not have this folder, so if you don’t see it there, do not be alarmed.
Ensure that all critical data has been successfully copied. Specifically, be
sure the the gnupg, bookmarks, and Persistent folders are
completely copied. Any loss of data from these folders could prevent users
from accessing submissions.
Tip
Create subdirectories for each USB drive (Admin, Journalist, and SVS) within the Backup Device. Not only will doing so speed up the upgrade process, it will also provide you with long-term encrypted backups of the USB devices. In the event of a lost or stolen drive, you can restore access via this encrypted backup device.
Once data are correctly copied, unmount the TailsData partition.
4. Upgrade a Tails USB¶
With the Admin/Journo/SVS Tails USB still inserted in the machine, navigate to Applications ▸ Tails ▸ Tails Installer and select the Upgrade by cloning option.
Select the Tails 1.x USB that you wish to upgrade from the drop-down menu labeled Target Device. If it is the only other USB plugged in to the computer, it should be automatically selected.
The clone process will take a few minutes, and will display a message once it is complete. If you see an error message about the device not being ready, try unplugging and remounting the Tails device you’re trying to upgrade.
5. Re-install the automatic Tails configuration¶
Note
This step is only applicable to Admin Tails USBs and Journalist Tails USBs. If you are upgrading the Secure Viewing Station Tails USB, you can skip this step.
Shut down the Tails USB on the airgapped computer and move it to the computer you normally use it on. Boot into each newly upgraded Tails USB, enabling persistence, and setting a root password. Confirm that the persistent files are present on the upgraded Tails USB. If they are not, or something else went wrong, see Troubleshooting.
Now that you have successfully upgraded to Tails 2.x with your persistence intact, the final step is to re-install the Tails automatic configuration from the latest version of SecureDrop (0.3.7 or later). The Tails auto-configuration was originally set up during installation in Configure the Admin Workstation Post-Install and Onboard Journalists. There were enough changes in Tails 2.x that we had to update various aspects of the auto-configuration to work properly on it, which is why you need to re-install.
Once you’ve ensured that you’re running SecureDrop 0.3.7 or later, you can re-install the Tails auto-configuration:
./securedrop-admin tailsconfig
This is the same process as described in Configure the Admin Workstation Post-Install (for the Admin Workstation) and Onboard Journalists (for the Journalist Workstations). If you have questions, consult that documentation first.
When you’re done, repeat this final step on the rest of the Tails devices. Once you have re-installed the Tails auto-configuration on all of the Tails devices, move on to the Finishing up section below.
Finishing up¶
Verify all devices are working¶
Shut down each Tails USB on the airgapped computer and move it to the computer you normally use it on. Boot into each newly upgraded Tails USB, enabling persistence. Confirm that the persistent files are present and that your workflow is unaffected.
As a test, consider submitting a test submission, downloading it on the Journalist Workstation, and finally decrypting it on the SVS. If you are able to decrypt the submission successfully, you have verified that the Journalist Workstation and SVS are working correctly after the upgrade.
To test the Admin Workstation, make sure you can still SSH into the servers:
$ ssh <username>@<*Application Server* .onion address> hostname
app
$ ssh <username>@<*Monitor Server* .onion address> hostname
mon
Tip
If you forgot, your SSH username is in
install_files/ansible-base/group_vars/all/site-specific as the value of the
ssh_users variable. The .onion addresses for SSH for each server
are in install_files/ansible-base/app-ssh-aths and
install_files/ansible-base/mon-ssh-aths, respectively.
Tip
Consider retaining the encrypted backup drive as a disaster recovery device. Document the passphrase in the Admin Workstation KeePassX database, and store the physical Backup Device in a locked safe or other secure location.
Wipe the Backup Device¶
If you do not have a secure location for storing the backups, or already have other backups, you should wipe the Backup Device. There is a lot of debate over the best way to do this, but we think it’s sufficient to simply overwrite it with random data a couple of times. Since the Backup Device is encrypted with LUKS, which employs a number of anti-forensic-recovery techniques, this should be enough to prevent forensic recovery.
First, find the path to the Backup Device. You can find the path with the
Disks application, selecting the drive in the left column, and looking at
the Device entry. It is usually a string that starts with /dev/sd.
Warning
Make sure you use the correct path for the Backup Device in the next command! Otherwise, you run the risk of irreversibly wiping a different drive on the system, such as the Tails USB you are running.
To overwrite the Backup Device, open a Terminal and run:
dd if=/dev/urandom of=<path to Backup Device>
Re-run this command at least twice. Each run will take a while.
If you want to reuse the drive for another purpose, use the Disks utility to reformat it appropriately.
Note
While it probably isn’t necessary to physically destroy a Backup Device (because it’s encrypted, and LUKS is designed to thwart forensic recovery), if you’re really paranoid you can additionally smash the device with a hammer until the chips containing its flash memory are broken up, then dispose of the pieces in the garbage.
Troubleshooting¶
The steps described above should cleanly update your Tails devices without issue. In the event that one or more of your upgraded Tails USBs are not working as expected, don’t worry: you can still manually restore from the Backup Device you created. (Isn’t it great to have backups?)
1. Restore data from the Backup Device¶
On the same airgapped machine, boot up the Tails USB stick you want to restore, with both persistence and admin privileges. Insert your Backup Device into a free USB port, and mount it by navigating to Places ▸ Computer, and clicking on the encrypted disk. You will be prompted to enter its passphrase.
Open a Nautilus window with admin privileges by navigating to Applications ▸
System Tools ▸ Root Terminal. At the terminal prompt, simply type nautilus
and hit Enter. Type ctrl + l, type
/live/persistence/TailsData_unlocked, and hit Enter to navigate there.
Open a new tab in Nautilus (ctrl + t) and navigate to your Backup
Device. Drag and drop the backup data from your Backup Device onto the
TailsData_unlocked tab.
When copying a folder, select the Apply this action to all files option and click Merge to apply to all subfolders. Then you might have to select again the Apply this action to all files option and click Replace to apply to all files.
In a root terminal, or as sudo, execute the following command to fix the ownership of your personal files:
find /live/persistence/TailsData_unlocked/ -uid 1000 -exec chown -R 1000:1000 '{}' \;
2. Verify the restored data¶
Shut down, and reboot the Tails USB. Now that you’ve restored the files, you should re-do the post-upgrade verification to make sure everything is working correctly.
Upgrade Tails from 2.x to 3.x¶
Why you should upgrade¶
Starting with SecureDrop version 0.4, we require users update to Tails version 3.0 or later. Upgrading Tails from 2.x to 3.x must be done manually. This guide will show you how to upgrade each Tails USB stick used in your SecureDrop instance.
What you need¶
- Your existing SecureDrop Tails USB sticks (Admin Workstation, Journalist Workstation, and Secure Viewing Station).
- An airgapped machine to perform the Tails upgrades. The Secure Viewing Station may be used for this task.
- Two USB drives: one to create a new master Tails 3.x USB and one to backup the data on your current SecureDrop Tails USB sticks.
Warning
An airgapped machine (such as the Secure Viewing Station) is required in order to perform these upgrades safely. By isolating the machine from all network access, you reduce the exposure of sensitive data to networked computers, thereby reducing the threat of compromise by adversaries who wish to gain access to your SecureDrop instance.
The airgapped machine should have 3 USB ports, so you can plug in the Tails drive you wish to upgrade, the master Tails USB drive, and the backup drive at the same time. If you don’t have 3 USB ports available, you can use a USB hub, which may reduce transfer speeds.
1. Prepare the master Tails USB¶
Because Tails 3.x is incompatible with older versions, you must create a new “master” Tails USB stick for subsequent installations and upgrades to the USB sticks already in use by your organization.
To create this brand new master Tails, follow the same directions for provisioning the first USB sticks on another networked computer.
Once you’ve created a new Tails 3.x USB, boot into it from your airgapped computer to perform the remaining steps.
At the Tails Greeter screen, enable admin privileges by setting a root password. In Tails 3.x, you do this by clicking the + button, then navigating to Additional Settings ▸ Administration Password.
2. Backup the Tails drives¶
Note
The steps in this section should be performed for each Secure Viewing Station, Journalist Workstation, and Admin Workstation USB drive in your organization.
Before you upgrade your Tails drives, you should backup the data in case something goes wrong.
Navigate to Applications ▸ Utilities ▸ Disks.
Insert the USB drive you wish to use as a backup drive.
Select the drive from the list of drives in the left column.
Click the button with the two cogs and click Format Partition…
Fill out the form as follows:
- Erase: Don’t overwrite existing data (Quick)
- Type: Encrypted, compatible with Linux systems (LUKS + Ext4)
- Name: Backup
Warning
Make sure you use a strong passphrase if this is a long term backup drive.
Click Format.
A dialog box will appear asking you Are you sure you want to format the volume? appears, click Format.
Once completed, you will see two partitions appear:
Now that you made the backup device, plug in the device you want to backup. Then, browse to Places ▸ Computer:
Click on the disk on the left side column. Fill in the passphrase you usually use when you enable Persistence on that device:
You should now have both the Backup and TailsData partition to be backed up mounted and ready to access.
Open a Nautilus window with admin privileges by going to Applications ▸ System Tools ▸ Terminal.
Type gksu nautilus at the terminal prompt and hit enter. You’ll need to type
your admin password.
Note
When you run gksu nautilus, you may run into an error where Nautilus
complains that it can’t create a required folder. If that happens, just click
OK and continue normally.
If a Nautilus window doesn’t come up, it might be because an admin password wasn’t set. If that’s the case, you’ll need to restart and set an admin password before continuing.
Warning
Make sure you use keep the Terminal window open while you perform the backups. Otherwise, the Nautilus window will close.
Make sure you create a directory on the backup drive to store the data from the drive you are backing up:
Copy over everything in the TailsData partition to the relevant folder on the Backup drive. You can simply drag to select all the files and then copy and paste them to the relevant folder on the Backup drive.
In particular, ensure gnupg and Persistent have been successfully
copied over. These files are critical for decrypting submissions.
Once complete, unmount the TailsData partition.
Repeat these steps for every device, making a new folder on the backup device for each device you backup.
Finally, once you have completed the steps described in this section for each USB drive, unmount the Backup partition and store the drive somewhere safely.
3. Upgrade the Tails drives¶
Note
The steps in this section should be performed for each Secure Viewing Station, Journalist Workstation, and Admin Workstation USB drive in your organization.
Next you will upgrade each drive.
Begin by inserting the drive you wish to upgrade into the machine.
Navigate to Applications ▸ Tails ▸ Tails Installer.
Click Upgrade by cloning.
Make sure the correct drive is selected.
Click Install Tails.
A dialog box will appear asking you to Please confirm your device selection.
Click Yes to proceed with the installation.
Note
The upgrade can take quite a bit of time, so please be patient!
Once complete, you should see a success message:
4. Upgrade KeePassX Database¶
Your password databases will be in KeePass 1 database format (a file that ends
in .kdb). You should upgrade them to the new format by following these steps:
- Open KeePassX.
- Navigate to Database and then Import KeePass 1 database.
- Select your password database and click Open.
- Put in a master password if necessary to open the database.
- Then navigate to Database and then Save database as to save the database in its new format (a file ending in
.kdbx) in the same folder as the previous database.
5. Upgrade Secure Viewing Stations¶
Due to a change in Tails 3, if you wish to preserve the names of files when decrypting, you’ll need to apply the following fix by opening a Terminal on the Secure Viewing Station and typing the following commands:
cd /live/persistence/TailsData_unlocked/dotfiles
echo "/usr/bin/dconf write /org/gnome/nautilus/preferences/automatic-decompression false" > .xsessionrc
Note
This only needs to be done once on each Secure Viewing Station. After a reboot it will persist.
6. Upgrade SecureDrop to 0.4.x¶
Now that you’ve upgraded the Tails workstation to Tails 3, follow the 0.4.x Upgrade Guide to configure the Tails environment to access your SecureDrop instance. You will need to perform further upgrade steps for the Admin and Journalist Workstations.
After upgrading to 0.4.x, you should move your backup drive to a safe location (if you used a strong passphrase). Else, you should destroy the backup drive following the instructions here.
If you encounter issues¶
If you run into issues, you can always restore your data from the Backup device following the instructions here.
If you continue to have problems, you can contact us through the SecureDrop Support Portal.
Getting Started¶
Note
SecureDrop maintains two branches of documentation, stable
and latest,
the former being the default used by our Read the Docs powered site.
stable is built from our latest signed git tag, while latest
is built from the head of the develop git branch. In almost all
cases involving development work, you’ll want to make sure you have
the latest version selected by clicking the appropriate link
above, or by using the menu in the bottom left corner.
Prerequisites¶
SecureDrop is a multi-machine design. To make development and testing easy, we provide a set of virtual environments, each tailored for a specific type of development task. We use Vagrant, VirtualBox, and Docker to conveniently develop with a set of virtual environments, and our Ansible playbooks can provision these environments on either virtual machines or physical hardware.
To get started, you will need to install Vagrant, VirtualBox, Docker, and Ansible on your development workstation.
Ubuntu/Debian¶
Note
Tested on: Ubuntu 16.04 and Debian Stretch
sudo apt-get install -y build-essential libssl-dev libffi-dev python-dev \
dpkg-dev git linux-headers-$(uname -r) virtualbox
We recommend using the latest stable version of Vagrant, 1.8.5 at the time
of this writing, which might be newer than what is in your distro’s package
repositories. Older versions of Vagrant has been known to cause problems
(GitHub #932, GitHub #1381). If apt-cache policy vagrant says your
candidate version is not at least 1.8.5, you should download the current version
from the Vagrant Downloads page and then install it.
# If your OS vagrant is recent enough
sudo apt-get install vagrant
# OR this, if you downloaded the deb package.
sudo dpkg -i vagrant.deb
We recommend using the stable version of Docker CE (Community Edition) which can be installed via the official documentation links:
Warning
We do not recommend installing vagrant-cachier. It destroys apt’s state unless the VMs are always shut down/rebooted with Vagrant, which conflicts with the tasks in the Ansible playbooks. The instructions in Vagrantfile that would enable vagrant-cachier are currently commented out.
VirtualBox should be at least version 5.x. See GitHub #1381 for documentation of incompatibility with the older VirtualBox 4.x release series.
Finally, install Ansible so it can be used with Vagrant to automatically
provision VMs. We recommend installing Ansible from PyPi with pip to ensure
you have the latest stable version.
sudo apt-get install python-pip
The version of Ansible recommended to provision SecureDrop VMs may not be the same as the version in your distro’s repos, or may at some point flux out of sync. For this reason, and also just as a good general development practice, we recommend using a Python virtual environment to install Ansible and other development-related tooling. Using virtualenvwrapper:
sudo apt-get install virtualenvwrapper
source /usr/share/virtualenvwrapper/virtualenvwrapper.sh
mkvirtualenv -p /usr/bin/python2 securedrop
Note
You’ll want to add the command to source virtualenvwrapper.sh
to your ~/.bashrc (or whatever your default shell configuration
file is) so that the command-line utilities virtualenvwrapper
provides are automatically available in the future.
Mac OS X¶
Install the dependencies for the development environment:
- Vagrant
- VirtualBox
- Ansible
- Docker
- rsync >= 3.1.0
Note
Note that the version of rsync installed by default on macOS is
extremely out-of-date, as is Apple’s custom. We recommend using
Homebrew to install a modern version (3.1.0 or greater):
brew install rsync.
There are several ways to install Ansible on a Mac. We recommend installing it
to a virtual environment using virtualenvwrapper and pip, so as not to
install the older version we use system-wide. The following commands assume your
default Python is the Python2 that ships with macOS. If you are using a
different version, the path to virtualenvwrapper.sh will differ. Running
pip show virtualenvwrapper should help you find it.
sudo easy_install pip # if you don't already have pip
pip install -U virtualenvwrapper
source /usr/local/bin/virtualenvwrapper.sh
mkvirtualenv -p python2 securedrop
Note
You’ll want to add the command to source virtualenvwrapper.sh
to your ~/.bashrc (or whatever your default shell configuration
file is) so that the command-line utilities virtualenvwrapper
provides are automatically available in the future.
Fork & Clone the repository¶
Now you are ready to get your own copy of the source code. Visit our repository fork it and clone it on you local machine:
git clone git@github.com:<your_github_username>/securedrop.git
Install python requirments¶
SecureDrop uses many 3rd party open source packages from the python community. Ensure your virtualenv is activated and install the packages.
pip install -r securedrop/requirements/develop-requirements.txt
Note
You will need to run this everytime new packages are added.
Virtual Environments: Servers¶
There are three predefined virtual environments in the Vagrantfile:
This document explains the purpose of, and how to get started working with, each one.
Note
If you plan to alter the configuration of any of these machines, make sure to review the Testing: Configuration Tests documentation.
Note
If you have errors with mounting shared folders in the Vagrant guest machine, you should look at GitHub #1381.
Note
If you see test failures due to Too many levels of symbolic links
and you are using VirtualBox, try restarting VirtualBox.
Development¶
This VM is intended for rapid development on the SecureDrop web application. It
syncs the top level of the SecureDrop repo to the /vagrant directory on the
VM, which means you can use your favorite editor on your host machine to edit
the code. This machine has no security hardening or monitoring.
Tip
This is the default VM, so you don’t need to specify the
development machine name when running commands like vagrant up and
vagrant ssh. Of course, you can specify the name if you want to.
To get started working with the development environment:
vagrant up
vagrant ssh
cd /vagrant/securedrop
./manage.py run # run development servers
./manage.py reset # resets the state of the development instance
./manage.py add-admin # create a user to use when logging in to the Journalist Interface
pytest -v tests/ # run the unit and functional tests
SecureDrop consists of two separate web applications (the Source Interface and the Journalist Interface) that run concurrently. In the Development environment they are configured to detect code changes and automatically reload whenever a file is saved. They are made available on your host machine by forwarding the following ports:
- Source Interface: localhost:8080
- Journalist Interface: localhost:8081
Staging¶
A compromise between the development and production environments. This configuration can be thought of as identical to the production environment, with a few exceptions:
- The Debian packages are built from your local copy of the code, instead of installing the current stable release packages from https://apt.freedom.press.
- The production environment only allows SSH over an Authenticated Tor Hidden Service (ATHS), but the staging environment allows direct SSH access so it’s more ergonomic for developers to interact with the system during debugging.
- The Postfix service is disabled, so OSSEC alerts will not be sent via email.
This is a convenient environment to test how changes work across the full stack.
You should first bring up the VM required for building the app code Debian packages on the staging machines:
make build-debs
vagrant up /staging/
vagrant ssh app-staging
sudo su
cd /var/www/securedrop
./manage.py add-admin
pytest -v tests/
To rebuild the local packages for the app code:
make build-debs
The Debian packages will be rebuilt from the current state of your local git repository and then installed on the staging servers.
Note
If you are using Mac OS X and you run into errors from Ansible
such as OSError: [Errno 24] Too many open files, you may need to
increase the maximum number of open files. Some guides online suggest
a procedure to do this that involves booting to recovery mode
and turning off System Integrity Protection (csrutil disable).
However this is a critical security feature and should not be
disabled. Instead follow this procedure to increase the file limit.
Set /Library/LaunchDaemons/limit.maxfiles.plist to the following:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>Label</key>
<string>limit.maxfiles</string>
<key>ProgramArguments</key>
<array>
<string>launchctl</string>
<string>limit</string>
<string>maxfiles</string>
<string>65536</string>
<string>65536</string>
</array>
<key>RunAtLoad</key>
<true/>
<key>ServiceIPC</key>
<false/>
</dict>
</plist>
The plist file should be owned by root:wheel:
sudo chown root:wheel /Library/LaunchDaemons/limit.maxfiles.plist
This will increase the maximum open file limits system wide on Mac OS X (last tested on 10.11.6).
The web interfaces and SSH are available over Tor. A copy of the the Onion URLs
for Source and Journalist Interfaces, as well as SSH access, are written to the
Vagrant host’s install_files/ansible-base directory, named:
app-source-thsapp-journalist-athsapp-ssh-aths
For working on OSSEC monitoring rules with most system hardening active, update
the OSSEC-related configuration in
install_files/ansible-base/staging-specific.yml so you receive the OSSEC
alert emails.
A copy of the the Onion URL for SSH access to the Monitor Server is written to
the Vagrant host’s install_files/ansible-base directory, named:
mon-ssh-aths
Direct SSH access is available via Vagrant for staging hosts, so you can use
vagrant ssh app-staging and vagrant ssh mon-staging to start an
interactive session on either server.
Production¶
This is a production installation with all of the system hardening active, but
virtualized, rather than running on hardware. You will need to
configure prod-like secrets, or export
ANSIBLE_ARGS="--skip-tags validate" to skip the tasks that prevent the prod
playbook from running with Vagrant-specific info.
You can provision production VMs from an Admin Workstation (most realistic), or from your host. Instructions for both follow.
Install from an Admin Workstation VM¶
In SecureDrop, admin tasks are performed from a Tails Admin Workstation. You should configure a Tails VM in order to install the SecureDrop production VMs by following the instructions in the Virtualizing Tails guide.
Once you’re prepared the Admin Workstation, you can start each VM:
vagrant up --no-provision /prod/
At this point you should be able to SSH into both app-prod and mon-prod.
From here you can follow the server configuration instructions to test connectivity and prepare the servers. These
instructions will have you generate SSH keys and use ssh-copy-id to transfer
the key onto the servers.
Note
If you have trouble SSHing to the servers from Ansible, remember
to remove any old ATHS files in install_files/ansible-base.
Now from your Admin workstation:
cd ~/Persistent/securedrop
./securedrop-admin setup
./securedrop-admin sdconfig
./securedrop-admin install
Note
The sudo password for the app-prod and mon-prod servers is by
default vagrant.
After install you can configure your Admin Workstation to SSH into each VM via:
./securedrop-admin tailsconfig
Install from Host OS¶
If you are not virtualizing Tails, you can manually modify site-specific,
and then provision the machines. You should set the following options in
site-specific:
ssh_users: "vagrant"
monitor_ip: "10.0.1.5"
monitor_hostname: "mon-prod"
app_hostname: "app-prod"
app_ip: "10.0.1.4"
Note that you will also need to generate Submission and OSSEC PGP public keys, and provide email credentials to send emails to. Refer to this document on configuring prod-like secrets for more details on those steps.
To create the prod servers, run:
vagrant up /prod/
vagrant ssh app-prod
sudo su
cd /var/www/securedrop/
./manage.py add-admin
A copy of the the Onion URLs for Source and Journalist Interfaces, as well as
SSH access, are written to the Vagrant host’s install_files/ansible-base
directory, named:
app-source-thsapp-journalist-athsapp-ssh-athsmon-ssh-aths
SSH Access¶
Direct SSH access is not available in the prod environment. You will need to log in over Tor after initial provisioning. See Connecting to VMs via SSH over Tor for more info.
Virtual Environments: Admin Workstation¶
SecureDrop uses Tails for the Admin Workstation environment. In order to perform a fully virtualized production install, you will need to first set up Tails in a virtual machine.
Note
For the instructions that follow, you need to download the most recent Tails ISO from the Tails website.
macOS¶
For the macOS instructions, you will use VirtualBox to create a Tails VM that
you can use to install SecureDrop on app-prod and mon-prod.
Create a VirtualBox VM¶
- Open VirtualBox
- Click New to create a new VM with the following options:
- Name: “Admin Workstation”
- Type: “Linux”
- Version: “Debian (64-bit)”
Note
You may call the VM a different name, but you must replace “Admin Workstation” later on in these instructions with the name you select.
- Click Continue.
- At the prompt, configure at least 2048 MB of RAM. Click Continue.
- Leave the default Create a virtual hard disk now selected and click Create. All the default options (Hard disk file type: VDI (VirtualBox Disk Image) and Dynamically allocated) are fine. Click Create.
Booting Tails¶
Now that the VM is set up, you are ready to boot to Tails. Select the new VM in the VirtualBox sidebar, and click Settings.
Click Storage.
Click Empty under Controller: IDE.
Click the CD icon next to Optical Drive: and click Choose Virtual Optical Disk File.
Navigate to the Tails ISO to boot from.
Click General then Advanced.
Under Shared Clipboard select Bidirectional instead of Disabled. This option will enable you to transfer text from your host to the Tails VM, which we will use later on in these steps.
Note
Alternatively you can open these docs in Tor Browser in Tails. This will obviate the need to copy and paste between the guest and host OS.
Install Tails¶
Next you will install Tails onto the Virtual Hard Disk Image. Start the VM, boot to Tails, and enter an administration password and start Tails.
Note
For all the instructions that follow, you will need to configure an administrator password each time you boot Tails.
- Copy the following patch and save it as
installer.patchin a folder in your Tails VM:
--- /usr/lib/python2.7/dist-packages/tails_installer/creator.py 2017-06-30 11:14:11.000000000 +0000
+++ /usr/lib/python2.7/dist-packages/tails_installer/creator.py.mod 2017-07-20 06:53:31.152000000 +0000
@@ -615,15 +615,6 @@
if not data['removable']:
self.log.debug('Skipping non-removable device: %s' % data['device'])
- # Only pay attention to USB and SDIO devices, unless --force'd
- iface = drive.props.connection_bus
- if iface != 'usb' and iface != 'sdio' and self.opts.force != data['device']:
- self.log.warning(
- "Skipping device '%(device)s' connected to '%(interface)s' interface"
- % {'device': data['udi'], 'interface': iface}
- )
- continue
-
# Skip optical drives
if data['is_optical'] and self.opts.force != data['device']:
self.log.debug('Skipping optical device: %s' % data['device'])
--- /usr/lib/python2.7/dist-packages/tails_installer/gui.py 2017-06-30 11:14:11.000000000 +0000
+++ /usr/lib/python2.7/dist-packages/tails_installer/gui.py.mod 2017-07-20 06:53:44.040000000 +0000
@@ -483,16 +483,6 @@
'model': info['model'],
'details': details
}
- # Skip devices with non-removable bit enabled
- if not info['removable']:
- message =_('The USB stick "%(pretty_name)s"'
- ' is configured as non-removable by its'
- ' manufacturer and Tails will fail to start on it.'
- ' Please try installing on a different model.') % {
- 'pretty_name': pretty_name
- }
- self.status(message)
- continue
# Skip too small devices, but inform the user
if not info['is_device_big_enough']:
message =_('The device "%(pretty_name)s"'
- Now run the following two commands in a Terminal in your Tails VM:
sudo patch -p0 -d/ < installer.patch
sudo /usr/bin/python -tt /usr/lib/tails_installer/tails-installer -u -n --clone -P -m -x
- The Tails Installer will appear. Click Install Tails.
- Once complete, navigate to Applications, Utilities and open Disks.
- Click on the disk named “Tails” and click the Play icon to mount the disk.
- Next open
/media/amnesia/Tails/syslinux/live*.cfgand delete all instances oflive-media=removable. - Shut down the VM.
Boot to Tails Hard Drive Install¶
Now we will remove the CD and boot to the Tails we just installed on our virtual hard drive. From macOS you should:
- Click the VM in the sidebar of VirtualBox and click Settings.
- Click Storage and select the Tails .iso under Controller: IDE.
- Click the CD icon, then Remove Disk from Virtual Drive.
- Click Ok.
- Start the VM.
Configure Persistence¶
Now in your booted Tails VM you should:
- Configure an admin password when prompted.
- Copy the following patch to the Tails VM and save it as
persistence.patch:
--- /usr/share/perl5/Tails/Persistence/Setup.pm 2017-06-30 09:56:25.000000000 +0000
+++ /usr/share/perl5/Tails/Persistence/Setup.pm.mod 2017-07-20 07:17:48.472000000 +0000
@@ -404,19 +404,6 @@
my @checks = (
{
- method => 'drive_is_connected_via_a_supported_interface',
- message => $self->encoding->decode(gettext(
- "Tails is running from non-USB / non-SDIO device %s.")),
- needs_drive_arg => 1,
- },
- {
- method => 'drive_is_optical',
- message => $self->encoding->decode(gettext(
- "Device %s is optical.")),
- must_be_false => 1,
- needs_drive_arg => 1,
- },
- {
method => 'started_from_device_installed_with_tails_installer',
message => $self->encoding->decode(gettext(
"Device %s was not created using Tails Installer.")),
- To apply the patch, from the Terminal run:
sudo patch -p0 -d/ < persistence.patch
- Navigate to Applications then Tails and click Configure persistent volume. Configure a persistent volume enabling all persistence options.
Allow the Guest to Create Symlinks¶
Finally, you’ll need to allow the guest to create symlinks, which are disabled by default in VirtualBox.
Shut down the Tails VM, and in your host run:
VBoxManage setextradata "Admin Workstation" VBoxInternal2/SharedFoldersEnableSymlinksCreate/securedrop 1
Note
If you named your Tails VM something other than “Admin Workstation”,
you can run VBoxManage list vms to get the name of the Virtual Machine.
Finally, restart VirtualBox.
Configure Networking¶
In order to communicate with the server VMs, you’ll need to attach this
virtualized Admin Workstation to the securedrop network.
Warning
If you named the SecureDrop repository something other than
securedrop, you should connect your VM to the network of the same name.
With the Admin Workstation VM turned off, you should:
- Click on the VM in VirtualBox.
- Click Settings.
- Click Network and then Adapter 2.
- Enable this network adapter and attach it to the Internal Network called
securedrop. - Click OK and start the VM.
Now you should be able to boot to Tails, decrypt the Persistent volume,
navigate to ~/Persistent/securedrop and proceed with the production
install.
Linux¶
For the Linux instructions, you will use KVM/libvirt to create a Tails VM that
you can use to install SecureDrop on app-prod and mon-prod.
Create a libvirt VM¶
Follow the Tails virt-manager instructions for Running Tails from a virtual USB storage. After installing Tails on the removable USB device, shut down the VM and edit the boot options. You’ll need to manually enable booting from the USB device by checking the box labeled USB Disk 1.
Then proceed with booting to the USB drive, and configure a persistence volume.
Shared Folders¶
In order to mount the SecureDrop git repository as a folder inside the Tails persistence volume, you must add a filesystem via virt-manager.
- Choose View ▸ Details to edit the configuration of the virtual machine.
- Click on the Add Hardware button on the bottom of the left pane.
- Select Filesystem in the left pane.
- In the right pane, change the Mode to Mapped.
- In the right pane, change Source path to the path to the SecureDrop git repository on the host machine.
- In the right pane, change Target path to securedrop.
- Click Finish.
On the next VM boot, you will be able to mount the SecureDrop git repository from the host machine via:
mkdir -p ~/Persistent/securedrop
sudo mount -t 9p securedrop ~/Persistent/securedrop
You will need to run the mount command every time you boot the VM.
By default only read operations are supported. In order to support modifying files
in the git repository, you will need to configure file ACLs.
On the host machine, from within the SecureDrop git repository, run:
make libvirt-share
All files will be created with mode 0600 and ownership libvirt-qemu:libvirt-qemu.
You will need to modify the files manually on the host machine in order to commit them.
Contributing Guidelines¶
Branching Strategy¶
SecureDrop uses a branching model based on git-flow. The master
branch always points to the latest stable release. Use this branch if you are
interested in installing or auditing SecureDrop. Development for the upcoming
release of SecureDrop takes place on develop, which is the default
branch. If you want to contribute, you should branch from and submit pull
requests to develop.
Automated Testing¶
When a pull request is submitted, we have Travis CI automatically run the SecureDrop test suites, which consist of:
- Unit tests of the Python SecureDrop application code.
- Functional tests that use Selenium to drive a web browser to verify the function of the application from the user’s perspective.
- Tests of the system configuration state using testinfra.
Before a PR can be merged, these tests must all pass. If you modify the application code, you should verify the tests pass locally before submitting your PR. If you modify the server configuration, you should run the testinfra tests. Please denote in the checklist when you submit the PR that you have performed these checks locally.
Code Style¶
We use code linters to keep a consistent code quality and style. These linters also run in CI and will produce build failures. To avoid this, we have included a git pre-commit hook. You can install it with the following command run at the root of the repository:
ln -sf ../../git/pre-commit .git/hooks/pre-commit
Note
The code linters are installed automatically on the Development VM, but for the pre-commit hook to work, you will need to install the linting tools locally on your host machine. From the root of the repo you can run the following:
pip install -r securedrop/requirements/develop-requirements.txt
Shell¶
All Shell code (e.g. bash, sh) should be shellcheck
compliant. You can run shellcheck locally via:
make shellcheck
For reference, consult the shellcheck wiki for detailed explanations of any reported violations.
HTML¶
HTML should be in compliance with
Google’s HTML style guide.
We use html-linter to lint
our HTML templates in securedrop/source_templates and
securedrop/journalist_templates. Run the HTML linting options we use via:
make html-lint
Git History¶
We currently use an explicit merge strategy to merge feature branches into
develop. In order to keep our git history as clean as possible, please squash
your commits to package up your changes into a clear history. If you have
many unnecessary commits that do not add information to aid in review, they
should be removed. If you are unfamiliar with how to squash commits with rebase,
check out this
blog post.
Privileges¶
Dedicated contributors to SecureDrop will be granted extra privileges such as the right to push new branches or to merge pull requests. There is no formal process at the moment but the general idea is that any contributor with the right technical and social skills is entitled to ask. The people who have the power to grant such privileges are commited to do so in a transparent way to avoid any dispute.
Other Tips¶
- To aid in review, please write clear commit messages and include a descriptive PR summary. We have a PR template that specifies the type of information you should include.
- To maximize the chance that your PR is merged, please include the minimal changes to implement the feature or fix the bug.
- If there is not an existing issue for the PR you are interested in submitting, you should submit an issue first or comment on an existing issue outlining how you intend to approach the problem.
Tips & Tricks¶
Using Tor Browser with the development environment¶
We strongly encourage sources to use the Tor Browser when they access the Source Interface. Tor Browser is the easiest way for the average person to use Tor without making potentially catastrophic mistakes, makes disabling Javascript easy via the handy NoScript icon in the toolbar, and prevents state about the source’s browsing habits (including their use of SecureDrop) from being persisted to disk.
Since Tor Browser is based on an older version of Firefox (usually the current ESR release), it does not always render HTML/CSS the same as other browsers (especially more recent versions of browsers). Therefore, we recommend testing all changes to the web application in the Tor Browser instead of whatever browser you normally use for web development. Unfortunately, it is not possible to access the local development servers by default, due to Tor Browser’s proxy configuration.
To test the development environment in Tor Browser, you need to add an exception to allow Tor Browser to access localhost:
- Open the “Tor Browser” menu and click “Preferences…”
- Choose the “Advanced” section and the “Network” subtab under it
- In the “Connection” section, click “Settings…”
- In the text box labeled “No Proxy for:”, enter
127.0.0.1- Note: for some reason,
localhostdoesn’t work here.
- Note: for some reason,
- Click “Ok” and close the Preferences window
You should now be able to access the development server in the Tor
Browser by navigating to 127.0.0.1:8080 and 127.0.0.1:8081.
Upgrading or Adding Python Dependencies¶
We use a pip-compile
based workflow for adding Python dependencies. If you would like to add a Python
dependency, instead of editing the securedrop/requirements/*.txt files
directly, please:
Edit the relevant
*.infile insecuredrop/requirements/Use the following shell script to generate
securedrop/requirements/*.txtfiles:make update-pip-dependenciesCommit both the
securedrop/requirements/*.inandsecuredrop/requirements/*.txtfiles
Connecting to VMs via SSH over Tor¶
Ubuntu/Debian setup¶
You will need to install a specific variant of the nc tool
in order to support the -x option for specifying a proxy host.
Mac OS X already runs the OpenBSD variant by default.
sudo apt-get install netcat-openbsd
After installing netcat-openbsd and appending the Tor config options
to your local torrc, you can export the environment variable
SECUREDROP_SSH_OVER_TOR=1 in order to use vagrant ssh to access the
staging or prod instances over Tor. Here is an example of how that works:
$ vagrant up --provision /prod/ # restricts SSH to Tor after final reboot
$ vagrant ssh-config app-prod # will show incorrect info due to lack of env var
Host app-prod
HostName 127.0.0.1
User vagrant
Port 2201
UserKnownHostsFile /dev/null
StrictHostKeyChecking no
PasswordAuthentication no
IdentityFile /home/conor/.vagrant.d/insecure_private_key
IdentitiesOnly yes
LogLevel FATAL
$ vagrant ssh app-prod -c 'echo hello' # will fail due to incorrect ssh-config
ssh_exchange_identification: read: Connection reset by peer
$ export SECUREDROP_SSH_OVER_TOR=1 # instruct Vagrant to use Tor for SSH
$ vagrant ssh-config app-prod # will show correct info, with ProxyCommand
Host app-prod
HostName l57xhqhltlu323vi.onion
User vagrant
Port 22
UserKnownHostsFile /dev/null
StrictHostKeyChecking no
PasswordAuthentication no
IdentityFile /home/conor/.vagrant.d/insecure_private_key
IdentitiesOnly yes
LogLevel FATAL
ProxyCommand nc -x 127.0.0.1:9050 %h %p
$ # ensure ATHS values are active in local Tor config:
$ cat *-aths | sudo tee -a /etc/tor/torrc > /dev/null && sudo service tor reload
$ vagrant ssh app-prod -c 'echo hello' # works
hello
Connection to l57xhqhltlu323vi.onion closed.
If SECUREDROP_SSH_OVER_TOR is true, Vagrant will look up the ATHS URLs
for each server by examining the contents of app-ssh-aths and mon-ssh-aths
in ./install_files/ansible-base. You can manually inspect these files
to append values to your local torrc, as in the cat example above.
Note that the cat example above will also add the ATHS info for the
Journalist Interface, as well, which is useful for testing.
Internationalization (i18n)¶
The code, templates and javascript user visible strings must all be
wrapped with gettext functions to be substituted at runtime with
the equivalent localized string. These function names are used as
markers to collect the strings to be translated and store them into
the securedrop/translations/messages.pot file. For each language
to be translated, a directory is created such as
securedrop/translations/fr_FR and populated with files derived
from securedrop/translations/messages.pot, for translators to work
with and for the gettext substitution at runtime.
The desktop icon are in the
install_files/ansible-base/roles/tails-config/templates directory.
Their labels are collected in the desktop.pot file and translated
in the corresponding .po files in the same directory (fr.po,
de.po etc.)
The manage.py translate helper¶
The pybabel and gettext command line is wrapped into the
manage.py translate-messages and manage.py translate-desktop
helpers for convenience. It is designed to be used by developers, to
run tests with fixtures and for packaging.
Creating new translations¶
For the applications, a user with weblate admin rights must visit the Weblate translation creation page and add the desired languages.
For the desktop, the translations must be suspended in Weblate to avoid conflicts.
- Go to the Weblate commit page for SecureDrop
- Click
Lock
Now new files must be created and pushed to weblate with:
$ git clone -b i18n http://lab.securedrop.club/bot/securedrop
$ cd securedrop/install_files/ansible-base/roles/tails-config/templates
$ msginit --no-translator --locale ar --output ar.po --input desktop.pot
$ git add ar.po
$ git commit -m 'i18n: add ar.po' ar.po
$ git push
Where ar is the name of the locale, exactly matching the name of
the corresponding application translation.
After pushing the new translation, make sure to unlock the translations.
The list of supported languages in the SecureDrop installation documentation must be updated.
Updating strings to be translated¶
After modifying a string in the code, templates, javascript or desktop
labels, the securedrop/translations/messages.pot files must be
updated by running the following command in /vagrant/securedrop,
in the development virtual machine:
make translate
which wraps manage.py translate-messages and manage.py
translate-desktop. The updated
securedrop/translations/messages.pot and
install_files/ansible-base/roles/tails-config/templates/desktop.pot
should then be reviewed and commited. Once merged in develop, the
changes will be visible in the Weblate web interface used by
translators because it watches the develop branch of the SecureDrop
repository.
Compiling translations¶
gettext needs a compiled file for each language (the *.mo
files). This can be done by running the following command
in /vagrant/securedrop, in the development virtual machine:
./manage.py --verbose translate-messages --compile
For desktop files the compilation phases creates a modified version of
the original file which includes all the translations collected from
the .po files.
This can be done by running the following command in
/vagrant/securedrop, in the development virtual machine:
./manage.py --verbose translate-desktop --compile
Verifying translations¶
After a translation is compiled, the web page in which it shows can be
verified visually by navigating to the corresponding state from
http://localhost:8080 for the source interface or
http://localhost:8081 for the journalist interface after running
the following:
./manage.py run
An easier way is to generate screenshots for each desired language with:
$ export PAGE_LAYOUT_LOCALES=en_US,fr_FR
$ pytest -v --page-layout tests/pages-layout
...
...TestJournalistLayout::test_col_no_documents[en_US] PASSED
...TestJournalistLayout::test_col_no_documents[fr_FR] PASSED
...
Note
if unset, PAGE_LAYOUT_LOCALES defaults to en_US
The screenshots for fr_FR are available in
securedrop/tests/pages-layout/screenshots/fr_FR and the name of
the file can be found in the function that created it in
securedrop/tests/pages-layout/test_journalist.py or
securedrop/tests/pages-layout/test_source.py.
Merging translations back to develop¶
Weblate automatically pushes the translations done via the web
interface as a series of commit to the i18n branch in the Weblate
SecureDrop branch which is a fork of the develop branch of the
SecureDrop git repository. These translations need to be submitted
to the develop branch via pull requests for merge on a regular basis.
$ git clone https://github.com/freedomofpress/securedrop
$ cd securedrop
$ git remote add lab http://lab.securedrop.club/bot/securedrop/tree/i18n
$ git fetch lab
$ git checkout -b wip-i18n origin/develop
$ git checkout lab/i18n -- securedrop/translations \
install_files/ansible-base/roles/tails-config/templates/{nl,fr,de_DE,nb_NO,pt_BR,es_ES}.po
$ git add translations
$ vagrant ssh development
$ cd /vagrant/securedrop ; ./manage.py --verbose translate-desktop --compile
$ git commit -m 'sync with weblate' translations
$ git push wip-i18n
Verify the translations are not broken:
$ vagrant ssh development
$ cd /vagrant/securedrop
$ PAGE_LAYOUT_LOCALES='de_DE,es_ES,fr_FR,nb_NO,nl,pt_BR' \
pytest -v --page-layout tests/pages-layout
Go to https://github.com/freedomofpress/securedrop and propose a pull request.
Note
contrary to the applications translations, the desktop
translations are compiled and merged into the
repository. They need to be available in their translated
form when securedrop-admin tailsconfig is run because
the development environment is not available.
Merging develop into the weblate fork¶
Weblate works on a long standing fork of the SecureDrop git
repository and is exclusively responsible for the content of the
*.pot and *.po files. It needs to merge the content of the
develop branch back into its i18n branch to be able to extract
from the sources new strings to translate or existing strings that
have been updated.
The translations must be suspended in Weblate to avoid conflicts.
- Go to the Weblate commit page for SecureDrop
- Click
Lock
The develop branch can now be merged into i18n as follows:
$ git clone https://github.com/freedomofpress/securedrop
$ cd securedrop
$ git remote add lab http://lab.securedrop.club/bot/securedrop/tree/i18n
$ git fetch lab
$ git checkout -b i18n lab/i18n
$ git merge origin/develop
$ make translate
The manage.py command examines all the source files, looking for
strings that need to be translated (i.e. gettext(‘translate me’) etc.)
and update the files used by Weblate, removing, updating and inserting
strings to keep them in sync withe the sources. Carefully review the
output of git diff. Check messages.pot first for updated strings,
looking for formatting problems. Then review the messages.po of one
existing translation, with a focus on fuzzy translations. There is
no need to review other translations because they are processed in the
same way. When you are satisfied with the result, it can be merged
with:
$ git commit -a -m 'l10n: sync with upstream origin/develop'
$ git push lab i18n
- Go to the Weblate commit page for SecureDrop and verify the
commit hash matches the last commit of the
i18nbranch. This must happen instantly after the branch is pushed because Weblate is notified by GitLab via a webhook. If it is different, ask for help.
Weblate pushes the translations done via the web interface to the develop branch in a fork of the SecureDrop git repository. These commits must be manually cherry-picked and proposed as pull requests for the SecureDrop git repository.
Updating the full text index¶
The full text index can occasionally not be up to date. The symptom may be that the search function fails to find a word that you know exists in the source strings. If that happens you can rebuild the index from scratch with:
$ ssh debian@weblate.securedrop.club
$ cd /app/weblate
$ sudo docker-compose run weblate rebuild_index --all --clean
Note that the new index will not be used right away, some workers may still have the old index open. Rebooting the machine is an option, waiting for a few hours is another option.
Getting Started with Weblate Translations¶
SecureDrop is a whistleblower submission system that media organizations can use to securely accept documents from and communicate with anonymous sources. For more information, you may be interested to learn about what makes SecureDrop unique.
SecureDrop uses the Weblate platform. This page lists detailed instructions for getting started with the Weblate platform as a translator. Before starting this guide, you should know which language you would like to translate.
Who uses SecureDrop?¶
There are two kind of SecureDrop users: Sources and Journalists. A source is an individual who wants to communicate securely and anonymously with a journalist. Sources are not expected to be have any technical background. Journalists using SecureDrop have all received proper training and know what a PGP public key is, they understand the basic workflow of SecureDrop.
Register for Weblate¶
Login via GitHub for the first time¶
If you already have a GitHub account, go to the Weblate registration page:
Click on the octocat icon and agree to login via GitHub.
You will then be redirected to the Weblate dashboard.
Register a Weblate account¶
Go to the Weblate registration page
Fill the form and click Register and check your mail for a confirmation mail from admin@securedrop.club with the subject [Weblate] Your registration on Weblate. Click the first link to confirm: you will be redirected to the Weblate dashboard:
Choose a language¶
From your Weblate dashboard:
Click the Watched translations menu and select Suggested translations:
And click the translate button to the right on the line that shows your native language:
Translate a phrase¶
Each string to be translated is shown in a Source box and you can translate it right below in the Translation text area. When you are done, click Save and another string will be proposed.
For most strings a screenshot is available on the right side to show how it looks in context. The screenshot can be displayed in full size by clicking on it:
Placeholders¶
The strings may contain placeholders between braces: they will be substituted with actual content at runtime and must be left unmodified. For instance:
Edit user {user}
will be displayed to the user as:
Edit user Jean-Claude
The French translated string should look like:
Modifier l'utilisateur {user}
And it would be incorrect to translate the placeholder like so:
Modifier l'utilisateur {utilisateur}
Glossary¶
A glossary is available to explain the SecureDrop specific terms. In addition, it is important that some key terms are understood and precisely translated.
Adversary¶
Your adversary is the person or organization attempting to undermine your security goals. Adversaries can be different, depending on the situation. For instance, you may worry about criminals spying on the network at a cafe, or your classmates at a school. Often the adversary is hypothetical.
This definition was copied from the EFF glossary
Air gap¶
A computer or network that is physically isolated from all other networks, including the Internet, is said to be air-gapped.
This definition was copied from the EFF glossary
Attack¶
In computer security, an attack is a method that can be used to compromise security, or its actual use. An attacker is the person or organization using an attack. An attack method is sometimes called an “exploit.”
This definition was copied from the EFF glossary
Command line tool (command)¶
The “command line” is an ancient way of giving a computer a series of small, self-contained orders (think of those science fiction movies where teenage geniuses type long strings of green text onto black screens). To use a command line tool, the user types a command into a window called a terminal emulator, hits the return or enter key, and then receives a textual response in the same window. Windows, Linux and Apple desktop computers still let you run software using this interface, and even some mobile phones can do the same with the right app. The command line can be used to run software pre-packaged with your operating system. Some downloadable programs, especially technical utilities, use the command line instead of a more familiar “icons and buttons” user interface. The command line needn’t be scary, but it does require you to type in exactly the right set of letters and numbers to get the correct result, and it’s often unclear what to do if the responses don’t match your expectations.
This definition was copied from the EFF glossary
Cryptography¶
The art of designing secret codes or ciphers that let you send and receive messages to a recipient without others being able to understand the message.
This definition was copied from the EFF glossary
Decrypt¶
Make a secret message or data intelligible. The idea behind encryption is to make messages that can only be decrypted by the person or people who are meant to receive them.
This definition was copied from the EFF glossary
Encryption¶
A process that takes a message and makes it unreadable except to a person who knows how to decrypt it back into a readable form.
This definition was copied from the EFF glossary
Encryption key¶
An encryption key is a piece of information that is used to convert a message into an unreadable form. In some cases, you need the same encryption key to decode the message. In others, the encryption key and decryption key are different.
This definition was copied from the EFF glossary
Fingerprint¶
The keys of public key cryptography are very large numbers, sometimes a thousand or more digits long. A fingerprint is a much smaller number or set of numbers and letters that can be used as a unique name for that key, without having to list all of the key’s digits. So, for instance, if you and a friend wished to make sure you both had the same key, you could either spend a long time reading off all the hundreds of digits in the key, or you could each calculate your key’s fingerprint and compare those instead. The fingerprints presented by cryptographic software usually consist of around 40 letters and numbers. If you carefully check that a fingerprint has the right value, you should be safe against impersonation using a fake key. Some software tools may offer more convenient alternative ways to verify a friend’s key, but some form of verification needs to happen to prevent communications providers from easily being able to listen in.
This definition was copied from the EFF glossary
HTTPS¶
If you’ve ever seen a web address spelled out as “http://www.example.com/”, you’ll recognize the “http” bit of this term. HTTP (hypertext transfer protocol) is the way a web browser on your machine talks to a remote web server. Unfortunately, standard http sends text insecurely across the Internet. HTTPS (the S stands for “secure”) uses encryption to better protect the data you send to websites, and the information they return to you, from prying eyes.
This definition was copied from the EFF glossary
Key¶
In cryptography, a piece of data which gives you the capability to encrypt or decrypt a message.
This definition was copied from the EFF glossary
Keyring¶
If you use public key cryptography, you’ll need to keep track of many keys: your secret, private key, your public key, and the public keys of everyone you communicate with. The collection of these keys is often referred to as your keyring.
This definition was copied from the EFF glossary
Man-in-the-middle attack (MITM)¶
Suppose you believe you were speaking to your friend, Bahram, via encrypted instant messager. To check it’s really him, you ask him to tell you the city where you first met. “Istanbul” comes the reply. That’s correct! Unfortunately, without you or Bahram knowing, someone else online has been intercepting all your communications. When you first connected to Bahram, you actually connected to this person, and she, in turn, connected to Bahram. When you think you are asking Bahram a question, she receives your message, relays the question to Bahram, receives his answer back , and then sends it to you. Even though you think you are communicating securely with Bahram, you are, in fact, only communicating securely with the spy, who is also communicating securely to Bahram! This is the man-in-the-middle attack. Men-in-the-middle can spy on communications or even insert false or misleading messages into your communications. Security-focused internet communications software needs to defend against the man-in-the-middle attack to be safe against attackers who have control of any part of the Internet between two communicators.
This definition was copied from the EFF glossary
Public key encryption¶
Traditional encryption systems use the same secret, or key, to encrypt and decrypt a message. So if I encrypted a file with the password “bluetonicmonster”, you would need both the file and the secret “bluetonicmonster” to decode it. Public key encryption uses two keys: one to encrypt, and another to decrypt. This has all kinds of useful consequences. For one, it means that you can hand out the key to encrypt messages to you, and as long as you keep the other key secret, anyone with that key can talk to you securely. The key you hand out widely is known as the “public key”: hence the name of the technique. Public key encryption is used to encrypt email and files by Pretty Good Privacy (PGP), OTR for instant messaging, and SSL/TLS for web browsing.
This definition was copied from the EFF glossary
Two-factor authentication¶
“Something you know, and something you have.” Login systems that require only a username and password risk being broken when someone else can obtain (or guess) those pieces of information. Services that offer two-factor authentication also require you to provide a separate confirmation that you are who you say you are. The second factor could be a one-off secret code, a number generated by a program running on a mobile device, or a device that you carry and that you can use to confirm who you are. Companies like banks, and major internet services like Google, Paypal and Twitter now offer two-factor authentication.
This definition was copied from the EFF glossary
Weblate glossary¶
For each string to be translated, Weblate shows a glossary of terms and their translation to help unify their translations. For instance when translating Please wait for a new two-factor token before logging in again, Weblate notices the word two-factor is found in the glossary and displays the translation in the glossary to the right.
Before translating strings, it is recommended to add all terms in the SecureDrop localization glossary by clicking on the pen in the right corner of the glossary displayed with each translated string and then Add new word:
When all the terms are in the glossary, it is recommended to take another look at the full list of terms and verify there is no duplicate or other mistakes.
Tip
The terms copied from the EFF glossary already have a translation in a number of languages.
Getting help¶
Should you need help, you can do one of the following:
- post a message in the translation category of the SecureDrop forum
- chat in the SecureDrop instant messenging channel
- read the Weblate documentation
Frequently Asked Questions¶
What if the language I want to translate is not on the list?
You can send a request for a new language in the translation category of the SecureDrop forum. But please make sure the language you want is definitely not present!
Documentation Guidelines¶
SecureDrop’s documentation is written in ReStructuredText (ReST),
and is built by and hosted on Read the Docs (RTD). The
documentation files are stored in the primary SecureDrop git
repository under the docs/ directory.
To get started editing the docs:
Clone the SecureDrop repository:
git clone https://github.com/freedomofpress/securedrop.git
Install the dependencies:
pip install -r securedrop/requirements/develop-requirements.txt
Build the docs and open the index page in your web browser:
make docs
If you have the Development VM running, you should run
make docs from within the /vagrant directory inside the VM, otherwise
the forwarded port on 8000 will collide with sphinx-autobuild process running
on localhost.
You can then can browse the documentation at http://127.0.0.1:8000/. As you make changes, the docs will automatically rebuild in the browser window, so you don’t need to refresh the page manually.
Testing documentation changes¶
You can check the docs for formatting violations by running the linting option:
make docs-lint
The make docs command will display warnings, but will still build the
documentation if formatting mistakes are found. Using make docs-lint
will convert any warnings to errors, causing the build to fail.
The CI tests will automatically perform linting via the same
command.
The CI tests by default create staging servers to test the
application code. If your PR only makes documentation changes, you should
prefix the branch name with docs- to skip the staging run. Project
maintainers will still need to approve the PR prior to merge, and the linting
checks will also still run.
Updating screenshots¶
The user guides for SecureDrop contain screenshots of the web applications.
To update these screenshots automatically, from /vagrant inside a
development VM you can run:
make update-user-guides
This will generate screenshots for each image in the web application and copy
them to the folder under docs/images/manual/screenshots where they will
replace the existing screenshots. Stage for commit any screenshots you wish to
update. If you wish to update all screenshots, simply stage for commit all
changed files in that directory.
Integration with Read the Docs¶
Note
SecureDrop maintains two branches of documentation, stable
and latest,
the former being the default used by our Read the Docs powered site.
stable is built from our latest signed git tag, while latest
is built from the head of the develop git branch. In almost all
cases involving development work, you’ll want to make sure you have
the latest version selected by clicking the appropriate link
above, or by using the menu in the bottom left corner.
Our documentation is built and hosted by Read the Docs and is available at https://docs.securedrop.org. We use a webhook so the docs are rebuilt automatically when commits get pushed to the branch.
Style Guide¶
When specific elements from a user interface are mentioned by name or by label, bold it.
“Once you’re sure you have the right drive, click Format Drive.”
When SecureDrop-specific terminology is used, italicize it.
“To get started, you’ll need two Tails drives: one for the Admin Workstation and one for the Secure Viewing Station.”
Try to keep your lines wrapped to near 80 characters when editing the docs. Some exceptions are warranted, such as complex code blocks showing example commands, or long URLs, but in general the docs should be tightly wrapped.
When referring to virtual machines in the development environment, use lowercase for the name:
app-staging VM
Ensure that example commands in codeblocks are easily copy/pasteable.
Do not prepend the $ shell prompt indicator to example commands:
echo hello
In the context of a terminal session, with both typed commands and printed
output text, then use $, but only on the typed command lines:
$ echo hello hello $ echo sunshine sunshine
Use absolute paths when referring to files outside the SecureDrop repository. Exceptions made for when it’s clear from the surrounding context what the intended working directory is. For files inside the SecureDrop directory, write them as ./some_dir/file, where . is the top level directory of the SecureDrop repo. Since by default the git repo will be cloned under the name securedrop and it also contains a securedrop subdirectory this is intended to avoid confusion. Exceptions made for when it’s clear from the context we’re outside of the SecureDrop repo, but would like to somehow interact with it (e.g., we just cloned the repo and now we’re going to cd into it).
Testing SecureDrop¶
The SecureDrop project ships both application code for running on servers hosted on-site at news organizations, as well as configuration scripts for provisioning the servers to accept updates to the application code, and to harden the system state. Therefore testing for the project includes Application Tests for validating that the app code behaves as expected, and Configuration Tests to ensure that the servers are appropriately locked down, and able to accept updates to the app code.
In addition, the Continuous Integration automatically runs the above Application and Configuration tests against cloud hosts, to aid in PR review.
Testing: Application Tests¶
The application test suite uses:
The application tests consist of unit tests for the Python application code and functional tests that verify the functionality of the application code from the perspective of the user through a web browser.
The functional tests use an outdated version of Firefox chosen specifically for compatibility with Selenium 2, and a rough approximation of the most recent Tor Browser.
Note
We’re working on running the Selenium tests in Tor Browser. See GitHub #1629 for more info.
Installation¶
The application tests are installed automatically in the development
and app-staging VMs, based on the contents of
securedrop/requirements/test-requirements.txt.
If you wish to change the dependencies, see Upgrading or Adding Python Dependencies.
Running the application tests¶
The tests can be run inside the development VM:
vagrant ssh development
cd /vagrant/securedrop
pytest -v tests
Or the app-staging VM:
vagrant ssh app-staging
sudo su www-data -s /bin/bash
cd /var/www/securedrop
pytest -v tests
For explanation of the difference between these machines, see Virtual Environments: Servers.
If you just want to run the functional tests, you can use:
pytest -v tests/functional/
Similarly, if you want to run a single test, you can specify it through the file, class, and test name:
pytest tests/test_journalist.py::TestJournalistApp::test_invalid_credentials
Some Selenium tests are decorated to produce before and after screenshots to aid
in debugging. This behavior is enabled with the SCREENSHOTS_ENABLED environment
variable. Output PNG files will be placed in the tests/log/ directory.
The gnupg library can be quite verbose in its
output. The default log level applied to this package is ERROR but this can
be controlled via the GNUPG_LOG_LEVEL environment variable. It can have values
such as INFO or DEBUG if some particular test case or test run needs
greater verbosity.
SCREENSHOTS_ENABLED=1 pytest tests/functional/
Page Layout Tests¶
You can check the rendering of the layout of each page in each translated language using the page layout tests. These will generate screenshots of each page and can be used for example to update the SecureDrop user guides when modifications are made to the UI.
You can run all tests, including the page layout tests with the –page-layout option:
pytest tests/ --page-layout
Updating the application tests¶
Unit tests are stored in the securedrop/tests/ directory and functional
tests are stored in the functional test directory:
securedrop/tests/
├── functional
│ ├── test_admin_interface.py
│ ├── test_submit_and_retrieve_file.py
│ │ ...
│ └── submission_not_in_memory.py
├── utils
│ ├── db_helper.py
│ ├── env.py
│ └── async.py
├── test_journalist.py
├── test_source.py
│ ...
└── test_store.py
securedrop/tests/utils contains helper functions for writing tests.
If you want to add a test, you should see if there is an existing file
appropriate for the kind of test, e.g. a new unit testing manage.py
should go in test_manage.py.
Testing: Configuration Tests¶
Testinfra tests verify the end state of the Vagrant machines. Any changes to the Ansible configuration should have a corresponding spectest.
Installation¶
pip install -r securedrop/requirements/develop-requirements.txt
Running the config tests¶
In order to run the tests, first create and provision the VM you intend to test. For the development VM:
vagrant up development
For the staging VMs:
make build-debs
vagrant up /staging/
Running all VMs concurrently may cause performance problems if you have less than 8GB of RAM. You can isolate specific machines for faster testing:
./testinfra/test.py development
./testinfra/test.py app-staging
./testinfra/test.py mon-staging
Note
The config tests for the app-prod and mon-prod hosts are
incomplete. Further changes are necessary to run the tests via
SSH over Authenticated Tor Hidden Service (ATHS), for both local
testing via Vagrant and automated testing via CI.
Test failure against any host will generate a report with informative output about the specific test that triggered the error. The wrapper script will also exit with a non-zero status code.
Updating the config tests¶
Changes to the Ansible config should result in failing config tests, but only if an existing task was modified. If you add a new task, make sure to add a corresponding spectest to validate that state after a new provisioning run. Tests import variables from separate YAML files than the Ansible playbooks:
testinfra/vars/
├── app-prod.yml
├── app-staging.yml
├── build.yml
├── development.yml
├── mon-prod.yml
└── mon-staging.yml
Any variable changes in the Ansible config should have a corresponding
entry in these vars files. These vars are dynamically loaded for each
host via the testinfra/conftest.py file. Make sure to add your tests to
relevant location for the host you plan to test:
testinfra/app/
├── apache
│ ├── test_apache_journalist_interface.py
│ ├── test_apache_service.py
│ ├── test_apache_source_interface.py
│ └── test_apache_system_config.py
├── test_apparmor.py
├── test_appenv.py
├── test_network.py
└── test_ossec.py
In the example above, to add a new test for the app-staging host,
add a new file to the testinfra/spec/app-staging directory.
Tip
Read Updating OSSEC Rules to learn how to write tests for the OSSEC rules.
Config test layout¶
The config tests are mostly broken up according to machines in the Vagrantfile:
testinfra/
├── app
├── app-code
├── build
├── common
├── development
└── mon
Ideally the config tests would be broken up according to roles, mirroring the Ansible configuration. Prior to the reorganization of the Ansible layout, the tests are rather tightly coupled to hosts. The layout of config tests is therefore subject to change.
Config testing strategy¶
The config tests currently emphasize testing implementation rather than functionality. This was a temporary measure to increase the testing baseline for validating the Ansible provisioning flow, which aided in migrating to a current version of Ansible (v2+). Now that the Ansible version is current, the config tests can be improved to validate behavior, such as confirming ports are blocked via external network calls, rather than simply checking that the iptables rules are formatted as expected.
Testing: CI¶
The SecureDrop project uses multiple automated third-party solutions for running automated test suites on code changes:
Travis tests¶
The Travis test suite provisions the development VM and runs the application test suite against the latest version of the code. It also performs basic linting and validation, e.g. checking for mistakes in the Sphinx documentation (see Documentation Guidelines).
CI test layout¶
The relevant files for configuring the CI tests are:
├── .circleci <--- folder contains config for CircleCI
├── devops
│ ├── inventory <-- environment specific inventory
│ ├── playbooks <-- playbooks to start CI boxes
│ ├── scripts <-- shell wrapper scripts
│ ├── templates <-- contains templates for ansible tasks
│ └── vars <-- environment specific variables
├── .travis.yml <--- config for development tests on travis
└── Makefile <-- defines make task shortcuts
The files under devops/ are used to create a minimized staging environment
on AWS EC2. The CircleCI host is used as the Ansible controller to provision
the machines and run the Testing: Configuration Tests against them.
Running the CI staging environment¶
The staging environment tests will run automatically in CircleCI,
when changes are submitted by Freedom of the Press Foundation staff
(i.e. members of the freedomofpress GitHub organization).
Tip
You will need an Amazon Web Services EC2 account to proceed. See the AWS Getting Started Guide for detailed instructions.
In addition to an EC2 account, you will need a working Docker installation in order to run the container that builds the deb packages.
You can verify that your Docker installation is working by running
docker run hello-world and confirming you see “Hello from Docker” in the
output as shown below:
$ docker run hello-world
Hello from Docker!
This message shows that your installation appears to be working correctly.
...
Setup environment parameters¶
Source the setup script using the following command:
source ./devops/scripts/local-setup.sh
You will be prompted for the values of the required environment variables. There are some defaults set that you may want to change. You will need to determine the value of your VPC ID to use which is outside the scope of this guide.
Use Makefile to provision hosts¶
Run make help to see the full list of CI commands in the Makefile:
$ make help
Makefile for developing and testing SecureDrop.
Subcommands:
docs: Build project documentation in live reload for editing.
docs-lint: Check documentation for common syntax errors.
ci-spinup: Creates AWS EC2 hosts for testing staging environment.
ci-teardown: Destroy AWS EC2 hosts for testing staging environment.
ci-run: Provisions AWS EC2 hosts for testing staging environment.
ci-test: Tests AWS EC2 hosts for testing staging environment.
ci-go: Creates, provisions, tests, and destroys AWS EC2 hosts
for testing staging environment.
ci-debug: Prevents automatic destruction of AWS EC2 hosts on error.
To run the tests locally:
make ci-debug # hosts will not be destroyed automatically
make ci-go
You can use make ci-run to provision the remote hosts while making changes,
including rebuilding the Debian packages used in the Staging environment.
See Virtual Environments: Servers for more information.
Note that if you typed make ci-debug above, you will have to manually remove
a blank file in ${HOME}/.FPF_CI_DEBUG and then run make ci-teardown to
bring down the CI environment. Otherwise, specifically for AWS, you will be
charged hourly charges until those machines are terminated.
SecureDrop apt repository¶
This document contains a brief description of the Debian packages which are hosted and maintained by Freedom of the Press Foundation in our apt repository at apt.freedom.press.
- linux-image-3.14.*-grsec
- This package contains the Linux kernel image, patched with grsecurity.
Listed as a dependency of
securedrop-grsec. - linux-headers-3.14.*-grsec
- Header files related to the Linux kernel.
- ossec-agent
- Installs the OSSEC agent, repackaged for Ubuntu.
Listed as a dependency of
securedrop-ossec-agent. - ossec-server
- Installs the OSSEC manager, repackaged for Ubuntu.
Listed as a dependency of
securedrop-ossec-server. - securedrop-app-code
- Packages the SecureDrop application code, Python pip dependencies and AppArmor profiles.
- securedrop-ossec-agent
- Installs the SecureDrop-specific OSSEC configuration for the Application Server.
- securedrop-ossec-server
- Installs the SecureDrop-specific OSSEC configuration for the Monitor Server.
- securedrop-grsec
- SecureDrop grsecurity kernel metapackage, depending on the latest version
of
linux-image-3.14-*-grsec. - securedrop-keyring
- Packages the public signing key used conjunction with this apt repository. Allows for managed key rotation via automatic updates, as implemented in SecureDrop 0.3.10.
Note
The SecureDrop install process configures a custom Linux kernel hardened with the grsecurity patch set. Only binary images are hosted in the apt repo. For source packages, see the Source Offer.
Updating OSSEC Rules¶
SecureDrop uses the OSSEC open source host-based intrusion detection system (IDS) for log analysis, file integrity checking, policy monitoring, rootkit detection and real-time alerting. Refer to our OSSEC guide to learn more about how SecureDrop admins set up and monitor OSSEC alerts.
Alerting Strategy¶
The goals of the OSSEC alerts in SecureDrop is to notify admins of:
- Suspicious security events
- Changes that require some kind of admin action
- Other important notifications regarding system state.
If an alert is purely informational and there is no realistic action an admin is expected to take, you should think carefully before suggesting a rule for it. Each additional alert that admins must read and/or respond to takes time. Alerts that are unimportant or otherwise require no action can lead to alert fatigue and thus to critical alerts being ignored.
Using ossec-logtest¶
Development on the OSSEC rules should be done from the staging environment.
On mon-staging, there is a utility installed as part of OSSEC called
ossec-logtest that you can use to test log events. In order to evaluate
whether an alert will be produced, and if so, what rule triggered it and its
level, you can simply pass the event to ossec-logtest:
root@mon-staging:/home/vagrant# sudo echo "Feb 10 23:34:40 app-prod kernel: [ 124.188641] grsec: denied RWX mmap of <anonymous mapping> by /usr/sbin/apache2[apache2:1328] uid/euid:33/33 gid/egid:33/33, parent /usr/sbin/apache2[apache2:1309] uid/euid:0/0 gid/egid:0/0" | /var/ossec/bin/ossec-logtest
2017/08/16 22:28:25 ossec-testrule: INFO: Reading local decoder file.
2017/08/16 22:28:25 ossec-testrule: INFO: Started (pid: 18973).
ossec-testrule: Type one log per line.
**Phase 1: Completed pre-decoding.
full event: 'Feb 10 23:34:40 app-prod kernel: [ 124.188641] grsec: denied RWX mmap of <anonymous mapping> by /usr/sbin/apache2[apache2:1328] uid/euid:33/33 gid/egid:33/33, parent /usr/sbin/apache2[apache2:1309] uid/euid:0/0 gid/egid:0/0'
hostname: 'app-prod'
program_name: 'kernel'
log: '[ 124.188641] grsec: denied RWX mmap of <anonymous mapping> by /usr/sbin/apache2[apache2:1328] uid/euid:33/33 gid/egid:33/33, parent /usr/sbin/apache2[apache2:1309] uid/euid:0/0 gid/egid:0/0'
**Phase 2: Completed decoding.
decoder: 'iptables'
**Phase 3: Completed filtering (rules).
Rule id: '100101'
Level: '7'
Description: 'grsec error was detected'
**Alert to be generated.
This is the utility we use in automated tests of OSSEC.
Writing Automated Tests for OSSEC Rules¶
We strongly recommend before making changes to OSSEC rules to attempt to write a failing test which you then can make pass with a patch to the OSSEC rules:
- Identify a log event you can use to trigger the alert.
Warning
Be sure to use only log events from test SecureDrop instances or those you have verified do not contain any sensitive data.
- Write a Testinfra test to verify that the log event does or does not trigger an alert.
- Apply your patch to the OSSEC rule on the relevant VM (likely
app). - Restart the service via
sudo service ossec restartonmon.
Deployment¶
The OSSEC rules and associated configuration files are distributed via Debian packages maintained by Freedom of the Press Foundation. Any changes made to OSSEC configuration files will land on production SecureDrop monitoring servers as part of each SecureDrop release. This upgrade will occur automatically.
Note
The use of automatic upgrades for release deployment means that any changes made locally by admins to their OSSEC rules will not persist after a SecureDrop update.
Generating AppArmor profiles for Tor and Apache¶
vagrant up /staging$/
vagrant ssh app-staging
sudo su
cd /var/www/securedrop
Run tests, use the application web interface, restart services,
reboot the VMs via vagrant reload /staging/. The goal is to
create as much interaction with the system as possible, in order
to establish an expected baseline of behavior. Then run:
aa-logprof
Follow the prompts on screen and save the new configuration. Then set the profile to complain mode:
aa-complain /etc/apparmor.d/<PROFILE_NAME>
Rinse and repeat, again running aa-logprof to update the profile.
The AppArmor profiles are saved in /etc/apparmor.d/. There are two
profiles:
/etc/apparmor.d/usr.sbin.tor/etc/apparmor.d/usr.sbin.apache2
After running aa-logprof you will need to copy the modified profile back to
your host machine to include them in the securedrop-app-code package.
ansible -i .vagrant/provisioners/ansible/inventory/vagrant_ansible_inventory app-prod -m fetch -a 'flat=yes dest=install_files/ansible-base/ src=/etc/apparmor.d/usr.sbin.apache2'
ansible -i .vagrant/provisioners/ansible/inventory/vagrant_ansible_inventory app-prod -m fetch -a 'flat=yes dest=install_files/ansible-base/ src=/etc/apparmor.d/usr.sbin.tor'
The AppArmor profiles are packaged with the securedrop-app-code.
The securedrop-app-code postinst puts the AppArmor profiles in enforce mode
on production and staging hosts.
Threat Model¶
This document outlines the threat model for SecureDrop 0.3 and is inspired by a document Adam Langley wrote for Pond. The threat model is defined in terms of what each possible adversary can achieve. This document is still a work in progress. If you have questions or comments, please open an issue on GitHub or send an email to securedrop@freedom.press.
Assumptions¶
Assumptions about the source¶
- The source acts reasonably and in good faith, e.g. if the user were to give their codename or private key material to the attacker that would be unreasonable.
- The source would like to remain anonymous, even against a forensic attacker.
- The source obtains an authentic copy of Tails or the Tor Browser.
- The source follows our guidelines for using SecureDrop.
- The source is accessing an authentic SecureDrop site.
Assumptions about the admin and the journalist¶
- The admin and the journalist act reasonably and in good faith, e.g. if either of them were to give their credentials or private key material to the attacker that would be unreasonable.
- The admin and the journalist obtain authentic copies of Tails.
- The journalist follows our guidelines for using SecureDrop and working with submitted documents.
Assumptions about the person installing SecureDrop, usually the admin¶
- The person acts reasonably and in good faith, e.g. if they were to give the attacker system-level access that would be unreasonable.
- The person obtains an authentic copy of SecureDrop and its dependencies.
- The person follows our guidelines for deploying the system, setting up the landing page for the organization, and for installing SecureDrop.
Assumptions about the source’s computer¶
- The computer correctly executes Tails or the Tor Browser.
- The computer is not compromised by malware.
Assumptions about the Admin Workstation and the Journalist Workstation¶
- The computer correctly executes Tails.
- The computer and the Tails device are not compromised by malware.
- The two-factor authentication device used with the workstation are not compromised by malware.
Assumptions about the Secure Viewing Station¶
- The computer is airgapped.
- The computer correctly executes Tails.
- The computer and the Tails device are not compromised by malware.
Assumptions about the SecureDrop hardware¶
- The servers correctly execute Ubuntu, SecureDrop and its dependencies.
- The servers, network firewall, and physical media are not compromised by malware.
Assumptions about the organization hosting SecureDrop¶
- The organization wants to preserve the anonymity of its sources.
- The organization acts in the interest of allowing sources to submit documents, regardless of the contents of these documents.
- The users of the system, and those with physical access to the servers, can be trusted to uphold the previous assumptions unless the entire organization has been compromised.
- The organization is prepared to push back on any and all requests to compromise the integrity of the system and its users, including requests to deanonymize sources, block document submissions, or hand over encrypted or decrypted submissions.
Assumptions about the world¶
- The security assumptions of RSA (4096-bit GPG and SSH keys) are valid.
- The security assumptions of scrypt with randomly-generated salts are valid.
- The security/anonymity assumptions of Tor and the Hidden Service protocol are valid.
- The security assumptions of the Tails operating system are valid.
Attack Scenarios¶
What the Application Server can achieve¶
- The server sees the plaintext codename, used as the login identifier, of every source.
- The server sees all HTTP requests made by the source, the admin, and the journalist.
- The server sees the plaintext submissions of every source.
- The server sees the plaintext communication between journalists and their sources.
- The server stores hashes of codenames, created with scrypt and randomly-generated salts.
- The server stores only encrypted submissions and communication on disk.
- The server stores a GPG key for each source, with the source’s codename as the passphrase.
- The server may store plaintext submissions in memory for at most 24 hours.
- The server stores sanitized Tor logs, created using the SafeLogging option, for the Source Interface, the Journalist Interface, and SSH.
- The server stores both access and error logs for the Journalist Interface.
- The server stores connection history and audit logs for the admin.
- The server can connect to the Monitor Server using an SSH key and a passphrase.
What the Monitor Server can achieve¶
- The server stores the plaintext alerts on disk, data may also reside in RAM.
- The server stores the GPG public key the OSSEC alerts are encrypted to.
- The server stores plaintext credentials for the SMTP relay used to send OSSEC alerts.
- The server stores the email address the encrypted OSSEC alerts are sent to.
- The server stores sanitized Tor logs, created using the SafeLogging option, for SSH.
- The server stores connection history and audit logs for the admin.
- The server stores OSSEC and Procmail logs on disk.
- The server can connect to the Application Server using an SSH key and a passphrase.
What the Workstations can achieve¶
- The Admin Workstation requires Tails with a persistent volume, which stores information such as GPG and SSH keys, as well as a database with passphrases for the Application Server, the Monitor Server, and the GPG key the Monitor Server will encrypt OSSEC alerts to.
- The Journalist Workstation requires Tails with a persistent volume, which stores information such as the Hidden Service value required to connect to the Journalist Interface, as well as a database with passphrases for the Journalist Interface and the journalist’s personal GPG key.
- The Secure Viewing Station requires Tails with a persistent volume, which stores information such as the SecureDrop application’s GPG key, as well as a database with the passphrase for that key.
What a compromise of the source’s property can achieve¶
- Use of the Tor Browser will leave traces that can be discovered through a forensic analysis of the source’s property following either a compromise or physical seizure. Unless the compromise or seizure happens while the source is submitting documents to SecureDrop, the traces will not include information about sites visited or actions performed in the browser.
- Use of Tails with a persistent volume will leave traces on the device the operating system was installed on. Unless the compromise or seizure happens while the source is submitting documents to SecureDrop, or using the persistent volume, the traces will not include information about sites visited or actions performed in the browser or on the system.
- SecureDrop 0.3 encourages sources to protect their codenames by memorizing them. If a source cannot memorize the codename right away, we recommend writing it down and keeping it in a safe place at first, and gradually working to memorize it over time. Once the source has memorized it, they should destroy the written copy. If the source does write down the codename, a compromise or physical seizure of the source’s property may result in the attacker obtaining the source’s codename.
- An attacker with access to the source’s codename can:
- Show that the source has visited the SecureDrop site, but not necessarily submitted anything.
- Upload new documents or submit messages.
- Communicate with the journalist as that source.
- See any replies from journalists that the source has not yet deleted.
What a physical seizure of the source’s property can achieve¶
- Document use of Tor or Tails, but not necessarily research into SecureDrop
- Prevent the source from submitting documents by taking the device the documents are stored on.
- If the property is seized while powered on, the attacker can also analyze any plaintext information that resides in RAM.
- Tamper with the hardware.
- A physical seizure of, and access to, the source’s codename will allow the attacker to access the Source Interface as that source.
- A physical seizure of the admin’s property will allow the attacker
to:
- Prevent the admin from working on SecureDrop for some period of time.
- Access any stored, decrypted documents taken off the Secure Viewing Station.
- If the property is seized while powered on, the attacker can also analyze any plaintext information that resides in RAM.
- A physical seizure of, and access to, the admin’s Tails persistent volume, password database, and two-factor authentication device will allow the attacker to access both servers and the Journalist Interface.
What a compromise of the admin’s property can achieve¶
- To access the Journalist Interface, the Application Server, or the Monitor Server, the attacker needs to obtain the admin’s login credentials and the admin’s two-factor authentication device. Unless the attacker has physical access to the servers, the attacker will also need to obtain the Hidden Service values for the Interface and the servers. This information is stored in a password-protected database in a persistent volume on the admin’s Tails device. The volume is protected by a passphrase. If the admin’s two-factor authentication device is a mobile phone, this will also be protected by a passphrase.
- An attacker with access to the admin’s computer can:
- Access any stored, decrypted documents taken off the Secure Viewing Station.
- An attacker with access to the persistent volume on the admin’s
Tails device can:
- Add, modify, and delete files on the volume.
- Access the Hidden Service values used by the Interfaces and the servers.
- Access SSH keys and passphrases for the Application Server and the Monitor Server.
- Access the GPG key and passphrase for the encrypted OSSEC email alerts.
- Access the credentials for the account the encrypt alerts are sent to.
- Access the admin’s personal GPG key.
- An attacker with admin access to the Journalist Interface can:
- Add, modify, and delete journalist users.
- Change the codenames associated with sources within the Interface.
- Download, but not decrypt, submissions.
- Communicate with sources.
- Delete one or more submissions.
- Delete one or more sources, which destroys all communication with that source and prevents the source from ever logging back in with that codename.
- An attacker with admin access to the Application Server can:
- Add, modify, and delete software, configurations, and other files.
- See all HTTP requests made by the source, the admin, and the journalist.
- See the plaintext codename of a source as they are logging in.
- See the plaintext communication between a source and a journalist as it happens.
- See the stored list of hashed codenames.
- Access the GPG public key used to encrypt communications between a journalist and a source.
- Download stored, encrypted submissions and replies from the journalists.
- Decrypt replies from the journalists if the source’s codename, and thus the passphrase, is known.
- Analyze any plaintext information that resides in RAM, which may include plaintext of submissions made within the past 24 hours.
- Review logs stored on the system.
- Access the Monitor Server.
- An attacker with admin access to the Monitor Server can:
- Add, modify, and delete software, configurations, and other files.
- Change the SMTP relay, email address, and GPG key used for OSSEC alerts.
- Analyze any plaintext information that resides in RAM.
- Review logs stored on the system.
- Trigger arbitrary commands to be executed by the OSSEC agent user, which, assuming the attacker is able to escalate privileges, may affect the Application Server.
What a physical seizure of the admin’s property can achieve¶
- Tamper with the hardware.
- Prevent the admin from working on SecureDrop for some period of time.
- Access any stored, decrypted documents taken off the Secure Viewing Station.
- If the property is seized while powered on, the attacker can also analyze any plaintext information that resides in RAM.
- A physical seizure of, and access to, the admin’s Tails persistent volume, password database, and two-factor authentication device will allow the attacker to access both servers and the Journalist Interface.
What a compromise of the journalist’s property can achieve¶
- To access the Journalist Interface, the attacker needs to obtain the journalist’s login credentials and the journalist’s two-factor authentication device. Unless the attacker has physical access to the server, the attacker will also need to obtain the Hidden Service value for the Interface. This information is stored in a password-protected database in a persistent volume on the journalist’s Tails device. The volume is protected by a passphrase. If the journalist’s two-factor authentication device is a mobile phone, this will also be protected by a passphrase.
- An attacker with access to the journalist’s computer can:
- Access any stored, decrypted documents taken off the Secure Viewing Station.
- An attacker with access to the persistent volume on the
journalist’s Tails device can:
- Add, modify, and delete files on the volume.
- Access the Hidden Service values used by the Journalist Interface.
- Access SSH keys and passphrases for the Application Server and the Monitor Server.
- Access the journalist’s personal GPG key.
- An attacker with journalist access to the Journalist Interface can:
- Change the codenames associated with sources within the Interface.
- Download, but not decrypt, submissions.
- Delete one or more submissions.
- Communicate with sources.
What a physical seizure of the journalist’s property can achieve¶
- Tamper with the hardware.
- Prevent the journalist from working on SecureDrop for some period of time.
- Access any stored, decrypted documents taken off the Secure Viewing Station.
- If the property is seized while powered on, the attacker can also analyze any plaintext information that resides in RAM.
- A physical seizure of, and access to, the journalist’s Tails persistent volume, password database, and two-factor authentication device will allow the attacker to access the Journalist Interface.
What a compromise of the Application Server can achieve¶
- If the Application Server is compromised, the system user the attacker has control over defines what kind of information the attacker will be able to view and what kind of actions the attacker can perform.
- An attacker with access to the debian-tor user can:
- View, modify, and delete all files owned by this user. This includes sanitized Tor logs, created using the SafeLogging option, for SSH, the Source Interface and the Journalist Interface.
- View, modify, and delete the Tor configuration file, root is required to reload the config.
- An attacker with access to the ossec user can:
- Add, view, modify, and delete the log files, and in doing so send inaccurate information to the Monitor Server and the admin.
- An attacker with access to the www-data user can:
- View, modify, and delete all files owned by this user. This includes all files in use by the SecureDrop application, such as text, code, the database containing encrypted submissions and communications. The attacker needs root access to reload configuration files.
- View, modify, and delete both access and error logs for the Journalist Interface.
- View any HTTP requests made by the source, the admin, and the journalist in that moment. This includes seeing plaintext codenames, submissions, and communications.
- Add and delete communications between a journalist and a source by writing to the database.
- An attacker with access to the root user can:
- Do anything the www-data user can do in terms of the SecureDrop application, this user is in full control of the server and can view, modify, and delete anything at will. This user is not able to decrypt submissions or communications, unless the attacker has access to the encryption key required to do so.
What a physical seizure of the Application Server can achieve¶
- If the Application Server is seized, the attacker will be able to view any and all unencrypted files on the server. This includes all files in use by the SecureDrop Application. If the server is seized while it is powered on, the attacker can also analyze any plaintext information that resides in RAM. The attacker can also tamper with the hardware.
What a compromise of the Monitor Server can achieve¶
- If the Monitor Server is compromised, the system user the attacker has control over defines what kind of information the attacker will be able to view and what kind of actions the attacker can perform.
- An attacker with access to the debian-tor user can:
- View, modify, and delete all files owned by this user. This includes sanitized Tor logs, created using the SafeLogging option, for SSH.
- View, modify, and delete the Tor configuration file, root is required to reload the config.
- An attacker with access to the ossec user can:
- ???
- An attacker with access to the root user can:
- Do anything the ossec user can do in terms of the SecureDrop application, this user is in full control of the server and can view, modify, and delete anything at will. This user is not able to decrypt encrypted email alerts, unless the attacker has access to the encryption key required to do so.
What a physical seizure of the Monitor Server can achieve¶
- If the Monitor Server is seized, the attacker will be able to view any and all unencrypted files on the server. This includes all files in use by OSSEC. If the server is seized while it is powered on, the attacker can also analyze any plaintext information that resides in RAM. The attacker can also tamper with the hardware.
What a compromise of the Secure Viewing Station can achieve¶
- The Secure Viewing Station is only useful to an attacker while powered on and with the Tails persistent volume mounted. The attacker may learn more if the Transfer device is in use at the time of compromise or seizure. A physical seizure of this machine, the Tails device or the Transfer device will also achieve nothing, assuming that Tails’ implementation of full-disk encryption works as expected.
- A compromise of the Secure Viewing Station allows the attacker to:
- Run commands as the amnesia user.
- View, modify, and delete files owned by the amnesia user. This includes the GPG private key used to encrypt and decrypt submitted documents.
- View, modify, and delete encrypted–and possibly also decrypted submissions–if the Transfer device is in use.
What a physical seizure of the Secure Viewing Station can achieve¶
- The Secure Viewing Station is only useful to an attacker while powered on and with the Tails persistent volume mounted. The attacker may learn more if the Transfer device is in use at the time of compromise or seizure. A physical seizure of this machine, the Tails device or the Transfer device will also achieve nothing, assuming that Tails’ implementation of full-disk encryption works as expected.
- A physical seizure of the Secure Viewing Station, while on and with
the persistent volume decrypted and mounted, allows the attacker to:
- Tamper with the hardware.
- Run commands as the amnesia user.
- View, modify, and delete the GPG private key used to encrypt and decrypt submitted documents.
- View, modify, and delete encrypted–and possibly also decrypted submissions–if the Transfer device is in use.
What a local network attacker can achieve against the source, admin, or journalist:¶
- A local network can observe when they are using Tor.
- A local network can block Tor and prevent them from accessing SecureDrop.
- A local network may be able to deduce use of SecureDrop by looking at request sizes, plaintext uploads and encrypted downloads, although research suggests this is very difficult.
What a global adversary can achieve against the source, admin, or journalist:¶
- A global adversary capable of observing all Internet traffic may have more luck than the local network attacker in deducing use of SecureDrop by looking at request sizes, plaintext uploads and encrypted downloads.
- A global adversary may be able to link a source to a specific SecureDrop server.
- A global adversary may be able to link a source to a specific journalist.
- A global adversary may be able to correlate data points during a leak investigation, including looking at who has read up on SecureDrop and who has used Tor.
- A global adversary may be able to forge an SSL certificate and use it to spoof an organization’s HTTPS landing page, thereby tricking the source into visiting a fake SecureDrop site.
What a random person on the Internet can achieve¶
- A random person can attempt to DoS the SecureDrop server and overwhelm the journalists by generating a high number of codenames and uploading many large documents.
- A random person can submit empty, forged, or inaccurate documents.
- A random person can submit malicious documents, e.g. malware that will attempt to compromise the Secure Viewing Station.
- A random person can attempt to get sensitive information from a SecureDrop user’s browser session, such as the source’s codename.
- A random person can attempt to compromise the SecureDrop server by attacking the exposed attack surface, including the kernel network stack, Tor, Apache, the SecureDrop web interfaces, Python, OpenSSH, and the TLS implementation.
Data Flow Diagram¶
The following diagram captures all data flows to and from a SecureDrop deployment.
