Skip to content

docs: clarify integrity protection requirements for connection serialization#5782

Open
WesleyRosenblum wants to merge 1 commit intomainfrom
WesleyRosenblum/serializedocs
Open

docs: clarify integrity protection requirements for connection serialization#5782
WesleyRosenblum wants to merge 1 commit intomainfrom
WesleyRosenblum/serializedocs

Conversation

@WesleyRosenblum
Copy link
Contributor

Goal

Strengthen the documentation around connection serialization to make the lack of built-in integrity protection explicit and actionable.

Why

The serialized connection blob contains cryptographic secrets and security-critical parameters (cipher suite, sequence numbers, protocol version) but does not include a MAC or signature. The existing documentation mentioned that users should "MAC and encrypt" the blob, but did not explain why integrity protection matters or what happens when it's missing. This could lead users to overlook the integrity requirement, especially if they only read one of the three documentation surfaces (usage guide, serialize API doc, or deserialize API doc).

How

  • docs/usage-guide/topics/ch14-connection-serialization.md: Rewrote the warning block as a single cohesive piece that explains what the blob contains, that it has no MAC or signature, and that users must provide both secrecy and integrity.
  • api/s2n.h (s2n_connection_serialize and s2n_connection_deserialize): Updated the warning to note that the blob has no MAC or signature and that a modified buffer will be deserialized as-is. Upgraded the recommendation from "it is recommended" to "callers MUST" to match the serialize doc's tone. Added encrypt-then-MAC as the recommended approach.
  • tls/s2n_connection_serialize.c: Added a brief comment at the s2n_connection_deserialize entry point noting the trust assumption and pointing to the API docs.

Testing

Documentation-only change.

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.

@github-actions github-actions bot added the s2n-core team label Mar 11, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants