Making and verifying a cleartext digital signature using a PGP key pair in Linux

Monday, August 12, 2024 at 5:28 PM | 3 min read

Last modified on Monday, July 20, 2026 at 1:34 PM

#asymmetric encryption, #cleartext signature, #gpg, #linux, #pgp, #pgp key pair, #security, #series, #verification

Photo by cottonbro studio on pexels.com

• What is the gpg --clear-sign option?
• Creating a cleartext digital signature with the --clear-sign option
• Verifying the cleartext signature
• Detached signatures vs cleartext signatures
• Conclusion
• Related Resources
• Related Posts
• Footnotes

The --clear-sign or --clearsign option creates a cleartext digital signature and is readable without any special software. OpenPGP software is only needed to verify the signature. cleartext signatures may modify end-of-line whitespace for platform independence and are not intended to be reversible. The signing key is chosen by default or can be set explicitly using the --local-user and --default-key options.

To create a cleartext signature, I run the following command in Terminal:

# first I create a .txt file called clear_text.txt to use when creating my --clear-sign signature
echo This is a text file for testing out a cleartext signature. > clear_text.txt
# next I create a --clear-sign signature on the clear_text.txt file
gpg --clear-sign clear_text.txt
# the command creates the following:
clear_text.txt.asc

gpg still prompts me for the passphrase for the PGP key pair I am using.

When I run vim clear_text.txt.asc, it contains the following:

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA512

This is a text file for testing out a cleartext signature.
-----BEGIN PGP SIGNATURE-----

iQGzBAEBCgAdFiEEMDJikESyFz19ih9IyW2LTU5YAXkFAma6B7QACgkQyW2LTU5Y
AXnMZgv+Oi0W0hcji79O+fB3TgNkIDAInKdQxQMD42sgRF09gR+vVRuBhN6Eu0gu
6HAjUh0gYng1tmMUhcf8caz4AcbqzE3/PxDiv9wn9g+AGySgUz4RFxsQByGY89b6
SWXZLqwWXno5F6Y2fe5KYo17dSqi/MJ1HCsySUS8fW9iozSubxK5YHtj2n6ANPg3
xM79JJldbNXnkMjjKMbhuq5eirYiBwof+IhTtF2tbeU488fEo7TNZ8XXovlNWLy/
FFscmu7UzWUJMiJ1E6mAx5nc2foFaV8/pzlTI3wQTwTyp4MKwwmgdjcFYrzyI3Js
9nnSPMrVXEvQH+scSSV0mH4Qn1s+naywjx8OLRoFlxEKAUbTd7CCMEP91Lymjkek
p3HmgCY/hu3aGwGf/VPZacmljUKS5jwlHHwRXOt1ku20Hp4VVJJv4ECMdghCLfbQ
nThGPWz9/SFpuYgraJWf3n4b8oPomGP8KI7MMcCH/z+B5ebYeTCF4PTfjmI6dnOV
3eveJuAg
=ljzv
-----END PGP SIGNATURE-----

gpg doesn't encrypt the text content itself, and gpg is not needed to decrypt the file text. The signature is added as readable text (a base64 ascii-armor signature). That is why the .asc extension.

To verify a cleartext signature, I (or a real-world recipient of the file) run the following in Terminal:

gpg --verify clear_text.txt.asc

And the following is stdout in Terminal:

gpg: Signature made Mon 12 Aug 2024 09:52:43 AM EDT
gpg:                using RSA key xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
gpg: Good signature from "Maria (GPG key pair for local testing with correct email) <maria@maria-VirtualBox>" [ultimate]
gpg: WARNING: not a detached signature; file 'clear_text.txt' was NOT verified!

The recipient of the clear_text.txt.asc file verifying it gets the warning not a detached signature; file 'clear_text.txt' was NOT verified! because I verified clear_text.txt.asc which resulted from the creation of the cleartext signature, but the original clear_text.txt file itself was not recognized as being verified.

To rectify this, I could make the clear_text.txt a detached signature instead:

gpg -b clear_text.txt

And gpg generates the ensuing:

clear_text.txt.sig

And then I run the following command to verify the detached signature:

gpg --verify clear_text.txt.sig

Which yields:

gpg: assuming signed data in 'clear_text.txt'
gpg: Signature made Mon 12 Aug 2024 12:03:26 PM EDT
gpg:                using RSA key xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
gpg: Good signature from "Maria (GPG key pair for local testing with correct email) <maria@maria-VirtualBox>" [ultimate]

But if I delete the original clear_text.txt file, and run gpg --verify clear_text.txt.sig again, gpg yields:

gpg: no signed data
gpg: can't hash datafile: No data

This confirms that the recipient of the detached signature must receive both the original clear_text.txt file AND clear_text.txt.sig file in order for the detached signature verification to work.

If I create a cleartext signature, then delete the original text file, just keeping the .asc file, it makes no difference. The original text file contents in text format make up part of the .asc file.

With detached signatures, the original data (file) is not modified, and the signature itself is stored as a standalone file with a .sig extension. And the .sig file contains binary data.

A detached signature file (.sig) can be distributed alongside or independent of the original data. The authenticity and integrity of the original data file can be verified by using the detached signature file, but the original text file is required as well for the verification process to work.

The detached signature format is especially useful for signing software releases and other files where it is imperative that the content remains unaltered during the signing process.

With cleartext signatures, even though they are popular, they have their limitations and are considered a legacy method. Cleartext digital signatures are incompatible with semantically meaningful whitespace¹, they don't work well with very large messages, and an attacker can include additional text in the Hash header, which may mislead the user into thinking it is part of the signed text. Given these limitations and issues, it is better to either use a complete (aka inline) digital signature or a detached signature.

In this post, I walk through the process of creating a cleartext digital signature with the --clear-sign option, and verifying it. I also compare detached signatures to cleartext signatures. The difference between a detached and cleartext signature is that the signature itself is stored in a standalone .sig file, separate from the original text file. The original file is also not modified. This is good for situations where it is crucial that the original content remains untouched during the signing process. On the other hand, a cleartext signature contains both the original content and the signature. Whether I use a cleartext digital signature or detached signature depends on what my procedural requirements are.

• 7. Signatures over data: OpenPGP for application developers

• Asymmetric encryption and decryption series table of contents: mariadcampbell.com