Skip to content

Clarify how TLS works and when sensitive information in URIs should not be used #277

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
diderikvw wants to merge 10 commits into
base: develop
Choose a base branch
from
+9 −1
Open

Clarify how TLS works and when sensitive information in URIs should not be used #277

Changes from all commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
c5a46f6
Remove BSN as example and add note to sensitive uris
diderikvw Nov 7, 2025
65f8b05
Major edit of text
diderikvw Nov 21, 2025
b9b3ff1
Reversed styling changes
diderikvw Nov 28, 2025
6c90a8c
Reverse more styling changes
diderikvw Nov 28, 2025
854224d
Reverse more styling changes
diderikvw Nov 28, 2025
d945878
Reverse even more style changes
diderikvw Nov 28, 2025
9139959
Reverse removing extra space
diderikvw Nov 28, 2025
34d5428
Clarify how TLS works when interrupted in between
diderikvw Nov 28, 2025
025f085
Apply suggestions from code review
sanderke Jan 22, 2026
a5ec16a
Aanpassing voor system-to-system
diderikvw Jan 28, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 9 additions & 1 deletion sections/designRules.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -745,9 +745,17 @@ Note: security controls for signing and encrypting of application level messages
</dd>
<dt>Rationale</dt>
<dd>
<p>Even when using TLS connections, information in URIs is not secured. URIs can be cached and logged outside of the servers controlled by clients and servers. Any information contained in them should therefore be considered readable by anyone with access to the network (in the case of the internet, the whole world) and MUST NOT contain any sensitive information. This includes client secrets used for authentication, privacy sensitive information such as BSNs or any other information which should not be shared.
<p>When using TLS connections, the path and query information in URIs are secured just like the message headers and body. However, URIs can be cached and logged, as can headers and bodies in the following situations:
<ul>
<li>before the TLS connection starts on the server
<li>after the TLS connection ends on the client
<li>whenever the TLS protocol is terminated and newly initiated in between
</ul>
<p>For REST API's that are accessed directly from user devices, like web browsers, do not put client secrets used for authentication and other sensitive information in the URI. These are directly visible to users, are stored in the web browser's history and cache and can be bookmarked and sent to others.
<p>For REST API's that are only used for system-to-system interation on closed networks where all systems are under control of the involved client and server organisations, do not put client secrets used for authentication in the URI and be careful to put sensitive information in the URI. Intermediate network components that terminate and newly initiate TLS could log or otherwise store URIs. Consider the consequences, advantages and disadvantages of using sensitive information in the URI and be deliberate about which information is logged, for which purposes and who has access.
<p>Be aware that queries (anything after the '?' in a URI) are also part of a URI.
</dd>
<p class="note">The term sensitive is deliberately left undefined in this document.</p>
</dl>
</div>

Expand Down