plugins: Move to blocklists and allowlists

doc/admin-guide/plugins/cachekey.en.rst

@@ -121,9 +121,9 @@ Cache key structure and related plugin parameters
   configured               |
 
 * ``User-Agent`` classification
-    * ``--ua-whitelist=<classname>:<filename>`` (default: empty string) - loads a regex patterns list from a file ``<filename>``, the patterns are matched against the ``User-Agent`` header and if matched ``<classname>`` is added it to the key.
-    * ``--ua-blacklist=<classname>:<filename>`` (default: empty string) - loads a regex patterns list from a file ``<filename>``, the patterns are matched against the ``User-Agent`` header and if **not** matched ``<classname>`` is added it to the key.
-    * Multiple ``--ua-whitelist`` and ``--ua-blacklist`` can be used and the result will be defined by their order in the plugin configuration.
+    * ``--ua-allowlist=<classname>:<filename>`` (default: empty string) - loads a regex patterns list from a file ``<filename>``, the patterns are matched against the ``User-Agent`` header and if matched ``<classname>`` is added it to the key.
+    * ``--ua-blocklist=<classname>:<filename>`` (default: empty string) - loads a regex patterns list from a file ``<filename>``, the patterns are matched against the ``User-Agent`` header and if **not** matched ``<classname>`` is added it to the key.
+    * Multiple ``--ua-allowlist`` and ``--ua-blocklist`` can be used and the result will be defined by their order in the plugin configuration.
 * ``User-Agent`` regex capturing and replacement
     * ``--ua-capture=<capture_definition>`` (default: empty string) - if specified and not empty then strings are captured from the ``User-Agent`` header based on ``<capture_definition>`` (see below) and are added to the `cache key`.
 * If any ``User-Agent`` classification and regex capturing and replacement plugin parameters are used together they are added to the `cache key` in the order shown in the diagram.
@@ -264,7 +264,7 @@ Traffic server configuration ::
   $ cat etc/trafficserver/remap.config
   map http://www.example.com http://www.origin.com \
       @plugin=cachekey.so \
-          @pparam=--ua-whitelist=popular:popular_agents.config \
+          @pparam=--ua-allowlist=popular:popular_agents.config \
           @pparam=--ua-capture=(Mozilla\/[^\s]*).* \
           @pparam=--include-headers=H1,H2 \
           @pparam=--include-cookies=C1,C2 \
@@ -575,7 +575,7 @@ User-Agent white-list classifier
 If the plugin is used with the following plugin parameter::
 
   @plugin=cachekey.so \
-      @pparam=--ua-whitelist=browser:browser_agents.config
+      @pparam=--ua-allowlist=browser:browser_agents.config
 
 and if ``browser_agents.config`` contains: ::
 

doc/admin-guide/plugins/esi.en.rst

@@ -98,14 +98,14 @@ And inside handler.conf you can provide the list of cookie name that is allowed.
 
 ::
 
-    whitelistCookie A
-    whitelistCookie LOGIN
+    allowlistCookie A
+    allowlistCookie LOGIN
 
 We can also allow all cookie for HTTP_COOKIE variable by using a wildcard character. e.g.
 
 ::
 
-    whitelistCookie *
+    allowlistCookie *
 
 4. We need a mapping for origin server response that contains the ESI markup. Assume that the ATS server is abc.com. And your origin server is xyz.com and the response containing ESI markup is http://xyz.com/esi.php. We will need
    the following line in /usr/local/etc/trafficserver/remap.config

plugins/cachekey/configs.cc

@@ -274,11 +274,11 @@ makeConfigPath(const String &path)
 /**
  * @brief a helper function which loads the classifier from files.
  * @param args classname + filename in '<classname>:<filename>' format.
- * @param blacklist true - load as a blacklist classifier, false - whitelist.
+ * @param blocklist true - load as a blocklist classifier, false - allowlist.
  * @return true if successful, false otherwise.
  */
 bool
-Configs::loadClassifiers(const String &args, bool blacklist)
+Configs::loadClassifiers(const String &args, bool blocklist)
 {
   static const char *EXPECTED_FORMAT = "<classname>:<filename>";
 
@@ -310,7 +310,7 @@ Configs::loadClassifiers(const String &args, bool blacklist)
   }
 
   MultiPattern *multiPattern;
-  if (blacklist) {
+  if (blocklist) {
     multiPattern = new NonMatchingMultiPattern(classname);
   } else {
     multiPattern = new MultiPattern(classname);
@@ -341,11 +341,11 @@ Configs::loadClassifiers(const String &args, bool blacklist)
     p = new Pattern();
 
     if (nullptr != p && p->init(regex)) {
-      if (blacklist) {
-        CacheKeyDebug("Added pattern '%s' to black list '%s'", regex.c_str(), classname.c_str());
+      if (blocklist) {
+        CacheKeyDebug("Added pattern '%s' to block list '%s'", regex.c_str(), classname.c_str());
         multiPattern->add(p);
       } else {
-        CacheKeyDebug("Added pattern '%s' to white list '%s'", regex.c_str(), classname.c_str());
+        CacheKeyDebug("Added pattern '%s' to allow list '%s'", regex.c_str(), classname.c_str());
         multiPattern->add(p);
       }
     } else {
@@ -385,8 +385,8 @@ Configs::init(int argc, const char *argv[], bool perRemapConfig)
     {const_cast<char *>("include-headers"), optional_argument, nullptr, 'g'},
     {const_cast<char *>("include-cookies"), optional_argument, nullptr, 'h'},
     {const_cast<char *>("ua-capture"), optional_argument, nullptr, 'i'},
-    {const_cast<char *>("ua-whitelist"), optional_argument, nullptr, 'j'},
-    {const_cast<char *>("ua-blacklist"), optional_argument, nullptr, 'k'},
+    {const_cast<char *>("ua-allowlist"), optional_argument, nullptr, 'j'},
+    {const_cast<char *>("ua-blocklist"), optional_argument, nullptr, 'k'},
     {const_cast<char *>("static-prefix"), optional_argument, nullptr, 'l'},
     {const_cast<char *>("capture-prefix"), optional_argument, nullptr, 'm'},
     {const_cast<char *>("capture-prefix-uri"), optional_argument, nullptr, 'n'},
@@ -452,15 +452,15 @@ Configs::init(int argc, const char *argv[], bool perRemapConfig)
         status = false;
       }
       break;
-    case 'j': /* ua-whitelist */
-      if (!loadClassifiers(optarg, /* blacklist = */ false)) {
-        CacheKeyError("failed to load User-Agent pattern white-list '%s'", optarg);
+    case 'j': /* ua-allowlist */
+      if (!loadClassifiers(optarg, /* blocklist = */ false)) {
+        CacheKeyError("failed to load User-Agent pattern allow-list '%s'", optarg);
         status = false;
       }
       break;
-    case 'k': /* ua-blacklist */
-      if (!loadClassifiers(optarg, /* blacklist = */ true)) {
-        CacheKeyError("failed to load User-Agent pattern black-list '%s'", optarg);
+    case 'k': /* ua-blocklist */
+      if (!loadClassifiers(optarg, /* blocklist = */ true)) {
+        CacheKeyError("failed to load User-Agent pattern block-list '%s'", optarg);
         status = false;
       }
       break;

plugins/cachekey/configs.h

@@ -217,16 +217,16 @@ class Configs
   Pattern _prefixCaptureUri; /**< @brief cache key prefix captured from the URI as a whole */
   Pattern _pathCapture;      /**< @brief cache key element captured from the URI path */
   Pattern _pathCaptureUri;   /**< @brief cache key element captured from the URI as a whole */
-  Classifier _classifier;    /**< @brief blacklist and white-list classifier used to classify User-Agent header */
+  Classifier _classifier;    /**< @brief blocklist and allow-list classifier used to classify User-Agent header */
 
 private:
   /**
    * @brief a helper function which loads the classifier from files.
    * @param args classname + filename in '<classname>:<filename>' format.
-   * @param blacklist true - load as a blacklist classifier, false - white-list.
+   * @param blocklist true - load as a blocklist classifier, false - allow-list.
    * @return true if successful, false otherwise.
    */
-  bool loadClassifiers(const String &args, bool blacklist = true);
+  bool loadClassifiers(const String &args, bool blocklist = true);
 
   bool _prefixToBeRemoved  = false; /**< @brief instructs the prefix (i.e. host:port) not to added to the cache key */
   bool _pathToBeRemoved    = false; /**< @brief instructs the path not to added to the cache key */

plugins/esi/combo_handler.cc

@@ -65,7 +65,7 @@ unsigned MaxFileCount = DEFAULT_MAX_FILE_COUNT;
 
 int arg_idx;
 static string SIG_KEY_NAME;
-static vector<string> HEADER_WHITELIST;
+static vector<string> HEADER_ALLOWLIST;
 
 #define DEFAULT_COMBO_HANDLER_PATH "admin/v1/combo"
 static string COMBO_HANDLER_PATH{DEFAULT_COMBO_HANDLER_PATH};
@@ -175,14 +175,14 @@ class ContentTypeHandler
 public:
   ContentTypeHandler(std::string &resp_header_fields) : _resp_header_fields(resp_header_fields) {}
 
-  // Returns false if _content_type_whitelist is not empty, and content-type field is either not present or not in the
-  // whitelist.  Adds first Content-type field it encounters in the headers passed to this function.
+  // Returns false if _content_type_allowlist is not empty, and content-type field is either not present or not in the
+  // allowlist.  Adds first Content-type field it encounters in the headers passed to this function.
   //
   bool nextObjectHeader(TSMBuffer bufp, TSMLoc hdr_loc);
 
-  // Load whitelist from config file.
+  // Load allowlist from config file.
   //
-  static void loadWhiteList(std::string const &file_spec);
+  static void loadAllowList(std::string const &file_spec);
 
 private:
   // Add Content-Type field to these.
@@ -191,10 +191,10 @@ class ContentTypeHandler
 
   bool _added_content_type{false};
 
-  static vector<std::string> _content_type_whitelist;
+  static vector<std::string> _content_type_allowlist;
 };
 
-vector<std::string> ContentTypeHandler::_content_type_whitelist;
+vector<std::string> ContentTypeHandler::_content_type_allowlist;
 
 bool
 InterceptData::init(TSVConn vconn)
@@ -407,26 +407,26 @@ TSPluginInit(int argc, const char *argv[])
     stringstream strstream(argv[optind++]);
     string header;
     while (getline(strstream, header, ':')) {
-      HEADER_WHITELIST.push_back(header);
+      HEADER_ALLOWLIST.push_back(header);
     }
   }
   ++optind;
 
-  for (unsigned int i = 0; i < HEADER_WHITELIST.size(); i++) {
-    LOG_DEBUG("WhiteList: %s", HEADER_WHITELIST[i].c_str());
+  for (unsigned int i = 0; i < HEADER_ALLOWLIST.size(); i++) {
+    LOG_DEBUG("AllowList: %s", HEADER_ALLOWLIST[i].c_str());
   }
 
-  std::string content_type_whitelist_filespec = (argc > optind && (argv[optind][0] != '-' || argv[optind][1])) ? argv[optind] : "";
-  if (content_type_whitelist_filespec.empty()) {
-    LOG_DEBUG("No Content-Type whitelist file specified (all content types allowed)");
+  std::string content_type_allowlist_filespec = (argc > optind && (argv[optind][0] != '-' || argv[optind][1])) ? argv[optind] : "";
+  if (content_type_allowlist_filespec.empty()) {
+    LOG_DEBUG("No Content-Type allowlist file specified (all content types allowed)");
   } else {
     // If we have a path and it's not an absolute path, make it relative to the
     // configuration directory.
-    if (content_type_whitelist_filespec[0] != '/') {
-      content_type_whitelist_filespec = std::string(TSConfigDirGet()) + '/' + content_type_whitelist_filespec;
+    if (content_type_allowlist_filespec[0] != '/') {
+      content_type_allowlist_filespec = std::string(TSConfigDirGet()) + '/' + content_type_allowlist_filespec;
     }
-    LOG_DEBUG("Content-Type whitelist file: %s", content_type_whitelist_filespec.c_str());
-    ContentTypeHandler::loadWhiteList(content_type_whitelist_filespec);
+    LOG_DEBUG("Content-Type allowlist file: %s", content_type_allowlist_filespec.c_str());
+    ContentTypeHandler::loadAllowList(content_type_allowlist_filespec);
   }
   ++optind;
 
@@ -967,7 +967,7 @@ prepareResponse(InterceptData &int_data, ByteBlockList &body_blocks, string &res
     TSMLoc field_loc;
     time_t expires_time;
     bool got_expires_time = false;
-    int num_headers       = HEADER_WHITELIST.size();
+    int num_headers       = HEADER_ALLOWLIST.size();
     int flags_list[num_headers];
     CacheControlHeader cch;
 
@@ -980,7 +980,7 @@ prepareResponse(InterceptData &int_data, ByteBlockList &body_blocks, string &res
     for (StringList::iterator iter = int_data.creq.file_urls.begin(); iter != int_data.creq.file_urls.end(); ++iter) {
       if (int_data.fetcher->getData(*iter, resp_data) && resp_data.status == TS_HTTP_STATUS_OK) {
         body_blocks.push_back(ByteBlock(resp_data.content, resp_data.content_len));
-        if (find(HEADER_WHITELIST.begin(), HEADER_WHITELIST.end(), TS_MIME_FIELD_CONTENT_TYPE) == HEADER_WHITELIST.end()) {
+        if (find(HEADER_ALLOWLIST.begin(), HEADER_ALLOWLIST.end(), TS_MIME_FIELD_CONTENT_TYPE) == HEADER_ALLOWLIST.end()) {
           if (!cth.nextObjectHeader(resp_data.bufp, resp_data.hdr_loc)) {
             LOG_ERROR("Content type missing or forbidden for requested URL [%s]", iter->c_str());
             int_data.creq.status = TS_HTTP_STATUS_FORBIDDEN;
@@ -1012,7 +1012,7 @@ prepareResponse(InterceptData &int_data, ByteBlockList &body_blocks, string &res
             continue;
           }
 
-          const string &header = HEADER_WHITELIST[i];
+          const string &header = HEADER_ALLOWLIST[i];
 
           field_loc = TSMimeHdrFieldFind(resp_data.bufp, resp_data.hdr_loc, header.c_str(), header.size());
           if (field_loc != TS_NULL_MLOC) {
@@ -1048,10 +1048,10 @@ prepareResponse(InterceptData &int_data, ByteBlockList &body_blocks, string &res
     }
     if (int_data.creq.status == TS_HTTP_STATUS_OK) {
       // Add in Cache-Control header
-      if (find(HEADER_WHITELIST.begin(), HEADER_WHITELIST.end(), TS_MIME_FIELD_CACHE_CONTROL) == HEADER_WHITELIST.end()) {
+      if (find(HEADER_ALLOWLIST.begin(), HEADER_ALLOWLIST.end(), TS_MIME_FIELD_CACHE_CONTROL) == HEADER_ALLOWLIST.end()) {
         resp_header_fields.append(cch.generate());
       }
-      if (find(HEADER_WHITELIST.begin(), HEADER_WHITELIST.end(), TS_MIME_FIELD_EXPIRES) == HEADER_WHITELIST.end()) {
+      if (find(HEADER_ALLOWLIST.begin(), HEADER_ALLOWLIST.end(), TS_MIME_FIELD_EXPIRES) == HEADER_ALLOWLIST.end()) {
         if (got_expires_time) {
           if (expires_time <= 0) {
             resp_header_fields.append("Expires: 0\r\n");
@@ -1092,14 +1092,14 @@ ContentTypeHandler::nextObjectHeader(TSMBuffer bufp, TSMLoc hdr_loc)
       value = TSMimeHdrFieldValueStringGet(bufp, hdr_loc, field_loc, i, &value_len);
       ts::TextView tv{value, value_len};
       tv = tv.prefix(';').rtrim(std::string_view(" \t"));
-      if (_content_type_whitelist.empty()) {
+      if (_content_type_allowlist.empty()) {
         ;
-      } else if (std::find_if(_content_type_whitelist.begin(), _content_type_whitelist.end(), [tv](ts::TextView tv2) -> bool {
+      } else if (std::find_if(_content_type_allowlist.begin(), _content_type_allowlist.end(), [tv](ts::TextView tv2) -> bool {
                    return strcasecmp(tv, tv2) == 0;
-                 }) == _content_type_whitelist.end()) {
+                 }) == _content_type_allowlist.end()) {
         return false;
       } else if (tv.empty()) {
-        // Whitelist is bad, contains an empty string.
+        // allowlist is bad, contains an empty string.
         return false;
       }
       if (!_added_content_type) {
@@ -1121,12 +1121,12 @@ ContentTypeHandler::nextObjectHeader(TSMBuffer bufp, TSMLoc hdr_loc)
     }
     return true;
   }
-  // No content type header field so doesn't pass whitelist if there is one.
-  return _content_type_whitelist.empty();
+  // No content type header field so doesn't pass allowlist if there is one.
+  return _content_type_allowlist.empty();
 }
 
 void
-ContentTypeHandler::loadWhiteList(std::string const &file_spec)
+ContentTypeHandler::loadAllowList(std::string const &file_spec)
 {
   std::fstream fs;
   char line_buffer[256];
@@ -1154,22 +1154,22 @@ ContentTypeHandler::loadWhiteList(std::string const &file_spec)
         extra_junk_on_line = true;
         break;
       }
-      _content_type_whitelist.emplace_back(content_type);
+      _content_type_allowlist.emplace_back(content_type);
     }
   }
   if (fs.fail() && !(fs.eof() && (fs.gcount() == 0))) {
-    LOG_ERROR("Error reading Content-Type whitelist config file %s, line %d", file_spec.c_str(), line_num);
+    LOG_ERROR("Error reading Content-Type allowlist config file %s, line %d", file_spec.c_str(), line_num);
   } else if (extra_junk_on_line) {
-    LOG_ERROR("More than one type on line %d in Content-Type whitelist config file %s", line_num, file_spec.c_str());
-  } else if (_content_type_whitelist.empty()) {
-    LOG_ERROR("Content-type whitelist config file %s must have at least one entry", file_spec.c_str());
+    LOG_ERROR("More than one type on line %d in Content-Type allowlist config file %s", line_num, file_spec.c_str());
+  } else if (_content_type_allowlist.empty()) {
+    LOG_ERROR("Content-type allowlist config file %s must have at least one entry", file_spec.c_str());
   } else {
     // End of file.
     return;
   }
-  _content_type_whitelist.clear();
+  _content_type_allowlist.clear();
   // An empty string marks object as bad.
-  _content_type_whitelist.emplace_back("");
+  _content_type_allowlist.emplace_back("");
 }
 
 static const char INVARIANT_FIELD_LINES[]    = {"Vary: Accept-Encoding\r\n"};
@@ -1178,15 +1178,15 @@ static const char INVARIANT_FIELD_LINES_SIZE = sizeof(INVARIANT_FIELD_LINES) - 1
 static bool
 writeStandardHeaderFields(InterceptData &int_data, int &n_bytes_written)
 {
-  if (find(HEADER_WHITELIST.begin(), HEADER_WHITELIST.end(), TS_MIME_FIELD_VARY) == HEADER_WHITELIST.end()) {
+  if (find(HEADER_ALLOWLIST.begin(), HEADER_ALLOWLIST.end(), TS_MIME_FIELD_VARY) == HEADER_ALLOWLIST.end()) {
     if (TSIOBufferWrite(int_data.output.buffer, INVARIANT_FIELD_LINES, INVARIANT_FIELD_LINES_SIZE) == TS_ERROR) {
       LOG_ERROR("Error while writing invariant fields");
       return false;
     }
     n_bytes_written += INVARIANT_FIELD_LINES_SIZE;
   }
 
-  if (find(HEADER_WHITELIST.begin(), HEADER_WHITELIST.end(), TS_MIME_FIELD_LAST_MODIFIED) == HEADER_WHITELIST.end()) {
+  if (find(HEADER_ALLOWLIST.begin(), HEADER_ALLOWLIST.end(), TS_MIME_FIELD_LAST_MODIFIED) == HEADER_ALLOWLIST.end()) {
     time_t time_now = static_cast<time_t>(TShrtime() / 1000000000); // it returns nanoseconds!
     char last_modified_line[128];
     struct tm gmnow;

plugins/esi/esi.cc

@@ -59,7 +59,7 @@ struct OptionInfo {
 };
 
 static HandlerManager *gHandlerManager = nullptr;
-static Utils::HeaderValueList gWhitelistCookies;
+static Utils::HeaderValueList gAllowlistCookies;
 
 #define DEBUG_TAG "plugin_esi"
 #define PROCESSOR_DEBUG_TAG "plugin_esi_processor"
@@ -254,7 +254,7 @@ ContData::init()
       data_fetcher = new HttpDataFetcherImpl(contp, client_addr, createDebugTag(FETCHER_DEBUG_TAG, contp, fetcher_tag));
     }
     if (!esi_vars) {
-      esi_vars = new Variables(createDebugTag(VARS_DEBUG_TAG, contp, vars_tag), &TSDebug, &TSError, gWhitelistCookies);
+      esi_vars = new Variables(createDebugTag(VARS_DEBUG_TAG, contp, vars_tag), &TSDebug, &TSError, gAllowlistCookies);
     }
 
     esi_proc = new EsiProcessor(
@@ -288,7 +288,7 @@ ContData::getClientState()
 
   if (!esi_vars) {
     string vars_tag;
-    esi_vars = new Variables(createDebugTag(VARS_DEBUG_TAG, contp, vars_tag), &TSDebug, &TSError, gWhitelistCookies);
+    esi_vars = new Variables(createDebugTag(VARS_DEBUG_TAG, contp, vars_tag), &TSDebug, &TSError, gAllowlistCookies);
   }
   if (!data_fetcher) {
     string fetcher_tag;
@@ -1564,7 +1564,7 @@ loadHandlerConf(const char *file_name, Utils::KeyValueMap &handler_conf)
       conf_lines.push_back(string(buf));
     }
     TSfclose(conf_file);
-    Utils::parseKeyValueConfig(conf_lines, handler_conf, gWhitelistCookies);
+    Utils::parseKeyValueConfig(conf_lines, handler_conf, gAllowlistCookies);
     TSDebug(DEBUG_TAG, "[%s] Loaded handler conf file [%s]", __FUNCTION__, file_name);
   } else {
     TSError("[esi][%s] Failed to open handler config file [%s]", __FUNCTION__, file_name);