howto/Registry-Authentication.md
... ...
@@ -6,13 +6,20 @@ When a pull request is submitted to the registry, the submitter signs the git co
6 6
7 7
The signature and verification process varies depending on the type of public key within the `auth` attribute.
8 8
9
----
9
+## Preferred signing methods
10
+
11
+*Tip: Add your GPG or SSH key to your account in gitea, doing so enables gitea to automatically check your signature when you sign the commit*
10 12
11
-*The registry now contains an experimental script 'sign-my-commit' which can authenticate requests using PGP or generic SSH key signing. Users are encouraged to use the script where possible as it will help with automating pull request reviews.*
13
+### When using a GPG/PGP Key
14
+1) **Sign the commit using git** - this is the best option as the signature is recorded directly in the git log
15
+2) Sign using `gpg --clearsign` and provide the signature in the PR comments - only do this if you absolutely cannot sign the commit in git
12 16
13
-*Run `./sign-my-commit --help` to get usage information.*
17
+### When using an SSH key
18
+1) **Sign the commit using git** - git >= 2.34.0 can now sign commits using ssh keys, this is the best option if you able to do so
19
+2) Use the `sign-my-commit` script in the registry - the script adds your signature in a format that allows for automated checking
20
+3) Manually provide a signature in the PR comments using one of the methods detailed below - only do this if you can't sign using git or with the included script
14 21
15
-*If the script fails, please report the problem using the registry issue log (or better fix it and submit a PR!). You can always sign your commit manually using the methods below.*
22
+The sections below provide detailed instructions for each of the auth methods.
16 23
17 24
---
18 25
... ...
@@ -27,55 +34,165 @@ Date: Mon Jan 01 01:01:01 2020 +0000
27 34
Change some stuff
28 35
```
29 36
30
-## Authentication with PGP Key
37
+In this case the full commit hash is `6e2e9ac540e2e4e3c3a135ad90c8575bb8fa1784`
38
+
39
+---
31 40
32
-PGP keys may be uploaded to a public keyserver for verification, or added in the registry.
41
+## Authentication using a GPG/PGP Key
33 42
34
-### Using a public keyserver
43
+To verify your key, the registry maintainers need to be able to find your full public key.
44
+There are three options for doing this. but you only need to do **one** of these:
45
+
46
+ 1) **Add your public key to your account in gitea** - this is the best option as gitea will automatically check your signature
47
+ 2) Upload your key to a public key server
48
+ 3) Create a `key-cert` object in the registry containing your public key
49
+
50
+### `auth` attribute format, when your public key is in gitea or a public keyserver
35 51
36 52
- Use the following `auth` attribute in your `mntner` object:
37 53
```
38 54
auth: pgp-fingerprint <fingerprint>
39 55
```
40
-Where `<fingerprint>` is your full 40-digit key fingerprint, without spaces.
56
+Where `<fingerprint>` is your **full 40-digit** key fingerprint, without spaces.
41 57
42
-- Ensure that your public key has been uploaded to a public keyserver, e.g. [SKS](https://sks-keyservers.net/), [OpenPGP](https://keys.openpgp.org/), [keybase](https://keybase.io/).
58
+- Ensure that your public key has been uploaded to your account in gitea or a public keyserver, e.g. [SKS](https://sks-keyservers.net/), [OpenPGP](https://keys.openpgp.org/), [keybase](https://keybase.io/).
43 59
44
-#### Adding to the registry
60
+### `auth` attribute format when creating a `key-cert` object
45 61
46
-- Use the following `auth` attribute in your `mntner` object:
62
+*Tip: look at the existing key-cert objects for examples of how to add your public key*
63
+
64
+- In this case the `auth` attribute must refer to the new key-cert object so use the following in your `mntner` object:
47 65
```
48
-auth: PGPKEY-<fprint>
66
+auth: PGPKEY-<short fingerprint>
49 67
```
50
-Where `<fprint>` is the last 8 digits from your key fingerprint.
68
+Where `<short fingerprint>` is the last **8** digits from your key fingerprint.
51 69
52
-- Create a `key-cert` object for your public key, using `PGPKEY-<fprint>` for the filename. Do browse the registry and check the existing objects for examples.
70
+- Create a `key-cert` object for your public key, using `PGPKEY-<fprint>` for the filename.
53 71
54
-#### Signing your commits
72
+### How to sign your commit
55 73
56
-- Use `git commit -S` to commit and sign your change. See the [github guide](https://help.github.com/en/github/authenticating-to-github/signing-commits).
74
+*Tip: There are many public guides available with step by step instructions on how to sign commits, e.g. [github guide](https://help.github.com/en/github/authenticating-to-github/signing-commits)*
57 75
58
-- If you have already committed your change, you can sign it using.
76
+- Use `git commit -S` to commit and sign your change.
77
+
78
+- If you have already committed your change without signing it, you can sign the existing commit using:
59 79
```
60 80
git commit --amend --no-edit -S
61 81
```
82
+If you had already pushed your change to gitea, you must also do a force push (`git push --force`) to update the remote copy.
62 83
63
-#### Verifying the signature
84
+### Verifying the signature
64 85
65
-- Use `git log --show-signature` to show recent commits and signatures.
86
+- Use `git log --show-signature` to show recent commits and signatures
87
+- If you have uploaded your key to gitea, you can also check in the gitea UI that your commit is signed and has been verified successfully
88
+
89
+---
66 90
67 91
## Authentication using an SSH key
68 92
93
+Older versions of git and ssh don't support generic ssh signing so there are multiple ways of providing ssh signatures based on the versions you have and the type of key you are using. The newer signature methods are preferred as they allow automatic verification of your signature.
94
+
95
+In preference order:
96
+
97
+1) **Sign using git**
98
+2) Sign using the included `sign-my-commit` script
99
+
100
+If you cannot get the above to work you may also:
101
+
102
+3) Manually sign using the generic ssh-keygen method
103
+4) Manual sign using specific methods for rsa or ecdsa
104
+
105
+### `auth` attribute format when using an ssh key
106
+
69 107
The generic format for authentication using an SSH key is as follows:
70 108
```
71 109
auth: ssh-<keytype> <pubkey>
72 110
```
73
-There are examples below for each specific key type.
74 111
75
-### Generic process for signing with an SSH key
112
+Common examples:
113
+
114
+```
115
+auth: ssh-ed25519 <pubkey>
116
+```
117
+
118
+```
119
+auth: ssh-rsa <pubkey>
120
+```
121
+
122
+*Tip: look in the existing registry objects for examples*
123
+
124
+### Signing using git
125
+
126
+If you have git >= 2.34.0 you can now sign git commits directly with an SSH key.
127
+
128
+Brief instructions are below, however there are also more detailed guides available on how to do this, e.g. [here](https://blog.dbrgn.ch/2021/11/16/git-ssh-signatures/) or [here](https://calebhearth.com/sign-git-with-ssh)
129
+
130
+#### Configuration
131
+
132
+- Set your git signature format to be SSH
133
+
134
+```
135
+git config --global gpg.format ssh
136
+```
137
+
138
+- Tell git which SSH key to use
139
+
140
+```
141
+git config --global user.signingKey '<ssh public key>'
142
+```
143
+
144
+#### How to sign
145
+
146
+Once configured, you can now use git to sign your commit as normal:
147
+
148
+- Use `git commit -S` to commit and sign your change.
149
+
150
+- If you have already committed your change without signing it, you can sign the existing commit using:
151
+```
152
+git commit --amend --no-edit -S
153
+```
154
+If you had already pushed your change to gitea, you must also do a force push (`git push --force`) to update the remote copy.
155
+
156
+#### Verifying the signature
157
+
158
+Verifying an ssh signature is slightly more complicated than with gpg keys, please see the guides linked above.
159
+
160
+The easiest way to verify your signature is to ensure your SSH key is uploaded then push your changes to gitea. Gitea will automatically verify your signature for you and show if it was successful in the UI.
161
+
162
+### Sign using the `sign-my-commit` script
163
+
164
+The registry includes a script that uses ssh-keygen signatures to sign your changes in a format that allows for automatic verification. It requires ssh-keygen >= v8.
165
+
166
+*Tip: use `./sign-my-commit --help` to see all options*
167
+
168
+#### How to sign
169
+
170
+```
171
+./sign-my-commit --ssh --key <path to your SSH private key> --push <MNTNER>
172
+```
173
+
174
+e.g.
175
+
176
+```
177
+./sign-my-commit --ssh -key /home/foo/.ssh/id_ed25519 --push FOO-MNT
178
+```
179
+
180
+#### Verifying the signature
181
+
182
+The script can also verify your signature:
183
+
184
+```
185
+./sign-my-commit --ssh --verify <MNTNER>
186
+```
187
+
188
+### Manually signing using ssh-keygen
189
+
190
+*Please only manually sign if you cannot use either of the automated methods*
76 191
77 192
OpenSSH v8 introduced new functionality for creating signatures using SSH keys. If you have an older version, you can compile the latest version of ssh-keygen from the [openssh-portable repo](https://github.com/openssh/openssh-portable).
78 193
194
+#### How to sign
195
+
79 196
Use the following to sign the latest `<commit hash>` (that you found using `git log`)
80 197
```sh
81 198
echo "<commit hash>" | ssh-keygen -Y sign -f <private key file> -n dn42
... ...
@@ -101,6 +218,16 @@ echo "<commit hash>" | \
101 218
ssh-keygen -Y verify -f allowed.tmp -n dn42 -I YOU-MNT -s sig.tmp
102 219
```
103 220
221
+---
222
+
223
+### Manually signing - SSH legacy methods
224
+
225
+**Only use the methods below if you cannot use any of the previous signature methods**
226
+
227
+Please try and upgrade your ssh-keygen version and use the generic ssh-keygen method first.
228
+
229
+---
230
+
104 231
### Authentication with an SSH RSA key
105 232
106 233
- Use the following `auth` attribute in your `mntner` object:
... ...
@@ -139,43 +266,6 @@ openssl pkeyutl \
139 266
-sigfile <(echo "<signature>" | base64 -d)
140 267
```
141 268
142
-### Authentication with an SSH ed25519 key
143
-
144
-- Use the following `auth` attribute in your `mntner` object:
145
-```
146
-auth: ssh-ed25519 <pubkey>
147
-```
148
-Where `<pubkey>` is the ssh public key copied from your id_ed25519.pub file.
149
-
150
-#### Signing your commits
151
-
152
-There is no alternative process for signing using ed25519 keys, you must use the generic process described above. The process only works with ssh-keygen versions >= v8.
153
-
154
-Use the following to sign your `<commit hash>` (that you found using `git log`)
155
-```sh
156
-echo "<commit hash>" | ssh-keygen -Y sign -f ~/.ssh/id_ed25519 -n dn42
157
-```
158
-
159
-Post the signature in to the 'Conversation' section of your pull request to allow the registry maintainers to verify it. It can help to also include the commit hash that you have signed, to avoid any confusion.
160
-
161
-#### Verifying the signature
162
-
163
-The following procedure will verify the signature (using the `<commit hash>`, your ed25519 `<pubkey>` and the `<signature>` generated in the previous step.
164
-
165
-Create a temporary file containing the signature
166
-```sh
167
-echo "<signature>" > sig.tmp
168
-```
169
-Create a temporary 'allowed users' file
170
-```sh
171
-echo "YOU-MNT ssh-ed25519 <pubkey>" > allowed.tmp
172
-```
173
-Verify the signature
174
-```sh
175
-echo "<commit hash>" | \
176
- ssh-keygen -Y verify -f allowed.tmp -n dn42 -I YOU-MNT -s sig.tmp
177
-```
178
-
179 269
### Authentication with an SSH ecdsa key
180 270
181 271
- Use the following `auth` attribute in your `mntner` object: