long as they do not result in a reduction of security over the above MTI requirements.  For example, ESP compression MAY be used. <del> IKEv2 MUST follow RFC8247 as necessary to support the above listed IPsec requirements. </del>  6.7.1.2.

long as they do not result in a reduction of security over the above MTI requirements.  For example, ESP compression MAY be used.  <ins> As for ESP (above), for IKEv2, the ENCR_AES_GCM_16 encryption algorithm (with 256-bit keys) MUST be supported.  The IKEv2 PRF_HMAC_SHA2_512 pseudorandom function MUST be supported. IKEv2 Diffie-Hellman key exchange group 19 (256-bit random ECP) MUST be supported (in addition to 2048-bit MODP).  ECC provides a similar security level to finite-field (MODP) key exchange with a shorter key length, so is generally preferred absent other considerations. IKEv2 authentication MUST use the ACP domain certificates.  The Certificate Encoding "PKCS #7 wrapped X.509 certificate" (1) MUST be supported (see IKEV2IANA for this and other IANA IKEv2 parameter names used in this text).  If certificate chains are used, all intermediate certificates up to, but not including the locally provisioned trust anchor certificate must be signaled. A certificate payload with the ACP certificate MUST be included during IKEv2 authentication to support the ACP domain membership check as described in certcheck, because it is using additional elements of the ACP certificates.  ACP peers are expected to have the same set of Trust Anchors (TA), so a certificate path MUST only be included in the signaled payload when the path contains intermediate certificates not in the TA set, such as sub-CAs (see acp-registrars). ACP nodes are identified by their ACP address, so the ID_IPv6_ADDR IKEv2 identification payload MUST be used and MUST convey the ACP address.  If the peer's ACP domain certificate includes an ACP address in the domain information, the address in the identification payload must match the address in the certificate (allowing for the presence of virtualization bits in the ACP addressing scheme used). IKEv2 authentication MUST use authentication method 14 ("Digital Signature") for ACP certificates; this authentication method can be used with both RSA and ECDSA certificates, as indicated by a PKIX- style OID. The Digital Signature hash SHA2-512 MUST be supported (in addition to SHA2-256). Once there are updates to RFC8247, these should accordingly be reflected in updates to these ACP requirements, for example if ENCR_AES_GCM_16 was to be superceeded in the future or the key- exchange group recommendations are changed. Additional requirements from RFC8247 MAY be used for ACP channels as long as they do not result in a reduction of security over the above MTI requirements. </ins> 6.7.1.2.


the first transport encryption supported in some classes of constrained devices.  To run ACP via UDP and DTLS v1.2 RFC6347 a locally assigned UDP port is used that is announced as a parameter in the GRASP AN_ACP objective to candidate neighbors.

During IETF 106 I solicited some feedback on the ACP IPsec/IKEv2 usage from Valery Smyslov; I've tried to digest that feedback into new text here. Some aspects are still subject to change. I also made a minor tweak to the DTLS section to bring it into parity with the IPsec one.
Merging first, then fixing.

the first transport encryption supported in some classes of constrained devices. <ins> An ACP node announces its ability to support DTLS as the ACP secure channel protocol in GRASP as the "DTLS" method for the "AN_ACP" objective. </ins> To run ACP via UDP and DTLS v1.2 RFC6347 a locally assigned UDP port is used that is announced as a parameter in the GRASP AN_ACP objective to candidate neighbors.


Abstract <del> This document defines a YANG RPC and a minimal datastore tree required to retrieve attestation evidence about integrity measurements from a composite device with one or more roots of trust for reporting.  Complementary measurement logs are also provided by the YANG RPC originating from one or more roots of trust of measurement.  The module defined requires at least one TPM 1.2 or TPM 2.0 and corresponding Trusted Software Stack included in the device components of the composite device the YANG server is running on. </del>  1. This document is based on the terminology defined in the I-D.ietf- <del> rats-architecture and uses the interaction model and information elements defined in the I-D.birkholz-rats-reference-interaction-model document.  The currently supported hardware security modules (HWM) - sometimes also referred to as an embedded secure element (eSE) - is the Trusted Platform Module (TPM) version 1.2 and 2.0 specified by the Trusted Computing Group (TCG).  One ore more TPMs embedded in the components of a composite device - sometimes also referred to as an aggregate device - are required in order to use the YANG module defined in this document.  A TPM is used as a root of trust for reporting (RTR) in order to retrieve attestation evidence from a composite device (quote primitive operation).  Additionally, it is used as a root of trust for storage (RTS) in order to retain shielded secrets and store system measurements using a folding hash function (extend primitive operation). </del>  1.1.

Provides more context around the various elements of the model
Thanks a lot for your stab at Security Considerations! Also the I-D was in dire need for some expositional english text. Reads straight forward and comprehensive.

Abstract  <ins> This document defines a YANG RPC and a minimal datastore required to retrieve attestation evidence about integrity measurements from a device following the operational context defined in I-D.ietf-rats- tpm-based-network-device-attest.  Complementary measurement logs are also provided by the YANG RPC originating from one or more roots of trust of measurement.  The module defined requires at least one TPM 1.2 or TPM 2.0 and corresponding Trusted Software Stack included in the device components of the composite device the YANG server is running on. </ins> 1. This document is based on the terminology defined in the I-D.ietf-  <ins> rats-architecture and uses the operational context defined in I- D.ietf-rats-tpm-based-network-device-attest as well as the interaction model and information elements defined in I-D.birkholz- rats-reference-interaction-model.  The currently supported hardware security modules (HWM) are the Trusted Platform Module (TPM) TPM1.2 and TPM2.0 specified by the Trusted Computing Group (TCG).  One ore more TPMs embedded in the components of a composite device - sometimes also referred to as an aggregate device - are required in order to use the YANG module defined in this document.  A TPM is used as a root of trust for reporting (RTR) in order to retrieve attestation evidence from a composite device (quote primitive operation).  Additionally, it is used as a root of trust for storage (RTS) in order to retain shielded secrets and store system measurements using a folding hash function (extend primitive operation). </ins> 1.1.


2.2.1. This YANG module imports modules from RFC6991, RFC8348, I-D.ietf- <del> netconf-crypto-types, ietf-asymmetric-algs.yang. </del>  <del> 2.3. </del>  Cryptographic algorithm types were initially included within -v14 NETCONF's iana-crypto-types.yang.  Unfortunately all this content including the algorithms needed here failed to make the -v15 used <del> WGLC.  Therefore a modified version of this draft is included here. Perhaps someone will steward this list as a separate draft. </del>  3. This document will include requests to IANA: <del> To be defined yet. </del>  4. <del> There are always some. </del>  5.  Changes from version 01 to version 02: Extracted Crypto-types into a separate YANG file

2.2.1. This YANG module imports modules from RFC6991, RFC8348, I-D.ietf-  <ins> netconf-keystore, ietf-tcg-algs.yang. </ins>  <ins> 2.2.1.1. This module supports the following types of attestation event logs: <ima>, <bios>, and <netequip_boot>. 2.2.1.2. <tpm12-challenge-response-attestation> - Allows a Verifier to request a quote of PCRs from a TPM1.2 compliant cryptoprocessor.  When one or more <certificate-name> is not provided, all TPM1.2 compliant cryptoprocessors will respond. <tpm20-challenge-response-attestation> - Allows a Verifier to request a quote of PCRs from a TPM2.0 compliant cryptoprocessor.  When one or more <certificate-name> is not provided, all TPM2.0 compliant cryptoprocessors will respond. <log-retrieval> - Allows a Verifier to acquire the evidence which was extended into specific PCRs. 2.2.1.3. container <rats-support-structures> - This exists when there are more than one TPM for a particular Attester.  This allows each specific TPM to identify on which <compute-node> it belongs. container <tpms> - Provides configuration and operational details for each supported TPM, including the tpm-firmware-version, PCRs which may be quoted, certificates which are associated with that TPM, and the current operational status.  Of note is the certificates which are associated with that TPM.  As a certificate is associated with a single Attestation key, knowledge of the certificate allows a specific TPM to be identified. container <attester-supported-algos> - Identifies which TCG algorithms are available for use the Attesting platform.  This allows an operator to limit algorithms available for use by RPCs to just a desired set from the universe of all allowed by TCG. 2.2.1.4. 2.2.2. </ins> Cryptographic algorithm types were initially included within -v14 NETCONF's iana-crypto-types.yang.  Unfortunately all this content including the algorithms needed here failed to make the -v15 used  <ins> WGLC.  As a result this document has encoded the TCG Algorithm definitions of TCG-Algos, revision 1.32.  By including this full table as a separate YANG file within this document, it is possible for other YANG models to leverage the contents of this model. 2.2.2.1. There are two types of features supported <TPM12> and <TPM20>. Support for either of these features indicates that a cryptoprocessor supporting the corresponding type of TCG API is present on an Attester.  Most commonly, only one type of cryptoprocessor will be available on an Attester. 2.2.2.2. There are three types of identities in this model. The first are the cryptographic functions supportable by a TPM algorithm, these include: <asymmetric>, <symmetric>, <hash>, <signing>, <anonymous_signing>, <encryption_mode>, <method>, and <object_type>.  The definitions of each of these are in Table 2 of TCG-Algos. The second are API specifications for tpms: <tpm12> and <tpm2>. The third are specific algorithm types.  Each algorithm type defines what cryptographic functions may be supported, and on which type of API specification.  It is not required that an implementation of a specific TPM will support all algorithm types.  The contents of each specific algorithm mirrors what is in Table 3 of TCG-Algos. 2.2.2.3. Note that not all cryptographic functions are required for use by ietf-tpm-remote-attestation.yang.  However the full definition of Table 3 of TCG-Algos will allow use by additional YANG specifications. </ins> 3. This document will include requests to IANA:  <ins> To be defined yet.  But keeping up with changes to ietf-tcg-algs.yang will be necessary. </ins> 4.  <ins> The YANG module specified in this document defines a schema for data that is designed to be accessed via network management protocols such as NETCONF RFC6241 or RESTCONF RFC8040.  The lowest NETCONF layer is the secure transport layer, and the mandatory-to-implement secure transport is Secure Shell (SSH) RFC6242.  The lowest RESTCONF layer is HTTPS, and the mandatory-to-implement secure transport is TLS RFC5246. There are a number of data nodes defined in this YANG module that are writable/creatable/deletable (i.e., config true, which is the default).  These data nodes may be considered sensitive or vulnerable in some network environments.  Write operations (e.g., edit-config) to these data nodes without proper protection can have a negative effect on network operations.  These are the subtrees and data nodes and their sensitivity/vulnerability: Container: </rats-support-structures/attester-supported-algos> <tpm12-asymmetric-signing>, <tpm12-hash>, <tpm20-asymmetric- signing>, and <tpm20-hash> all could be populated with algorithms which are not supported by the underlying physical TPM installed by the equipment vendor. Container: </rats-support-structures/tpms> <tpm-name> - Although shown as 'rw', it is system generated <tpm20-pcr-bank> - It is possible to configure PCRs for extraction which are not being extended by system software.  This could unnecessarily use TPM resources. <certificates> - It is possible to provision a certificate which does not correspond to a Attestation Identity Key (AIK) within the TPM. RPC: <tpm12-challenge-response-attestation> - Need to verify that the certificate is for an active AIK. RPC: <tpm20-challenge-response-attestation> - Need to verify that the certificate is for an active AIK. RPC: <log-retrieval> - Pulling lots of logs can chew up system resources. </ins> 5. <ins> Changes from version 02 to version 03: moved to tcg-algs cleaned up model to eliminate sources of errors removed key establishment RPC added lots of XPATH which must all be scrubbed still Descriptive text added on model contents. </ins> Changes from version 01 to version 02: Extracted Crypto-types into a separate YANG file


1. Bootstrapping Remote Secure Key Infrastructures BRSKI specifies <del> automated bootstrapping of an Autonomic Control Plane.  BRSKI Section 2.7 describes how a pledge "MAY contact a well-known URI of a cloud registrar if a local registrar cannot be discovered or if the pledge's target use cases do not include a local registrar". </del>  This document further specifies use of a BRSKI cloud registrar and clarifies operations that are not sufficiently specified in BRSKI.

Not quite. It specifies secure bootstrapping of the individual nodes. It's RFC 8994 that bootstraps the ACP.

1. Bootstrapping Remote Secure Key Infrastructures BRSKI specifies  <ins> automated network onboarding of devices, referred to as pledges, within an Autonomic Control Plane or other managed network infrastructure.  BRSKI Section 2.7 describes how a pledge "MAY contact a well-known URI of a cloud registrar if a local registrar cannot be discovered or if the pledge's target use cases do not include a local registrar". </ins> This document further specifies use of a BRSKI cloud registrar and clarifies operations that are not sufficiently specified in BRSKI.


logically separate entities.  The two functions could of course be integrated into a single service. <del> TWO CHOICES: 1.  Cloud Registrar redirects to Owner Registrar 2. Cloud Registrar returns VOUCHER pinning Owner Register. </del>  2.1.

I find the "??" in the figure confusing. The Cloud Registrar and the MASA could just be shown as adjacent boxes; the explanation in the text is fine. That looks ugly as a single pseudo-sentence, and I'm not sure what it means. A more complete explanation would be good.

logically separate entities.  The two functions could of course be integrated into a single service.  <ins> There are two different mechanisms for a cloud registrar to handle voucher requests: 1. the Cloud Registrar redirects the request to Owner Registrar for handling 2. the Cloud Registrar returns a voucher pinning the Owner Register and includes additional bootstrapping information embedded in the voucher Both mechanisms are described in detail later in this document. </ins> 2.1.


<del> CAPPORT Architecture </del>  draft-ietf-capport-architecture-08 Abstract <del> This document describes a CAPPORT architecture.  DHCP or Router Advertisements, an optional signaling protocol, and an HTTP API are used to provide the solution.  The role of Provisioning Domains (PvDs) is described. </del>  1.

This replaces all mentions of capport (other than document slugs) with "captive portal". Note: this change includes the title of the document.
Joel Halpern writes, We should do this.
Or erase all mentions of 'capport'

<ins> Captive Portal Architecture </ins> draft-ietf-capport-architecture-08 Abstract  <ins> This document describes a captive portal architecture.  DHCP or Router Advertisements, an optional signaling protocol, and an HTTP API are used to provide the solution.  The role of Provisioning Domains (PvDs) is described. </ins> 1.


2.2.1. A standard for providing a portal URI using DHCP or Router <del> Advertisements is described in RFC7710bis.  The CAPPORT architecture expects this URI to indicate the API described in section_api. </del>  2.2.2.

2.2.1. A standard for providing a portal URI using DHCP or Router  <ins> Advertisements is described in RFC7710bis.  The captive portal architecture expects this URI to indicate the API described in section_api. </ins> 2.2.2.


A side-benefit of the architecture described in this document is that devices without user interfaces are able to identify parameters of <del> captivity.  However, this document does not yet describe a mechanism for such devices to escape captivity. </del>  The architecture uses the following mechanisms:

Multiple reviewers objected to the way in which we captured interactions with headless/UI-less devices. Clarify the document's intent. Do this by removing language that indicated that we would eventually get around to adding the requirements, and specify explicitly that we are not handling devices without UIs.
Eric points out in his review: He suggests as a solution: I propose we do this. The first mention is in section one. We can say something along the lines of "A future document could provide a solution for devices without user interfaces. This document focuses on devices with user interfaces."
On page 4: Joel Halpern writes,
We might want to avoid relying on the captivity concept so heavily, but this is a good change nonetheless.

A side-benefit of the architecture described in this document is that devices without user interfaces are able to identify parameters of  <ins> captivity.  However, this document does not describe a mechanism for such devices to negotiate for unrestricted network access.  A future document could provide a solution to devices without user interfaces. This document focuses on devices with user interfaces. </ins> The architecture uses the following mechanisms:


section_capport_enforcement, until site-specific requirements have been met. <del> At this time we consider only devices with web browsers, with web </del>  applications being the means of satisfying Captive Portal Conditions. <del> An example interactive User Equipment is a smart phone. </del>  The User Equipment:

section_capport_enforcement, until site-specific requirements have been met.  <ins> This document only considers devices with web browsers, with web </ins> applications being the means of satisfying Captive Portal Conditions.  <ins> An example of such User Equipment is a smart phone. </ins> The User Equipment:


A Captive Portal API needs to present information to clients that is unique to that client.  To do this, some systems use information from the context of a request, such as the source address, to identify the <del> UE. </del>  Using information from context rather than information from the URI allows the same URI to be used for different clients.  However, it also means that the resource is unable to provide relevant <del> information if the UE makes a request using a different network path. This might happen when UE has multiple network interfaces.  It might also happen if the address of the API provided by DNS depends on where the query originates (as in split DNS RFC8499). </del>  Accessing the API MAY depend on contextual information.  However, the <del> URIs provided in the API SHOULD be unique to the UE and not dependent on contextual information to function correctly. Though a URI might still correctly resolve when the UE makes the request from a different network, it is possible that some functions could be limited to when the UE makes requests using the captive network.  For example, payment options could be absent or a warning could be displayed to indicate the payment is not for the current connection. </del>  URIs could include some means of identifying the User Equipment in the URIs.  However, including unauthenticated User Equipment

We only use UE in one section. Everywhere else we use User Equipment. Expand UE in that section so we are consistent with our use of it.
It was pointed out that we sometimes use UE rather than user equipment (e.g. section 3.5.). Let's be consistent, perhaps shortening all references to UE other than where it is defined.

A Captive Portal API needs to present information to clients that is unique to that client.  To do this, some systems use information from the context of a request, such as the source address, to identify the  <ins> User Equipment. </ins> Using information from context rather than information from the URI allows the same URI to be used for different clients.  However, it also means that the resource is unable to provide relevant  <ins> information if the User Equipment makes a request using a different network path.  This might happen when User Equipment has multiple network interfaces.  It might also happen if the address of the API provided by DNS depends on where the query originates (as in split DNS RFC8499). </ins> Accessing the API MAY depend on contextual information.  However, the  <ins> URIs provided in the API SHOULD be unique to the User Equipment and not dependent on contextual information to function correctly. Though a URI might still correctly resolve when the User Equipment makes the request from a different network, it is possible that some functions could be limited to when the User Equipment makes requests using the captive network.  For example, payment options could be absent or a warning could be displayed to indicate the payment is not for the current connection. </ins> URIs could include some means of identifying the User Equipment in the URIs.  However, including unauthenticated User Equipment


Captive Portal Signaling Protocol: Also known as Signaling Protocol. The protocol for communicating Captive Portal Signals.  2. 2.1.

The idea of a session is important, both because it is used in the API document, and because it helps to tie everything together. Define it in the terminology.
This is a first stab at defining the session. I suspect we may need to iterate on it once or twice. Let me know if you think it deserves its own section on top of the terminology.
Thanks for doing this! Here’s a suggested alternate way to explain this. Feel free to modify as desired. Captive Portal Session: Also referred to simply as the “session”, a Captive Portal Session is the association for a particular User Equipment that starts when it interacts with the Captive Portal and gains open access to the network, and ends when the User Equipment moves back into the original captive state. The Captive Network maintains the state of each active Session, and can limit Sessions based on a length of time or a number of bytes used. The Session is associated with a particular User Equipment using the User Equipment's identifier (see ).
Your phrasing is better. It manages to work in the session limits while keeping it about the same lenght. I've taken it almost verbatim. NAME Do you have any input on this topic?
From Ben's review of the API document, we should define "session" formally in the architecture. The architecture doc mentions it in passing once already. The API doc uses the term session much more.

Captive Portal Signaling Protocol: Also known as Signaling Protocol. The protocol for communicating Captive Portal Signals. <ins> Captive Portal Session: Also referred to simply as the "session", a Captive Portal Session is the association for a particular User Equipment that starts when it interacts with the Captive Portal and gains open access to the network, and ends when the User Equipment moves back into the original captive state.  The Captive Network maintains the state of each active Session, and can limit Sessions based on a length of time or a number of bytes used.  The Session is associated with a particular User Equipment using the User Equipment's identifier (see ue_identity). </ins> 2. 2.1.


Architecture RFC7556 provides some discussion on authenticating an operator. <del> Given that a user chooses to visit a Captive Portal URI, the URI location SHOULD be securely provided to the user's device.  E.g., the DHCPv6 AUTH option can sign this information. </del>  If a user decides to incorrectly trust an attacking network, they might be convinced to visit an attacking web page and unwittingly

The language of this section was hard for some of the reviewers to understand. Rephrase it to be more explicit and clear.
Yes. We should probably rephrase this. E.g. "The user makes an informed choice in deciding to visit and trust the Captive Portal URI. Since the network provides Captive Portal URI to the user equipment, thenetwork SHOULD do so securely so that the user's trust in the network can extend to their trust of the Captive Portal URI. E.g., the DHCPv6 AUTH option can sign this information."

Architecture RFC7556 provides some discussion on authenticating an operator.  <ins> The user makes an informed choice to visit and trust the Captive Portal URI.  Since the network provides Captive Portal URI to the user equipment, the network SHOULD do so securely so that the user's trust in the network can extend to their trust of the Captive Portal URI.  E.g., the DHCPv6 AUTH option can sign this information. </ins> If a user decides to incorrectly trust an attacking network, they might be convinced to visit an attacking web page and unwittingly


This document describes an architecture for implementing captive portals while addressing most of the problems arising for current captive portal mechanisms.  The architecture is guided by these <del> principles: </del>  A side-benefit of the architecture described in this document is that devices without user interfaces are able to identify parameters of

Attempting to fix issue . I attempted to reword the principles, adding more prose for the rationale. Also upgraded some SHOULD NOT to MUST NOT because it seems some people thought the SHOULD NOT says the existing approach is OK. These are just some ideas. I won't be offended if rejected.
I believe I addressed all comments. You'll probably want to review the complete diff again.
Benjamin writes in his review: Michael replied with this suggested text: This seems reasonable, as I mentioned in the reply. We should go with it, unless anyone has an objection. Also, attribute it to Michael Richardson.
S. Moonesamy writes
One approach I suggested in my reply to the feedback:
This is good. Thanks for sorting through this; it's important that this is right, and you have cleared it up a lot.Much clearer. Thanks!

This document describes an architecture for implementing captive portals while addressing most of the problems arising for current captive portal mechanisms.  The architecture is guided by these  <ins> requirements: </ins> A side-benefit of the architecture described in this document is that devices without user interfaces are able to identify parameters of


The authors thank Benjamin Kaduk for providing the content related to TLS certificate validation of the API server.  The authors thank various individuals for their feedback on the mailing list and during the IETF98 hackathon: David Bird, Erik Kline, Alexis La Goulette, Alex Roscoe, Darshak Thakore, and Vincent van

The authors thank Benjamin Kaduk for providing the content related to TLS certificate validation of the API server. <ins> The authors thank Michael Richardson for providing wording requiring DNSSEC and TLS to operate without the user adding exceptions. </ins> The authors thank various individuals for their feedback on the mailing list and during the IETF98 hackathon: David Bird, Erik Kline, Alexis La Goulette, Alex Roscoe, Darshak Thakore, and Vincent van


The API MUST ensure the integrity of this information, as well as its confidentiality.  7.4. If a Signaling Protocol is implemented, it may be possible for any

One of the reviewers asked for more information about the attacker in section 7.3. This does so, describing what the attacker could achieve by compromising the security.
Benjamin writes, Without knowing the details of the particular solution, it's a bit hard to say for sure, but roughly I'd say it's someone who wants to interact with the API using the identity of the user. E.g. if we're using an 'unguessable' URI, an attacker snooping on the communication with the API could determine the URI, and use it.

The API MUST ensure the integrity of this information, as well as its confidentiality. <ins> An attacker with access to this information might be able to masquerade as a specific User Equipment when interacting with the API, which could then allow them to masquerade as that User Equipment when interacting with the User Portal.  This could give them the ability to determine whether the User Equipment has accessed the portal, or deny the User Equipment service by ending their session using mechanisms provided by the User Portal, or consume that User Equipment's quota.  An attacker with the ability to modify the information could deny service to the User Equipment, or cause them to appear as a different User Equipment. </ins> 7.4. If a Signaling Protocol is implemented, it may be possible for any


2.5. <del> User Equipment may send traffic to hosts blocked by the captive network prior to the Enforcement device granting it access.  The Enforcement Device rightly blocks or resets these requests.  However, in the absence of a signal from the Enforcement Device or interaction with the API server, the User Equipment can only guess at whether it is captive.  Consequently, allowing the Enforcement Device to explicitly signal to the User Equipment that the traffic is being blocked may improve the user's experience. An Enforcement Device may also want to notify the User Equipment of a pending expiry of its access to the external network, so providing the Enforcement Device the ability to preemptively signal may be desirable. A specific Captive Portal Signaling Protocol is out of scope for this document.  However, in order to ensure that future protocols fit into the architecture, requirements for a Captive Portal Signaling Protocol follow: The Captive Portal Signaling Protocol does not provide any means of indicating that the network prevents access to some destinations. The intent is to rely on the Captive Portal API and the web portal to which it points to communicate local network policies. The Captive Portal Enforcement function MAY send Captive Portal Signals when User Equipment that has not satisfied the Captive Portal Conditions attempts to send traffic to the network.  These signals MUST be rate-limited to a configurable rate. The signals MUST NOT be sent to the destinations/peers that the User Equipment is restricted from accessing.  The indications are only to be sent to the User Equipment. </del>  2.6.

The working group has decided that we do not need to tackle specifying the signaling protocol. Rather than leaving the document with it partially specified, remove most of the text related to it. Keep some basic examples of constraints. This also removes the text which claimed that the document would specify rqeuirements for the protocol. It does not. Made a few related editorial changes.
As suggested by NAME : Do a pass through the document with this text in mind and make sure it makes sense. Clean up anything that may have depended on removed text.
Thanks for putting this together. This seems sufficient, and brief.

2.5.  <ins> When User Equipment first connects to a network, or when there are changes in status, the Enforcement Device could generate a signal toward the User Equipment.  This signal indicates that the User Equipment might need to contact the API Server to receive updated information.  For instance, this signal might be generated when the end of a session is imminent, or when network access was denied. An Enforcement Device MUST rate-limit any signal generated in response to these conditions.  See section_signal_risks for a discussion of risks related to a Captive Portal Signal. </ins> 2.6.


7.5. <del> The Signal could inform the User Equipment that it is being held captive.  There is no requirement that the User Equipment do something about this.  Devices MAY permit users to disable automatic reaction to captive-portal indications for privacy reasons.  However, there would be the trade-off that the user doesn't get notified when network access is restricted.  Hence, end-user devices MAY allow users to manually control captive portal interactions, possibly on the granularity of Provisioning Domains. </del>

7.5.  <ins> The Captive Portal Signal could inform the User Equipment that it is being held captive.  There is no requirement that the User Equipment do something about this.  Devices MAY permit users to disable automatic reaction to Captive Portal Signals indications for privacy reasons.  However, there would be the trade-off that the user doesn't get notified when network access is restricted.  Hence, end-user devices MAY allow users to manually control captive portal interactions, possibly on the granularity of Provisioning Domains. </ins>


information, expiry time, method of providing credentials, security token for validating ICMP messages. <del> This document does not specify the details of the API. </del>  <del> The CAPPORT API MUST support TLS for privacy and server authentication. </del>  2.4.

We want to make TLS a requirement, not a suggestion, so I've chagned the wording around TLS to reflect this. I also added a section to the security section discussing the motivation behind the requirement.
Can you forward to the list please?

information, expiry time, method of providing credentials, security token for validating ICMP messages.  <ins> The API MUST use TLS for privacy and server authentication.  The implementation of the API MUST ensure both privacy and integrity of any information provided by or required by it. </ins>  <ins> This document does not specify the details of the API. </ins> 2.4.


5.2. The solution described here assumes that when the User Equipment <del> needs to trust the API server, server authentication will be utilized using TLS mechanisms. </del>  5.3.  It is possible for any user on the Internet to send ICMP packets in an attempt to cause the receiving equipment to go to the captive portal.  This has been considered and addressed in the following

5.2. The solution described here assumes that when the User Equipment  <ins> needs to trust the API server, server authentication will be performed using TLS mechanisms. </ins> 5.3. <ins> The solution described here requires that the API be secured using TLS.  This is required to allow the user equipment and API server to exchange secrets which can be used to validate future interactions. The API must ensure the integrity of this information, as well as its confidentiality. 5.4. </ins> It is possible for any user on the Internet to send ICMP packets in an attempt to cause the receiving equipment to go to the captive portal.  This has been considered and addressed in the following


Even when redirected, the User Equipment securely authenticates with API servers. <del> 5.4. </del>  The ICMP messaging informs the User Equipment that it is being held captive.  There is no requirement that the User Equipment do

Even when redirected, the User Equipment securely authenticates with API servers.  <ins> 5.5. </ins> The ICMP messaging informs the User Equipment that it is being held captive.  There is no requirement that the User Equipment do


3.  This section aims to improve understanding by describing a possible workflow of solutions adhering to the architecture. <del> 3.1. </del>  This section describes a possible work-flow when User Equipment initially joins a Captive Network.

We need to discuss what information will be used to identify the UE from the perspective of the various components in the system. This updates the draft to discuss this concept, including desired properties of the identifier and some examples. This aims to address issue 5 (URL)

3. <ins> Multiple components in the architecture interact with both the User Equipment and each other.  Since the User Equipment is the focus of these interactions, the components must be able to both identify the user equipment from their interactions with it, and be able to agree on the identify of the user equipment when interacting with each other. The methods by which the components interact restrict the type of information that may be used as an identifying charactertics.  This section discusses the identifying charactersitics. 3.1. An Identifier is a chatacteristic of the User Equipment used by the components of a Captive Portal to uniquely determine which specific User Equipment is interacting with them.  An Identifier MAY be a field contained in packets sent by the User Equipment to the External Network.  Or, an Identifier MAY be an ephemeral property not contained in packets destined for the External Network, but instead correlated with such information through knowledge available to the different components. 3.2. The set of possible identifiers is quite large.  However, in order to be considered a good identifer, an identifier SHOULD meet the following criteria.  Note that the optimal identifier will likely change depending on the positino of the components in the network as well as the information available to them.  An identifier SHOULD: Uniquely Identify the User Equipment Be Hard to Spoof Be Visible to the API Be Visible to the Enforcement Device 3.2.1. In order to uniquely identify the User Equipment, at most one user equipment interacting with the other components of the Captive Portal MUST have a given value of the identifier. Over time, the user equipment identified by the value MAY change. Allowing the identified device to change over time ensures that the space of possible identifying vallues need not be overly large. Independent Captive Portals MAY use the same identifying value to identify different User Equipment.  Allowing indendent captive portals to reuse identifying values allows the identifier to be a property of the local network, expanding the space of possible identifiers. 3.2.2. A good identifier does not lend itself to being easily spoofed.  At no time should it be simple or straightforward for one User Equipment to pretend to be another User Equipment, regardless of whether both are active at the same time.  This property is particularly important when the user equipment is extended externally to devices such as billing systems, or where the identity of the User Equipment could imply liability. 3.2.3. Since the API will need to perform operations which rely on the identify of the user equipment, such as query whether it is captive, the API needs to be able to relate requests to the User Equipment making the request. 3.2.4. The Enforcement Device will decide on a per packet basis whether it should be permitted to communicate with the external network.  Since this decision depends on which User Equipment sent the packet, the Enforcement Device requires that it be able to map the packet to its concept of the User Equipment. 3.3. To evaluate whether an identifer is appropriate, one should consider every recommended property from the perspective of interactions among the components in the architecture.  When comparing identifiers, choose the one which best satifies all of the recommended properties. The architecture does not provide an exact measure of how well an identifier satisfies a given property; care should be taken in performing the evaluation. 3.4. This section provides some examples of identifiers, along with some evaluation of whether they are good identifiers.  The list of identifiers is not exhaustive.  Other identifiers may be used.  An important point to note is that whether the identifiers are good depends heavily on the capabilities of the components and where in the network the components exist. 3.4.1. The physical interface by which the User Equipment is attached to the network can be used to identify the User Equipment.  This identifier has the property of being extremely difficult to spoof: the User Equipment is unaware of the property; one User Equipment cannot manipulate its interactions to appear as though it is another. Further, if only a single User Equipment is attatched to a given physical interface, then the identifier will be unique.  If multiple User Equipment is attached to the network on the same physical interface, then this property is not appropriate. Another consideration related to uniqueness of the User Equipment is that if the attached User Equipment changes, both the API server and the Enforcement Device must invalidate their state related to the User Equipment. The Enforcement Device needs to be aware of the physical interface, which constrains the environment: it must either be part of the device providing physical access (e.g., implemented in firmware), or packets traversing the network must be extended to include information about the source physical interface (e.g.  a tunnel). The API server faces a similar problem, implying that it should co- exist with the Enforcement Device, or that the enforcement device should extend requests to it with the identifying information. 3.4.2. A natural identifier to consider is the IP address of the User Equipment.  At any given time, no device on the network can have the same IP address without causing the network to malfunction, so it is appropriate from the perspective of uniqueness. However, it may be possible to spoof the IP address, particularly for malicious reasons where proper functioning of the network is not necessary for the malicious actor.  Consequently, any solution using the IP address should proactively try to prevent spoofing of the IP address.  Similarily, if the mapping of IP address to User Equipment is changed, the components of the architecture must remove or update their mapping to prevent spoofing.  Demonstrations of return routeability, such as that required for TCP connection establishment, might be sufficient defense against spoofing, though this might not be sufficient in networks that use broadcast media (such as some wireless networks). Since the IP address may traverse multiple segments of the network, more flexibility is afforded to the Enforcement Device and the API server: they simply must exist on a segment of the network where the IP address is still unique.  However, consider that a NAT may be deployed between the User Equipment and the Enforcement Device.  In such cases, it is possible for the components to still uniquely identify the device if they are aware of the port mapping. In some situtations, the User Equipment may have multiple IP addresses, while still satisfying all of the recommended properties. This raises some challenges to the components of the network.  For example, if the user equipment tries to access the network with multiple IP addresses, should the enforcement device and API server treat each IP address as a unique User Equipment, or should it tie the multiple addresses together into one view of the subscriber?  An implementation MAY do either.  Attention should be paid to IPv6 and the fact that it is expected for a device to have multiple IPv6 addresses on a single link.  In such cases, idenfication could be performed by subnet, such as the /64 to which the IP belongs. 4. </ins> This section aims to improve understanding by describing a possible workflow of solutions adhering to the architecture.  <ins> 4.1. </ins> This section describes a possible work-flow when User Equipment initially joins a Captive Network.


The User Equipment accesses the network until conditions Expire. <del> 3.2. </del>  This section describes a possible work-flow when conditions expire and the user visits the portal again (e.g., low quota, or time

The User Equipment accesses the network until conditions Expire.  <ins> 4.2. </ins> This section describes a possible work-flow when conditions expire and the user visits the portal again (e.g., low quota, or time


The User Equipment accesses the external network. <del> 4. </del>  This memo includes no request to IANA. <del> 5. </del>  <del> 5.1. </del>  When joining a network, some trust is placed in the network operator. This is usually considered to be a decision by a user on the basis of

The User Equipment accesses the external network.  <ins> 5. </ins> This memo includes no request to IANA.  <ins> 6. </ins>  <ins> 6.1. </ins> When joining a network, some trust is placed in the network operator. This is usually considered to be a decision by a user on the basis of


provide credentials to an attacker.  Browsers can authenticate servers but cannot detect cleverly misspelled domains, for example. <del> 5.2. </del>  The solution described here assumes that when the User Equipment needs to trust the API server, server authentication will be performed using TLS mechanisms. <del> 5.3. </del>  The solution described here requires that the API be secured using TLS.  This is required to allow the user equipment and API server to

provide credentials to an attacker.  Browsers can authenticate servers but cannot detect cleverly misspelled domains, for example.  <ins> 6.2. </ins> The solution described here assumes that when the User Equipment needs to trust the API server, server authentication will be performed using TLS mechanisms.  <ins> 6.3. </ins> The solution described here requires that the API be secured using TLS.  This is required to allow the user equipment and API server to


The API must ensure the integrity of this information, as well as its confidentiality. <del> 5.4. </del>  It is possible for any user on the Internet to send ICMP packets in an attempt to cause the receiving equipment to go to the captive

The API must ensure the integrity of this information, as well as its confidentiality.  <ins> 6.4. </ins> It is possible for any user on the Internet to send ICMP packets in an attempt to cause the receiving equipment to go to the captive


Even when redirected, the User Equipment securely authenticates with API servers. <del> 5.5. </del>  The ICMP messaging informs the User Equipment that it is being held captive.  There is no requirement that the User Equipment do

Even when redirected, the User Equipment securely authenticates with API servers.  <ins> 6.5. </ins> The ICMP messaging informs the User Equipment that it is being held captive.  There is no requirement that the User Equipment do


2.2. <del> Both the client and the server MUST send a Capabilities and Settings message (CSM see csm) as its first message on the connection.  This message establishes the initial settings and capabilities for the endpoint such as maximum message size or support for block-wise transfers.  The absence of options in the CSM indicates that base values are assumed. To avoid unnecessary latency, a client MAY send additional messages without waiting to receive the server CSM; however, it is important to note that the server CSM might advertise capabilities that impact how a client is expected to communicate with the server.  For example, the server CSM could advertise a Max-Message-Size option (see max-message-size) that is smaller than the base value (1152). Clients and servers MUST treat a missing or invalid CSM as a connection error and abort the connection (see sec-abort). 2.3. </del> The CoAP message format defined in RFC7252, as shown in CoAP-Header, relies on the datagram transport (UDP, or DTLS over UDP) for keeping the individual messages separate and for providing length

URL CoAP over WebSockets The following now seems unrelated: Another possible configuration is to set up a CoAP forward proxy at the WebSocket endpoint. Depending on what transports are available Figure 12: CoAP Client (UDP client) accesses sleepy CoAP Server (WebSocket client) via a CoAP proxy (UDP server/WebSocket server) s/sleepy// (There is no mention of sleepiness here.) CoAP over WebSockets is intentionally very similar to CoAP over UDP. Therefore, instead of presenting CoAP over WebSockets as a new protocol, this document specifies it as a series of deltas from [RFC7252]. Probably best to delete that paragraph -- it is true not only for WS, but also for TCP. So why only here? 3.1. Opening Handshake Hmm, the title is confusing. WS also uses the same opening handshake as 2.3. The parts that relate to both TCP/TLS and WS/S need to be factored out. 3.2. Message Format The message format shown in Figure 14 is the same as the CoAP over TCP message format (see Section 2.4) with one restriction. The Length (Len) field MUST be set to zero because the WebSockets frame already contains the length. s/restriction/change/. The CoAP over TCP message format eliminates the Version field defined in CoAP over UDP. If CoAP version negotiation is required in the future, CoAP over WebSockets can address the requirement by the definition of a new subprotocol identifier that is negotiated during the opening handshake. This paragraph is a bit weird. Maybe: As with CoAP over TCP, the message format for CoAP over Websockets eliminates the Version field defined in CoAP over UDP. If CoAP Empty messages (Code 0.00) MUST be ignored by the recipient (see also Section 4.4). Why are we saying this here and not in Section 2? Factor out. 3.3. Message Transmission Similar as with CoAP over TCP, Retransmission and deduplication of messages is provided by the WebSocket protocol. CoAP over WebSockets therefore does not make a distinction between Confirmable or Non-Confirmable messages, and does not provide Acknowledgement or Reset messages. 3.4. Connection Health There is no way to retransmit a request without creating a new one. Re-registering interest in a resource is permitted, but entirely unnecessary. (See the discussion we already had.) [Brian] - The reference is
Closing the Connection Does this mean, only the client must cancel the requests? Or should the server do this also? Then a clarfication may be useful.
The original - URL - was specific to Observe: ~ All updates to Observe are now captured in a single place - Appendix A. This specific case is in URL At this point, I think that Closing the Connection could simply be deleted because there are no specific changes required.
Let's say a client has sent one or more requests to a server but hasn't received any response yet, and/or is observing a resource at a server. If the client or the server closes the connection or if the connection goes down unexpectedly, then the client will never receive the responses or any further notifications. The client has to reconnect and send new requests. Neither the client nor the server needs to send anything to cancel active requests before closing the connection; when a connection closes, all active requests are canceled automatically. The client should signal that to the code waiting for the responses, e.g., by throwing an exception. The server should abort processing the requests or at least discard the responses once the requests have been processed. The server also should remove the client from the lists of observers (at latest when it tries to send the next notification and it notices that the connection is down).
URL General - It's not clear "how" mandatory the use of the CSM is. Clause 2.3 on TCP/TLS indicates that the CSM message must be sent at the start of the connection. Clause 3.1 on Websockets makes no mention of CSM messages. Clause 4.3 indicates that the CSM MUST be sent at the start of the connection also and makes no distinction between TCP/TLS and Websockets. Clause 2.3 also indicates that the connection must be aborted if the CSM is missing or invalid as the first message on the connection. Given the discussion about address changes does more information need to be provided what start of connection means?
In the , the intent of this statement is unclear: There is no way to retransmit a request without creating a new one. Re-registering interest in a resource is permitted, but entirely unnecessary.
Response from Klaus Hartke: In general, CoAP clients are not allowed to use a token while it is still in use. RFC 7641 defines an exception: a client is allowed to confirm its interest in receiving notifications for a resource by sending a request identical to the original registration request, including the token that is already in use. The above paragraph just says that this is also the case for CoAP over TCP/TLS/WebSockets, but points out that sending a Ping (which checks the health of the connection and hence of all active observations) is better than confirming the interest for all active observations individually. Response from Carsten: Yes, the text is much easier to understand in that context — in the old draft, it was clear that this talks about reregistering interest. So in the new text, we probably need to prefix a sentence like For use with UDP, RFC 7641 discusses ways to re-register interest in a resource to deal with the case that the server providing this resource might have lost the information about this interest. In CoAP over TCP, the framework of the current connection provides fate-sharing between the health of the connection and the health of the expression of interest.
After further review, I think that this note belongs in Appendix A with the other updates/guidance for Observe on reliable transports. Connection Health should limit its discussion to WebSocket specific changes - in this case, the use of the CoAP Ping Signaling message instead of WebSocket Ping/Pong.

2.2.  The CoAP message format defined in RFC7252, as shown in CoAP-Header, relies on the datagram transport (UDP, or DTLS over UDP) for keeping the individual messages separate and for providing length


The semantics of the other CoAP header fields are left unchanged. <del> 2.4. </del>  CoAP requests and responses are exchanged asynchronously over the TCP/TLS connection.  A CoAP client can send multiple requests without

The semantics of the other CoAP header fields are left unchanged.  <ins> 2.3. Once a connection is established, both the client and the server MUST send a Capabilities and Settings message (CSM see csm) as its first message on the connection.  This message establishes the initial settings and capabilities for the endpoint such as maximum message size or support for block-wise transfers.  The absence of options in the CSM indicates that base values are assumed. To avoid unnecessary latency, a client MAY send additional messages without waiting to receive the server CSM; however, it is important to note that the server CSM might advertise capabilities that impact how a client is expected to communicate with the server.  For example, the server CSM could advertise a Max-Message-Size option (see max-message-size) that is smaller than the base value (1152). Clients and servers MUST treat a missing or invalid CSM as a connection error and abort the connection (see sec-abort). </ins> CoAP requests and responses are exchanged asynchronously over the TCP/TLS connection.  A CoAP client can send multiple requests without


Retransmission and deduplication of messages is provided by the TCP/ TLS protocol.  3.  CoAP over WebSockets can be used in a number of configurations.  The most basic configuration is a CoAP client retrieving or updating a <del> CoAP resource located at a CoAP server that exposes a WebSocket </del>  endpoint (arch-1).  The CoAP client acts as the WebSocket client, establishes a WebSocket connection, and sends a CoAP request, to which the CoAP server returns a CoAP response.  The WebSocket

Retransmission and deduplication of messages is provided by the TCP/ TLS protocol. <ins> 2.4. Empty messages (Code 0.00) can always be sent and MUST be ignored by the recipient.  This provides a basic keep-alive function that can refresh NAT bindings. If a client does not receive any response for some time after sending a CoAP request (or, similarly, when a client observes a resource and it does not receive any notification for some time), it can send a CoAP Ping Signaling message (sec-ping) to test the connection and verify that the server is responsive. </ins> 3. <ins> CoAP over WebSockets is intentionally similar to CoAP over TCP; therefore, this section only specifies the differences between the transports. </ins> CoAP over WebSockets can be used in a number of configurations.  The most basic configuration is a CoAP client retrieving or updating a  <ins> CoAP resource located on a CoAP server that exposes a WebSocket </ins> endpoint (arch-1).  The CoAP client acts as the WebSocket client, establishes a WebSocket connection, and sends a CoAP request, to which the CoAP server returns a CoAP response.  The WebSocket


Further configurations are possible, including those where a WebSocket connection is established through an HTTP proxy. <del> CoAP over WebSockets is intentionally very similar to CoAP over UDP. Therefore, instead of presenting CoAP over WebSockets as a new protocol, this document specifies it as a series of deltas from RFC7252. </del> 3.1. Before CoAP requests and responses are exchanged, a WebSocket

Further configurations are possible, including those where a WebSocket connection is established through an HTTP proxy.  3.1. Before CoAP requests and responses are exchanged, a WebSocket


frames as specified in Sections 5 and 6 of RFC6455. The message format shown in ws-message-format is the same as the CoAP <del> over TCP message format (see tcp-message-format) with one restriction.  The Length (Len) field MUST be set to zero because the WebSockets frame contains the length. </del>  <del> The CoAP over TCP message format eliminates the Version field defined in CoAP over UDP.  If CoAP version negotiation is required in the future, CoAP over WebSockets can address the requirement by the definition of a new subprotocol identifier that is negotiated during the opening handshake. </del>  Requests and response messages can be fragmented as specified in Section 5.4 of RFC6455, though typically they are sent unfragmented

frames as specified in Sections 5 and 6 of RFC6455. The message format shown in ws-message-format is the same as the CoAP  <ins> over TCP message format (see tcp-message-format) with one change. The Length (Len) field MUST be set to zero because the WebSockets frame contains the length. </ins>  <ins> As with CoAP over TCP, the message format for CoAP over Websockets eliminates the Version field defined in CoAP over UDP.  If CoAP version negotiation is required in the future, CoAP over WebSockets can address the requirement by the definition of a new subprotocol identifier that is negotiated during the opening handshake. </ins> Requests and response messages can be fragmented as specified in Section 5.4 of RFC6455, though typically they are sent unfragmented


requests and responses can be transferred in a block-wise fashion as defined in RFC7959. <del> Empty messages (Code 0.00) MUST be ignored by the recipient (see also sec-ping). </del> 3.3.  CoAP requests and responses are exchanged asynchronously over the WebSocket connection.  A CoAP client can send multiple requests without waiting for a response and the CoAP server can return

requests and responses can be transferred in a block-wise fashion as defined in RFC7959.  3.3. <ins> As with CoAP over TCP, both the client and the server MUST send a Capabilities and Settings message (CSM see csm) as its first message on the WebSocket connection. </ins> CoAP requests and responses are exchanged asynchronously over the WebSocket connection.  A CoAP client can send multiple requests without waiting for a response and the CoAP server can return


The connection is bi-directional, so requests can be sent both by the entity that established the connection and the remote host. <del> Retransmission and deduplication of messages is provided by the WebSocket protocol.  CoAP over WebSockets therefore does not make a distinction between Confirmable or Non-Confirmable messages, and does not provide Acknowledgement or Reset messages. </del>  3.4. <del> When a client does not receive any response for some time after sending a CoAP request (or, similarly, when a client observes a resource and it does not receive any notification for some time), the connection between the WebSocket client and the WebSocket server may be lost or temporarily disrupted without the client being aware of it. To check the health of the WebSocket connection (and thereby of all active requests, if any), a client can send a CoAP Ping Signaling message (sec-ping).  WebSocket Ping and unsolicited Pong frames as specified in Section 5.5 of RFC6455 SHOULD NOT be used to ensure that redundant maintenance traffic is not transmitted. There is no way to retransmit a request without creating a new one. Re-registering interest in a resource is permitted, but entirely unnecessary. 3.5. The WebSocket connection is closed as specified in Section 7 of RFC6455. All requests for which the CoAP client has not received a response yet are cancelled when the connection is closed. </del>  4.

The connection is bi-directional, so requests can be sent both by the entity that established the connection and the remote host.  <ins> As with CoAP over TCP, retransmission and deduplication of messages is provided by the WebSocket protocol.  CoAP over WebSockets therefore does not make a distinction between Confirmable or Non- Confirmable messages, and does not provide Acknowledgement or Reset messages. </ins> 3.4.  <ins> As with CoAP over TCP, the client can test the health of the CoAP over WebSocket connection by sending a CoAP Ping Signaling message (sec-ping).  WebSocket Ping and unsolicited Pong frames (Section 5.5 of RFC6455) SHOULD NOT be used to ensure that redundant maintenance traffic is not transmitted. </ins> 4.


4.4. <del> In CoAP over TCP, Empty messages (Code 0.00) can always be sent and MUST be ignored by the recipient.  This provides a basic keep-alive function that can refresh NAT bindings.  In contrast, Ping and Pong messages are a bidirectional exchange. </del>  Upon receipt of a Ping message, a single Pong message is returned with the identical token.  As with all Signaling messages, the

4.4.  <ins> In CoAP over reliable transports, Empty messages (Code 0.00) can always be sent and MUST be ignored by the recipient.  This provides a basic keep-alive function.  In contrast, Ping and Pong messages are a bidirectional exchange. </ins> Upon receipt of a Ping message, a single Pong message is returned with the identical token.  As with all Signaling messages, the


"authority" as defined in Section 3.2 of RFC3986. The Alternative-Address Option is a repeatable option as defined in <del> Section 5.4.5 of RFC7252. </del>  The elective Hold-Off Option indicates that the server is requesting that the peer not reconnect to it for the number of seconds given in

URL - WGLC review by Esko Dijk Page 20: Alternative-Address Option - the semantics of including multiple of these options is not defined. Can the receiver pick any of the addresses? Or does it need to try the first address first? And then keep trying all alternatives until one succeeds, or not?
URL Unless Carsten or Hannes (authors of draft-bormann-core-coap-sig-02) have a preference, I would suggest that the addresses are unordered (pick any).

"authority" as defined in Section 3.2 of RFC3986. The Alternative-Address Option is a repeatable option as defined in  <ins> Section 5.4.5 of RFC7252.  When multiple occurrences of the option are included, the peer can choose any of the alternative transport addresses. </ins> The elective Hold-Off Option indicates that the server is requesting that the peer not reconnect to it for the number of seconds given in


The syntax for the URI schemes in this section are specified using Augmented Backus-Naur Form (ABNF) RFC5234.  The definitions of <del> "host", "port", "path-abempty", and "query" are adopted from RFC3986. </del>  Section 8 (Multicast CoAP) in RFC7252 is not applicable to these schemes.

Do we need to include the RFC7252 note for emphasis?
Probably not, as we are not changing anything about 5.10.1, are we? (But then 7.5 also points out a place where we maintain a property of 5.10.1.) ((But then, again, where would be put this?))
We need to identify the ABNF fragments as ABNF as in so they become easier to check in BAP.
We could add the note to Section 7, right after the new reference to "fragment":
Merged in abnf annotations from
is relevant to Section 7.
Good point. So I assume applying the same fix (add »[ "#" fragment ]«) four times to the ABNF in 7.1 to 7.4 would fix that? (We probably want to line-break before path-abempty in all four cases.)
If would be helpful to have more context for how the fragment identifier is used in CoAP. I don't see much detail in RFC7252 besides: Note: Fragments ([RFC3986], Section 3.5) are not part of the request URI and thus will not be transmitted in a CoAP request.
Fragment identifiers are not used in a transfer protocol; their use is a local matter on the client side. The mistake we made in RFC 7252 is providing ABNF that doesn't show fragment identifiers at all in the URI syntax. While CoAP as a protocol does not care about them, they are intended to be allowed in CoAP URIs so they can indeed be used on the client side. The note mentions this, but the ABNF does not reflect that. Same for coap-tcp-tls. Does it matter? The meaning of fragment identifiers is defined by the media type. So far, there has been little use of fragment identifiers in the media types being used with CoAP. Now, SenML actually does go ahead and defines a meaning for them, and other media types in the future might as well. So it would be good if the ABNF in the CoAP standards did not give the impression fragment identifiers cannot be used at all with CoAP URIs.
Note from Carsten: We may have to reopen that issue based on the about-face that the HTTP WG made here:
From URL which references: Absolute URI Some protocol elements allow only the absolute form of a URI without a fragment identifier. For example, defining a base URI for later use by relative references calls for an absolute-URI syntax rule that does not allow a fragment. absolute-URI = scheme ":" hier-part [ "?" query ] URI scheme specifications must define their own syntax so that all strings matching their scheme-specific syntax will also match the grammar. Scheme specifications will not define fragment identifier syntax or usage, regardless of its applicability to resources identifiable via that scheme, as fragment identification is orthogonal to scheme definition. However, scheme specifications are encouraged to include a wide range of examples, including examples that show use of the scheme's URIs with fragment identifiers when such usage is appropriate. and URL further states: Requirements for Permanent Scheme Definitions This section gives considerations for new schemes. Meeting these guidelines is REQUIRED for 'permanent' scheme registration. 'Permanent' status is appropriate for, but not limited to, use in standards. For URI schemes defined or normatively referenced by IETF Standards Track documents, 'permanent' registration status is REQUIRED. [RFC3986] defines the overall syntax for URIs as: URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ] A scheme definition cannot override the overall syntax for URIs. For example, this means that fragment identifiers cannot be reused outside the generic syntax restrictions and that fragment identifiers are not scheme specific. A scheme definition must specify the scheme name and the syntax of the scheme-specific part, which is clarified as follows: URI = scheme ":" scheme-specific-part [ "#" fragment ] scheme-specific-part = hier-part [ "?" query ] On Jan 28, 2015, at 1:56 PM, Julian Reschke wrote: The answer is "no". URL I don't know how I got beaten into submission on that for RFC7230. ....Roy

The syntax for the URI schemes in this section are specified using Augmented Backus-Naur Form (ABNF) RFC5234.  The definitions of  <ins> "host", "port", "path-abempty", "query", and "fragment" are adopted from RFC3986. </ins> Section 8 (Multicast CoAP) in RFC7252 is not applicable to these schemes.


Capability and Settings messages are used for two purposes: <del> Capability options advertise the capabilities of the sender to the recipient. </del>  Setting options indicate a setting that will be applied by the sender.

sig-02 did not define the length for options with uint values. Can you confirm whether 0-4 is correct? I note that there are variants in the RFC7252 options with uint values.
Good catch. 0-4 definitely is right for Max-Message-Size. 0-4 is a bit over the top for Hold-Off, but arbitrarily limiting the time at, say, 65535 seconds (0-2) or 16777215 seconds (0-3) doesn't sound right either -- well, maybe half a year max (0-3) is about right. Option numbers are 65535 max, so Bad-CSM-Option needs to be 0-2.

Capability and Settings messages are used for two purposes:  <ins> Each capability option advertises one capability of the sender to the recipient. </ins> Setting options indicate a setting that will be applied by the sender.


2.3.  The CoAP message format defined in RFC7252, as shown in CoAP-Header, relies on the datagram transport (UDP, or DTLS over UDP) for keeping the individual messages separate and for providing length

This text does not address who might be allowed to wait for the other guy to make their statement (if both wait, there is a deadlock).
The intention is that neither side needs to wait. The only open issue is whether we want to allow the client to immediately start sending messages after it sends its CSM without waiting for the server CSM similar to the HTTP/2 case. I planned to discuss that on-list when I "advertised" this set of pull requests.
From your message I understand that in HTTP/2 the client can send messages immediately without waiting for the server to respond either. To me it feels like we should be doing what has been done in the HTTP/2 case even though there is a risk that some problems occur when the client sends data in way that the server will subsequently not handle well. If that is the case, the client will have to re-send the data, I guess. For the currently defined options I don't see problems.
When I submitted the original pull request, I also posed a question on the but did not receive a response. One open question is whether we want to allow a client to immediately send messages after sending its CSM without waiting for the server CSM. This would be similar to HTTP/2: URL To avoid unnecessary latency, clients are permitted to send additional messages to the server immediately after sending the client connection preface, without waiting to receive the server connection preface. It is important to note, however, that the server connection preface SETTINGS frame might include parameters that necessarily alter how a client is expected to communicate with the server. Upon receiving the SETTINGS frame, the client is expected to honor any parameters established. In some configurations, it is possible for the server to transmit SETTINGS before the client sends additional frames, providing an opportunity to avoid this issue.
I support not blocking the device until the server CSM. The server can choose to not process messages that are invalid (e.g. too large) and immediately follow up with the server CSM. From the perspective of a cloud and gateway software provider, the CoAP (using TCP/TLS) server will usually be in the cloud or gateway and therefore usually not power constrained. I may be missing other scenarios where a battery powered device is acting as a CoAP/TCP server. Does anyone have plans for any of those scenarios?
NAME added a related comment to (which is closed) From your message I understand that in HTTP/2 the client can send messages immediately without waiting for the server to respond either. To me it feels like we should be doing what has been done in the HTTP/2 case even though there is a risk that some problems occur when the client sends data in way that the server will subsequently not handle well. If that is the case, the client will have to re-send the data, I guess. For the currently defined options I don't see problems.
Michel Veillette points out that a peer that wants to use a new connection has an uncertainty whether a CSM message with capability indications will come or not, so it is hard to decide when to send the first request (either based on default capabilities or waiting for the CSM to come in). One way out of having to do arbitrary waits would be to require the exchange of a CSM message (even an option-less one) after connection setup. The burden is very low, as a minimal implementation would just need to send a constant message of 0x00 0xe1 at setup. This requirement could be stated without giving a sequence, effectively allowing both sides to send the initial CSM in parallel, or it could give the listener the opportunity to not send its CSM until the connection opener has sent theirs, trying to avoid the need to answer right away to a connection setup -- this makes it too easy to scan for ports (OK, we also have a default port, and making scanning harder does not by itself provide any security, but it sure makes life a little harder for the attacker). (To avoid deadlock, the connection opener would not have the opportunity to wait sending the CSM.)
+1 ... especially for Maximum-Message-Size. HTTP/2 has a similar flow for SETTINGS during connection including potentially empty settings: URL URL
No objections. I will create a pull request for review by the WG.

2.3. <ins> Both the client and the server MUST send a Capability and Settings message (CSM see csm) as its first message on the connection.  This message establishes the initial settings and capabilities for the endpoint such as maximum message size or support for block-wise transfers.  The absence of options in the CSM indicates that base values are assumed. Clients and servers MUST treat a missing or invalid CSM as a connection error and abort the connection (see sec-abort). 2.4. </ins> The CoAP message format defined in RFC7252, as shown in CoAP-Header, relies on the datagram transport (UDP, or DTLS over UDP) for keeping the individual messages separate and for providing length


The semantics of the other CoAP header fields are left unchanged.  <ins> 2.5. </ins> CoAP requests and responses are exchanged asynchronously over the TCP/TLS connection.  A CoAP client can send multiple requests without


Setting options indicate a setting that will be applied by the sender. <del> Most CSM Options are useful mainly as initial messages in the connection. </del>  Both capability and settings options are cumulative.  A Capability and Settings message does not invalidate a previously sent capability

Setting options indicate a setting that will be applied by the sender.  <ins> A Capability and Settings message MUST be sent by both endpoints at the start of the connection and MAY be sent at any other time by either endpoint over the lifetime of the connection. </ins> Both capability and settings options are cumulative.  A Capability and Settings message does not invalidate a previously sent capability


Base values are listed below for CSM Options.  These are the values for the Capability and Setting before any Capability and Settings <del> messages sends a modified value. </del>  These are not default values for the option as defined in Section 5.4.4 in RFC7252.  A default value would mean that an empty

Base values are listed below for CSM Options.  These are the values for the Capability and Setting before any Capability and Settings  <ins> messages send a modified value. </ins> These are not default values for the option as defined in Section 5.4.4 in RFC7252.  A default value would mean that an empty


1.1. <del> The terminology from RFC7252 and STD94 applies.  Readers are also expected to be familiar with the terminology from RFC7807. </del>  In this document, the structure of data is specified in CDDL RFC8610 RFC9165.

Start collecting changes from AD review
Comment by NAME : /example value 4711 not actually registered like this:/ ~~~ I don't get the sentence above - if this is to highlight that this is an example and that the value 4711 is not actually registered, I think this is redundant (and you could also add that in the Figure caption rather than in the example's text).
See : The danger that people are just blindly copying an example is just too high. So we would prefer to keep this redundant comment in. We could improve the wording of the comment.
Comment by NAME : Please explicitly state that the example (or examples if you add one in ) uses CBOR diagnostic notation.
Fixed in .
Closed by 7463ce1

1.1.  <ins> The terminology from RFC7252, STD94, and RFC8610 applies; in particular CBOR diagnostic notation is defined in STD94 and RFC8610. Readers are also expected to be familiar with the terminology from RFC7807. </ins> In this document, the structure of data is specified in CDDL RFC8610 RFC9165.


be dereferenced in the normal course of handling problem details (i.e., outside diagnostic/debugging procedures involving humans). <del> An example of a custom extension using a URI as "custom-problem- detail-entries" key is shown in fig-example-custom-with-uri. </del>  Obviously, an SDO like 3GPP can also easily register such a custom problem detail entry to receive a more efficient unsigned integer <del> key; the same example but using a registered unsigned int as "custom- problem-detail-entries" key is shown in fig-example-custom-with-uint. </del>  In summary, the keys for the maps used inside Custom Problem Detail entries are defined specifically to the identifier of that Custom

be dereferenced in the normal course of handling problem details (i.e., outside diagnostic/debugging procedures involving humans).  <ins> fig-example-custom-with-uri shows an example (in CBOR diagnostic notation) of a custom extension using a (made-up) URI as "custom- problem-detail-entries" key. </ins> Obviously, an SDO like 3GPP can also easily register such a custom problem detail entry to receive a more efficient unsigned integer  <ins> key; fig-example-custom-with-uint shows how the same example would look like using a (made-up) registered unsigned int as "custom- problem-detail-entries" key: </ins> In summary, the keys for the maps used inside Custom Problem Detail entries are defined specifically to the identifier of that Custom


calculation of the counter signature can be computed.  Details on computing counter signatures are found in counter_signature. <del> This parameter provides the time the content was created.  For signatures and recipient structures, this would be the time that the signature or recipient key object was created.  For content structures, this would be the time that the content was created. The unsigned integer value is the number of seconds, excluding leap seconds; after midnight UTC, January 1, 1970. </del>  The CDDL fragment that represents the set of headers defined in this section is given below.  Each of the headers is tagged as optional

It makes sense that we do not talk about creation time of the content. However the concept of having a time in the header is also very reasonable for things like countersignatures where one wants to make a timestamp as there is no content that the time marker can be placed in. We therefore change the text to make the time field be the time that the cryptographic operation was performed at.

calculation of the counter signature can be computed.  Details on computing counter signatures are found in counter_signature.  <ins> This parameter provides the time the content cryptographic operation is performed.  For signatures and recipient structures, this would be the time that the signature or recipient key object was created.  For content structures, this would be the time that the content structure was created.  The unsigned integer value is the number of seconds, excluding leap seconds; after midnight UTC, January 1, 1970.  The field is primarily intended to be to be used for countersignatures, however it can additionally be used for replay detection as well. </ins> The CDDL fragment that represents the set of headers defined in this section is given below.  Each of the headers is tagged as optional


1.3. There currently is no standard CBOR grammar available for use by <del> specifications.  In this document, we use a modified version of the CBOR data definition language (CDDL) defined in I-D.greevenbosch- appsawg-cbor-cddl.  The differences between the defined grammar and the one we used are mostly self explanatory.  The biggest difference being the addition of the choice operator '|'.  Additionally, note the use of the null value which is used to occupy a location in an array but to mark that the element is not present. </del>  2.

The document is updated to use the CDDL grammer from the latest version (-05) Fixed a couple of small errors where my thinking and my text did not match.

1.3. There currently is no standard CBOR grammar available for use by  <ins> specifications.  In this document, we use the grammar defined in the CBOR data definition language (CDDL) I-D.greevenbosch-appsawg-cbor- cddl. </ins> 2.


contains the information about the plain text or encryption process that is to be integrity protected.  The field is encoded <del> in CBOR as a 'bstr' if present and the value 'null' if there is no </del>  data.  The contents of the protected field is a CBOR map of the protected data names and values.  The map is CBOR encoded before placing it into the bstr.  Only values associated with the current

contains the information about the plain text or encryption process that is to be integrity protected.  The field is encoded  <ins> in CBOR as a 'bstr' if present and the value 'nil' if there is no </ins> data.  The contents of the protected field is a CBOR map of the protected data names and values.  The map is CBOR encoded before placing it into the bstr.  Only values associated with the current


would apply to multiple recipient structures. contains information about the plain text that is not integrity <del> protected.  If there are no field, then the value 'null' is used. </del>  Only values associated with the current cipher text are to be placed in this location even if the value would apply to multiple recipient structures. contains the initialization vector (IV), or it's equivalent, if one is needed by the encryption algorithm.  If there is no IV, <del> then the value 'null' is used. </del>  contains additional authenticated data (aad) supplied by the application.  This field contains information about the plain text data that is authenticated, but not encrypted.  If the application <del> does not provide this data, the value 'null' is used. </del>  contains the encrypted plain text.  If the cipherText is to be transported independently of the control information about the <del> encryption process (i.e. detached content) then the value 'null' is encoded here. </del>  contains the recipient information.  The field can have one of three data types:

would apply to multiple recipient structures. contains information about the plain text that is not integrity  <ins> protected.  If there are no field, then the value 'nil' is used. </ins> Only values associated with the current cipher text are to be placed in this location even if the value would apply to multiple recipient structures. contains the initialization vector (IV), or it's equivalent, if one is needed by the encryption algorithm.  If there is no IV,  <ins> then the value 'nil' is used. </ins> contains additional authenticated data (aad) supplied by the application.  This field contains information about the plain text data that is authenticated, but not encrypted.  If the application  <ins> does not provide this data, the value 'nil' is used. </ins> contains the encrypted plain text.  If the cipherText is to be transported independently of the control information about the  <ins> encryption process (i.e. detached content) then the value 'nil' is encoded here. </ins> contains the recipient information.  The field can have one of three data types:


recipients can be encoded either this way or as a single array element. <del> A 'null' value if there are no recipients. </del>  4.1.

recipients can be encoded either this way or as a single array element.  <ins> A 'nil' value if there are no recipients. </ins> 4.1.


4.1.1. In direct encryption mode, a shared secret between the sender and the <del> recipient is used as the CEK.  For direct encryption mode, no recipient structure is built.  All of the information about the key is placed in either the protected or unprotected fields at the content level.  When direct encryption mode is used, it MUST be the only mode used on the message.  It is a massive security leak to have both direct encryption and a different key management mode on the same message. </del>  For JOSE, direct encryption key management is the only key management method allowed for doing MAC-ed messages.  In COSE, all of the key

4.1.1. In direct encryption mode, a shared secret between the sender and the  <ins> recipient is used as the CEK.  When direct encryption mode is used, it MUST be the only mode used on the message.  It is a massive security leak to have both direct encryption and a different key management mode on the same message. </ins> For JOSE, direct encryption key management is the only key management method allowed for doing MAC-ed messages.  In COSE, all of the key


The COSE_encrypt structure for the recipient is organized as follows: The 'protected', 'iv', 'aad', 'ciphertext' and 'recipients' fields <del> MUST be null. </del>  At a minimum, the 'unprotected' field SHOULD contain the 'alg' parameter as well as a parameter identifying the shared secret.

The COSE_encrypt structure for the recipient is organized as follows: The 'protected', 'iv', 'aad', 'ciphertext' and 'recipients' fields  <ins> MUST be nil. </ins> At a minimum, the 'unprotected' field SHOULD contain the 'alg' parameter as well as a parameter identifying the shared secret.


The COSE_encrypt structure for the recipient is organized as follows: <del> The 'protected', 'aad', and 'recipients' fields MUST be null. </del>  The plain text to be encrypted is the key from next layer down (usually the content layer).

The COSE_encrypt structure for the recipient is organized as follows:  <ins> The 'protected', 'aad', and 'recipients' fields MUST be nil. </ins> The plain text to be encrypted is the key from next layer down (usually the content layer).


4.1.4. Direct Key Agreement derives the CEK from the shared secret computed <del> by the key agreement operation.  For Direct Key Agreement, no recipient structure is built.  All of the information about the key and key agreement process is placed in either the 'protected' or 'unprotected' fields at the content level. </del>  When direct key agreement mode is used, it SHOULD be the only mode used on the message.  This method creates the CEK directly and that

4.1.4. Direct Key Agreement derives the CEK from the shared secret computed  <ins> by the key agreement operation. </ins> When direct key agreement mode is used, it SHOULD be the only mode used on the message.  This method creates the CEK directly and that


The COSE_encrypt structure for the recipient is organized as follows: <del> The 'protected', 'aad', and 'iv' fields all use the 'null' value. </del>  At a minimum, the 'unprotected' field SHOULD contain the 'alg' parameter as well as a parameter identifying the asymmetric key.

The COSE_encrypt structure for the recipient is organized as follows:  <ins> The 'protected', 'aad', and 'iv' fields all use the 'nil' value. </ins> At a minimum, the 'unprotected' field SHOULD contain the 'alg' parameter as well as a parameter identifying the asymmetric key.


The COSE_encrypt structure for the recipient is organized as follows: <del> The 'protected', 'aad', and 'iv' fields all use the 'null' value. </del>  The plain text to be encrypted is the key from next layer down (usually the content layer).

The COSE_encrypt structure for the recipient is organized as follows:  <ins> The 'protected', 'aad', and 'iv' fields all use the 'nil' value. </ins> The plain text to be encrypted is the key from next layer down (usually the content layer).


The following values are used for L: <del> limits messages to 2^16 bytes in length.  The nonce length is 13 bytes allowing for 2^(13*8) possible values of the nonce without repeating. </del>  limits messages to 2^64 byes in length.  The nonce length is 7 bytes allowing for 2^56 possible values of the nonce without

Assign integer tags to the CCM modes that we are keeping. Remove the 192-bit key CCM modes from the table. Update example using CCM

The following values are used for L:  <ins> limits messages to 2^16 bytes (64Kbyte) in length.  This sufficently long for messages in the constrainted world.  The nonce length is 13 bytes allowing for 2^(13*8) possible values of the nonce without repeating. </ins> limits messages to 2^64 byes in length.  The nonce length is 7 bytes allowing for 2^56 possible values of the nonce without


7. Security considerations for DetNet are described in detail in I- <del> D.ietf-detnet-security.  This section considers exclusively security considerations which are specific to the DetNet data plane. </del>  Security aspects which are unique to DetNet are those whose aim is to provide the specific quality of service aspects of DetNet, which are

Sorry, now it is uploaded to the right folder. Simple accept pull request. Thx Bala'zs

7. Security considerations for DetNet are described in detail in I-  <ins> D.ietf-detnet-security.  General security considerations are described in I-D.ietf-detnet-architecture.  This section considers exclusively security considerations which are specific to the DetNet IP data plane. </ins> Security aspects which are unique to DetNet are those whose aim is to provide the specific quality of service aspects of DetNet, which are


and bounded end-to-end delivery latency. The primary considerations for the data plane is to maintain <del> confidentiality of data traversing the DetNet network, application flows can be protected through whatever means is provided by the underlying technology.  For example, encryption may be used, such as that provided by IPSec RFC4301 for IP flows and by MACSec IEEE802.1AE-2018 for Ethernet (Layer-2) flows. DetNet flows are identified on a per-flow basis, which may provide attackers with additional information about the data flows (when compared to networks that do not include per-flow identification). This is an inherent property of DetNet which has security implications that should be considered when determining if DetNet is a suitable technology for any given use case. To provide uninterrupted availability of the DetNet quality of service, provisions can be made against DOS attacks and delay attacks.  To protect against DOS attacks, excess traffic due to malicious or malfunctioning devices can be prevented or mitigated, for example through the use of traffic admission control applied at the input of a DetNet domain.  To prevent DetNet packets from being delayed by an entityexternal to a DetNet domain, DetNet technology definition can allow for the mitigation of Man-In-The-Middle attacks, for example through use of authentication and authorization of devices within the DetNet domain. Because DetNet mechanisms or applications that rely on DetNet can make heavy use of methods that require precise time synchronization, the accuracy, availability, and integrity of time synchronization is of critical importance.  Extensive discussion of this topic can be found in RFC7384. </del>  8.

and bounded end-to-end delivery latency. The primary considerations for the data plane is to maintain  <ins> integrity of data and delivery of the associated DetNet service traversing the DetNet network.  Application flows can be protected through whatever means is provided by the underlying technology.  For example, encryption may be used, such as that provided by IPSec RFC4301 for IP flows and/or by an underlying sub-net using MACSec IEEE802.1AE-2018 for IP over Ethernet (Layer-2) flows. From a data plane perspective this document does not add or modify any header information. At the management and control level DetNet flows are identified on a per-flow basis, which may provide controller plane attackers with additional information about the data flows (when compared to controller planes that do not include per-flow identification).  This is an inherent property of DetNet which has security implications that should be considered when determining if DetNet is a suitable technology for any given use case. To provide uninterrupted availability of the DetNet service, provisions can be made against DOS attacks and delay attacks.  To protect against DOS attacks, excess traffic due to malicious or malfunctioning devices can be prevented or mitigated, for example through the use of existing mechanism such as policing and shaping applied at the input of a DetNet domain.  To prevent DetNet packets from being delayed by an entity external to a DetNet domain, DetNet technology definition can allow for the mitigation of Man-In-The- Middle attacks, for example through use of authentication and authorization of devices within the DetNet domain. </ins> 8.


The "Deprecation" response header field describes the deprecation of the resource identified with the response it occurred within (see <del> Section 3.1.4.1 of HTTP).  It conveys either the deprecation date, which may be in the future (the resource context will be deprecated at that date) or in the past (the resource context has been deprecated at that date), or it simply flags the resource context as being deprecated. </del>  Servers MUST NOT include more than one "Deprecation" header field in the same response. <del> The date, if present, is the date when the resource was or will be deprecated.  It is in the form of an IMF-fixdate timestamp. </del>  The following example shows that the resource context has been deprecated on Sunday, November 11, 2018 at 23:59:59 GMT: The deprecation date can be in the future.  This means that the <del> resource will be deprecated at the given date in future. If the deprecation date is not known, the header field can carry the simple string "true", indicating that the resource context is deprecated, without indicating when that happened: </del>  2.2.

Looks good to me.
... are considered a 'bad smell'. Instead of a date vs. a fixed string, could we just say that a date in the past is equal to 'true'?
i guess we could. and we already say that a date in the past means that the resource is deprecated. the motivation to allow a flag was to not force services to make up a date when they don't have one and simply want to flag something as deprecated. but we could also "force" them to make up a date by not allowing the "true" flag. i am fine either way and i do see the point that the syntax may cause some implementations to not parse the field correctly. maybe others can weigh in as well?
FWIW, I see it like Expires -- if it's already stale, you just assign a date in the past.
i could definitely live with such a design.
One use case was to align the header's usage with API contract as defined using OpenAPI. Having boolean helps align this header with OpenAPI's flag which does not require date. Forcing API developers to add a random date in the past in case if it is not available due toe various reasons would not be desirable for various other reasons (SLA?). Although, I wish that OpenAPI adds date for . >If the deprecation date is not known, the header field can carry the simple string "true", indicating that the resource context is deprecated, without indicating when that happened: On Jul 31, 2021, at 06:46, Mark Nottingham NAME wrote: FWIW, I see it like Expires -- if it's already stale, you just assign a date in the past.
For Expires, January 1 1970 (epoch 0) is widely used.
NAME I wish OpenAPI supported deprecated date also. But when we do, it won't be with a property that can be boolean or date.
Ok NAME thanks for clarification on the OpenAPI side of things. I agree. We can just use date. There are some implementations out there, I would not know if any of those use boolean but since we are not an RFC yet, such a change should not be unexpected.
it seems like we can safely remove the alternative syntax. i have created a PR asking for review by NAME
LGTM

The "Deprecation" response header field describes the deprecation of the resource identified with the response it occurred within (see  <ins> Section 3.1.4.1 of HTTP).  It conveys the deprecation date, which may be in the future (the resource context will be deprecated at that date) or in the past (the resource context has been deprecated at that date). </ins> Servers MUST NOT include more than one "Deprecation" header field in the same response.  <ins> The date is the date when the resource was or will be deprecated.  It is in the form of an IMF-fixdate timestamp. </ins> The following example shows that the resource context has been deprecated on Sunday, November 11, 2018 at 23:59:59 GMT: The deprecation date can be in the future.  This means that the  <ins> resource will be deprecated at the indicated date in the future. </ins> 2.2.


10. <del> The first example shows a deprecation header field without date information: The second example shows a deprecation header with date information </del>  and a link to the successor version: <del> The third example shows a deprecation header field with links for the successor version and for the API's deprecation policy.  In addition, it shows the sunset date for the deprecated resource: </del>

10.  <ins> The first example shows a deprecation header with date information </ins> and a link to the successor version:  <ins> The second example shows a deprecation header field with links for the successor version and for the API's deprecation policy.  In addition, it shows the sunset date for the deprecated resource: </ins>