Changeset 2398

Timestamp:

14/09/13 23:59:24 (8 years ago)

Author:

fielding@…

Message:

rephrase misused SHOULDs; addresses #472

Location:

draft-ietf-httpbis/latest

Files:

• p1-messaging.html (modified) (3 diffs)
• p1-messaging.xml (modified) (3 diffs)
• p2-semantics.html (modified) (2 diffs)
• p2-semantics.xml (modified) (2 diffs)
• p4-conditional.html (modified) (1 diff)
• p4-conditional.xml (modified) (1 diff)
• p7-auth.html (modified) (1 diff)
• p7-auth.xml (modified) (2 diffs)

draft-ietf-httpbis/latest/p1-messaging.html

@@ -1555 +1555 @@
          the user agent <em class="bcp14">MUST</em> count the terminating CRLF octets as part of the message body length.
       </p>
-      <p id="rfc.section.3.5.p.2">In the interest of robustness, servers <em class="bcp14">SHOULD</em> ignore at least one empty line received where a request-line is expected. In other words, if a server is reading the protocol
-         stream at the beginning of a message and receives a CRLF first, the server <em class="bcp14">SHOULD</em> ignore the CRLF.
+      <p id="rfc.section.3.5.p.2">In the interest of robustness, a server that is expecting to receive and parse a request-line <em class="bcp14">SHOULD</em> ignore at least one empty line (CRLF) received prior to the request-line.
       </p>
       <p id="rfc.section.3.5.p.3">Although the line terminator for the start-line and header fields is the sequence CRLF, recipients <em class="bcp14">MAY</em> recognize a single LF as a line terminator and ignore any preceding CR.
@@ -2644 +2643 @@
       <p id="rfc.section.9.3.p.3">This specification also provides a way for servers to reject messages that have request-targets that are too long (<a href="p2-semantics.html#status.414" title="414 URI Too Long">Section 6.5.12</a> of <a href="#Part2" id="rfc.xref.Part2.30"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content">[Part2]</cite></a>) or request entities that are too large (<a href="p2-semantics.html#status.4xx" title="Client Error 4xx">Section 6.5</a> of <a href="#Part2" id="rfc.xref.Part2.31"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content">[Part2]</cite></a>). Additional status codes related to capacity limits have been defined by extensions to HTTP <a href="#RFC6585" id="rfc.xref.RFC6585.1"><cite title="Additional HTTP Status Codes">[RFC6585]</cite></a>.
       </p>
-      <p id="rfc.section.9.3.p.4">Recipients <em class="bcp14">SHOULD</em> carefully limit the extent to which they read other fields, including (but not limited to) request methods, response status
-         phrases, header field-names, and body chunks, so as to avoid denial of service attacks without impeding interoperability.
+      <p id="rfc.section.9.3.p.4">Recipients ought to carefully limit the extent to which they read other fields, including (but not limited to) request methods,
+         response status phrases, header field-names, and body chunks, so as to avoid denial of service attacks without impeding interoperability.
       </p>
       <h2 id="rfc.section.9.4"><a href="#rfc.section.9.4">9.4</a>&nbsp;<a id="message.integrity" href="#message.integrity">Message Integrity</a></h2>
@@ -2670 +2669 @@
          needs to be securely stored and appropriate guidelines followed for its analysis. Anonymization of personal information within
          individual entries helps, but is generally not sufficient to prevent real log traces from being re-identified based on correlation
-         with other access characteristics. As such, access traces that are keyed to a specific client should not be published even
-         if the key is pseudonymous.
-      </p>
-      <p id="rfc.section.9.5.p.3">To minimize the risk of theft or accidental publication, log information should be purged of personally identifiable information,
+         with other access characteristics. As such, access traces that are keyed to a specific client are unsafe to publish even if
+         the key is pseudonymous.
+      </p>
+      <p id="rfc.section.9.5.p.3">To minimize the risk of theft or accidental publication, log information ought to be purged of personally identifiable information,
          including user identifiers, IP addresses, and user-provided query parameters, as soon as that information is no longer necessary
          to support operational needs for security, auditing, or fraud control.

draft-ietf-httpbis/latest/p1-messaging.xml

@@ -1905 +1905 @@
 </t>
 <t>
-   In the interest of robustness, servers &SHOULD; ignore at least one
-   empty line received where a request-line is expected. In other words, if
-   a server is reading the protocol stream at the beginning of a
-   message and receives a CRLF first, the server &SHOULD; ignore the CRLF.
+   In the interest of robustness, a server that is expecting to receive and
+   parse a request-line &SHOULD; ignore at least one empty line (CRLF)
+   received prior to the request-line.
 </t>
 <t>
@@ -3836 +3835 @@
 </t>
 <t>
-   Recipients &SHOULD; carefully limit the extent to which they read other
+   Recipients ought to carefully limit the extent to which they read other
    fields, including (but not limited to) request methods, response status
    phrases, header field-names, and body chunks, so as to avoid denial of
@@ -3886 +3885 @@
    but is generally not sufficient to prevent real log traces from being
    re-identified based on correlation with other access characteristics.
-   As such, access traces that are keyed to a specific client should not
-   be published even if the key is pseudonymous.
+   As such, access traces that are keyed to a specific client are unsafe to
+   publish even if the key is pseudonymous.
 </t>
 <t>
    To minimize the risk of theft or accidental publication, log information
-   should be purged of personally identifiable information, including
+   ought to be purged of personally identifiable information, including
    user identifiers, IP addresses, and user-provided query parameters,
    as soon as that information is no longer necessary to support operational

draft-ietf-httpbis/latest/p2-semantics.html

@@ -1470 +1470 @@
          appropriate error message containing sufficient information to explain why the representation is unsuitable. The <a href="#status.409" class="smpl">409 (Conflict)</a> or <a href="#status.415" class="smpl">415 (Unsupported Media Type)</a> status codes are suggested, with the latter being specific to constraints on <a href="#header.content-type" class="smpl">Content-Type</a> values.
       </p>
-      <p id="rfc.section.4.3.4.p.5">For example, if the target resource is configured to always have a <a href="#header.content-type" class="smpl">Content-Type</a> of "text/html" and the representation being PUT has a Content-Type of "image/jpeg", then the origin server <em class="bcp14">SHOULD</em> do one of: 
+      <p id="rfc.section.4.3.4.p.5">For example, if the target resource is configured to always have a <a href="#header.content-type" class="smpl">Content-Type</a> of "text/html" and the representation being PUT has a Content-Type of "image/jpeg", the origin server ought to do one of: 
       </p>
       <ol class="la">
@@ -1867 +1867 @@
       <p id="rfc.section.5.3.2.p.6">The example</p>
       <div id="rfc.figure.u.25"></div><pre class="text">  Accept: audio/*; q=0.2, audio/basic
-</pre><p id="rfc.section.5.3.2.p.8"><em class="bcp14">SHOULD</em> be interpreted as "I prefer audio/basic, but send me any audio type if it is the best available after an 80% mark-down in
+</pre><p id="rfc.section.5.3.2.p.8">is interpreted as "I prefer audio/basic, but send me any audio type if it is the best available after an 80% mark-down in
          quality".
       </p>

draft-ietf-httpbis/latest/p2-semantics.xml

@@ -1460 +1460 @@
    For example, if the target resource is configured to always have a
    <x:ref>Content-Type</x:ref> of "text/html" and the representation being PUT
-   has a Content-Type of "image/jpeg", then the origin server &SHOULD; do one of:
+   has a Content-Type of "image/jpeg", the origin server ought to do one of:
    <list style="letters">
       <t>reconfigure the target resource to reflect the new media type;</t>
@@ -2128 +2128 @@
 </artwork></figure>
 <t>
-   &SHOULD; be interpreted as "I prefer audio/basic, but send me any audio
+   is interpreted as "I prefer audio/basic, but send me any audio
    type if it is the best available after an 80% mark-down in quality".
 </t>

draft-ietf-httpbis/latest/p4-conditional.html

@@ -682 +682 @@
          data is available prior to the response header fields being sent and the digest does not need to be recalculated every time
          a validation request is received. However, if a resource has distinct representations that differ only in their metadata,
-         such as might occur with content negotiation over media types that happen to share the same data format, then the origin server <em class="bcp14">SHOULD</em> incorporate additional information in the validator to distinguish those representations.
+         such as might occur with content negotiation over media types that happen to share the same data format, then the origin server
+         needs to incorporate additional information in the validator to distinguish those representations.
       </p>
       <p id="rfc.section.2.1.p.6">In contrast, a "weak validator" is representation metadata that might not change for every change to the representation data.

draft-ietf-httpbis/latest/p4-conditional.xml

@@ -244 +244 @@
    only in their metadata, such as might occur with content negotiation over
    media types that happen to share the same data format, then the origin
-   server &SHOULD; incorporate additional information in the validator to
+   server needs to incorporate additional information in the validator to
    distinguish those representations.
 </t>

draft-ietf-httpbis/latest/p7-auth.html

@@ -726 +726 @@
       <h2 id="rfc.section.4.1"><a href="#rfc.section.4.1">4.1</a>&nbsp;<a id="header.authorization" href="#header.authorization">Authorization</a></h2>
       <p id="rfc.section.4.1.p.1">The "Authorization" header field allows a user agent to authenticate itself with an origin server — usually, but not necessarily,
-         after receiving a <a href="#status.401" class="smpl">401
-            (Unauthorized)</a> response. Its value consists of credentials containing information of the user agent for the realm of the resource being requested.
+         after receiving a <a href="#status.401" class="smpl">401 (Unauthorized)</a> response. Its value consists of credentials containing the authentication information of the user agent for the realm of the
+         resource being requested.
       </p>
       <div id="rfc.figure.u.4"></div><pre class="inline"><span id="rfc.iref.g.6"></span>  <a href="#header.authorization" class="smpl">Authorization</a> = <a href="#challenge.and.response" class="smpl">credentials</a>
-</pre><p id="rfc.section.4.1.p.3">If a request is authenticated and a realm specified, the same credentials <em class="bcp14">SHOULD</em> be valid for all other requests within this realm (assuming that the authentication scheme itself does not require otherwise,
-         such as credentials that vary according to a challenge value or using synchronized clocks).
+</pre><p id="rfc.section.4.1.p.3">If a request is authenticated and a realm specified, the same credentials are presumed to be valid for all other requests
+         within this realm (assuming that the authentication scheme itself does not require otherwise, such as credentials that vary
+         according to a challenge value or using synchronized clocks).
       </p>
       <p id="rfc.section.4.1.p.4">See <a href="p6-cache.html#caching.authenticated.responses" title="Storing Responses to Authenticated Requests">Section 3.2</a> of <a href="#Part6" id="rfc.xref.Part6.1"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Caching">[Part6]</cite></a> for details of and requirements pertaining to handling of the Authorization field by HTTP caches.

draft-ietf-httpbis/latest/p7-auth.xml

@@ -362 +362 @@
   <x:anchor-alias value="Authorization"/>
 <t>
-   The "Authorization" header field allows a user agent to authenticate
-   itself with an origin server &mdash; usually, but not necessarily, after receiving a <x:ref>401
-   (Unauthorized)</x:ref> response. Its value consists of credentials containing 
-   information of the user agent for the realm of the resource being
-   requested.
+   The "Authorization" header field allows a user agent to authenticate itself
+   with an origin server &mdash; usually, but not necessarily, after receiving
+   a <x:ref>401 (Unauthorized)</x:ref> response. Its value consists of
+   credentials containing the authentication information of the user agent for
+   the realm of the resource being requested.
 </t>
 <figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="Authorization"/>
@@ -372 +372 @@
 </artwork></figure>
 <t>
-   If a request is
-   authenticated and a realm specified, the same credentials &SHOULD;
-   be valid for all other requests within this realm (assuming that
-   the authentication scheme itself does not require otherwise, such
-   as credentials that vary according to a challenge value or using
-   synchronized clocks).
+   If a request is authenticated and a realm specified, the same credentials
+   are presumed to be valid for all other requests within this realm (assuming
+   that the authentication scheme itself does not require otherwise, such as
+   credentials that vary according to a challenge value or using synchronized
+   clocks).
 </t>
 <t>