A
security.txt
file is an industry standard used by organizations to provide a clear point of contact for vulnerability reporting. This blog will walk you through implementing a signedsecurity.txt
file using PGP (Pretty Good Privacy).
Introduction
The security.txt
file, typically hosted at /.well-known/security.txt
, provides a standardized way for security researchers to find the correct point of contact for reporting vulnerabilities. It helps ensure that security issues are directed to the right people quickly and efficiently. While it’s recommended to optionally sign the file with a PGP key for added authenticity, the primary goal is to clearly list how to reach your security team or responsible contact. Below, we’ll cover how to create a straightforward, effective security.txt
file for your site.
Step 1: Generate a PGP Key Pair
If you don’t already have a PGP key pair, you’ll need to generate one. A PGP key pair consists of a public key, which you can share publicly, and a private key, which is kept secret.
1. Install GPG (GNU Privacy Guard)
GPG is the most common tool for generating and managing PGP keys. Install it using your package manager:
- Linux:
sudo apt-get install gnupg
- MacOS (via Homebrew):
brew install gnupg
- Windows: Download GPG4Win from https://gpg4win.org.
2. Generate the Key Pair
Run the following command:
gpg --full-generate-key
- Choose RSA and RSA for encryption.
- Select the desired key size (e.g., 4096 bits for stronger security).
- Set an expiration date (it is not recommended to select no expiration for permanent use).
- Enter your name and email address when prompted.
- Set a strong passphrase to secure the private key.
Once complete, your keys will be stored in the GPG keyring. You can view your generated key pair, including the corresponding Fingerprint
, by running the following commands to list the public and private keys:
- Public key:
gpg --list-keys --keyid-format LONG
- Private key:
gpg --list-secret-keys --keyid-format LONG
3. Export your Public Key
Others will need your public key to verify your signature:
gpg --armor --export your_email@example.com > pgp-publickey.txt
This will export the public key to a file named pgp-publickey.txt
.
Step 2: Create and sign the security.txt file
-
Create the security.txt file: Create a plain text file named
security.txt
with the following content (customize as needed):# Security address Contact: mailto:security@example.com # OpenPGP key Encryption: https://example.com/.well-known/pgp-publickey.txt # Expiration of security.txt file Expires: expiration date of your pgp key pair # Privacy Policy Policy: https://example.com/security-policy.html # Languages Preferred-Languages: EN, NL
-
Sign the file with your Private Key: Use the following command to create a cleartext signature (replace the
Fingerprint
with the actual fingerprint):gpg --clearsign --local-user Fingerprint security.txt
After you enter the passphrase to unlock the OpenPGP Private Key, a signature file
security.txt.asc
is created. Copy the contents ofsecurity.txt.asc
into the originalsecurity.txt
file. -
Host the files: In the
/.well-known/
folder on your webserver, upload thesecurity.txt
andpgp-publickey.txt
files:https://example.com/.well-known/security.txt https://example.com/.well-known/pgp-publickey.txt
Step 3: Confirm authenticity and secure communication
To confirm the authenticity of the security.txt
file, anyone can verify it using your public key.
1. Import the Public Key
A user downloads your public key and imports it into their GPG keyring:
gpg --import pgp-publickey.txt
To trust a public key using GPG, the user can follow these steps:
- Open a terminal and run:
gpg --edit-key Fingerprint
(replace theFingerprint
with the actual fingerprint) - At the gpg> prompt, type:
trust
- When prompted to choose a trust level, enter:
5
(which stands for “I trust ultimately”), then press Enter. - To exit the editor: On Windows, press Ctrl + C, On Mac, press Command + C (or type
quit
and confirm if prompted)
2. Verify the Signature
The user runs the following command to verify the signature (replace the Fingerprint
with the actual fingerprint):
gpg --verify --local-user Fingerprint security.txt
If the file is authentic, they’ll see output confirming the signature, such as:
gpg: Signature made Fri 23 Nov 2024 10:30:00 AM UTC
gpg: using RSA key ABC123DEF4567890
gpg: Good signature from "Your Name <your_email@example.com>"
3. Secure communication
For secure communication, users can use your public key to send an encrypted message to the email address listed in your security.txt
file, which is cryptographically bound to your public key. This will look something like:
-----BEGIN PGP MESSAGE-----
...
-----END PGP MESSAGE-----
To decrypt this message using your private key:
- Save the encrypted message:
nano message.asc
(paste the entire PGP message and save the file, Ctrl+O, Enter, Ctrl+X) - Decrypt the message with your private key:
gpg --decrypt --local-user Fingerprint message.asc
(replace theFingerprint
with the actual fingerprint) - You should see output like this:
gpg: encrypted with 2048-bit RSA key, ID ABCD1234...
gpg: decryption successful
This is the decrypted message content.
Conclusion
Adding a signed security.txt
file to your webserver is a simple yet powerful way to build trust with security researchers and users. It ensures that the contact information provided is legitimate and hasn’t been tampered with. By following these steps, you create a clear and verifiable point of contact for handling vulnerabilities responsibly.