1 files changed, 67 insertions, 3 deletions

diff --git a/src/mailman_pgp/commands/eml_key.py b/src/mailman_pgp/commands/eml_key.py
index deb396a..4bce1cf 100644
--- a/src/mailman_pgp/commands/eml_key.py
+++ b/src/mailman_pgp/commands/eml_key.py
@@ -47,6 +47,17 @@ def _get_email(msg):
 
 
 def _cmd_set(pgp_list, mlist, msg, msgdata, arguments, results):
+    """
+    `key set "token"` command.
+
+    Used during the subscription to a PGP enabled mailing list, if the user
+    didn't already setup a `PGPaddress`.
+
+     * This command message CAN be encrypted to the list key, in which case it
+     will be decrypted.
+     * This command message MUST have exactly one transferrable PGP public key
+     attached (either PGP/MIME or inline PGP).
+    """
     if len(arguments) != 2:
         print('Missing token.', file=results)
         return ContinueProcessing.no
@@ -98,6 +109,19 @@ def _cmd_set(pgp_list, mlist, msg, msgdata, arguments, results):
 
 
 def _cmd_confirm(pgp_list, mlist, msg, msgdata, arguments, results):
+    """
+    `key confirm "token"` command.
+
+    Used during subscription to confirm the setting of a users key, also for
+    confirming the change of a key of a subscriber after the `key change`
+    command.
+
+     * This command message CAN be encrypted to the list key, in which case it
+     will be decrypted.
+     * This command message MUST contain the appropriate statement of key
+     ownership, sent to the user after the `key set` or `key change` commands.
+     This statement MUST be singed by the users current key.
+    """
     if len(arguments) != 2:
         print('Missing token.', file=results)
         return ContinueProcessing.no
@@ -152,14 +176,26 @@ def _cmd_confirm(pgp_list, mlist, msg, msgdata, arguments, results):
 
 
 def _cmd_change(pgp_list, mlist, msg, msgdata, arguments, results):
-    # New public key in attachment, requires to be signed with current
-    # key
+    """
+    `key change` command.
+
+    Used when a user wants to change a key of a `PGPAddress`.
+
+     * This command message CAN be encrypted to the list key, in which case it
+     will be decrypted.
+     * This command message MUST have exactly one transferrable PGP public key
+     attached (either PGP/MIME or inline PGP).
+    """
     if len(arguments) != 1:
         print('Extraneous argument/s: ' + ','.join(arguments[1:]),
               file=results)
         return ContinueProcessing.no
 
     wrapped = PGPWrapper(msg)
+    if wrapped.is_encrypted():
+        decrypted = wrapped.decrypt(pgp_list.key)
+        wrapped = PGPWrapper(decrypted)
+
     if not wrapped.has_keys():
         print('No keys attached? Send a key.', file=results)
         return ContinueProcessing.no
@@ -238,8 +274,36 @@ class KeyCommand:
 
     name = 'key'
     argument_description = ARGUMENTS
-    short_description = ''
+    short_description = 'PGP key management.'
     description = """\
+    A general command for PGP key management for PGP enabled mailing lists.
+
+    `key set <token>`
+      A command used to set the address public key during subscription to a
+      mailing list. Is only required on the first subscription of a given
+      address to a PGP enabled mailing list. This command requires the command
+      message to have exactly one PGP public key attached (either PGP/MIME or
+      inline). This command should be encrypted to the mailing list public key.
+
+    `key confirm <token>`
+      A command used to confirm the setting of a new public key, either during
+      subscription or later after a `key change` command. Is only required on
+      the first subscription of a given address to a PGP enabled mailing list.
+      This command requires the command message to contain the statement sent
+      from the mailing list in response to the `key set <token>` command, and
+      requires this statement signed by the key that was attached to the `key
+      set` command message.
+
+    `key change`
+      A command used to change the address public key.
+
+    `key revoke`
+
+    `key sign`
+
+    `key receive`
+      A command used to request the list public key. The list public key will
+      be send in a response.
     """
 
     def process(self, mlist, msg, msgdata, arguments, results):