howto/Getting-Started.md
... ...
@@ -28,6 +28,8 @@ When submitting your pull request, you must squash multiple changes to a single
28 28
29 29
Remember to add authentication to your `mntner` object, and you **must** [sign your commit](/howto/Registry-Authentication)
30 30
31
+*Tip: Remember to keep a backup of your authorisation keys*
32
+
31 33
The registry includes a number of scripts to help check your request:
32 34
33 35
- `fmt-my-stuff <FOO>-MNT`: automatically fixes minor formatting errors
... ...
@@ -40,7 +42,7 @@ The registry maintainers run the checking scripts against each request, so pleas
40 42
41 43
Do browse through the registry and look at the [pull request queue](https://git.dn42.dev/dn42/registry/pulls) to see examples, understand how the process works and see the types of questions asked by the registry maintainers.
42 44
43
-*You should not use the gitea web interface to edit files, doing so creates a large number of commits and prevents running of the registry scripts*
45
+*You cannot use the gitea web interface to edit files, doing so creates a large number of commits and prevents running of the registry scripts*
44 46
45 47
---
46 48
... ...
@@ -66,6 +68,8 @@ Common authentication methods are:
66 68
- PGP Key: `auth: pgp-fingerprint <pgp-fingerprint>`
67 69
- SSH Key: `auth: ssh-{rsa,ed25519} <key>`
68 70
71
+Losing your auth keys is a significant source of registry noise and wasted effort. We recommend configuring at least two authentication methods (a primary key and a backup key) in your mntner object. Always keep secure, separate backups of both private keys.
72
+
69 73
Example: data/mntner/FOO-MNT
70 74
```conf
71 75
mntner: FOO-MNT
... ...
@@ -73,6 +77,7 @@ admin-c: FOO-DN42
73 77
tech-c: FOO-DN42
74 78
mnt-by: FOO-MNT
75 79
auth: pgp-fingerprint 0123456789ABCDEF0123456789ABCDEF01234567
80
+auth: ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIGd7P9yG3xK6uBv3m8V1p8Z0K2yJ4uL7wP9qR3sT5uV1 user@example.com
76 81
source: DN42
77 82
```
78 83
... ...
@@ -89,7 +94,9 @@ Create a `person` object in `data/person/` for **yourself** (not your organisat
89 94
90 95
**Data Privacy**
91 96
92
-Contact attributes are optional but DN42 is a dynamic network and being able to contact users is really important if there are changes or problems. However, please also be aware that the DN42 registry is a public resource and you must assume that any details provided will be made public and cannot be fully removed. If this is a concern for you, please do not provide bogus contact details; simply provide anonymous details that are specific for use within DN42 or leave them out entirely.
97
+Contact attributes are optional but dn42 is a dynamic network and being able to contact users is really important if there are changes or problems. Reviewers won't accept new registrations without any contact details and an e-mail address is also the only way to recover your mntner if you lose access to your auth keys.
98
+
99
+However, please also be aware that the dn42 registry is a public resource and you must assume that any details provided will become part of the git history, will be made public and cannot be subsequently removed. If this is a concern for you, please do not provide bogus contact details, simply provide anonymous details that are specific for use within dn42.
93 100
94 101
95 102
Example: data/person/FOO-DN42
... ...
@@ -169,9 +176,9 @@ source: DN42
169 176
170 177
#### IPv6
171 178
172
-Even if you do not currently support IPv6, networks in dn42 are encouraged to be IPv6 first and many services are available only using IPv6.
179
+Even if you do not currently support IPv6, networks in dn42 are encouraged to be IPv6 first and many services are available only using IPv6.
173 180
174
-To register an IPv6 prefix, you create an `inet6num` object. dn42 uses the fd00::/8 ([ULA](https://tools.ietf.org/html/rfc4193)) range.
181
+To register an IPv6 prefix, you create an `inet6num` object. dn42 uses the fd00::/8 ([ULA](https://tools.ietf.org/html/rfc4193)) range.
175 182
176 183
A single /48 allocation is typical, it will provide more than enough room for a global network and there are no compelling reasons for choosing a different size. The smallest announceable prefix length is /64 but registering IP blocks smaller than /48 can often be limiting and restrict what you can do.
177 184
... ...
@@ -220,13 +227,13 @@ Check the registry (data/inetnum) to make sure no-one else has allocated the sam
220 227
| **/27** | 32 | **default allocation** |
221 228
| /26 | 64 | more than enough for the largest networks |
222 229
223
-Please **think before you allocate**; the current guideline is to allocate a /27 by default.
230
+Please **think before you allocate**; the current guideline is to allocate a /27 by default.
224 231
225
-New users will not be allocated an IP block larger than /26.
232
+New users will not be allocated an IP block larger than /26.
226 233
227 234
dn42 typically uses point-to-point addressing in VPN tunnels making transit networks unnecessary, a single IP address per host or public service will be sufficient and you should consider IPv6 first or NAT for devices that do not directly offer dn42 services. dn42 is not the public internet, but our IPv4-space is valuable too!
228 235
229
-**Note:** Reverse DNS works with _any_ prefix length, as long as your [recursive nameserver](/services/dns/Overview) supports [RFC 2317](https://www.ietf.org/rfc/rfc2317.txt).
236
+**Note:** Reverse DNS works with _any_ prefix length, as long as your [recursive nameserver](/services/dns/Overview) supports [RFC 2317](https://www.ietf.org/rfc/rfc2317.txt).
230 237
231 238
example: data/inetnum/172.20.150.0_27
232 239
```conf
howto/Registry-Authentication.md
... ...
@@ -2,16 +2,25 @@
2 2
3 3
`auth` attributes within registry `mntner` objects define a public key that is used to verify the identity of the maintainer and prove that changes to registry objects are authorised.
4 4
5
-When a pull request is submitted to the registry, the submitter signs the git commit hash with their private key. The registry maintainers will then check the signature against the registered public key to authorise the change.
5
+When a pull request is submitted to the registry, the submitter signs the git commit hash with their private key. The registry maintainers will then check the signature against the registered public key to authorise the change.
6 6
7 7
The signature and verification process varies depending on the type of public key within the `auth` attribute.
8 8
9
+You can have multiple `auth` methods, a valid signature from any key is sufficient for authorisation.
10
+
11
+## Keep your keys safe
12
+
13
+MNTNERs losing their keys is a significant source of registry noise, increasing the number of commits and wasting administrator effort.
14
+
15
+- **Keep a safe backup of your keys**
16
+- Adding a second key can allow you to recover your MNTNER if you lose the first key.
17
+
9 18
## Preferred signing methods
10 19
11 20
*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*
12 21
13 22
### 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
23
+1. **Sign the commit using git** - this is the best option as the signature is recorded directly in the git log
15 24
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
16 25
17 26
### When using an SSH key
... ...
@@ -19,7 +28,68 @@ The signature and verification process varies depending on the type of public ke
19 28
2. Use the `sign-my-commit` script in the registry - the script adds your signature in a format that allows for automated checking
20 29
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
21 30
22
-The sections below provide detailed instructions for each of the auth methods.
31
+There are detailed instructions below for how to sign using each of the available auth methods.
32
+
33
+---
34
+
35
+## Key Rotation
36
+
37
+The registry automation supports key rotation. Always keep secure backups of your private keys to prevent the need for account recovery.
38
+
39
+### Scenario A: You still have access to your existing keys
40
+
41
+Use this procedure if you still hold at least one private key currently listed in your `mntner` object.
42
+
43
+1. Update your `mntner` object with your new public key(s).
44
+2. Sign the commit using one of your **existing** private keys.
45
+3. Push your branch and open a Pull Request (PR).
46
+4. The CI *pipeline* will detect the key rotation and ask for a signature from one of the **new** keys.
47
+5. Sign the commit hash with your **new** private key (see signature commands below).
48
+6. Post a comment on the PR containing the signature:
49
+
50
+```text
51
+### DN42 Signature
52
+
53
+<paste signature here>
54
+```
55
+
56
+7. In the Gitea UI, request a re-review from the *pipeline* user. This triggers the CI check again.
57
+8. The *pipeline* validates the signature and automatically approves the PR.
58
+
59
+#### How to sign the commit hash
60
+
61
+Replace `{commit_hash}` with the full 40-character commit SHA.
62
+
63
+Using a GPG key:
64
+
65
+``` sh
66
+echo -n "{commit hash}" | gpg --armor --detach-sign
67
+```
68
+
69
+Using an SSH key:
70
+
71
+``` sh
72
+echo -n "{commit hash}" | ssh-keygen -Y sign -n dn42 -f ~/.ssh/your_existing_key
73
+```
74
+
75
+### Scenario B: You lost all existing keys (mntner recovery)
76
+
77
+If you lose access to all existing keys, you can recover your `mntner` object using the verified email address from your `person` object.
78
+
79
+**Note: Key recovery is a fallback mechanism** You should look to review and improve your key backup process after completing this procedure.
80
+
81
+1) Ensure the email address listed in your `person` object is added to your Gitea account and is verified.
82
+2) Update your `mntner` object with your new public key(s).
83
+3) Sign the commit using one of the **new** keys.
84
+4) Push your branch and open a PR.
85
+5) Post a comment on the PR with the exact text:
86
+
87
+``` text
88
+### DN42 Recovery
89
+```
90
+
91
+6) In the Gitea UI, request a re-review from the *pipeline* user to re-run the check.
92
+7) The *pipeline* will authorise the change if your verified Gitea email address matches an email in your `person` object.
23 93
24 94
---
25 95
... ...
@@ -40,14 +110,16 @@ In this case the full commit hash is `6e2e9ac540e2e4e3c3a135ad90c8575bb8fa1784`
40 110
41 111
## Authentication using a GPG/PGP Key
42 112
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:
113
+To verify your key, the registry maintainers need to be able to find your full public key.
45 114
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
115
+There are two options for doing this. but you only need to do **one** of these:
49 116
50
-### `auth` attribute format, when your public key is in gitea or a public keyserver
117
+ 1. **Add your public key to your account in gitea** - this is the best option as you can see in gitea when your commit is signed and the key can be used automatically by the registry tooling check your signature.
118
+ 2. Create a `key-cert` object in the registry containing your public key
119
+
120
+### `auth` attribute format, when your public key is in gitea
121
+
122
+- Ensure that your public key has been uploaded to your account in gitea.
51 123
52 124
- Use the following `auth` attribute in your `mntner` object:
53 125
```conf
... ...
@@ -55,20 +127,21 @@ auth: pgp-fingerprint <fingerprint>
55 127
```
56 128
Where `<fingerprint>` is your **full 40-digit** key fingerprint, without spaces.
57 129
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/).
130
+
59 131
60 132
### `auth` attribute format when creating a `key-cert` object
61 133
62 134
*Tip: look at the existing key-cert objects for examples of how to add your public key*
63 135
136
+
137
+- Create a `key-cert` object for your public key, using `PGPKEY-<fprint>` for the filename.
138
+
64 139
- In this case the `auth` attribute must refer to the new key-cert object so use the following in your `mntner` object:
65 140
```conf
66 141
auth: PGPKEY-<short fingerprint>
67 142
```
68 143
Where `<short fingerprint>` is the last **8** digits from your key fingerprint.
69 144
70
-- Create a `key-cert` object for your public key, using `PGPKEY-<fprint>` for the filename.
71
-
72 145
### How to sign your commit
73 146
74 147
*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)*
... ...
@@ -84,20 +157,22 @@ If you had already pushed your change to gitea, you must also do a force push (`
84 157
### Verifying the signature
85 158
86 159
- 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
160
+- You can also check in the gitea UI that your commit is signed and has been verified successfully
88 161
89 162
---
90 163
91 164
## Authentication using an SSH key
92 165
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.
166
+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.
167
+
168
+Please try and sign using one of the newer methods as they can be automatically verified by the registry tooling, which saves a lot of reviewer time.
94 169
95 170
In preference order:
96 171
97 172
1. **Sign using git**
98 173
2. Sign using the included `sign-my-commit` script
99 174
100
-If you cannot get the above to work you may also:
175
+If you cannot get the above to work you may also:
101 176
102 177
3. Manually sign using the generic ssh-keygen method
103 178
4. Manual sign using specific methods for rsa or ecdsa
... ...
@@ -157,11 +232,11 @@ If you had already pushed your change to gitea, you must also do a force push (`
157 232
158 233
Verifying an ssh signature is slightly more complicated than with gpg keys, please see the guides linked above.
159 234
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.
235
+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 236
162 237
### Sign using the `sign-my-commit` script
163 238
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.
239
+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 240
166 241
*Tip: use `./sign-my-commit --help` to see all options*
167 242
... ...
@@ -198,11 +273,11 @@ Use the following to sign the latest `<commit hash>` (that you found using `git
198 273
echo "<commit hash>" | ssh-keygen -Y sign -f <private key file> -n dn42
199 274
```
200 275
201
-Post the signature into 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.
276
+Post the signature into 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.
202 277
203 278
#### Verifying the signature
204 279
205
-The following procedure will verify the signature (using the `<commit hash>`, your `<pubkey>` and the `<signature>` generated in the previous step.
280
+The following procedure will verify the signature (using the `<commit hash>`, your `<pubkey>` and the `<signature>` generated in the previous step.
206 281
207 282
Create a temporary file containing the signature
208 283
```sh
... ...
@@ -234,7 +309,7 @@ Please try and upgrade your ssh-keygen version and use the generic ssh-keygen me
234 309
```conf
235 310
auth: ssh-rsa <pubkey>
236 311
```
237
-Where `<pubkey>` is the ssh public key copied from your id_rsa.pub file.
312
+Where `<pubkey>` is the ssh public key copied from your id_rsa.pub file.
238 313
239 314
#### Signing your commits
240 315
... ...
@@ -248,11 +323,11 @@ openssl pkeyutl \
248 323
-in <(echo "<commit hash>") | base64
249 324
```
250 325
251
-Post the signature into 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.
326
+Post the signature into 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.
252 327
253 328
#### Verifying the signature
254 329
255
-The following script will verify the signature (using the `<commit hash>`, your rsa `<pubkey>` and the `<signature>` generated in the previous step.
330
+The following script will verify the signature (using the `<commit hash>`, your rsa `<pubkey>` and the `<signature>` generated in the previous step.
256 331
```sh
257 332
openssl pkeyutl \
258 333
-verify \
... ...
@@ -272,16 +347,16 @@ openssl pkeyutl \
272 347
```conf
273 348
auth: ecdsa-sha2-nistp256 <pubkey>
274 349
```
275
-Where `<pubkey>` is the ssh public key copied from your id_ecdsa.pub file.
350
+Where `<pubkey>` is the ssh public key copied from your id_ecdsa.pub file.
276 351
277 352
#### Signing your commits
278 353
279 354
If you cannot use the generic SSH process described above then ecdsa signatures can also be created using openssl.
280 355
281
-**DO NOT do this on your original ssh key.**
356
+**DO NOT do this on your original ssh key.**
282 357
Make a copy and use the copy as the ssh-keygen command below will overwrite the key file given.
283 358
284
-Convert your private ssh key to a file that openssl can read:
359
+Convert your private ssh key to a file that openssl can read:
285 360
**DO THIS ON A COPY OF YOUR SSH KEY**
286 361
```sh
287 362
ssh-keygen -p -m pem -f <private key file copy>
... ...
@@ -294,11 +369,11 @@ openssl pkeyutl -sign \
294 369
-in <(echo "<commit hash>") | base64
295 370
```
296 371
297
-Post the signature into 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.
372
+Post the signature into 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.
298 373
299 374
#### Verifying the signature
300 375
301
-The following script will verify the signature (using the `<commit hash>`, your ecdsa `<pubkey>` and the `<signature>` generated in the previous step.
376
+The following script will verify the signature (using the `<commit hash>`, your ecdsa `<pubkey>` and the `<signature>` generated in the previous step.
302 377
```sh
303 378
openssl pkeyutl \
304 379
-verify \
... ...
@@ -309,5 +384,5 @@ openssl pkeyutl \
309 384
-m PKCS8 \
310 385
-f <(echo "ecdsa-sha2-nistp256 <pubkey>")\
311 386
) \
312
- -sigfile <(echo "<signature>" | base64 -d)
387
+ -sigfile <(echo "<signature>" | base64 -d)
313 388
```