Documentation for OSSN-0075 mitigation

Updates the Glance Administration Guide and adds a release note.

Depends-on: https://review.openstack.org/#/c/579507/
Change-Id: I87343b67614da8dea3a09b10456f4bfc0042ed0e

doc/source/admin/db.rst

@@ -16,6 +16,9 @@
 Database Management
 ===================
 
+Updating and Migrating the Database
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
 The default metadata driver for Glance uses `SQLAlchemy`_, which implies there
 exists a backend database which must be managed. The ``glance-manage`` binary
 provides a set of commands for making this easier.
@@ -128,3 +131,93 @@ upgrade, you should make a full database backup of your production data. As of
 the OpenStack Kilo release (April 2013), database downgrades are not supported,
 and the only method available to get back to a prior database version is to
 restore from backup.
+
+Database Maintenance
+~~~~~~~~~~~~~~~~~~~~
+
+Like most OpenStack systems, Glance performs *soft* deletions when it deletes
+records from its database.  Depending on usage patterns in your cloud, you may
+occasionally want to actually remove such soft deleted table rows.  This
+operation is called *purging* the database, and you can use the
+``glance-manage`` tool to do this.
+
+High-Level Database Architecture
+--------------------------------
+
+Roughly, what we've got in the glance database is an **images** table that
+stores the image **id** and some other core image properties.  All the other
+information about the image (for example: where the image data is stored in
+the backend, what projects an image has been shared with, image tags, custom
+image properties) is stored in other tables in which the **image id** is
+a foreign key.
+
+Because the **images** table keeps track of what image identifiers have been
+issued, it must be treated differently from the other tables with respect to
+purging the database.
+
+.. note::
+   Before the Rocky release (17.0.0), the **images** table was *not* treated
+   differently, which made Glance vulnerable to `OSSN-0075
+   <https://wiki.openstack.org/wiki/OSSN/OSSN-0075>`_, "Deleted Glance image
+   IDs may be reassigned".  Please read through that OpenStack Security
+   Note to understand the nature of the problem.
+
+   Additionally, the Glance spec `Mitigate OSSN-0075
+   <https://specs.openstack.org/openstack/glance-specs/specs/rocky/approved/glance/mitigate-ossn-0075.html>`_
+   contains a discussion of the issue and explains the changes made to the
+   ``glance-manage`` tool for the Rocky release.  The `Gerrit review of the
+   spec <https://review.openstack.org/468179>`_ contains an extensive
+   discussion of several alternative approaches and will give you an idea of
+   why the Glance team provided a "mitigation" instead of a fix.
+
+Purging the Database
+--------------------
+
+You can use the ``glance-manage`` tool to purge the soft-deleted rows from
+all tables *except* the images table::
+
+   glance-manage db purge
+
+This command takes two optional parameters:
+
+--age_in_days NUM    Only purge rows that have been deleted for longer
+                     than *NUM* days.  The default is 30 days.
+
+--max_rows NUM       Purge a maximum of *NUM* rows from each table.
+                     The default is 100.
+
+
+Purging the Images Table
+------------------------
+
+Remember that image identifiers are used by other OpenStack services that
+require access to images.  These services expect that when an image is
+requested by ID, they will receive the same data every time.  When the
+**images** table is purged of its soft-deleted rows, Glance loses its
+memory that those image IDs were ever mapped to some particular payload.
+Thus, care must be taken in purging the **images** table.  We recommend
+that it be done much less frequently than the "regular" purge operation.
+
+Use the following command to purge the images table::
+
+    glance-manage db purge_images_table
+
+Be sure you have read and understood the implications of `OSSN-0075
+<https://wiki.openstack.org/wiki/OSSN/OSSN-0075>`_ before you use this
+command, which purges the soft-deleted rows from the images table.
+
+It takes two optional parameters:
+
+--age_in_days NUM    Only purge rows that have been deleted for longer
+                     than *NUM* days.  The default is 180 days.
+
+--max_rows NUM       Purge a maximum of *NUM* rows from the **images** table.
+                     The default is 100.
+
+It is possible for this command to fail with an IntegrityError saying
+something like "Cannot delete or update a parent row: a foreign key
+constraint fails".  This can happen when you try to purge records from
+the **images** table when related records have not yet been purged from
+other tables.  The ``purge_images_table`` command should only be issued
+after all related information has been purged using the "regular" ``purge``
+command.

releasenotes/notes/bp-mitigate-ossn-0075-c0e74e60d86d8ea2.yaml

@@ -0,0 +1,12 @@
+---
+prelude: >
+  - The ``glance-manage`` utility has been updated to address OpenStack
+    Security Note OSSN-0075.
+security:
+  - |
+    The ``glance-manage`` tool has been updated to address `OSSN-0075`_.
+    Please see the `Database Maintenance`_ section of the Glance
+    Administration Guide for details.
+
+    .. _`OSSN-0075`: https://wiki.openstack.org/wiki/OSSN/OSSN-0075
+    .. _`Database Maintenance`: https://docs.openstack.org/glance/latest/admin/db.html#database-maintenance