--- a/doc/security.txt	Mon Nov 07 22:58:38 2022 -0500
+++ b/doc/security.txt	Thu Jun 08 00:10:32 2023 -0400
@@ -1,157 +1,139 @@
-===================
-Security Mechanisms
-===================
-
-Current situation
-=================
-
-Current logical controls:
-
-ANONYMOUS_ACCESS = 'deny'
- Deny or allow anonymous access to the web interface
-ANONYMOUS_REGISTER = 'deny'
- Deny or allow anonymous users to register through the web interface
-ANONYMOUS_REGISTER_MAIL = 'deny'
- Deny or allow anonymous users to register through the mail interface
-
-Current user interface authentication and controls:
+.. meta::
+    :description:
+        Documentation on how to report security issues with
+        Roundup. Also index to security related portions in other
+        Roundup documentation. How to verify distribution using gpg.
 
-- command-line tool access controlled with passwords, but no logical controls
-- CGI access is by username and password and has some logical controls
-- mailgw access is through identification using sender email address, with
-  limited functionality available
-
-The web interface implements has specific logical controls,
-preventing non-admin users from accessing:
-
- - other user's details pages
- - listing the base classes (not issues or their user page)
- - editing base classes
-
-Issues
-======
-
-1. The current implementation is ad-hoc, and not complete for all use cases.
-2. Currently it is not possible to allow submission of issues through email
-   but restrict those users from accessing the web interface.
-3. Only one user may perform admin functions.
-4. There is no verification of users in the mail gateway by any means other
-   than the From address. Support for strong identification through digital
-   signatures should be added.
-5. The command-line tool has no logical controls.
-6. The anonymous control needs revising - there should only be one way to be
-   an anonymous user, not two (currently there is user==None and
-   user=='anonymous').
+.. index::
+   single: Reporting Security Issues
+   single: Security Issues, Reporting
 
 
-Possible approaches
-===================
+=======================
+Roundup Security Issues
+=======================
 
-Security controls in Roundup could be approached in three ways:
+This page documents how to report security issues and verify the
+signatures for Roundup releases.
+
+Reporting Security Issues
+-------------------------
+Security issues with Roundup should be reported by email to:
 
-1) at the hyperdb level, with read/write/modify permissions on classes, items
-   and item properties for all or specific transitions.
-2) at the user interface level, with access permissions on CGI interface
-   methods, mailgw methods, roundup-admin methods, and so on.
-3) at a logical permission level, checked as needed.
+   rouilj@users.sourceforge.net  (John Rouillard)
+
+   rsc@runtux.com (Ralf Schlatterbeck)
 
-In all cases, the security built into roundup assumes restricted access to the
-hyperdatabase itself, through operating-system controls such as user or group
-permissions.
+If these fail, you can find rouilj on irc in channel #roundup at
+irc.oftc.net (see Contact_ for more directions and web
+interface). Methods listed at Contact_ are all public, so they should
+be used to contact somebody with the Roundup project for establishing
+a proper method of reporting the security issue.
 
+.. _Contact: https://www.roundup-tracker.org/contact.html
 
-Hyperdb-level control
+Verify Source Tarball
 ---------------------
 
-Control is implemented at the Class.get, Class.set and Class.create level. All
-other methods must access items through these methods. Since all accesses go
-through the database, we can implement deny by default.
+.. index::
+   single: Distribution, verify with gpg
+   single: Signature, verify
+
+If you download the source tarball using ``python3 -m pip download
+roundup`` or from https://pypi.org/project/roundup/#files you can
+verify the file using gpg.
+
+This is the information on the public PGP/GPG key used to sign Roundup
+distributions.  It is used to sign the 1.6.0, 2.2.0, and newer
+releases. (Note that the @ sign in email addresses have been replaced
+with the word "at" to reduce spam directed at the mailing list.)::
 
-Pros:
+  Key info: Roundup Team (signing key for roundup releases)
+      <roundup-devel at lists.sourceforge.net>
+  Expires: 2028-07-17
+  Key fingerprint = 411E 354B 5D1A F261 25D6  2122 1F2D D0CB 756A 76D8
+
+Releases 1.6.1, 2.0.0 and 2.1.0 were accidentally signed with this key
+[1]_::
+
+  Key info: John Rouillard (Roundup Release Key)
+      <rouilj+roundup at ieee.org>
+  Expires: 2023-07-09
+  Key fingerprint =  A1E6 364E 9429 E9D8 2B3B 2373 DB05 ADC4 2330 5876
 
-   - easier to implement as it only affects one module
-   - smaller number of permissions to worry about
+.. [1] Use gpg to import this key from the keyserver pgp.mit.edu
+       if you need to verify one of these releases. Use the gpg
+       pgp.mit.edu keyserver example replacing the key fingerprint
+       with the one starting A1E6.
 
-Cons:
+Importing the Public Key
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+This only has to be added to your keyring once. You can import a key
+from pgp.mit.edu using::
+
+   gpg --keyserver pgp.mit.edu --receive-keys 411E354B5D1AF26125D621221F2DD0CB756A76D8
 
-   - harder to determine the relationship between user interaction and hyperdb
-     permission.
-   - a lot of work to define
-   - must special-case to handle by-item permissions (editing user details,
-     having private messages)
+where the fingerprint (without spaces) is used to identify which key
+to receive. You can also extract and import the file
+``tools/roundup.public.pgp.key`` from the download source tarball
+using::
+
+  tar -xzvf roundup-2.2.0.tar.gz -O \
+     roundup-2.2.0/tools/roundup.public.pgp.key > pub.key
+
+  gpg --import pub.key
+
+Once you have loaded the public key, you need a detached signature for
+your release.
 
 
-User-interface control
-----------------------
+Download and Verify with Detached Signature
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This needs to be done once for each release you wish to verify.
 
-The user interfaces would have an extra layer between that which
-parses the request to determine action and the action method. This layer
-controls access. Since it is possible to require methods be registered
-with the security mechanisms to be accessed by the user, deny by default
-is possible.
+The Python Package Index (PyPI) used to support uploading gpg detached
+signatures. However that is no longer supported and downloading
+existing signatures may not work in the future.
 
-Pros:
-
-   - much more obvious at the user level what the controls are
-
-Cons:
+As a result, the signatures for all Roundup final releases starting
+with 1.6.0 have been moved and are linked below:
 
-   - much more work to implement
-   - most user interfaces have multiple uses which can't be covered by a
-     single permission
-
-Logical control
----------------
+.. rst-class:: multicol
 
-At each point that requires an action to be performed, the security mechanisms
-are asked if the current user has permission. Since code must call the
-check function to raise a denial, there is no possibility to have automatic
-default of deny in this situation.
+* `2.3.0b2 <../signatures/roundup-2.3.0b2.tar.gz.asc>`_
+* `2.2.0 <../signatures/roundup-2.2.0.tar.gz.asc>`_
+* `2.1.0 <../signatures/roundup-2.1.0.tar.gz.asc>`_
+* `2.0.0 <../signatures/roundup-2.0.0.tar.gz.asc>`_
+* `1.6.1 <../signatures/roundup-1.6.1.tar.gz.asc>`_
+* `1.6.0 <../signatures/roundup-1.6.0.tar.gz.asc>`_
 
-Pros:
-
-   - quite obvious what is going on
-   - is very similar to the current system
-
-Cons:
+To use the signature, download the correct versioned link and verify
+it with (note 1.5.7 is a dummy version, use the correct version
+number)::
 
-   - large number of possible permissions that may be defined, possibly
-     mirroring actual user interface controls.
-   - access to the hyperdb must be strictly controlled through program code
-     that implements the logical controls.
+  gpg --verify roundup-1.5.7.tar.gz.asc roundup-1.5.7.tar.gz
 
+You should see::
 
-Action
-======
-
-The CGI interface must be changed to:
-
-- authenticate over a secure connection
-- use unique tokens as a result of authentication, rather than pass the user's
-  real credentials (username/password) around for each request (this means
-  sessions and hence a session database)
-- use the new logical control mechanisms
+  gpg: Signature made Wed 13 Jul 2022 12:24:14 AM EDT
+  gpg:                using RSA key 411E354B5D1AF26125D621221F2DD0CB756A76D8
+  gpg: Good signature from "Roundup Team (signing key for roundup releases) <roundup-devel at lists.sourceforge.net>" [unknown]
+  gpg: WARNING: This key is not certified with a trusted signature!
+  gpg:          There is no indication that the signature belongs to the owner.
+  Primary key fingerprint: 411E 354B 5D1A F261 25D6  2122 1F2D D0CB 756A 76D8
 
-  - implement the permission module
-  - implement a Role editing interface for users
-  - implement htmltemplate tests on permissions
-  - switch all code over from using config vars for permission checks to using
-    permissions
-  - change all explicit admin user checks for Role checks
-  - include config vars for initial Roles for anonymous web, new web and new
-    email users
+which verifies the tarball integrity. The WARNING is expected and the
+date corresponds to the newest renewal of the Roundup key. As long as
+you see the output starting with "Good signature from" followed by the
+Key Info for your key, everything is OK.
 
-The mail gateway must be changed to:
+If something is wrong you will see::
 
-- use digital signatures
-- use the new logical control mechanisms
-
-  - switch all code over from using config vars for permission checks to using
-    permissions
+  gpg: Signature made Wed 13 Jul 2022 12:24:14 AM EDT
+  gpg:                using RSA key 411E354B5D1AF26125D621221F2DD0CB756A76D8
+  gpg: BAD signature from "Roundup Team (signing key for roundup releases) <roundup-devel at lists.sourceforge.net>"
 
-The command-line tool must be changed to:
-
-- use the new logical control mechanisms (only allowing write
-  access by admin users, and read-only by everyone else)
-
-
+**do not use** the tarball if the signature is BAD. Email the
+roundup-devel mailing list if you have this happen to you.