Merge branch 'main' into 'main'

add x-add-key command, add example how to update your key to subscribers docu

See merge request !98

schleuder/docs/subscribers.md

@@ -6,16 +6,79 @@ title: Documentation for subscribers
 
 {% include_relative _list_usage_basics.md %}
 
+   
+
+
 #### Subscription and key management
 
-The following keywords must be send to the request address of the list: `foo-request@hostname`.
+The following keywords must be send to the request address of the list: `foo-request@hostname`.  
+Include `x-list-name: foo@hostname` with every command you send.
 
-x-set-fingerprint: 0x12345678DEADBEEF12345678DEADBEEF12345678
+**x-add-key:**  
+: Import the attachment(s) or the rest of the email-body into the list’s keyring. Only ascii-armored keys are supported.
+
+**x-set-fingerprint:** 0x12345678DEADBEEF12345678DEADBEEF12345678
 : Assign the key with the given fingerprint to your subscription. It is not possible to set an empty fingerprint. To unset your fingerprint use `x-unset-fingerprint`.
 
-x-unset-fingerprint: person@example.org
+**x-unset-fingerprint:** person@example.org
 : Remove the fingerprint associated with your subscription.
 
+   
+
+
+#### Example: Updating your key for a list
+
+All commands to switch to a **new** key must be signed with the current **old** key. 
+
+##### 1. submit new key to lists keyring
+
+```
+x-list-name: foo@hostname
+x-add-key
+
+-----BEGIN PGP PUBLIC KEY BLOCK-----
+
+ASak6ezpIZkSZ/ql7UOiOIxi7dAWg4YwFB+yrkN+aUi9Io+No1Y0Rjz+/pUIvGx7
+KbyhUQjE6wvGJKDqWyLQVoyB+R0ZV3k6lQFqa7TETXCoGuU8CRM4XcynU7MNgGFQ
+...
+mDMEXuYDuxYJKwYBBAHaRw8BAQdAqP98Ao=
+=32SG
+-----END PGP PUBLIC KEY BLOCK-----
+```
+
+A successful answer should look something like this:
+> This key was newly added:
+> 0x12345678DEADBEEF12345678DEADBEEF12345678 youraccount@yourmail.net 2019-05-23 [expires: 2023-05-23] 
+
+##### 2. verify that uploaded key made it into the keyring
+
+```
+x-list-name: foo@hostname
+x-list-keys
+```
+The answer will be a list of all keys in the lists keyring.
+Make sure, your **new** key is in the keyring now.
+
+##### 3. change you subscription to use the new key
+
+```
+x-list-name: foo@hostname
+x-set-fingerprint: 0x12345678DEADBEEF12345678DEADBEEF12345678
+```
+
+A successful answer should look something like this:
+> Fingerprint for youraccount@yourmail.net set to 12345678DEADBEEF12345678DEADBEEF12345678.
+
+From now on, all mails will be encrpyted to the **new** key
+and all your mails must be signed with this key.
+
+##### One caveat: disabled commands 
+To further improve security and confidentiality, list-admins can manually **disable certain commands**
+like `x-add-key` for mere subscribers of the list. With these commands disabled for you,
+you have to rely on the list-admin for key management. 
+
+   
+
 #### Resending
 
 The resending-keywords must be included in messages sent to the normal list-address: `foo@hostname`.