howto/Registry-Authentication.md
... ...
@@ -0,0 +1,172 @@
1
+# How Authentication Works
2
+
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
+
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
+
7
+The signature and verification process varies depending on the type of public key within the `auth` attribute.
8
+
9
+#### Finding the commit hash
10
+
11
+`git log` will list all the recent commits and show the commit hash:
12
+```
13
+commit 6e2e9ac540e2e4e3c3a135ad90c8575bb8fa1784 (HEAD -> master)
14
+Author: foo <[email protected]>
15
+Date: Mon Jan 01 01:01:01 2020 +0000
16
+
17
+ Change some stuff
18
+```
19
+
20
+## Authentication with PGP Key
21
+
22
+PGP keys may be uploaded to a public keyserver for verification, or added in the registry.
23
+
24
+#### Using a public keyserver
25
+
26
+- Use the following `auth` attribute in your `mntner` object:
27
+```
28
+auth: pgp-fingerprint <fingerprint>
29
+```
30
+Where `<fingerprint>` is your full 40-digit key fingerprint, without spaces.
31
+
32
+- 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/).
33
+
34
+#### Adding to the registry
35
+
36
+- Use the following `auth` attribute in your `mntner` object:
37
+```
38
+auth: PGPKEY-<fprint>
39
+```
40
+Where `<fprint>` is the last 8 digits from your key fingerprint.
41
+
42
+- 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.
43
+
44
+#### Signing your commits
45
+
46
+- 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).
47
+
48
+- If you have already committed your change, you can sign it using.
49
+```
50
+git commit --amend --no-edit -S
51
+```
52
+
53
+#### Verifying the signature
54
+
55
+- Use `git log --show-signature` to show recent commits and signatures.
56
+
57
+## Authentication with an SSH RSA key
58
+
59
+- Use the following `auth` attribute in your `mntner` object:
60
+```
61
+auth: ssh-rsa <pubkey>
62
+```
63
+Where `<pubkey>` is the ssh public key copied from your id_rsa.pub file.
64
+
65
+#### Signing your commits
66
+
67
+Use the following to sign your `<commit hash>`
68
+```sh
69
+openssl pkeyutl \
70
+ -sign \
71
+ -inkey ~/.ssh/id_rsa \
72
+ -in <(echo "<commit hash>") | base64
73
+```
74
+
75
+Post the signature in to the 'Conversation' section of your pull request to allow the registry maintainers to verify it.
76
+
77
+#### Verifying the signature
78
+
79
+The following script will verify the signature (using the `<commit hash>`, your rsa `<pubkey>` and the `<signature>` generated in the previous step.
80
+```sh
81
+openssl pkeyutl \
82
+ -verify \
83
+ -pubin \
84
+ -in <(echo "<commit hash>") \
85
+ -inkey <(ssh-keygen \
86
+ -e \
87
+ -m PKCS8 \
88
+ -f <(echo "ssh-rsa <pubkey>")\
89
+ ) \
90
+ -sigfile <(echo "<signature>" | base64 -d)
91
+```
92
+
93
+## Authentication with an SSH ed25519 key
94
+
95
+- Use the following `auth` attribute in your `mntner` object:
96
+```
97
+auth: ssh-ed25519 <pubkey>
98
+```
99
+Where `<pubkey>` is the ssh public key copied from your id_ed25519.pub file.
100
+
101
+#### Signing your commits
102
+
103
+OpenSSH v8 introduced new functionality for signatures using SSH keys, and you must use a recent version to generate ed25519 signatures. If necessary compile the latest ssh-keygen from the [openssh-portable repo](https://github.com/openssh/openssh-portable).
104
+
105
+Use the following to sign your `<commit hash>`
106
+```sh
107
+echo "<commit hash>" | ssh-keygen -Y sign -f ~/.ssh/id_ed25519 -n dn42
108
+```
109
+
110
+Post the signature in to the 'Conversation' section of your pull request to allow the registry maintainers to verify it.
111
+
112
+#### Verifying the signature
113
+
114
+The following procedure will verify the signature (using the `<commit hash>`, your rsa `<pubkey>` and the `<signature>` generated in the previous step.
115
+
116
+Create a temporary file containing the signature
117
+```sh
118
+echo "<signature>" > sig.tmp
119
+```
120
+Create a temporary 'allowed users' file
121
+```sh
122
+echo "YOU-MNT ssh-ed25519 <pubkey>" > allowed.tmp
123
+```
124
+Verify the signature
125
+```sh
126
+echo "<commit hash>" | \
127
+ ssh-keygen -Y verify -f allowed.tmp -n dn42 -I YOU-MNT -s sig.tmp
128
+```
129
+
130
+## Authentication with an SSH ecdsa key
131
+
132
+- Use the following `auth` attribute in your `mntner` object:
133
+```
134
+auth: ecdsa-sha2-nistp256 <pubkey>
135
+```
136
+Where `<pubkey>` is the ssh public key copied from your id_ecdsa.pub file.
137
+
138
+#### Signing your commits
139
+
140
+**DO NOT do this on your original ssh key.**
141
+Make a copy and use the copy as the ssh-keygen command below will overwrite the key file given.
142
+
143
+Convert your private ssh key to a file that openssl can read:
144
+**DO THIS ON A COPY OF YOUR SSH KEY**
145
+```sh
146
+ssh-keygen -p -m pem -f <private key file copy>
147
+```
148
+
149
+Sign the commit hash using your ecdsa key, using openssl:
150
+```sh
151
+openssl pkeyutl -sign \
152
+ -inkey <converted key file> \
153
+ -in <(echo "<commit hash>") | base64
154
+```
155
+
156
+Post the signature in to the 'Conversation' section of your pull request to allow the registry maintainers to verify it.
157
+
158
+#### Verifying the signature
159
+
160
+The following script will verify the signature (using the `<commit hash>`, your rsa `<pubkey>` and the `<signature>` generated in the previous step.
161
+```sh
162
+openssl pkeyutl \
163
+ -verify \
164
+ -pubin \
165
+ -in <(echo "<commit hash>") \
166
+ -inkey <(ssh-keygen \
167
+ -e \
168
+ -m PKCS8 \
169
+ -f <(echo "ecdsa-sha2-nistp256 <pubkey>")\
170
+ ) \
171
+ -sigfile <(echo "<signature>" | base64 -d)
172
+```