diff options
author | Lars Wirzenius <liw@sequoia-pgp.org> | 2022-01-19 18:35:51 +0200 |
---|---|---|
committer | Lars Wirzenius <liw@sequoia-pgp.org> | 2022-01-19 19:35:06 +0200 |
commit | b82cfd007df135a1019a0f11bbbca189ab21b029 (patch) | |
tree | 1a09b8c7295ed24235a8ac02a9f572329a4d26c8 | |
parent | 2a9178673622c146afb15558e54f867a9c3094f1 (diff) |
sq: add scenarios to verify signing data
Sponsored-by: NLnet Foundation; NGI Assure; European Commission
-rw-r--r-- | sq/sq-subplot.md | 172 |
1 files changed, 119 insertions, 53 deletions
diff --git a/sq/sq-subplot.md b/sq/sq-subplot.md index 854d8cb7..b3336901 100644 --- a/sq/sq-subplot.md +++ b/sq/sq-subplot.md @@ -837,99 +837,165 @@ then files hello.txt and bob.txt match ~~~ -# Sign a document and verify the signature +# Sign a document and verify the signature: `sq sign` and `sq verify` -_Requirement: We must be able to sign a document, to prove it comes -from us. We must be able to verify a signature on a document._ +This chapter verifies that digital signatures work in `sq`. Like with +encryption, the verification is based on round trips: we create a +signature, and that it matches the signed data. We break this into a +number simple cases. -We break this into three scenarios. One that uses a binary signature, -one with textual cleartext signature, and one with a detached -signature. +## Create signature to stdout in ASCII armor -## Binary signature +_Requirement: We can create a signature and have it written to +stdout in ASCII armor form._ -This scenario creates a small text file, and signs it, and checks that -the signature is OK. +~~~scenario +given an installed sq +given file hello.txt +when I run sq key generate --export key.pgp +when I run sq sign --signer-key key.pgp hello.txt +then stdout contains "-----BEGIN PGP MESSAGE-----" +then stdout contains "-----END PGP MESSAGE-----" +~~~ + +## Create signature to stdout in binary + +_Requirement: We can create a signature and have it written to +stdout in binary form._ ~~~scenario given an installed sq given file hello.txt -when I run sq key generate --userid Tomjon --export tomjon.pgp -when I run sq sign -o s.pgp --signer-key tomjon.pgp hello.txt -then file s.pgp contains "-----BEGIN PGP MESSAGE-----" -then file s.pgp contains "-----END PGP MESSAGE-----" -when I run sq verify -o output.txt --signer-cert tomjon.pgp s.pgp -then files hello.txt and output.txt match -then file output.txt contains "hello, world" +when I run sq key generate --export key.pgp +when I run sq sign --signer-key key.pgp hello.txt --binary +then stdout doesn't contain "-----BEGIN PGP MESSAGE-----" +then stdout doesn't contain "-----END PGP MESSAGE-----" ~~~ -However, if the signed file is modified, verification must fail. We -check this by removing a line from the signed file, which is a crude -way of making sure the signature doesn't match. +## Create signature to named file -Further, the output must not contain the input if the verification -fails. This is to prevent accidents where the user is shown unverified -text, and possibly a warning that it's not to be trusted, but they -make use of the text anyway. +_Requirement: We can create a signature and have it written to a named +file._ ~~~scenario -when I run sed -i 3d s.pgp -when I try to run sq verify --signer-cert tomjon.pgp s.pgp -then exit code is not 0 -then stdout doesn't contain "hello, world" +given an installed sq +given file hello.txt +when I run sq key generate --export key.pgp +when I run sq sign --signer-key key.pgp hello.txt -o signed.txt +then file signed.txt contains "-----BEGIN PGP MESSAGE-----" +then file signed.txt contains "-----END PGP MESSAGE-----" ~~~ +## Signed file can be verified -## Cleartext signature +_Requirement: We can sign a file and verify the signature._ -This scenario is essentially the same, but uses a cleartext signature, -and the way the signed file is mangled is different. +~~~scenario +given an installed sq +given file hello.txt +when I run sq key generate --export key.pgp +when I run sq key extract-cert key.pgp -o cert.pgp +when I run sq sign --signer-key key.pgp hello.txt -o signed.txt +when I run sq verify --signer-cert cert.pgp signed.txt +then stdout contains "hello, world" +~~~ + +## Signed file cannot be verified if it has been modified + +_Requirement: We can sign a file and verifying the signature fails if +the signed file has been modified._ + +We modify the signed file by removing the third line of it. The file +starts with a line containing "-----BEGIN PGP MESSAGE-----" and then +an empty line, and the third line is actual data. If we delete that, +the file by definition can't be valid anymore. ~~~scenario given an installed sq given file hello.txt -when I run sq key generate --userid Tomjon --export tomjon.pgp -when I run sq sign --cleartext-signature -o s.pgp --signer-key tomjon.pgp hello.txt -then file s.pgp contains "hello, world" -when I run sq verify -o output.txt --signer-cert tomjon.pgp s.pgp -then files hello.txt and output.txt match -then file output.txt contains "hello, world" +when I run sq key generate --export key.pgp +when I run sq key extract-cert key.pgp -o cert.pgp +when I run sq sign --signer-key key.pgp hello.txt -o signed.txt +when I run sed -i 3d signed.txt +when I try to run sq verify --signer-cert cert.pgp signed.txt +then command fails ~~~ -We modify the signed file by converting the actual message embedded in -the signed file to upper case, which is easy to do, as it's in cleartext. +## Create cleartext signature + +_Requirement: We can create a signature such that the signed data is +included in a readable form. ~~~scenario -when I run sed -i 's/^hello, world/HELLO, WORLD/' s.pgp -when I try to run sq verify --signer-cert tomjon.pgp s.pgp +given an installed sq +given file hello.txt +when I run sq key generate --export key.pgp +when I run sq key extract-cert key.pgp -o cert.pgp + +when I run sq sign --cleartext-signature --signer-key key.pgp hello.txt -o signed.txt +then file signed.txt contains "-----BEGIN PGP SIGNED MESSAGE-----" +then file signed.txt contains "hello, world" +then file signed.txt contains "-----END PGP SIGNATURE-----" +when I run sq verify --signer-cert cert.pgp signed.txt +then stdout contains "hello, world" +~~~ + + +## Cleartext signature cannot be verified if it has been modified + +_Requirement: If a cleartext signature is modified, it can't be +verified._ + +~~~scenario +given an installed sq +given file hello.txt +when I run sq key generate --export key.pgp +when I run sq key extract-cert key.pgp -o cert.pgp + +when I run sq sign --cleartext-signature --signer-key key.pgp hello.txt -o signed.txt +when I run sed -i s/hello/HELLO/ signed.txt +when I try to run sq verify --signer-cert cert.pgp signed.txt then exit code is 1 -then stdout doesn't contain "hello, world" -then stdout doesn't contain "HELLO, WORLD" ~~~ -## Detached signature +## Create a detached signature -This scenario is essentially the same as the previous ones, but uses a -detached signature. +_Requirement: We can create a signature that is doesn't include the +data it signs._ ~~~scenario given an installed sq given file hello.txt -when I run sq key generate --userid Tomjon --export k.pgp -when I run sq sign --detached -o s.pgp --signer-key k.pgp hello.txt -when I run sq verify -o o.txt --signer-cert k.pgp --detached s.pgp hello.txt +when I run sq key generate --export key.pgp +when I run sq key extract-cert key.pgp -o cert.pgp + +when I run sq sign --detached --signer-key key.pgp hello.txt -o sig.txt +then file sig.txt contains "-----BEGIN PGP SIGNATURE-----" +then file sig.txt contains "-----END PGP SIGNATURE-----" +when I run sq verify --detached=sig.txt --signer-cert=cert.pgp hello.txt +then stdout doesn't contain "hello, world" +then exit code is 0 ~~~ -We modify the original file so that the signature doesn't match. + +## Detached signature cannot be verified if the data has been modified + +_Requirement: If the file that is signed using a detached signature is +modified, the signature can't be verified._ ~~~scenario -when I run sed -i 's/^hello, world/HELLO, WORLD/' hello.txt -when I try to run sq verify --signer-cert k.pgp --detached s.pgp hello.txt +given an installed sq +given file hello.txt +when I run sq key generate --export key.pgp +when I run sq key extract-cert key.pgp -o cert.pgp + +when I run sq sign --detached --signer-key key.pgp hello.txt -o sig.txt +when I run sed -i s/hello/HELLO/ hello.txt +when I try to run sq verify --detached=sig.txt --signer-cert=cert.pgp hello.txt then exit code is 1 -then stdout doesn't contain "hello, world" -then stdout doesn't contain "HELLO, WORLD" ~~~ + # ASCII Armor data representation: `sq armor` and `sq dearmor` The scenarios in this chapter verify that `sq` can convert data into |