[DRAFT] ICD - Design document for Check-in handler #35866

thivya-amazon · 2024-10-01T22:04:40Z

semanticdiff-com · 2024-10-01T22:04:43Z

github-actions · 2024-10-01T22:28:06Z

bzbarsky-apple · 2024-10-02T00:02:52Z

src/app/icd/docs/check-in_handler_design.md

@@ -0,0 +1,18 @@
+# Check-in handler overview
+
+ICD servers send check-in messages to a registered ICD client when a subscription is lost or one was never established. A subscription can be lost for several reasons, such as:


Suggested change

ICD servers send check-in messages to a registered ICD client when a subscription is lost or one was never established. A subscription can be lost for several reasons, such as:

ICD servers send check-in messages to a registered ICD client when a subscription is lost or one was never established. A subscription can be lost for a variety of reasons. Some non-exhaustive examples are:

bzbarsky-apple · 2024-10-02T00:03:55Z

src/app/icd/docs/check-in_handler_design.md

+
+• The client is unavailable for any reason
+
+The Check-In handler in an ICD client is responsible for handling unsolicited check-in messages from an ICD server. All ICD clients should add support for Check-In protocol as it is a fail safe mechanism that provides a means to re-establish a secure session with an ICD server. The heart of the module is the check-in handler that receives and parses check-in messages from ICD servers. After ensuring the validity of the message, the check-in handler passes it on to the check-in protocol to parse the message and retrieves the ICD counter value. The ICD counter is used to derive the nonce in the encryption process of the check-in protocol. Beyond that, ICD counters are also used to detect repeated reception of the same message and eliminate duplicates. Once the maximum value for an ICD counter is reached, the counter should roll-over to 0 and when that is done, it is necessary for the ICD client to re-register with the ICD server using a fresh key. 


Suggested change

The Check-In handler in an ICD client is responsible for handling unsolicited check-in messages from an ICD server. All ICD clients should add support for Check-In protocol as it is a fail safe mechanism that provides a means to re-establish a secure session with an ICD server. The heart of the module is the check-in handler that receives and parses check-in messages from ICD servers. After ensuring the validity of the message, the check-in handler passes it on to the check-in protocol to parse the message and retrieves the ICD counter value. The ICD counter is used to derive the nonce in the encryption process of the check-in protocol. Beyond that, ICD counters are also used to detect repeated reception of the same message and eliminate duplicates. Once the maximum value for an ICD counter is reached, the counter should roll-over to 0 and when that is done, it is necessary for the ICD client to re-register with the ICD server using a fresh key.

The Check-In handler in an ICD client is responsible for handling unsolicited check-in messages from an ICD server. All ICD clients should add support for Check-In protocol as it is a fail safe mechanism that provides a means to re-establish a secure session with an ICD server. The heart of the module is the check-in handler that receives and parses check-in messages from ICD servers. After ensuring the validity of the message, the check-in handler passes it on to the check-in protocol to parse the message and retrieve the ICD counter value. The ICD counter is used to derive the nonce in the encryption process of the check-in protocol. Beyond that, ICD counters are also used to detect repeated reception of the same message and eliminate duplicates. Once the maximum value for an ICD counter is reached, the counter should roll-over to 0 and when that is done, it is necessary for the ICD client to re-register with the ICD server using a fresh key.

bzbarsky-apple · 2024-10-02T00:04:19Z

src/app/icd/docs/check-in_handler_design.md

+
+• The client is unavailable for any reason
+
+The Check-In handler in an ICD client is responsible for handling unsolicited check-in messages from an ICD server. All ICD clients should add support for Check-In protocol as it is a fail safe mechanism that provides a means to re-establish a secure session with an ICD server. The heart of the module is the check-in handler that receives and parses check-in messages from ICD servers. After ensuring the validity of the message, the check-in handler passes it on to the check-in protocol to parse the message and retrieves the ICD counter value. The ICD counter is used to derive the nonce in the encryption process of the check-in protocol. Beyond that, ICD counters are also used to detect repeated reception of the same message and eliminate duplicates. Once the maximum value for an ICD counter is reached, the counter should roll-over to 0 and when that is done, it is necessary for the ICD client to re-register with the ICD server using a fresh key. 


I do wonder whether it's worth pointing to the relevant spec section here instead of trying to (poorly) duplicate it.

It was just an attempt to provide a gist of what spreads across multiple paragraphs in the spec to someone who is looking at the design without any context. Didn't intend to make a poor duplicate. FYI, the PR is still a draft.

@thivya-amazon I appreciate that this is still a draft, and if you would prefer that I not provide feedback on drafts, just let me know.

For the rest: It's hard to figure out, for me, what the right tradeoff here between talking about details and just giving an overview. But what I would suspect is most useful here is to give a high-level overview of what this thing is trying to accomplish, point to the relevant parts of the specification for details, and discuss which parts of the spec and which invariant enforcement are handled by the SDK code vs which parts are expected to be handed by the application.

Talking about behavior details here but simplifying compared to the spec risks getting them wrong in ways that will confuse people. As a concrete example, it is not in fact necessary for the ICD client to register when roll-over to 0 happens. It's necessary to do when 2^31 values have passed by, which could be way before rollover, or way after, depending on where one starts initially....

bzbarsky-apple · 2024-10-02T00:06:12Z

src/app/icd/docs/images/check-in_handler_design.png

What's the mechanism for ensuring this diagram is updated when the code changes?

The diagram is clearly generated by some tool; can the actual data file for the tool be checked in, so that the diagram is easy to fix if things change?

github-actions · 2025-04-04T02:04:53Z

Adding design document for ICD Check-in handler

fcf1ccc

thivya-amazon marked this pull request as draft October 1, 2024 22:04

github-actions bot added app icd Intermittently Connected Devices labels Oct 1, 2024

Adding design document for ICD Check-in handler

d50dba3

thivya-amazon force-pushed the ICD-document branch from bba5d02 to d50dba3 Compare October 1, 2024 22:07

bzbarsky-apple reviewed Oct 2, 2024

View reviewed changes

github-actions bot added the stale Stale issue or PR label Apr 4, 2025

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

[DRAFT] ICD - Design document for Check-in handler #35866

[DRAFT] ICD - Design document for Check-in handler #35866

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

		@@ -0,0 +1,18 @@
		# Check-in handler overview

		ICD servers send check-in messages to a registered ICD client when a subscription is lost or one was never established. A subscription can be lost for several reasons, such as:


		• The client is unavailable for any reason

		The Check-In handler in an ICD client is responsible for handling unsolicited check-in messages from an ICD server. All ICD clients should add support for Check-In protocol as it is a fail safe mechanism that provides a means to re-establish a secure session with an ICD server. The heart of the module is the check-in handler that receives and parses check-in messages from ICD servers. After ensuring the validity of the message, the check-in handler passes it on to the check-in protocol to parse the message and retrieves the ICD counter value. The ICD counter is used to derive the nonce in the encryption process of the check-in protocol. Beyond that, ICD counters are also used to detect repeated reception of the same message and eliminate duplicates. Once the maximum value for an ICD counter is reached, the counter should roll-over to 0 and when that is done, it is necessary for the ICD client to re-register with the ICD server using a fresh key.

[DRAFT] ICD - Design document for Check-in handler #35866

Are you sure you want to change the base?

[DRAFT] ICD - Design document for Check-in handler #35866

Conversation

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!