diff --git a/src/pipelineapi/concepts/data/evidencekeyfilter.md b/src/pipelineapi/concepts/data/evidencekeyfilter.md index 810fdda4e7..d0e36b74f1 100644 --- a/src/pipelineapi/concepts/data/evidencekeyfilter.md +++ b/src/pipelineapi/concepts/data/evidencekeyfilter.md @@ -41,17 +41,17 @@ The filter aggregator includes an evidence key if any child filter includes it. The share usage filter is a specific implementation for 51Degrees @usagesharing. It will include anything that meets the following criteria: -1. Any HTTP header. +1. Any HTTP header other than `Cookie`. 2. Any cookie with a name that starts with '51D_'. -3. A user session cookie, in .NET and Java. It is used only to tell user sessions apart when session tracking is turned on, and it is never sent to 51Degrees. -4. Any session value with a name that starts with '51D_'. +3. Any session value with a name that starts with '51D_'. +4. Any query string or form parameter. 5. Any evidence that is not a header, cookie, session value or query string parameter. -In .NET, evidence named `id.email`, `id.salt`, `request-query` or `request-path` is never shared, whatever its prefix and however the filter is configured. +Some evidence is never shared, whatever the configuration. That includes `id.email`, `id.salt`, `request-query` and `request-path` under any prefix, and every cookie whose name does not start with '51D_'. The @ref PipelineApi_Features_UsageSharing page lists it all. Configuration options allow this to be tuned to meet your requirements: -1. A blacklist of HTTP header names to exclude from sharing can be supplied. -2. In .NET and Java, session tracking can be turned on and the name of the session cookie - can be changed. (The default is the ASP.NET session cookie in .NET and `JSESSIONID` in Java.) -3. A whitelist of query string parameters to share can be supplied. +1. A block list of HTTP header names to exclude from sharing can be supplied. +2. Sharing every query string and form parameter can be turned off. Only those whose names start with '51D_' are then shared, along with any on an allow list that can be supplied. +3. Session tracking can be turned on, so that a repeat of the same evidence from a new user session is shared again. It compares the session cookie, which is not sent to 51Degrees unless its name starts with '51D_'. By default .NET uses the ASP.NET session cookie and Java uses `JSESSIONID`. Node.js, Python, Go and Rust have no default, so give the cookie's name when turning session tracking on. +4. All evidence can be shared, apart from the evidence that is never shared. diff --git a/src/pipelineapi/features/usagesharing.md b/src/pipelineapi/features/usagesharing.md index ffc4a81e9d..d37ea6fb67 100644 --- a/src/pipelineapi/features/usagesharing.md +++ b/src/pipelineapi/features/usagesharing.md @@ -74,17 +74,22 @@ These are never shared, whatever the configuration, even when all @evidence is s - `server.request-query`, the whole query string, and `server.request-path`, the path of the request. - `header.cookie`, the `Cookie` header, which carries every cookie. The cookies whose names start `51D_` are shared as their own `cookie.` values instead. - The `server.http-request` value itself. Only the values read from it are shared. +- A cookie whose name does not start `51D_`. A cookie a site sets for itself, such as its session cookie, is never shared. Unless all @evidence is shared, these rules decide the rest: - 'header.<name>' is shared unless <name> is on the configured block list. -- 'cookie.<name>' and 'session.<name>' are shared only when <name> starts with '51D_'. -- 'query.<name>' is shared when <name> starts with '51D_' or is on the configured allow list. +- 'session.<name>' is shared only when <name> starts with '51D_'. +- 'query.<name>' is shared, for every query string and form parameter. When sharing all query string parameters is turned off, it is shared only when <name> starts with '51D_' or is on the configured allow list. - Any other @evidence is shared. The Resource Key and License Key, held as `fiftyone.resource-key` and `fiftyone.license-key`, are always shared, because usage is counted against them. -The block list and the allow list can be configured using the **share usage** @elementbuilder, along with options to share all query string parameters or all @evidence. +The block list and the allow list can be configured using the **share usage** @elementbuilder, along with options to share all query string parameters, which is on by default, or all @evidence. Sharing all @evidence still leaves out what is never shared, so it shares no cookie other than the '51D_' ones. + +## What else each record carries + +Each record also names the @flowelements in the @Pipeline, the language and its version, the platform, the server's IP address, and every 51Degrees package in use with its version, so that 51Degrees can see how far each release has spread. ## Handing over the web request