From a9565893f29626093040cb38fe4a19e855e69afa Mon Sep 17 00:00:00 2001
From: Tim Burke <tim.burke@gmail.com>
Date: Thu, 10 Feb 2022 11:17:03 -0800
Subject: [PATCH] Add docs for registry module

Drive-By: make the register_sensitive_header() implementation more
obviously case-insensitive.

Change-Id: I5b299bc0adb526c468c6364a5706eb86809533e5
---
 doc/source/misc.rst               | 10 +++++++++
 swift/common/registry.py          | 37 ++++++++++++++++++++++++++++++-
 test/unit/common/test_registry.py |  8 +++----
 3 files changed, 50 insertions(+), 5 deletions(-)

diff --git a/doc/source/misc.rst b/doc/source/misc.rst
index afa1b26b85..c418dd5ed5 100644
--- a/doc/source/misc.rst
+++ b/doc/source/misc.rst
@@ -83,6 +83,16 @@ MemCacheD
     :members:
     :show-inheritance:
 
+.. _registry:
+
+Middleware Registry
+===================
+
+.. automodule:: swift.common.registry
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
 .. _request_helpers:
 
 Request Helpers
diff --git a/swift/common/registry.py b/swift/common/registry.py
index 912d6590ba..2aa5376ae0 100644
--- a/swift/common/registry.py
+++ b/swift/common/registry.py
@@ -92,24 +92,59 @@ _sensitive_params = set()
 
 
 def get_sensitive_headers():
+    """
+    Returns the set of registered sensitive headers.
+
+    Used by :mod:`swift.common.middleware.proxy_logging` to perform redactions
+    prior to logging.
+    """
     return frozenset(_sensitive_headers)
 
 
 def register_sensitive_header(header):
+    """
+    Register a header as being "sensitive".
+
+    Sensitive headers are automatically redacted when logging. See the
+    ``reveal_sensitive_prefix`` option in the proxy-server sample config
+    for more information.
+
+    :param header: The (case-insensitive) header name which, if present, may
+        contain sensitive information. Examples include ``X-Auth-Token`` and
+        (if s3api is enabled) ``Authorization``. Limited to ASCII characters.
+    """
     if not isinstance(header, str):
         raise TypeError
     if six.PY2:
         header.decode('ascii')
     else:
         header.encode('ascii')
-    _sensitive_headers.add(header)
+    _sensitive_headers.add(header.lower())
 
 
 def get_sensitive_params():
+    """
+    Returns the set of registered sensitive query parameters.
+
+    Used by :mod:`swift.common.middleware.proxy_logging` to perform redactions
+    prior to logging.
+    """
     return frozenset(_sensitive_params)
 
 
 def register_sensitive_param(query_param):
+    """
+    Register a query parameter as being "sensitive".
+
+    Sensitive query parameters are automatically redacted when logging. See
+    the ``reveal_sensitive_prefix`` option in the proxy-server sample config
+    for more information.
+
+    :param query_param: The (case-sensitive) query parameter name which, if
+        present, may contain sensitive information. Examples include
+        ``temp_url_signature`` and (if s3api is enabled) ``X-Amz-Signature``.
+        Limited to ASCII characters.
+    """
     if not isinstance(query_param, str):
         raise TypeError
     if six.PY2:
diff --git a/test/unit/common/test_registry.py b/test/unit/common/test_registry.py
index 6960c47502..9c49a61d8b 100644
--- a/test/unit/common/test_registry.py
+++ b/test/unit/common/test_registry.py
@@ -231,10 +231,10 @@ class TestSensitiveRegistry(unittest.TestCase):
         self.assertFalse(registry._sensitive_headers)
 
         registry.register_sensitive_header('Some-Header')
-        expected_headers = {'Some-Header'}
+        expected_headers = {'some-header'}
         self.assertEqual(expected_headers, registry._sensitive_headers)
 
-        expected_headers.add("New-Header")
+        expected_headers.add("new-header")
         registry.register_sensitive_header("New-Header")
         self.assertEqual(expected_headers, registry._sensitive_headers)
 
@@ -271,13 +271,13 @@ class TestSensitiveRegistry(unittest.TestCase):
         self.assertFalse(registry.get_sensitive_headers())
 
         registry.register_sensitive_header('Header1')
-        self.assertEqual(registry.get_sensitive_headers(), {'Header1'})
+        self.assertEqual(registry.get_sensitive_headers(), {'header1'})
         self.assertEqual(registry.get_sensitive_headers(),
                          registry._sensitive_headers)
 
         registry.register_sensitive_header('Header2')
         self.assertEqual(registry.get_sensitive_headers(),
-                         {'Header1', 'Header2'})
+                         {'header1', 'header2'})
         self.assertEqual(registry.get_sensitive_headers(),
                          registry._sensitive_headers)