910a109e2dd11a1cecc4b3028a2bae79cdce5fbc
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 | +``` |