Changes in 922d7e1: Updated Registry Authentication (markdown)

howto/Registry-Authentication.md

@@ -54,7 +54,44 @@ git commit --amend --no-edit -S

 - Use `git log --show-signature` to show recent commits and signatures.

-## Authentication with an SSH RSA key

+## Authentication using an SSH key

+

+The generic format for authentication using an SSH key is as follows:

+```

+auth: ssh-<keytype> <pubkey>

+```

+There are examples below for each specific key type.

+

+#### Generic process for signing with an SSH key

+

+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).

+

+Use the following to sign the latest `<commit hash>` (that you found using `git log`)

+```sh

+echo "<commit hash>" | ssh-keygen -Y sign -f <private key file> -n dn42

+```

+

+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. 

+

+#### Verifying the signature

+

+The following procedure will verify the signature (using the `<commit hash>`, your `<pubkey>` and the `<signature>` generated in the previous step. 

+

+Create a temporary file containing the signature

+```sh

+echo "<signature>" > sig.tmp

+```

+Create a temporary 'allowed users' file

+```sh

+echo "YOU-MNT ssh-<keytype> <pubkey>" > allowed.tmp

+```

+Verify the signature

+```sh

+echo "<commit hash>" | \

+ ssh-keygen -Y verify -f allowed.tmp -n dn42 -I YOU-MNT -s sig.tmp

+```

+

+### Authentication with an SSH RSA key

 - Use the following `auth` attribute in your `mntner` object:

 ```

@@ -64,7 +101,9 @@ Where `<pubkey>` is the ssh public key copied from your id_rsa.pub file.

 #### Signing your commits

-Use the following to sign your `<commit hash>`

+If you cannot use the generic SSH process described above then RSA signatures can also be created using openssl.

+

+Use the following to sign your `<commit hash>` (that you found using `git log`)

 ```sh

 openssl pkeyutl \

 -sign \

@@ -72,7 +111,7 @@ openssl pkeyutl \

 -in <(echo "<commit hash>") | base64

 ```

-Post the signature in to the 'Conversation' section of your pull request to allow the registry maintainers to verify it.

+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. 

 #### Verifying the signature

@@ -90,7 +129,7 @@ openssl pkeyutl \

 -sigfile <(echo "<signature>" | base64 -d)

 ```

-## Authentication with an SSH ed25519 key

+### Authentication with an SSH ed25519 key

 - Use the following `auth` attribute in your `mntner` object:

 ```

@@ -100,18 +139,18 @@ Where `<pubkey>` is the ssh public key copied from your id_ed25519.pub file.

 #### Signing your commits

-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).

+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. 

-Use the following to sign your `<commit hash>`

+Use the following to sign your `<commit hash>` (that you found using `git log`)

 ```sh

 echo "<commit hash>" | ssh-keygen -Y sign -f ~/.ssh/id_ed25519 -n dn42

 ```

-Post the signature in to the 'Conversation' section of your pull request to allow the registry maintainers to verify it.

+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. 

 #### Verifying the signature

-The following procedure will verify the signature (using the `<commit hash>`, your rsa `<pubkey>` and the `<signature>` generated in the previous step. 

+The following procedure will verify the signature (using the `<commit hash>`, your ed25519 `<pubkey>` and the `<signature>` generated in the previous step. 

 Create a temporary file containing the signature

 ```sh

@@ -127,7 +166,7 @@ echo "<commit hash>" | \

 ssh-keygen -Y verify -f allowed.tmp -n dn42 -I YOU-MNT -s sig.tmp

 ```

-## Authentication with an SSH ecdsa key

+### Authentication with an SSH ecdsa key

 - Use the following `auth` attribute in your `mntner` object:

 ```

@@ -137,6 +176,8 @@ Where `<pubkey>` is the ssh public key copied from your id_ecdsa.pub file.

 #### Signing your commits

+If you cannot use the generic SSH process described above then ecdsa signatures can also be created using openssl.

+

 **DO NOT do this on your original ssh key.** 

 Make a copy and use the copy as the ssh-keygen command below will overwrite the key file given.

@@ -153,11 +194,11 @@ openssl pkeyutl -sign \

 -in <(echo "<commit hash>") | base64

 ```

-Post the signature in to the 'Conversation' section of your pull request to allow the registry maintainers to verify it.

+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. 

 #### Verifying the signature

-The following script will verify the signature (using the `<commit hash>`, your rsa `<pubkey>` and the `<signature>` generated in the previous step. 

+The following script will verify the signature (using the `<commit hash>`, your ecdsa `<pubkey>` and the `<signature>` generated in the previous step. 

 ```sh

 openssl pkeyutl \

 -verify \

...	...	@@ -54,7 +54,44 @@ git commit --amend --no-edit -S
54	54
55	55	- Use `git log --show-signature` to show recent commits and signatures.
56	56
57		-## Authentication with an SSH RSA key
	57	+## Authentication using an SSH key
	58	+
	59	+The generic format for authentication using an SSH key is as follows:
	60	+```
	61	+auth: ssh-<keytype> <pubkey>
	62	+```
	63	+There are examples below for each specific key type.
	64	+
	65	+#### Generic process for signing with an SSH key
	66	+
	67	+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).
	68	+
	69	+Use the following to sign the latest `<commit hash>` (that you found using `git log`)
	70	+```sh
	71	+echo "<commit hash>" \| ssh-keygen -Y sign -f <private key file> -n dn42
	72	+```
	73	+
	74	+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.
	75	+
	76	+#### Verifying the signature
	77	+
	78	+The following procedure will verify the signature (using the `<commit hash>`, your `<pubkey>` and the `<signature>` generated in the previous step.
	79	+
	80	+Create a temporary file containing the signature
	81	+```sh
	82	+echo "<signature>" > sig.tmp
	83	+```
	84	+Create a temporary 'allowed users' file
	85	+```sh
	86	+echo "YOU-MNT ssh-<keytype> <pubkey>" > allowed.tmp
	87	+```
	88	+Verify the signature
	89	+```sh
	90	+echo "<commit hash>" \| \
	91	+ ssh-keygen -Y verify -f allowed.tmp -n dn42 -I YOU-MNT -s sig.tmp
	92	+```
	93	+
	94	+### Authentication with an SSH RSA key
58	95
59	96	- Use the following `auth` attribute in your `mntner` object:
60	97	```
...	...	@@ -64,7 +101,9 @@ Where `<pubkey>` is the ssh public key copied from your id_rsa.pub file.
64	101
65	102	#### Signing your commits
66	103
67		-Use the following to sign your `<commit hash>`
	104	+If you cannot use the generic SSH process described above then RSA signatures can also be created using openssl.
	105	+
	106	+Use the following to sign your `<commit hash>` (that you found using `git log`)
68	107	```sh
69	108	openssl pkeyutl \
70	109	-sign \
...	...	@@ -72,7 +111,7 @@ openssl pkeyutl \
72	111	-in <(echo "<commit hash>") \| base64
73	112	```
74	113
75		-Post the signature in to the 'Conversation' section of your pull request to allow the registry maintainers to verify it.
	114	+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.
76	115
77	116	#### Verifying the signature
78	117
...	...	@@ -90,7 +129,7 @@ openssl pkeyutl \
90	129	-sigfile <(echo "<signature>" \| base64 -d)
91	130	```
92	131
93		-## Authentication with an SSH ed25519 key
	132	+### Authentication with an SSH ed25519 key
94	133
95	134	- Use the following `auth` attribute in your `mntner` object:
96	135	```
...	...	@@ -100,18 +139,18 @@ Where `<pubkey>` is the ssh public key copied from your id_ed25519.pub file.
100	139
101	140	#### Signing your commits
102	141
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).
	142	+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.
104	143
105		-Use the following to sign your `<commit hash>`
	144	+Use the following to sign your `<commit hash>` (that you found using `git log`)
106	145	```sh
107	146	echo "<commit hash>" \| ssh-keygen -Y sign -f ~/.ssh/id_ed25519 -n dn42
108	147	```
109	148
110		-Post the signature in to the 'Conversation' section of your pull request to allow the registry maintainers to verify it.
	149	+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.
111	150
112	151	#### Verifying the signature
113	152
114		-The following procedure will verify the signature (using the `<commit hash>`, your rsa `<pubkey>` and the `<signature>` generated in the previous step.
	153	+The following procedure will verify the signature (using the `<commit hash>`, your ed25519 `<pubkey>` and the `<signature>` generated in the previous step.
115	154
116	155	Create a temporary file containing the signature
117	156	```sh
...	...	@@ -127,7 +166,7 @@ echo "<commit hash>" \| \
127	166	ssh-keygen -Y verify -f allowed.tmp -n dn42 -I YOU-MNT -s sig.tmp
128	167	```
129	168
130		-## Authentication with an SSH ecdsa key
	169	+### Authentication with an SSH ecdsa key
131	170
132	171	- Use the following `auth` attribute in your `mntner` object:
133	172	```
...	...	@@ -137,6 +176,8 @@ Where `<pubkey>` is the ssh public key copied from your id_ecdsa.pub file.
137	176
138	177	#### Signing your commits
139	178
	179	+If you cannot use the generic SSH process described above then ecdsa signatures can also be created using openssl.
	180	+
140	181	DO NOT do this on your original ssh key.
141	182	Make a copy and use the copy as the ssh-keygen command below will overwrite the key file given.
142	183
...	...	@@ -153,11 +194,11 @@ openssl pkeyutl -sign \
153	194	-in <(echo "<commit hash>") \| base64
154	195	```
155	196
156		-Post the signature in to the 'Conversation' section of your pull request to allow the registry maintainers to verify it.
	197	+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.
157	198
158	199	#### Verifying the signature
159	200
160		-The following script will verify the signature (using the `<commit hash>`, your rsa `<pubkey>` and the `<signature>` generated in the previous step.
	201	+The following script will verify the signature (using the `<commit hash>`, your ecdsa `<pubkey>` and the `<signature>` generated in the previous step.
161	202	```sh
162	203	openssl pkeyutl \
163	204	-verify \