Tinverse logo Tinverse LLC

Part 10 of 14

Protecting messages

With keys installed at both ends, every message can be encrypted, signed, or both. This is the part that runs on every message rather than once per peer, so it is written to allocate nothing and to copy the payload as few times as the cipher allows.

One ordering constraint governs all of it. Nothing derived from a message may be used, stored, or returned before the message has been authenticated. That sounds obvious and is violated easily: the header has to be read to know which key to use, so the reader is already acting on unverified bytes before it can verify anything.

Framing

Framing a protected message

Runs when

a protected message is built or received

How often

Once per protected message, in both directions.

A protected message carries a fixed header before its contents and a footer after them. The header names which key is in use, which algorithm, and where in the session this message sits; the footer carries the tag that proves the message has not been altered.

The header is exactly 20 bytes with every field at a fixed position: a three-byte key revision, one algorithm byte, an opaque key identifier, the session number, and the value that makes each message's encryption input unique. Its fields account for every one of those bytes exactly once, and the numeric ones are big-endian regardless of the machine.

Two refusals are worth pulling out, because both are about what must not happen before validation finishes.

Read-Protected-Header(b)

b the borrowed input bytes

  1. if |b| < 20
  2. return error // no provider chosen, no session touched
  3. h.revision = Read-24(b, 0)
  4. h.algorithm = b[3]
  5. if h.algorithm not in supported
  6. return error // an unknown algorithm selects nothing
  7. h.key-id = Read-Opaque(b, 4)
  8. h.session = Read-32(b, 8)
  9. h.suffix = Read-64(b, 12)
  10. return h

Line 1 refuses a header that is short. A partial header still has bytes at the positions the algorithm and session are read from, and using them would select a cipher and a replay session from whatever the truncation left behind.

Line 5 refuses an algorithm the implementation does not know. There is no default to fall back to: the algorithm decides how the rest of the message is interpreted, so guessing means interpreting an attacker's bytes under a scheme they chose.

Only once the header is complete and the footer's tag has verified does anything else happen — and the replay check described below runs after that, for the reason given there.

Framing

Framing the ciphertext

Runs when

a protected message is built or read

How often

Once per protected message.

Between the header and the tags sits the protected content, introduced by a four-byte length. The length is what lets the reader find where the content stops and the tags begin.

It is also, again, a number from the sender. Two things are checked before it is used: that it is within the configured capacity, and that adding the prefix width to it does not overflow. The second matters because a length near the maximum plus a four-byte prefix wraps to a small number, and the truncation check that follows would then compare against a value smaller than the content it is validating.

Read-Content(b, capacity, exact)

b the borrowed input · capacity the configured maximum · exact whether the content must consume the whole input

  1. if |b| < 4
  2. return error
  3. n = Read-32(b)
  4. if n > capacity
  5. return error
  6. extent = Checked-Add(4, n)
  7. if extent == overflow or extent > |b|
  8. return error
  9. if exact and extent ≠ |b|
  10. return error // trailing bytes are not ignored
  11. return (borrow of n bytes, extent)

Line 11 returns the extent as well as the content, so the caller can find the tags that follow without recomputing where they start from a number it would have to re-derive.

Cost

Reading is O(1) and borrows rather than copies. Writing copies the ciphertext only when the cipher did not already produce it in its final position; when it did, only the four-byte prefix is written.

Cipher

Calling the cipher

Runs when

anything is encrypted, decrypted, or authenticated

How often

Once per protected message.

The cipher itself is not implemented here. It is a standard library, used through a thin wrapper whose job is entirely about what surrounds the call rather than the cryptography.

When an association starts, the wrapper creates one context for sending and one for receiving, selects the AES algorithm, and retains the key. Each message resets the appropriate context with only that key and the message's nonce. It does not create a new context or select the algorithm again on the message path.

The wrapper has one rule that is easy to state and easy to get wrong: plaintext that has not been authenticated must never become visible.

Decrypt(ctx, nonce, aad, input, out, tag)

ctx the cipher context and its retained key · nonce this operation's unique value · aad data authenticated but not encrypted · input, out the ciphertext and caller-owned output · tag the tag to verify against

  1. if key width unsupported or |input| overflows or |out| too small
  2. return error // before the provider is touched
  3. Reinitialize(ctx, nonce)
  4. Feed-Aad(ctx, aad) // authenticated, not transformed
  5. Transform(ctx, input, out) // out now holds unverified plaintext
  6. Set-Expected-Tag(ctx, tag)
  7. if not Finalize(ctx) // this is where the tag is checked
  8. Erase(out) // the plaintext must not survive a failed check
  9. return error
  10. return ok

Line 5 produces plaintext and line 7 is where it is found out to be forged. There is no way round that ordering — the tag covers the whole ciphertext, so it cannot be checked until the whole ciphertext has been processed. What line 8 does is make the window harmless by erasing the buffer before returning.

Without it, the caller holds a buffer of attacker-influenced bytes and an error code. Every caller then has to remember not to look at the buffer, and one that logs it for diagnosis has built an oracle.

Large and fragmented samples

The cipher can process a long contiguous range in one pass, but a protected sample is not decrypted one network fragment at a time. Its authentication tag covers the complete ciphertext. The sender therefore protects the payload before RTPS splits it; the receiver reassembles the protected bytes and then authenticates and decrypts them. The final reassembly storage can be used directly, avoiding another payload-sized staging buffer without making partial plaintext visible.

Cost

O(a + n) for the authenticated and encrypted extents, into caller-owned output. Two contexts and their AES bindings are created when the association activates and reused per operation. When the data is already in its final position the in-place operation is used, so no copy is made merely to encrypt.

Transform

Protecting one payload

Runs when

a sample's payload is protected or unprotected

How often

Once per sample on a protected endpoint.

Putting the pieces together for one sample. There are two modes and the difference is whether the payload is hidden or merely proven: encryption replaces the payload with ciphertext, while authentication leaves it readable and attaches a tag.

The second is what you want for data that is not secret but must not be forged — a robot's position that any observer may see but nobody may fake.

Unprotect-Payload(a, b, out)

a the endpoint association, with its session and replay window · b the arriving protected bytes · out caller-owned output

  1. h = Read-Protected-Header(b)
  2. if h == error or h does not match a
  3. return error
  4. if h.algorithm is encrypting
  5. (body, extent) = Read-Content(b, a.capacity, false)
  6. footer = Read-Footer(b from extent, a.receivers)
  7. else
  8. body = the clear payload; footer = Read-Footer(b after body, 0)
  9. if not Verify(a.session, h, body, footer.common, out)
  10. return error // out already erased by the cipher wrapper
  11. if Admit-Fresh(a.window, h.session, h.suffix) ≠ accepted
  12. Erase(out)
  13. return error // authentic, but a replay
  14. return ok

Line 9 before line 11 is the ordering the last section of this part exists to explain. Line 12 erases again for the replay case: those bytes are authentic plaintext, which makes them more tempting to return than forged bytes, and returning them is exactly what accepting a replay means.

Cost

O(1) framing and admission around O(n) cipher work. Encrypting into the final position avoids a second copy of the payload. The authenticate-only mode instantiates no per-receiver storage at all, since it carries only the common tag.

Framing

The three-record envelope

Runs when

a whole submessage rather than a payload is protected

How often

Once per protected submessage.

Protecting a payload hides the sample. Protecting a whole submessage hides which endpoint it was for and what kind of record it was, and it is how the key-distribution traffic of Part 11 travels.

A protected submessage is three records: a prefix carrying the transform header, a body carrying the protected content, and a postfix carrying the tags. They must appear in that order and nothing may sit between them.

Decoding walks the three declared extents once and rejects wrong order, wrong flags, a zero or truncated length, or trailing bytes — before returning anything. Only after the triplet is structurally whole is it authenticated, and only after that is the record inside it classified.

That three-stage order — structure, then authentication, then meaning — is what keeps a malformed or forged message from reaching the code that interprets record kinds.

Cost

One preflight of the whole extent, then the cipher writes its output directly into the range the preflight identified, so the three headers are written around ciphertext that never moves.

Selection

Choosing which key to try

Runs when

a protected submessage arrives

How often

Once per protected submessage, before any authentication.

Here is the ordering problem stated at the top of this part, in its sharpest form. To authenticate a message you need the key. To know which key, you read the identifier in the header. The header is not authenticated yet.

There is no way to avoid acting on unverified bytes, so the question is how to act on them harmlessly. The answer is that the identifier may be used only to look something up, never to create anything.

Select-Association(p, msg)

p the participant and its registered associations · msg the arriving protected submessage

  1. t = Parse-Triplet(msg)
  2. if t == error
  3. return reject
  4. for each association a in p.writer-associations
  5. if a.key-id == t.header.key-id
  6. return a
  7. for each association a in p.reader-associations
  8. if a.key-id == t.header.key-id
  9. return a
  10. return reject // no association: nothing is created for an unknown id

Line 10 is the whole safety property. An unknown identifier finds nothing, and finding nothing is the end — no association is created, no storage reserved, no state changed. An attacker sending a million distinct identifiers gets a million scans of a bounded array and nothing else.

Both roles are searched because an identifier alone does not say whether the sender was acting as a writer or a reader. Searching only one would reject legitimate traffic whose direction happened to be the other one.

Sessions

A nonce that is never reused

Runs when

anything is protected for sending

How often

Once per outbound protected message.

The cipher requires that no two operations under one key use the same nonce. This is not a performance guideline. Reusing a nonce under AES-GCM lets an observer recover the relationship between the two plaintexts and, worse, recover the value used to forge tags — after which they can produce messages that authenticate.

The nonce here is the session number and a counter. Both are finite, so the session must roll over before either can repeat, and there is a limit on how much data one session key may protect.

Protect(s, payload, out)

s the outbound session — its key deriver, session number, next counter, and block budget · payload the bytes to protect · out caller-owned output

  1. if Encoded-Size(payload) > |out|
  2. return error // no identity consumed
  3. blocks = ⌈|payload| / 16⌉
  4. if blocks > s.limit
  5. return error // one message may not exceed a whole session
  6. if s.remaining < blocks
  7. Rotate(s) // next session number, counter back to zero
  8. if s.counter == maximum
  9. Rotate(s)
  10. if s.session == maximum
  11. s.terminal = true; return exhausted // permanently, from now on
  12. nonce = (s.session, s.counter) // captured
  13. s.counter = s.counter + 1 // advanced BEFORE the cipher runs
  14. s.remaining = s.remaining − blocks
  15. return Encrypt(s.cipher, nonce, payload, out)

Lines 12 to 15 are the heart of it. The counter advances before the cipher is called, not after, so a cipher failure has already consumed the nonce. That looks wasteful and is the only safe order: if the counter advanced only on success, a caller that retried after a failure would encrypt different bytes under the same nonce, which is precisely the catastrophe.

Lines 1 to 5 are the opposite case. Neither an output buffer that is too small nor an over-large payload has reached the cipher, so no identity has been spent and the session is untouched.

Line 11 makes exhaustion permanent. Once both counters are spent, every later operation returns the same failure and the cipher is never invoked again. Wrapping round to reuse the first nonce would be worse than refusing to send.

Both directions

The inbound side is the mirror and has no such counter, because it does not choose nonces — it reads them. What it owns instead is the replay window below, which decides whether a nonce it has been given is one it has already seen.

Cost

O(1) admission and rotation around O(n) cipher work. Rotation costs one key derivation and one context activation, and happens once per session rather than per message. Nothing on this path allocates.

Freshness

The replay window

Runs when

a protected message has passed its cryptographic check

How often

Once per protected message received. This is the security step that runs on every message.

A signature proves a message was written by someone holding the key. It does not prove the message is not one that was recorded an hour ago and sent again. An attacker who cannot read or forge traffic can still record it and repeat it — replaying "open the gripper" is as effective as composing it.

Refusing repeats needs a record of what has been seen. Keeping every number ever received is unbounded, so instead a window is kept: the highest number seen, and a bitmap of which of the positions just below it have already been used. Anything older than the window is refused for being too old; anything inside it is refused if its bit is already set.

before highest = 40 older than the window — refused shaded: already seen 44 arrives highest = 44 everything shifts by 4; what falls off the left edge is now simply too old The window moves only after the message's signature has been checked. A forged header that could move it would let anyone push it past the numbers a real peer is about to use.
Figure 10.1 Fixed storage, whatever the traffic. Positions that fall out of the window are refused as too old rather than remembered.

Admit-Fresh(w, session, n)

w the replay window for one peer, endpoint, and path · session the key epoch · n the message's number within it · W the configured window size

  1. if w.session == nil or session > w.session
  2. w.session = session; w.max = n; w.bits = {0}
  3. return accepted // a new session starts its own history
  4. if session < w.session
  5. return obsolete-session
  6. if n > w.max
  7. d = n − w.max
  8. if d ≥ W
  9. w.bits = empty // the whole window has moved past
  10. else
  11. w.bits = w.bits shifted older by d
  12. w.max = n
  13. Set(w.bits, 0)
  14. return accepted
  15. offset = w.max − n
  16. if offset ≥ W
  17. return too-old
  18. if Is-Set(w.bits, offset)
  19. return duplicate
  20. Set(w.bits, offset)
  21. return accepted

Worked example

A window of 8 positions. Messages arrive in this order, each already past its cryptographic check.

ArrivesResultWindow afterwards
20acceptedhighest 20; seen: 20
22acceptedhighest 22; seen: 20, 22
21acceptedhighest 22; seen: 20, 21, 22 — reordered, not replayed
21duplicateunchanged
14too oldunchanged — 8 positions behind 22
40acceptedhighest 40; seen: 40 only — the shift of 18 cleared the window
22too oldunchanged, though it was accepted three rows earlier

The last row is the cost of a fixed-size window, and it is deliberate. Once 40 has been seen, 22 is outside what can be remembered, and a message that cannot be proved fresh is refused rather than assumed fresh. A sender that reorders by more than the window will lose messages, which is why the window is configurable.

Messages that arrive out of order

Line 15 onwards accepts an older number as long as it is inside the window and has not been seen. Requiring strictly increasing numbers would reject perfectly good traffic that the network happened to reorder.

Why it runs after authentication, not before

The ordering constraint that matters most is not inside this procedure but around it. It runs only after the message's authentication has succeeded. If it ran first, the numbers in the header would be attacker-controlled, and sending one forged message with a very large number would slide the window far past where the real peer is — after which every genuine message is refused for being too old. That is a denial of service requiring no key at all, and the only thing preventing it is the order of the two steps.

Every rejection above happens before any assignment, so a message that is refused leaves the window exactly as it was.

Cost

Accepting or rejecting within the current session is O(1). Advancing shifts a fixed number of machine words. The whole structure is 128 bytes plus a few scalars and never allocates, so the memory cost does not depend on how much traffic arrives or how badly it is reordered.

Next: key distribution

A small reliable protocol inside an encrypted envelope, carrying secrets that must be erased on time.

Part 11 →

These descriptions follow the implementations in Tin DDS and Retina. Evaluation access and the full algorithm notes are available from engineering@tinverse.com.