Security Design - Wormhole (2024)

Every design decision in Wormhole begins with the safety and privacy of yourdata in mind. We can't read your files, and no one else can either. Privacyisn’t an optional mode — it’s just the way that Wormhole works.

Your files are end-to-end encrypted.

Your Wormhole files are end-to-end encrypted, and only you hold the keys to decrypt them. We can’t see your Wormhole files, so we can’t use them, share them, or sell them.

No ads. No trackers. No kidding.

There are no ads and no creepy tracking in Wormhole. So focus on sharing the files that matter with the people who matter to you.

We use state-of-the-art security.

Your Wormhole files are end-to-end encrypted to keep them safe at rest and in transit. Our security starts with AES 128-bit encryption, and we use multiple techniques to make sure only you have access to your information. We're continuously working to make sure our code is rock solid.

Wormhole uses state-of-the-art security and end-to-end encryption to protect your files. Your files are always end-to-end encrypted, so they can never be shared or viewed by anyone but you and the intended recipients.

Wormhole encrypts all files with 128-bit AES-GCM encryption before they leave the browser.

Key management

The secret key used for end-to-end encryption is never shared with our servers. It is sent directly to your intended recipient when you send them the "share link". The secret key is added to the URI fragment which is never sent to the server.

When an agent (such as a web browser) requests a web resource from a web server, the agent sends the URI to the server, but does not send the fragment.

The link format looks like this:

https://wormhole.app/<room-id>#<key>

Here's an example link:

https://wormhole.app/nb7dMz#fnQhVRrakH6ZUgQyUeAFfA

Streaming Encryption and Decryption

For streaming encryption and decryption, we use Encrypted Content-Encoding for HTTP.

This standard provides authenticated encryption to ensure that your files can't be seen or modified by an attacker once they leave your browser.

Web Crypto API

We use the browser's built in cryptography primitives via the Web Crypto API to encrypt files in the browser before they are sent to the recipient.

File transport

End-to-end encrypted files may be:

1. Sent directly to the recipient via a peer-to-peer WebRTC connection
2. Uploaded to our servers (assuming they are within the file size limit)

A fully peer-to-peer transfer is preferred, since it improves speed and privacy. The server copy helps to ensure files continue to be available even after the sender closes their browser. All files are end-to-end encrypted before they are uploaded or sent peer-to-peer.

Encryption at rest

In addition to Wormhole's end-to-end encryption, your files are protected by an additional layer of encryption on our servers.

Transport Layer Security (TLS)

TLS (formerly known as SSL) is the industry-standard encryption protocol used to encrypt communications between your browser and our servers. It ensures that the Wormhole webpage code is not modified by attackers, and provides an additional layer of protection on top of the client-side end-to-end encryption to ensure data uploads and downloads are private.

We support TLS 1.3 for modern devices and TLS 1.2 for all remaining devices. Deprecated versions of TLS and SSL are not used.

Qualys SSL Labs rates our TLS implementation an A+. See report.

Supply Chain Security

Wormhole depends on Socket to detect and block malicious dependencies from our open source software supply chain. Socket is a security tool built by the Wormhole team to solve one of the hardest problems in security.

The standard approach in industry is to scan for known vulnerabilities (CVEs). But this doesn't proactively catch malware or backdoors in dependencies. It can take months for a CVE to be discovered and reported. In fact, a recent paper found that malware is available on package managers for over 200 days before it's caught. We needed something that could detect and block a bad package before it's been discovered by the open source community, and definitely before it makes it into our codebase.

In order to protect Wormhole users, we audit every open source package we use to detect and block dozens of package issues. Most supply chain attacks follow a similar pattern (stealing environment variables, sending data to the network, etc.) so we built a tool that could catch all of the recent NPM supply chain attacks. The tool analyzes the actual behavior of the package instead of relying on stale data in a CVE database.

On March 1, 2022 we announced the public launch of Socket to help defend the open source ecosystem. Socket provides the most comprehensive open source risk analysis on the market, and we're releasing it for free for the open source community.

Certificate Transparency Logs

We monitor the Certificate Transparency logs for certificate misissuance.

DNS Certification Authority Authorization (CAA) Policy

A Certification Authority Authorization (CAA) policy allows a DNS domain name holder to specify the Certification Authorities (CAs) authorized to issue certificates for that domain.

By publishing a CAA record, we reduce the risk of unintended or malicious certificate misissuance.

Domain Name System Security Extensions (DNSSEC)

DNSSEC is a set of extensions to DNS which provide to DNS clients (resolvers) cryptographic authentication of DNS data, authenticated denial of existence, and data integrity.

We deploy DNSSEC to protect DNS records for wormhole.app.

Datagram Transport Layer Security (DTLS)

DTLS is the standard encrypton protocol used to encrypt WebRTC peer-to-peer communications between browsers. It provides an additional layer of protection on top of our own encryption to keep peer-to-peer transfers on Wormhole private.

Web security

Wormhole is configured with state-of-the-art security options to lock down the site as much as possible.

Mozilla Observatory rates our site configuration an A+.

Here are a few of the security features we deploy.

Strict-Transport-Security

Wormhole uses this header to ensure that your browser always communicates with our servers using the TLS protocol.

We additionally include wormhole.app in all major browser's HTTP Strict Transport Security (HSTS) preload lists. In the case of .app domains, the entire TLD is automatically included in the HSTS preload list.

Cross-Origin-Resource-Policy

Wormhole uses this header to prevent other origins from accessing data on wormhole.app. This is a mitigation for side-channel hardware vulnerabilities such as Meltdown and Spectre.

Cross-Origin-Embedder-Policy

Wormhole uses this header to enable cross-origin isolation. Cross-origin isolation ensures that supported browsers always load Wormhole in a separate renderer process, which protects against side-channel hardware vulnerabilities such as Meltdown and Spectre.

Permissions-Policy

Wormhole uses this header to disable some web browser features that we don't need, like camera and microphone access.

Content-Security-Policy

Wormhole uses Content Security Policy to prevent the site from being tricked into accessing resources (such as scripts, webpages, etc.) that could be used in Cross Site Sripting attacks.

We have a very strict policy that blocks execution of inline JavaScript, JavaScript's eval() function, browser plug-ins, active and passive HTTP content, clickjacking attacks, <base> tag attacks, <form> submissions to exfiltrate data, and more.

Step-by-step

Here's a high-level design document for Wormhole.

From the uploader's perspective

1. The client generates a main secret key and a salt using the Web Crypto API

2. The client uses the main secret key and salt to derive more keys via HKDF SHA-256

   • File keys: An encryption key and one salt for each files, via RFC 8188 (AES-GCM)
   • Metadata key: An encryption key for the file metadata (AES-GCM)
   • Reader authorization token: A token for authenticating download requests (HMAC SHA-256)

3. The client asks the server to create a "room"

   • The server generates a roomId and a "writer authorization token" (which will authenticate all modifications to this room)
   • The server responds to the client with the roomId and the "writer authorization token"

4. The client displays the "Share URL" as: https://wormhole.app/{roomId}#{mainSecretKey}, where mainSecretKey is base64url encoded.

   • Note: the secret key is stored in the URL fragment so it will never be sent to the server.

5. The client encrypts each file separately using the derived file key and the per-file salt.

6. The client creates a .torrent file using the encrypted files as the contents

7. The client encrypts the .torrent file using the derived metadata key and a random IV

8. The client uploads the salt, the encrypted files, the encrypted .torrent file, the reader authorization token, and the torrent info hash to the server

   • This request is authenticated by the server using the "writer authorization token"

9. The client asks the server for a Backblaze upload URL

   • This request is authenticated by the server using the "writer authorization token"
   • The server responds to the client with an authenticated upload URL for uploading files to Backblaze

10. The client uploads the encrypted files to Backblaze where they are stored at rest with an additional layer of at-rest encryption

From the downloader's perspective

1. The client reads the roomId and the main secret key from the URL, which follows the pattern https://wormhole.app/{roomId}#{mainSecretKey}

   • Note: the secret key is stored in the URL fragment so it will never be sent to the server.

2. The client asks server for the salt that corresponds to roomId.

   • This request is not authenticated by the server
   • The server responds to the client with the salt

3. The client uses the main secret key and salt to derive the following keys (the same ones that the uploader derived):

   • File keys: An encryption key and one salt for each files, via RFC 8188 (AES-GCM)
   • Metadata key: An encryption key for the file metadata (AES-GCM)
   • Reader authorization token: A token for authenticating download requests (HMAC SHA-256)

4. The client asks the server for the encrypted .torrent file

   • This request is authenticated by the server using the "reader authorization token"
   • The server responds with the encrypted .torrent file

5. The client decrypts the .torrent file using the derived metadata key and the IV (which is embedded in the ciphertext)

6. The client asks the server for a Backblaze download URL for roomId

   • This request is authenticated by the server using the "reader authorization token"
   • The server responds with an authenticated download URL to fetch files from Backblaze

7. The client asks server for WebRTC offers (to connect to WebTorrent peers) for the given torrent info hash

   • The server checks that torrent info hash corresponds to a valid room and if so, responds with WebRTC offers for peers in the given room

8. The client downloads files from Backblaze and WebRTC peers simultaneously, coordinated by WebTorrent library

9. WebTorrent hashes all received torrent pieces and compares them to the expected hashes, which are present in the .torrent file

   • File data which fails piece verification is discarded

10. Data which has been validated by WebTorrent is decrypted using the derived file key and per-file salts (which are embedded in the ciphertext)

    • This decryption process uses authenticated encryption (RFC 8188) so it will also fail if data is tampered with.

Source code

• wormhole-crypto - Streaming encryption implementation, based on Encrypted Content-Encoding for HTTP (RFC 8188)

How can I report a security vulnerability?

If you've found a security vulnerability in Wormhole, please report it using our Responsible Disclosure Process.