From 64e63a4d18a0376fe4e204586a4219c7ddb75002 Mon Sep 17 00:00:00 2001 From: "L. David Baron" Date: Tue, 22 Aug 2017 17:37:47 -0700 Subject: [PATCH 01/15] Describe when features should be limited to secure contexts. Fixes #32. --- index.bs | 59 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 59 insertions(+) diff --git a/index.bs b/index.bs index 0a7f7830..15ae8c99 100644 --- a/index.bs +++ b/index.bs @@ -345,6 +345,65 @@ and on when to use promises and when not to use promises, see Writing Promise-Using Specifications. +

Limit new and distinct APIs to secure contexts

+ +Many new APIs should be available only in +secure contexts. +This restriction exists for two reasons. +First, it helps encourage Web content and applications +to migrate to secure contexts. +Second, it can restrict new APIs where authentication, integrity, or confidentiality +are important to prevent substantial increases to the privacy or security risks of using the Web. +For more detail, see the W3C TAG Finding on +Securing the Web. + +When the new feature is defined in +WebIDL, +specification authors can limit a feature to secure contexts +by marking new interfaces and methods with the +[SecureContext] extended attribute +on interfaces, namespaces, or their members (such as methods and attributes). +Similar ways of marking features as limited to secure contexts should be added +to other points where the Web platform is extended over time +(for example, the definition of a new CSS property). +However, for some times of extension points (e.g., new DOM events), +limitation to secure contexts should just +be defined in normative prose in the specification. + +When deciding whether a feature should be limited to secure contexts, +we suggest considering the following factors: + + : Does the feature have a clear and understandable boundary? + + :: A feature that is limited to secure contexts + should be recognizable by the developers who use it as + distinct from features that are available in non-secure contexts. + This will reduce developer confusion about where the boundaries are. + For example, a new CSS property is a distinct feature, + whereas the ability to omit the commas in the CSS ''rgb()'' function is not. + New features that are clearly distinct + should generally be limited to secure contexts. + However, there are many cases where whether a feature is clearly distinct + is a matter of judgment. + + + : Does the feature depend on being in a secure context? + + :: If a feature depends on + the expectations of authentication, integrity, or confidentiality + that are met only in secure contexts, + then it should be limited to secure contexts, + even if it is not a clearly distinct feature as described in the previous point. + For example, a feature that communicates with USB devices + if those devices have allowed + Web content from the site's origin + to communicate those USB devices + depends on the authentication of the origin + and the integrity of the data + sent to the USB device, + since sending untrusted data to a USB device could damage that device + or compromise computers that the device connects to. +

Event Design

Always add event handler attributes

From fedee9d48dea32a1740c18f515fae943eeffe955 Mon Sep 17 00:00:00 2001 From: "L. David Baron" Date: Thu, 24 Aug 2017 14:08:54 -0700 Subject: [PATCH 02/15] Fix typo pointed out by annevk and jonathanKingston. --- index.bs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/index.bs b/index.bs index 15ae8c99..33bd1e7d 100644 --- a/index.bs +++ b/index.bs @@ -366,7 +366,7 @@ on interfaces, namespaces, or their members (such as methods and attributes). Similar ways of marking features as limited to secure contexts should be added to other points where the Web platform is extended over time (for example, the definition of a new CSS property). -However, for some times of extension points (e.g., new DOM events), +However, for some types of extension points (e.g., new DOM events), limitation to secure contexts should just be defined in normative prose in the specification. From 06189de8e35ed09edc5cc09014fe780ddd4799e2 Mon Sep 17 00:00:00 2001 From: "L. David Baron" Date: Thu, 24 Aug 2017 14:15:45 -0700 Subject: [PATCH 03/15] Change example about DOM events, per annevk. --- index.bs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/index.bs b/index.bs index 33bd1e7d..25c51554 100644 --- a/index.bs +++ b/index.bs @@ -366,7 +366,7 @@ on interfaces, namespaces, or their members (such as methods and attributes). Similar ways of marking features as limited to secure contexts should be added to other points where the Web platform is extended over time (for example, the definition of a new CSS property). -However, for some types of extension points (e.g., new DOM events), +However, for some types of extension points (e.g., dispatching an event), limitation to secure contexts should just be defined in normative prose in the specification. From 29a876c07c113a9cfc2c2c5250446ddc5b77fa0b Mon Sep 17 00:00:00 2001 From: "L. David Baron" Date: Thu, 24 Aug 2017 17:05:20 -0700 Subject: [PATCH 04/15] Make advice clearer and stronger in response to feedback, and restructure to put WebIDL note last. --- index.bs | 77 +++++++++++++++++++++++++++++++++++++------------------- 1 file changed, 51 insertions(+), 26 deletions(-) diff --git a/index.bs b/index.bs index 25c51554..021f0f42 100644 --- a/index.bs +++ b/index.bs @@ -345,35 +345,26 @@ and on when to use promises and when not to use promises, see Writing Promise-Using Specifications. -

Limit new and distinct APIs to secure contexts

+

Limit new features to secure contexts

-Many new APIs should be available only in +New features should be available only in secure contexts. +Adding a feature to the Web that is available in non-secure contexts +is discouraged and requires strong justification. + This restriction exists for two reasons. First, it helps encourage Web content and applications to migrate to secure contexts. -Second, it can restrict new APIs where authentication, integrity, or confidentiality -are important to prevent substantial increases to the privacy or security risks of using the Web. +Second, some new features depend on authentication, integrity, or confidentiality +to prevent substantial increases to the privacy or security risks of using the Web. For more detail, see the W3C TAG Finding on Securing the Web. -When the new feature is defined in -WebIDL, -specification authors can limit a feature to secure contexts -by marking new interfaces and methods with the -[SecureContext] extended attribute -on interfaces, namespaces, or their members (such as methods and attributes). -Similar ways of marking features as limited to secure contexts should be added -to other points where the Web platform is extended over time -(for example, the definition of a new CSS property). -However, for some types of extension points (e.g., dispatching an event), -limitation to secure contexts should just -be defined in normative prose in the specification. - -When deciding whether a feature should be limited to secure contexts, +When deciding whether a change to Web technology +should be limited to secure contexts, we suggest considering the following factors: - : Does the feature have a clear and understandable boundary? + : Is this change a new feature? :: A feature that is limited to secure contexts should be recognizable by the developers who use it as @@ -381,19 +372,40 @@ we suggest considering the following factors: This will reduce developer confusion about where the boundaries are. For example, a new CSS property is a distinct feature, whereas the ability to omit the commas in the CSS ''rgb()'' function is not. - New features that are clearly distinct - should generally be limited to secure contexts. - However, there are many cases where whether a feature is clearly distinct - is a matter of judgment. - + We also don't want to increase + the complexity of implementations of Web technology + by requiring tests for secure contexts in too many *types* of places. + + Changes that include + additions made at the major points at which new features are added + (such as additions of new IDL interfaces, namespaces, methods, or properties, + or additions of new CSS properties) + must be limited to secure contexts. + Changes made entirely + at more minor points where new capabilities are added to the platform + (such as new IDL method *overloads*, + or new *values* for an existing CSS property), + or at expansion points where feature detection is not possible, + do not necessarily need to be limited to secure contexts + (and for the purpose of this section, need not count as a new feature). + + : Can the presence of the feature be detected? + + :: The existence of new features should generally be detectable. + However, if, for some reason + (a reason that requires serious justification), + it is not possible for developers to detect whether a new feature is present, + limiting the feature to secure contexts + might cause problems + for libraries that may be used in either secure or non-secure contexts. : Does the feature depend on being in a secure context? :: If a feature depends on the expectations of authentication, integrity, or confidentiality that are met only in secure contexts, - then it should be limited to secure contexts, - even if it is not a clearly distinct feature as described in the previous point. + then it must be limited to secure contexts, + even if the other factors above suggest it doesn't need to be. For example, a feature that communicates with USB devices if those devices have allowed Web content from the site's origin @@ -404,6 +416,19 @@ we suggest considering the following factors: since sending untrusted data to a USB device could damage that device or compromise computers that the device connects to. +Specification authors can most features defined in +WebIDL, +to secure contexts +by using the +[SecureContext] extended attribute +on interfaces, namespaces, or their members (such as methods and attributes). +Similar ways of marking features as limited to secure contexts should be added +to other major points where the Web platform is extended over time +(for example, the definition of a new CSS property). +However, for some types of extension points (e.g., dispatching an event), +limitation to secure contexts should just +be defined in normative prose in the specification. +

Event Design

Always add event handler attributes

From 68a85220cf3959d5de187057ce59958dd2e33e6c Mon Sep 17 00:00:00 2001 From: "L. David Baron" Date: Thu, 24 Aug 2017 17:06:39 -0700 Subject: [PATCH 05/15] Fix missing 'with'. --- index.bs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/index.bs b/index.bs index 021f0f42..ca070e22 100644 --- a/index.bs +++ b/index.bs @@ -409,7 +409,7 @@ we suggest considering the following factors: For example, a feature that communicates with USB devices if those devices have allowed Web content from the site's origin - to communicate those USB devices + to communicate with those USB devices depends on the authentication of the origin and the integrity of the data sent to the USB device, From 85009e1c6b5d947185428d9c4c93b1c95871006f Mon Sep 17 00:00:00 2001 From: "L. David Baron" Date: Fri, 25 Aug 2017 00:20:32 -0700 Subject: [PATCH 06/15] Fix missing word pointed out by annevk. --- index.bs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/index.bs b/index.bs index ca070e22..11a70fe4 100644 --- a/index.bs +++ b/index.bs @@ -416,7 +416,7 @@ we suggest considering the following factors: since sending untrusted data to a USB device could damage that device or compromise computers that the device connects to. -Specification authors can most features defined in +Specification authors can limit most features defined in WebIDL, to secure contexts by using the From ecb1acfb67e18a8e7420797037b222741bc9ab7c Mon Sep 17 00:00:00 2001 From: "L. David Baron" Date: Sat, 30 Sep 2017 05:31:04 -0700 Subject: [PATCH 07/15] Remove paragraph that was too perscriptive. --- index.bs | 13 ------------- 1 file changed, 13 deletions(-) diff --git a/index.bs b/index.bs index 11a70fe4..464d1b15 100644 --- a/index.bs +++ b/index.bs @@ -376,19 +376,6 @@ we suggest considering the following factors: the complexity of implementations of Web technology by requiring tests for secure contexts in too many *types* of places. - Changes that include - additions made at the major points at which new features are added - (such as additions of new IDL interfaces, namespaces, methods, or properties, - or additions of new CSS properties) - must be limited to secure contexts. - Changes made entirely - at more minor points where new capabilities are added to the platform - (such as new IDL method *overloads*, - or new *values* for an existing CSS property), - or at expansion points where feature detection is not possible, - do not necessarily need to be limited to secure contexts - (and for the purpose of this section, need not count as a new feature). - : Can the presence of the feature be detected? :: The existence of new features should generally be detectable. From 9d9bb9c8a2ad3eec0e59c0d6187347440e4468f3 Mon Sep 17 00:00:00 2001 From: "L. David Baron" Date: Sat, 30 Sep 2017 05:50:31 -0700 Subject: [PATCH 08/15] Various edits to reflect the discussion in Nice. - require justification even for not-new-feature - say that the TAG can be consulted - expand on feature detection equivalence with unimplemented features - restructure a bit in order to do both of the above --- index.bs | 92 ++++++++++++++++++++++++++++++-------------------------- 1 file changed, 50 insertions(+), 42 deletions(-) diff --git a/index.bs b/index.bs index 464d1b15..4d32f85b 100644 --- a/index.bs +++ b/index.bs @@ -360,48 +360,56 @@ to prevent substantial increases to the privacy or security risks of using the W For more detail, see the W3C TAG Finding on Securing the Web. -When deciding whether a change to Web technology -should be limited to secure contexts, -we suggest considering the following factors: - - : Is this change a new feature? - - :: A feature that is limited to secure contexts - should be recognizable by the developers who use it as - distinct from features that are available in non-secure contexts. - This will reduce developer confusion about where the boundaries are. - For example, a new CSS property is a distinct feature, - whereas the ability to omit the commas in the CSS ''rgb()'' function is not. - We also don't want to increase - the complexity of implementations of Web technology - by requiring tests for secure contexts in too many *types* of places. - - : Can the presence of the feature be detected? - - :: The existence of new features should generally be detectable. - However, if, for some reason - (a reason that requires serious justification), - it is not possible for developers to detect whether a new feature is present, - limiting the feature to secure contexts - might cause problems - for libraries that may be used in either secure or non-secure contexts. - - : Does the feature depend on being in a secure context? - - :: If a feature depends on - the expectations of authentication, integrity, or confidentiality - that are met only in secure contexts, - then it must be limited to secure contexts, - even if the other factors above suggest it doesn't need to be. - For example, a feature that communicates with USB devices - if those devices have allowed - Web content from the site's origin - to communicate with those USB devices - depends on the authentication of the origin - and the integrity of the data - sent to the USB device, - since sending untrusted data to a USB device could damage that device - or compromise computers that the device connects to. +New capabilities added to the Web should be limited to secure contexts; +exposing them in non-secure contexts requires justification. +The TAG is interested in hearing about and discussing cases +where it is unclear whether exposing the capability +in non-secure contexts is justifiable. + +The most common justification that we expect +for supporting a new capability in non-secure contexts +is that the new capability is not a new feature. +If a feature is not recognizable by the developers who use it as +distinct from features that are available in non-secure contexts, +limiting it to secure contexts could cause +developer confusion about where the boundaries are. +We also don't want to increase +the complexity of implementations of Web technology +by requiring tests for secure contexts in too many *types* of places. +For example, exposing to non-secure contexts a new CSS property +that adds support for a new line spacing model +cannot be justified on this basis, +but exposing the ability to omit the commas in the CSS ''rgb()'' function can. + +The existence of new features should generally be detectable, +so that web content can act appropriately if the feature is present or not. +This applies both to features that are not present because they are not implemented, +and to features that are not present in a non-secure context because +they are limited to secure contexts. +Putting this another way, +a feature that is limited to secure contexts should, in non-secure contexts, +be indistinguishable from a feature that is not implemented. +However, if, for some reason +(a reason that itself requires serious justification), +it is not possible for developers to detect whether a feature is present, +limiting the feature to secure contexts +might cause problems +for libraries that may be used in either secure or non-secure contexts. + +If a feature depends on +the expectations of authentication, integrity, or confidentiality +that are met only in secure contexts, +then it must be limited to secure contexts, +even if the other factors above could justify exposing it in non-secure contexts. +For example, a feature that communicates with USB devices +if those devices have allowed +Web content from the site's origin +to communicate with those USB devices +depends on the authentication of the origin +and the integrity of the data +sent to the USB device, +since sending untrusted data to a USB device could damage that device +or compromise computers that the device connects to. Specification authors can limit most features defined in WebIDL, From 0392c1906a1410caa1613f44a94771bccee582db Mon Sep 17 00:00:00 2001 From: "L. David Baron" Date: Sat, 30 Sep 2017 05:54:18 -0700 Subject: [PATCH 09/15] Merge 2 paragraphs that ended up nearly identical. --- index.bs | 13 +++++-------- 1 file changed, 5 insertions(+), 8 deletions(-) diff --git a/index.bs b/index.bs index 4d32f85b..1a3ee3f4 100644 --- a/index.bs +++ b/index.bs @@ -347,10 +347,13 @@ Promise-Using Specifications.

Limit new features to secure contexts

-New features should be available only in +New capabilities added to the Web should be available only in secure contexts. -Adding a feature to the Web that is available in non-secure contexts +Exposing them in non-secure contexts is discouraged and requires strong justification. +The TAG is interested in hearing about and discussing cases +where it is unclear whether exposing the capability +in non-secure contexts is justifiable. This restriction exists for two reasons. First, it helps encourage Web content and applications @@ -360,12 +363,6 @@ to prevent substantial increases to the privacy or security risks of using the W For more detail, see the W3C TAG Finding on Securing the Web. -New capabilities added to the Web should be limited to secure contexts; -exposing them in non-secure contexts requires justification. -The TAG is interested in hearing about and discussing cases -where it is unclear whether exposing the capability -in non-secure contexts is justifiable. - The most common justification that we expect for supporting a new capability in non-secure contexts is that the new capability is not a new feature. From b4657950b74c337ef81783b74ac00b9b125d0221 Mon Sep 17 00:00:00 2001 From: "L. David Baron" Date: Sat, 30 Sep 2017 05:56:39 -0700 Subject: [PATCH 10/15] Wordsmith. --- index.bs | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/index.bs b/index.bs index 1a3ee3f4..a9dabb90 100644 --- a/index.bs +++ b/index.bs @@ -365,10 +365,9 @@ For more detail, see the W3C TAG Finding on The most common justification that we expect for supporting a new capability in non-secure contexts -is that the new capability is not a new feature. -If a feature is not recognizable by the developers who use it as -distinct from features that are available in non-secure contexts, -limiting it to secure contexts could cause +is that the new capability is not recognizably separate +from an existing feature that is available in non-secure contexts. +In this case, limiting it to secure contexts could cause developer confusion about where the boundaries are. We also don't want to increase the complexity of implementations of Web technology From f7a2d201d58c0673ac5e9dc7ad913f5332e6503c Mon Sep 17 00:00:00 2001 From: "L. David Baron" Date: Fri, 13 Oct 2017 16:08:11 -0700 Subject: [PATCH 11/15] Address @mikewest's concern that this sentence undercuts the prior ones too much. --- index.bs | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/index.bs b/index.bs index a9dabb90..92bdc14f 100644 --- a/index.bs +++ b/index.bs @@ -351,9 +351,8 @@ New capabilities added to the Web should be available only in secure contexts. Exposing them in non-secure contexts is discouraged and requires strong justification. -The TAG is interested in hearing about and discussing cases -where it is unclear whether exposing the capability -in non-secure contexts is justifiable. +The TAG is interested in hearing about and working to resolve +any cases where exposure in non-secure contexts is being seriously considered. This restriction exists for two reasons. First, it helps encourage Web content and applications From ee93b93f315c5fdac7d402815cc06e2b3094a491 Mon Sep 17 00:00:00 2001 From: "L. David Baron" Date: Fri, 13 Oct 2017 16:33:55 -0700 Subject: [PATCH 12/15] Cut down on feature detection prose, in favor of new section in #82. --- index.bs | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/index.bs b/index.bs index 92bdc14f..df8be6fa 100644 --- a/index.bs +++ b/index.bs @@ -376,12 +376,10 @@ that adds support for a new line spacing model cannot be justified on this basis, but exposing the ability to omit the commas in the CSS ''rgb()'' function can. -The existence of new features should generally be detectable, +As described in (UNCOMMENT ONCE #82 MERGED, AND ADD LINK FROM THERE TO HERE), +the existence of features should generally be detectable, so that web content can act appropriately if the feature is present or not. -This applies both to features that are not present because they are not implemented, -and to features that are not present in a non-secure context because -they are limited to secure contexts. -Putting this another way, +Since the detection should be the same no matter why the feature is unavailable, a feature that is limited to secure contexts should, in non-secure contexts, be indistinguishable from a feature that is not implemented. However, if, for some reason From 6d90d7c2078e9841eeb479efbbd36a3471c8e2d0 Mon Sep 17 00:00:00 2001 From: "L. David Baron" Date: Fri, 13 Oct 2017 18:37:02 -0700 Subject: [PATCH 13/15] Reword to address @mikewest comment about features that depend on guarantees of secure contexts. --- index.bs | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/index.bs b/index.bs index df8be6fa..c0aeb9c4 100644 --- a/index.bs +++ b/index.bs @@ -389,10 +389,10 @@ limiting the feature to secure contexts might cause problems for libraries that may be used in either secure or non-secure contexts. -If a feature depends on -the expectations of authentication, integrity, or confidentiality -that are met only in secure contexts, -then it must be limited to secure contexts, +If a feature would pose a risk to user privacy or security +without the authentication, integrity, or confidentiality +that is present only in secure contexts, +then the feature must be limited to secure contexts, even if the other factors above could justify exposing it in non-secure contexts. For example, a feature that communicates with USB devices if those devices have allowed From dfdd321de1a00d95c4649028f525b57933b90fa9 Mon Sep 17 00:00:00 2001 From: "L. David Baron" Date: Fri, 13 Oct 2017 18:42:57 -0700 Subject: [PATCH 14/15] Move paragraph, per @mikewest suggestion. --- index.bs | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/index.bs b/index.bs index c0aeb9c4..c033d932 100644 --- a/index.bs +++ b/index.bs @@ -362,6 +362,19 @@ to prevent substantial increases to the privacy or security risks of using the W For more detail, see the W3C TAG Finding on Securing the Web. +Specification authors can limit most features defined in +WebIDL, +to secure contexts +by using the +[SecureContext] extended attribute +on interfaces, namespaces, or their members (such as methods and attributes). +Similar ways of marking features as limited to secure contexts should be added +to other major points where the Web platform is extended over time +(for example, the definition of a new CSS property). +However, for some types of extension points (e.g., dispatching an event), +limitation to secure contexts should just +be defined in normative prose in the specification. + The most common justification that we expect for supporting a new capability in non-secure contexts is that the new capability is not recognizably separate @@ -404,19 +417,6 @@ sent to the USB device, since sending untrusted data to a USB device could damage that device or compromise computers that the device connects to. -Specification authors can limit most features defined in -WebIDL, -to secure contexts -by using the -[SecureContext] extended attribute -on interfaces, namespaces, or their members (such as methods and attributes). -Similar ways of marking features as limited to secure contexts should be added -to other major points where the Web platform is extended over time -(for example, the definition of a new CSS property). -However, for some types of extension points (e.g., dispatching an event), -limitation to secure contexts should just -be defined in normative prose in the specification. -

Event Design

Always add event handler attributes

From a6cb3c30181ca9b44d87116d9ba5b8dd5e1ebef8 Mon Sep 17 00:00:00 2001 From: "L. David Baron" Date: Fri, 13 Oct 2017 18:47:48 -0700 Subject: [PATCH 15/15] Reword sentence on informing the TAG, again. --- index.bs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/index.bs b/index.bs index c033d932..9ad3480a 100644 --- a/index.bs +++ b/index.bs @@ -351,8 +351,8 @@ New capabilities added to the Web should be available only in secure contexts. Exposing them in non-secure contexts is discouraged and requires strong justification. -The TAG is interested in hearing about and working to resolve -any cases where exposure in non-secure contexts is being seriously considered. +The TAG is interested in hearing about cases +where exposing new features in non-secure contexts is being considered. This restriction exists for two reasons. First, it helps encourage Web content and applications