Skip to content
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

Document deviations from RFC 8446 PL #566

Merged
merged 1 commit into from
Jul 27, 2024
Merged

Document deviations from RFC 8446 PL #566

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
92 changes: 82 additions & 10 deletions draft-ietf-ppm-dap.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -388,10 +388,6 @@ Report Share:

{:br}

This document uses the presentation language of {{!RFC8446}} to define messages
in the DAP protocol. Encoding and decoding of these messages as byte strings
also follows {{RFC8446}}.

# Overview {#overview}

The protocol is executed by a large set of Clients and a pair of servers
Expand Down Expand Up @@ -640,6 +636,82 @@ DAP has three major interactions which need to be defined:
Each of these interactions is defined in terms of "resources". In this section
we define these resources and the messages used to act on them.

## Message Encoding

We use the presentation language defined in {{!RFC8446, Section 3}} to define
messages in the DAP protocol, with the following deviations.

{{Section 3.7 of !RFC8446}} defines a syntax for structure fields whose values
are constants. In this document, we do not use that notation, but use something
similar to describe specific variants of structures containing enumerated types,
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@tgeoghegan does this mean the syntax from {{Section 3.7 of !RFC8446}} is forbidden in this doc?
If a structure has the following def:

struct {
   uint32 always_present;
   ExampleEnum type;
}

Then does the below have ambiguity?

struct variant {
   uint32 always_present = 0;
   ExampleEnum type = number;
}

Does it mean always_present can only be a constant 0 or it just happens to be 0 in this variant?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@tgeoghegan does this mean the syntax from {{Section 3.7 of !RFC8446}} is forbidden in this doc?

I don't think so. By introducing struct variant, we avoid collision with the RFC 8446 s3.7 notation, meaning it can be used without further complications. However, I don't think DAP ever should: TLS 1.3 needs that notation because it wants some its messages to be backward compatible with TLS 1.2. We have no such problem.

If a structure has the following def:

struct {
   uint32 always_present;
   ExampleEnum type;
}

Then does the below have ambiguity?

struct variant {
   uint32 always_present = 0;
   ExampleEnum type = number;
}

Does it mean always_present can only be a constant 0 or it just happens to be 0 in this variant?

I don't think there's ambiguity because using struct variant makes it clear we're not using the notation from RFC 8446 section 3.7.

Copy link
Contributor

@wangshan wangshan Jul 16, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think there's ambiguity because using struct variant makes it clear we're not using the notation from RFC 8446 section 3.7.

I see, so it essentially overrides RFC 8446 s3.7. Do you think it's worth calling out this in the example? @tgeoghegan

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It does not override that section of RFC 8446. The notation in 8446 section 3.7 is struct { ... } whatever. The notation we introduce here is struct variant { ... } whatever which does not conflict.

described in {{!RFC8446, Section 3.8}}.

For example, suppose we have an enumeration and a structure defined as follows:

~~~
enum {
number(0),
string(1),
(255)
} ExampleEnum;

struct {
uint32 always_present;
ExampleEnum type;
select (ExampleStruct.type) {
case number: uint32 a_number;
case string: opaque a_string<0..10>;
};
} ExampleStruct;
~~~

Then we describe the specific variant of `ExampleStruct` where `type == number`
with a `variant` block like so:

~~~
variant {
/* Field exists regardless of variant */
uint32 always_present;
ExampleEnum type = number;
/* Only fields included in the type == number variant is described */
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How do we express multiple selects and their associated qualified members in this notation? (Such case does not exist in DAP so far I think)

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Since this doesn't occur in DAP, I don't think we need to define it. Also, I would push back pretty hard on any struct definition that contained multiple selects. That would almost certainly allow construction of messages that aren't semantically valid, which would force extra validation checks on implementations. I think we would always prefer a struct contain a single enumeration where all its variants are valid over multiple enumerated types.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

From, the semantics of variants, it is possible to have several selects in a structure. Since variants allow dynamic members of structure, it sounds like legitimate definition to me. Am I missing anything here? Since we are coming up with a notation that could probably be followed in future DAP specs too, I'm trying to make sure we define something that lasts.

I'm fine if you would like to defer this to later updates.

Overall, In this notation, I didn't see the distinction between representing alwaysExsting fields vs fields added as a result of a specific value of enum. Since the order of fields matter, and these dynamic fields can appear in the middle of two static fields, some visual cue (bold/italicized etc) could help to locate them.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can you give an example of when multiple selects in the same struct is ambiguous?

uint32 a_number;
} ExampleStruct;
~~~

The protocol text accompanying this would explain how implementations should
handle the `always_present` and `a_number` fields but not `type`. This does not
mean that the `type` field of `ExampleStruct` can only ever have value `number`.

This notation can also be used in structures where the enum field does not
affect what fields are or are not present in the structure. For example:

~~~
enum {
something(0),
something_else(1),
(255)
} FailureReason;

struct {
FailureReason failure_reason;
opaque another_field<0..256>;
} FailedOperation;
~~~

The protocol text might include a description like:

~~~
variant {
FailureReason failure_reason = something;
opaque another_field<0..256>;
} FailedOperation;
~~~

Encoding and decoding of these messages as byte strings also follows
{{RFC8446}}.

## Basic Type Definitions

The following are some basic type definitions used in other messages:

~~~
Expand Down Expand Up @@ -1492,7 +1564,7 @@ For any report that was rejected, the Helper sets the outbound preparation
response to

~~~
struct {
variant {
ReportID report_id;
PrepareRespState prepare_resp_state = reject;
PrepareError prepare_error;
Expand Down Expand Up @@ -1525,7 +1597,7 @@ initial `outbound` message to send in response to the Leader. If `state` is of
type `Rejected`, then the Helper responds with

~~~
struct {
variant {
ReportID report_id;
PrepareRespState prepare_resp_state = reject;
PrepareError prepare_error = vdaf_prep_error;
Expand All @@ -1535,7 +1607,7 @@ struct {
Otherwise the Helper responds with

~~~
struct {
variant {
ReportID report_id;
PrepareRespState prepare_resp_state = continue;
opaque payload<0..2^32-1> = outbound;
Expand Down Expand Up @@ -1811,7 +1883,7 @@ denote the payload of the prep step. The Helper computes the following:
If `state == Rejected()`, then the Helper's response is

~~~
struct {
variant {
ReportID report_id;
PrepareRespState prepare_resp_state = reject;
PrepareError prepare_error = vdaf_prep_error;
Expand All @@ -1821,7 +1893,7 @@ struct {
Otherwise, if `outbound != None`, then the Helper's response is

~~~
struct {
variant {
ReportID report_id;
PrepareRespState prepare_resp_state = continue;
opaque payload<0..2^32-1> = outbound;
Expand All @@ -1831,7 +1903,7 @@ struct {
Otherwise, if `outbound == None`, then the Helper's response is

~~~
struct {
variant {
ReportID report_id;
PrepareRespState prepare_resp_state = finished;
} PrepareResp;
Expand Down
Loading