From 4bb762486e6de638ad541dba7cb153734228354f Mon Sep 17 00:00:00 2001 From: Nicco Kunzmann Date: Mon, 25 Jun 2018 13:56:02 +0200 Subject: [PATCH 01/11] How to sign code Problem: I did not know how to sign code in a how-to fashion Solution: I added the necessary steps as I did them in https://github.com/QubesOS/qubes-app-linux-usb-proxy/pull/4 --- basics_dev/code-signing.md | 65 ++++++++++++++++++++++++++++++++++++-- 1 file changed, 62 insertions(+), 3 deletions(-) diff --git a/basics_dev/code-signing.md b/basics_dev/code-signing.md index caecf566..9098bae0 100644 --- a/basics_dev/code-signing.md +++ b/basics_dev/code-signing.md @@ -81,6 +81,7 @@ sub 4096R/69B0EA85 2013-03-13 Using PGP with Git ------------------ +[Using PGP with Git]: #using-pgp-with-git If you're submitting a patch via GitHub (or a similar Git server), please sign your Git commits. @@ -109,19 +110,77 @@ your Git commits. git tag -s -m "" ~~~ - You can also create an alias to make this easier: + You can also create an alias to make this easier. + Edit your `~/.gitconfig` file. + In the `[alias]` section, add the `stag` command to created signed tags and `spush` to create signed tags and push them. ~~~ - stag = "!id=`git rev-parse --verify HEAD`; git tag -s tag_for_${id:0:8} -m \"Tag for commit $id\"" + [alias] + stag = "!bash -c 'id=\"`git rev-parse --verify HEAD`\"; tag_name="signed_tag_for_${id:0:8}"; git tag -s "$tag_name" -m \"Tag for commit $id\"; echo \"$tag_name\"'" + spush = "!bash -c 'git push origin `git stag`'" ~~~ You may also find it convenient to have an alias for verifying the tag on the latest commit: ~~~ - vtag = !git tag -v `git describe` + vtag = !git tag -v `git describe` ~~~ +How to Contribute Signed Code +----------------------------- + +The [signature-checker] checks if code contributions are signed. +Although GitHub adds a litte green `Verified` button next to the commit, the [signature-checker] uses another algorithm. +You may see this message: + +> Unable to verify (no valid key found) - [signature-checker/check-git-signature line 392](https://github.com/marmarek/signature-checker/blob/d143b8f2b4da828a9a93b91eb972dddb7e28b4f0/check-git-signature#L392) + +Which means that the following correct flow was not done in order or is missing steps: + +1. Create a signed commit. + If you have configured your git as in [Using PGP with Git], your commits are signed automatically. +2. Create a new signed tag for the commit. + The optional part of [Using PGP with Git] uses the `stag` alias to create the signed commit. + ``` + $ git stag + signed_tag_for_a8beed54 + ``` +3. Push the newly created tag to your repository. + ``` + git push origin signed_tag_for_a8beed54 + ``` + You can do this and the step before using `git spush` if you added the alias. +4. Push the commit to the repository. + ``` + git push origin branch-name + ``` + This triggers the check if the commit is signed in the pull request. + Then, the tag is already existent and the [signature-checker] can find it. + +### Error Handling + +Now, if you get + +> Unable to verify (no valid key found) + +chances are, you did already push a commit and wonder how to sign it properly. +You can do the following to re-trigger the signature check: + +1. Create a new signed commit with the same message. Add `-S` if you did not enable automatic signatures. + ``` + git commit --amend + ``` +2. Create a tag and push it. + ``` + git spush + ``` +4. Push the new commit replacing the old one. + ``` + git push -f + ``` + +[signature-checker]: https://github.com/marmarek/signature-checker Using PGP with Email -------------------- From d030e43dd831d15d2bd12e34c53d0d83f98c840e Mon Sep 17 00:00:00 2001 From: Nicco Kunzmann Date: Mon, 25 Jun 2018 14:16:37 +0200 Subject: [PATCH 02/11] correct spelling --- basics_dev/code-signing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/basics_dev/code-signing.md b/basics_dev/code-signing.md index 9098bae0..71d89b7a 100644 --- a/basics_dev/code-signing.md +++ b/basics_dev/code-signing.md @@ -131,7 +131,7 @@ How to Contribute Signed Code ----------------------------- The [signature-checker] checks if code contributions are signed. -Although GitHub adds a litte green `Verified` button next to the commit, the [signature-checker] uses another algorithm. +Although GitHub adds a little green `Verified` button next to the commit, the [signature-checker] uses another algorithm. You may see this message: > Unable to verify (no valid key found) - [signature-checker/check-git-signature line 392](https://github.com/marmarek/signature-checker/blob/d143b8f2b4da828a9a93b91eb972dddb7e28b4f0/check-git-signature#L392) From 24d0784a712989ae49e62a9919b8aab9da9ed53a Mon Sep 17 00:00:00 2001 From: Nicco Kunzmann Date: Mon, 25 Jun 2018 14:20:32 +0200 Subject: [PATCH 03/11] correct spelling --- basics_dev/code-signing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/basics_dev/code-signing.md b/basics_dev/code-signing.md index 71d89b7a..e115bb03 100644 --- a/basics_dev/code-signing.md +++ b/basics_dev/code-signing.md @@ -112,7 +112,7 @@ your Git commits. You can also create an alias to make this easier. Edit your `~/.gitconfig` file. - In the `[alias]` section, add the `stag` command to created signed tags and `spush` to create signed tags and push them. + In the `[alias]` section, add `stag` to create signed tags and `spush` to create signed tags and push them. ~~~ [alias] From fd53e7198323c6ac5dec1f6cd9a0b475cfd4ef20 Mon Sep 17 00:00:00 2001 From: Nicco Kunzmann Date: Mon, 25 Jun 2018 14:25:14 +0200 Subject: [PATCH 04/11] signed tags are not optional Problem: having (Optional) here creates confusion about how important this is to contribute code Solution: Remove (Optional) --- basics_dev/code-signing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/basics_dev/code-signing.md b/basics_dev/code-signing.md index e115bb03..8bded0cf 100644 --- a/basics_dev/code-signing.md +++ b/basics_dev/code-signing.md @@ -104,7 +104,7 @@ your Git commits. commit -S ~~~ -3. (Optional) Create signed tags: +3. Create signed tags: ~~~ git tag -s -m "" From 8ea5ffc99a1a410042ffeda132339d7c21f73a9a Mon Sep 17 00:00:00 2001 From: Nicco Kunzmann Date: Tue, 26 Jun 2018 09:39:02 +0200 Subject: [PATCH 05/11] add success message --- basics_dev/code-signing.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/basics_dev/code-signing.md b/basics_dev/code-signing.md index 8bded0cf..64d31a3b 100644 --- a/basics_dev/code-signing.md +++ b/basics_dev/code-signing.md @@ -134,7 +134,7 @@ The [signature-checker] checks if code contributions are signed. Although GitHub adds a little green `Verified` button next to the commit, the [signature-checker] uses another algorithm. You may see this message: -> Unable to verify (no valid key found) - [signature-checker/check-git-signature line 392](https://github.com/marmarek/signature-checker/blob/d143b8f2b4da828a9a93b91eb972dddb7e28b4f0/check-git-signature#L392) +> policy/qubesos/code-signing — Unable to verify (no valid key found) - [signature-checker/check-git-signature line 392](https://github.com/marmarek/signature-checker/blob/d143b8f2b4da828a9a93b91eb972dddb7e28b4f0/check-git-signature#L392) Which means that the following correct flow was not done in order or is missing steps: @@ -156,7 +156,9 @@ Which means that the following correct flow was not done in order or is missing git push origin branch-name ``` This triggers the check if the commit is signed in the pull request. - Then, the tag is already existent and the [signature-checker] can find it. +5. Then, the tag is already existent and the [signature-checker] can find it. + You can see a message like this: + > policy/qubesos/code-signing — Signed with 9BBAB2DEB1488C99 ### Error Handling From 090d617e91baccc96d3f1e4055ae2aac2aa217fc Mon Sep 17 00:00:00 2001 From: Nicco Kunzmann Date: Tue, 26 Jun 2018 10:15:28 +0200 Subject: [PATCH 06/11] Revert "signed tags are not optional" This reverts commit fd53e7198323c6ac5dec1f6cd9a0b475cfd4ef20. Signed tags are optional --- basics_dev/code-signing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/basics_dev/code-signing.md b/basics_dev/code-signing.md index 64d31a3b..5471cf4d 100644 --- a/basics_dev/code-signing.md +++ b/basics_dev/code-signing.md @@ -104,7 +104,7 @@ your Git commits. commit -S ~~~ -3. Create signed tags: +3. (Optional) Create signed tags: ~~~ git tag -s -m "" From 5e1731c7ead7b7dc48b08a9ef39f6d5107d94618 Mon Sep 17 00:00:00 2001 From: Nicco Kunzmann Date: Tue, 26 Jun 2018 10:24:18 +0200 Subject: [PATCH 07/11] Describe why tags are optional - https://github.com/QubesOS/qubes-doc/pull/666#issuecomment-400115131 - fix indentation - https://github.com/QubesOS/qubes-doc/pull/666#discussion_r198002571 - https://github.com/QubesOS/qubes-doc/pull/666#discussion_r198002716 --- basics_dev/code-signing.md | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/basics_dev/code-signing.md b/basics_dev/code-signing.md index 5471cf4d..aa4de24d 100644 --- a/basics_dev/code-signing.md +++ b/basics_dev/code-signing.md @@ -104,7 +104,13 @@ your Git commits. commit -S ~~~ -3. (Optional) Create signed tags: +3. (Optional) Create signed tags. + Signed commits are totally sufficient to contribute to Qubes OS. + However, if you have commits which are not signed and you do not want to change them, + you can create a signed tag for the commit and push it before the check. + + This is useful for example, if you have a commit back in the git history which + you like to sign now without rewriting the history. ~~~ git tag -s -m "" @@ -116,15 +122,15 @@ your Git commits. ~~~ [alias] - stag = "!bash -c 'id=\"`git rev-parse --verify HEAD`\"; tag_name="signed_tag_for_${id:0:8}"; git tag -s "$tag_name" -m \"Tag for commit $id\"; echo \"$tag_name\"'" - spush = "!bash -c 'git push origin `git stag`'" + stag = "!bash -c 'id=\"`git rev-parse --verify HEAD`\"; tag_name="signed_tag_for_${id:0:8}"; git tag -s "$tag_name" -m \"Tag for commit $id\"; echo \"$tag_name\"'" + spush = "!bash -c 'git push origin `git stag`'" ~~~ You may also find it convenient to have an alias for verifying the tag on the latest commit: ~~~ - vtag = !git tag -v `git describe` + vtag = !git tag -v `git describe` ~~~ How to Contribute Signed Code From 0b27771c893f3faa491cc3449a7d83ed7fe74d2a Mon Sep 17 00:00:00 2001 From: Nicco Kunzmann Date: Tue, 26 Jun 2018 10:30:50 +0200 Subject: [PATCH 08/11] move ref link to bottom --- basics_dev/code-signing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/basics_dev/code-signing.md b/basics_dev/code-signing.md index aa4de24d..d5e3ba5a 100644 --- a/basics_dev/code-signing.md +++ b/basics_dev/code-signing.md @@ -188,7 +188,6 @@ You can do the following to re-trigger the signature check: git push -f ``` -[signature-checker]: https://github.com/marmarek/signature-checker Using PGP with Email -------------------- @@ -202,4 +201,5 @@ Enigmail is a security addon for the Mozilla Thunderbird email client that allow [source code]: /doc/source-code/ [developer mailing list]: /support/#qubes-devel [Enigmail]: https://www.enigmail.net/ +[signature-checker]: https://github.com/marmarek/signature-checker From 723d3fc5fe7ea4fee042d7fb73915faf0341d6c3 Mon Sep 17 00:00:00 2001 From: Nicco Kunzmann Date: Tue, 26 Jun 2018 11:17:54 +0200 Subject: [PATCH 09/11] Convert How To Section into an Error Handling Section - remove link to heading https://github.com/QubesOS/qubes-doc/pull/666#discussion_r198002637 - remove wrong process - add ways to cope with signature-checker error messages --- basics_dev/code-signing.md | 78 +++++++++++++++++--------------------- 1 file changed, 35 insertions(+), 43 deletions(-) diff --git a/basics_dev/code-signing.md b/basics_dev/code-signing.md index d5e3ba5a..9b03d76c 100644 --- a/basics_dev/code-signing.md +++ b/basics_dev/code-signing.md @@ -81,7 +81,6 @@ sub 4096R/69B0EA85 2013-03-13 Using PGP with Git ------------------ -[Using PGP with Git]: #using-pgp-with-git If you're submitting a patch via GitHub (or a similar Git server), please sign your Git commits. @@ -133,60 +132,53 @@ your Git commits. vtag = !git tag -v `git describe` ~~~ -How to Contribute Signed Code ------------------------------ +Code Signature Checks +--------------------- The [signature-checker] checks if code contributions are signed. -Although GitHub adds a little green `Verified` button next to the commit, the [signature-checker] uses another algorithm. -You may see this message: +Although GitHub adds a little green `Verified` button next to the commit, the [signature-checker] uses this algorithm to check if a commit is currectly signed: -> policy/qubesos/code-signing — Unable to verify (no valid key found) - [signature-checker/check-git-signature line 392](https://github.com/marmarek/signature-checker/blob/d143b8f2b4da828a9a93b91eb972dddb7e28b4f0/check-git-signature#L392) +1. Is the commit signed? + If the commit is not signed, you can see the message + > policy/qubesos/code-signing — No signature found +2. If the commit is signed, the key is downloaded from a GPG key server. + If you can see the following error message, please check if you have uploaded the key to a key server. + > policy/qubesos/code-signing — Unable to verify (no valid key found) -Which means that the following correct flow was not done in order or is missing steps: +### No Signature Found -1. Create a signed commit. - If you have configured your git as in [Using PGP with Git], your commits are signed automatically. -2. Create a new signed tag for the commit. - The optional part of [Using PGP with Git] uses the `stag` alias to create the signed commit. - ``` - $ git stag - signed_tag_for_a8beed54 - ``` -3. Push the newly created tag to your repository. - ``` - git push origin signed_tag_for_a8beed54 - ``` - You can do this and the step before using `git spush` if you added the alias. -4. Push the commit to the repository. - ``` - git push origin branch-name - ``` - This triggers the check if the commit is signed in the pull request. -5. Then, the tag is already existent and the [signature-checker] can find it. - You can see a message like this: - > policy/qubesos/code-signing — Signed with 9BBAB2DEB1488C99 +> policy/qubesos/code-signing — No signature found -### Error Handling +In this case, you have several options to sign the commit: -Now, if you get - -> Unable to verify (no valid key found) - -chances are, you did already push a commit and wonder how to sign it properly. -You can do the following to re-trigger the signature check: - -1. Create a new signed commit with the same message. Add `-S` if you did not enable automatic signatures. +1. Amend the commit and repace it with a signed commit. + You can use this command to create a new signed commit: ``` - git commit --amend + git commit --amend -S ``` -2. Create a tag and push it. - ``` - git spush - ``` -4. Push the new commit replacing the old one. + This also rewrites the commit so you need to push it forcefully: ``` git push -f ``` +2. Create a signed tag for the unsigned commit. + If the commit is back in history and you do not want to change it, + you can create a signed tag for this commit and push the signature. + You can use the alias from above: + ``` + git checkout + git spush + ``` + Now, the signature checker needs to re-check the signature. + Please commit on the pull request that you would like to have the signatures checked again. + +### Unable To Verify + +> policy/qubesos/code-signing — Unable to verify (no valid key found) + +This means that the [signature-checker] has found a signature but is not able +to verify it using the any key available. +This might be that you forgot to upload the key to a key server. +Please upload it. Using PGP with Email From f08dea73206aeb4565e98c0266cbcefe8fb9dea8 Mon Sep 17 00:00:00 2001 From: Nicco Kunzmann Date: Tue, 26 Jun 2018 11:25:37 +0200 Subject: [PATCH 10/11] correct spelling --- basics_dev/code-signing.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/basics_dev/code-signing.md b/basics_dev/code-signing.md index 9b03d76c..d9035f22 100644 --- a/basics_dev/code-signing.md +++ b/basics_dev/code-signing.md @@ -169,14 +169,14 @@ In this case, you have several options to sign the commit: git spush ``` Now, the signature checker needs to re-check the signature. - Please commit on the pull request that you would like to have the signatures checked again. + Please comment on the pull request that you would like to have the signatures checked again. ### Unable To Verify > policy/qubesos/code-signing — Unable to verify (no valid key found) -This means that the [signature-checker] has found a signature but is not able -to verify it using the any key available. +This means that the [signature-checker] has found a signature for the commit +but is not able to verify it using the any key available. This might be that you forgot to upload the key to a key server. Please upload it. From f570d93b1cf0e0273941cb6f1b793f119b496e24 Mon Sep 17 00:00:00 2001 From: Nicco Kunzmann Date: Mon, 2 Jul 2018 10:51:10 +0200 Subject: [PATCH 11/11] correct spelling this addresses https://github.com/QubesOS/qubes-doc/pull/666#issuecomment-401643800 --- basics_dev/code-signing.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/basics_dev/code-signing.md b/basics_dev/code-signing.md index d9035f22..018dcf17 100644 --- a/basics_dev/code-signing.md +++ b/basics_dev/code-signing.md @@ -136,7 +136,7 @@ Code Signature Checks --------------------- The [signature-checker] checks if code contributions are signed. -Although GitHub adds a little green `Verified` button next to the commit, the [signature-checker] uses this algorithm to check if a commit is currectly signed: +Although GitHub adds a little green `Verified` button next to the commit, the [signature-checker] uses this algorithm to check if a commit is correctly signed: 1. Is the commit signed? If the commit is not signed, you can see the message @@ -151,7 +151,7 @@ Although GitHub adds a little green `Verified` button next to the commit, the [s In this case, you have several options to sign the commit: -1. Amend the commit and repace it with a signed commit. +1. Amend the commit and replace it with a signed commit. You can use this command to create a new signed commit: ``` git commit --amend -S