Re: [oslc-core] Review of OSLC Delegated Dialogs 3.0

["Jim Amsden" <jamsden@us.ibm.com>]

Ian, 
Again, thanks for a great review. Comments
below imbedded in <jra> tags.

Things that need additional discussion:

1. Is there any additional guidance
we want to include on the use of Dialog property oslc:Label?

2. Are there further edits that need
to be done on the Clickjacking section?

3. Should prefill be supported on selection
dialogs, and if so, how should servers treat the prefill entity request
body? See issue OSLCCORE-59
- Should Delegated Dialogs specify prefill for selectionDialogs?

4. Should we remove 6.4.6 concerning
clients not caching prefilled dialogs?

5. Should POST to a delegated dialog
descriptor support using query parameters for prefill? If so, do we need
to specify the format of the parameters? If we don't how will interoperability
be achieved?



Jim Amsden, Senior Technical Staff Member
OSLC and Linked Lifecycle Data
919-525-6575




From:      
 Ian Green1 <ian.green@uk.ibm.com>
To:      
 OASIS (oslc-core@lists.oasis-open.org)
<oslc-core@lists.oasis-open.org>
Date:      
 01/25/2016 12:17 PM
Subject:    
   [oslc-core]
Review of OSLC Delegated Dialogs 3.0
Sent by:    
   <oslc-core@lists.oasis-open.org>

---

Here's a review of 

https://tools.oasis-open.org/version-control/svn/oslc-core/trunk/specs/dialogs.html

as at svn revision 323. 

General comments 
Reference links are not working - it seems that fragment identifiers are
not right: eg https://tools.oasis-open.org/version-control/svn/oslc-core/trunk/specs/dialogs.html#bib-RFC2119.  (I know this is a known problem.) 
<jra>We were were having problems
with the source site being very slow so Nick changed the .jit.su host with
a W3C one in ReSpec handling of bibliographic references. But now all specs
get this error and the biblio reference section isn't being generated:

Error loading references from 'https://specref.jit.su/bibrefs?refs=RFC2119,OSLCCore2,OSLCCore3,LDP,TRS,ILDP,ITIL,ITSM':
error ()

Nick is aware of the issue and will address
this next week.</jra>


Section 4 - It is not clear whether the spec admits that other Link
Relations are permitted for uses other than selection and creation.  (The
wording "Each dialog type, creation or selection, has its own link
relation" suggests that only the two listed link relations is acceptable.)
<jra>The Service resource, and
OSLC3 link headers only distinguish creation and selection dialogs. Servers
could provide other link headers for their purposes, but these are the
only ones defined by OSLC.</jra>

The examples of the three mechanism do not show what happens when there
is more than one dialog resource of a given behaviour (create/select).
 In the service document, these would be distinguished by different
oslc:usage (or could be indistinguishable).   Is this an intended
 limitation of the Link and Prefer header mechanisms?  If the
Prefer header mechanism is permitted to indicate oslc:usage in those representations,
it would be helpful in the examples for this to be shown.
<jra>I don't know the history of this,
but the notion of oslc:usage was removed from OSLC3, even though it is
retained in the discovery resources for backward compatibility. However,
I just noticed its not in the delegated dialog resources. need to add it
back.

I think in OSLC3, it is expected that each
creation, selection, creation factory and query capability would be provided
by a different LDPC if they needed to be distinguished. A single LDPC can
support many different resource types, but wouldn't provide a distinguishing
container. Nested LDPCs would be needed if the resources needed to be grouped
further within a service. All the more reason for a Service to be an LDPC.
</jra>


Section 5 
Typo: "The user has created or selected a resource or canceled the
dialog" - should be plural since more than one can be created/selected.
I struggled with the wording of "JSON follows the prefix in the message
string " - i think this means "a stringified json object will
be concatenated to the message prefix." 
<jra>Fixed (both)</jra>

Even though it is non-normative, I would prefer that we don't suggest that
the "olsc:label" in an oslc-response be a substitute for information
which ought to be obtained from the resource.  Putting information
from the selected/created resource into the oslc:label encourages that
information to be stored in another resource (and/or repository); potentially
this information is in a different security context from the original.
 A common use case for oslc:label from a dialog is when a link is
being created, and there is a temptation to use that label as the link
label (but that same label can be used in other ways, too).  Apps
should be wary of enabling this kind of denormalization.  IBM has
some guidance on the link label issue at https://jazz.net/wiki/bin/view/Reference/LinkLabels.
 There are already known security issues in existing OSLC deployments
because of this denormalization. 
<jra>I think the purpose of oslc:label
in the JSON result is intended as a convenience for the app using a selection
dialog to have some human readable label available with the selection URIs
so that the URIs can be displayed without having to use resource preview.
It recognizes that processing selections may be a short-terms transition
operation where display of URIs with resource preview may not be appropriate
or desirable. This seems reasonable enough.

Regarding your specific issues:
1. oslc:label as substitute redundant information
- servers could easily use the same information as provided in the resource
preview, the JSON results should just be a copy of the same labe.

2. Information from a different security
context - likely the resource URI and its label are in the same security
context, but exposing the label without addressing a possible security
challenge on the URI does seem like a potential security issue. Servers
could address that by not allowing selections of resource the client does
not have access to, or by eliminating the labels in those cases.

3. Denormalization - yes, clients could
use the JSON result oslc:label for displaying links instead of resource
preview, and that could be desirable depending on why and for how long
the link is displayed. 

In any case, we can't remove oslc:label
because it was in OSLC2. Are you suggesting "The
result may also have an oslc:labelthat can be useful for client display without having to use resource preview
to access the Compact resource. "
should be removed, or that there should be some cautions added to its use?</jra>

Section 5.4 
This section could do with some editing.  It talks about ServiceProvider,
but is really referring to any dialog.  It also mentions compact resource,
which seems out of place in this spec. 
<jra>I updated the introductory
paragraph, it was not not clear what was the OSLC dialog vs. clickjack
layer in the iFrame and what the user was seeing vs actually clicking.</jra>

Typo: "delegates dialog" 
<jra>Fixed</jra>

I don't much of this analysis/recommentation -- I cannot usefully review
this material..  Does item 1 refer to the dialog resource, or the
URI of the dialog resource?  To my reading, items 2 and 3 seem to
have nothing to do with clickjacking.  Is there a clickjacking vulnerability
in any implementation which does not do this? 
<jra>Item 1 refers to a request of
the ServiceProvider (and it contained Service resources) to retrieve the
delegated dialog URI. This is indicating the access to the URIs through
the service provider should be protected, not just access to the dialogs
themselves. I clarified this. Items 1 and 2 ensure that 1) malware can't
guess at the delegated dialog URI from the users id and 2) that the URI
used by a user to access the dialog is the one created for that user and
not accessed through some other non-authenticated user.</jra>

If 2&3 were implemented, and 4 occurred, why would SAMEORIGIN be a
recommended X-Frame-Options - this system is being attacked - why play
along?  5 seems to be covering a different kind of resource - not
a dialog - why is that recommendation in this document? 
<jra>SAMEORIGIN gives the server a
bit more flexibility in that it can trust there is no clickjacking from
itself.

Re: item 5, agreed, I removed this.

I also added a reference to https://www.owasp.org/index.php/Clickjacking_Defense_Cheat_Sheet</jra>


Section 6 
What does "effective" mean in "The context URI is the effective
request URI"? 
<jra>I added this link: https://tools.ietf.org/html/rfc7230#page-45</jra>

Section 6.1.4 doesn't seem to be about discovery - in the wrong section?
 Also, in this section, the term "target resource" is incorrect,
it should be "resource". 
<jra>Isn't this about how discovered
dialog descriptors would be contained in the entity response body?</jra>

Section 6.1.5 Is this not better in Appendix A - Resource constraints?
<jra>It is there as well. Not sure
why this was called out, but it doesn't do any harm.</jra>

Section 6.1.6 seems out of place in this document.  Is this not just
good http practice?   
<jra>Perhaps, but it seems useful
to call this out in the context of delegated dialogs and doesn't do any
harm</jra>

Section 6.1.7 Is it clear what ServiceProvider and Service resources are
in this document?  I don't see any references or definitions. 
<jra>I made them links</jra>

Section 6.3.2 I don't see how a client wanting to use windowname protocol
would discover that a server supported it.  Since a server is not
REQUIRED to support windowname, clients are compelled to support postMessage,
or face failure.  I wonder then the utility of optional support of
windowname. 
<jra>Support for windowname protocol
was intentionally removed from OSLC3, but we added back 6.3.2 for backward
compatibility with OSLC2.0.

The protocol is not discoverable (never
was), rather clients specify what they wish (how they are implemented)
usin the oslc-core-postMessage-1.0 or oslc-core-windowName-1.0 fragment
identifiers on the delegated dialog URI. If the server doesn't support
the window name protocol, then that client request would fail. I added
text to indicate this is for backward compatibility with OSLC clients that
used the window name protocol.</jra>

Since the OSLC 2.0 use of a fragment identifier is not mentioned in this
document, is some comment on backward compatibility needed or are we okay
leaving unsaid that a dialogue MUST be robust to unknown fragment identifiers
in window.location?  There is a tension here with 6.3.4, which does
not specify what happens when a client DOES use #oslc-core-post-message-1.0?
<jra>I added text to indicate this
is for backward compatibility with OSLC clients that used the window name
protocol. And I extended 6.3.5 to include the oslc-core-postMessage-1.0
fragment identifier.</jra>

Section 6.3.5 Example 22 seems superfluous and it is also a duplicate
of Example 11.  Shouldn't all of the examples be in the non-normative
sections of the document? 
<jra>Section Conformance indicates
that all examples are non-normative and is OASIS boilerplate. This allows
examples to be easily embedded in normative sections</jra> 

Section 6.4.3 should indicate a resource of RDF type oslc:ResourceShape
rather than just "resource shape".  Are there constraints
on the values of the oslc:resourceShape (if any) and the value of the oslc:resourceType
(if any)?  Since this spec allows prefilling of a selection dialog,
servers could offer constraints to be POSTed that constrain the selection
of resources.  Such constraints would have a different shape from
the shape of those of the resources being selected.  Is this intentional?
<jra>I changed resource shape to be
a link to the new resource-shape.html#resourceShape-shape.

The Dialog shape defines the constraints
on oslc:resourceType - it should be one of the rdf:types of the resource,
but doesn't define any constraints on oslc:resourceShape. I suppose a server
could provide shapes that are incompatible with any of the rdf:types of
the resource and would  therefore fail all creation requests. But
I don't think avoiding that is something that necessarily needs to be stated.

I see from the change history that Steve
generalized dialog prefill to include selection dialogs. But everything
in the document describes prefill only in the context of resource creation.
Looks like prefill for selection dialogs never got finished. In thinking
this through, it seems the big question is what a server would be expected
to do with the entity request body POSTed to the dialog descriptor URI
for a selectionDialog. That actual content of that entity request body
could in general be unpredictable, even if resourceShapes are specified
for the selection dialog. The best we could say is that servers would use
the information in the entity request body to inform the creation of the
selection dialog, perhaps including resource URIs in that dialog that somehow
match the POSTed prefill content. 

This seems useful, but a bit wide open.
It could represent a simple query by example mechanism, or something as
complex as sift or mongoDB query language. Without specifying what the
POSTed request body means, is prefill on selection dialogs meaningful in
the standard? I'll raise an issue.</jra>

Section 6.4.6 I think "Clients SHOULD NOT cache dialog URIs
from prefill requests since they are often temporary. " is beyond
the scope of this document. A server can use whatever cache-control headers
it sees fit, and a well-behaved client will do the right thing 
<jra>I see this logic, but also
the logic of clause 6.4.6. This clause is stating something about client,
not server caching. Sure, a server could cache or store prefill dialogs
forever, and use some mechanism to reuse them based on subsequent client
prefill requests. This would be useful for resource creation templates
for example. But a client might not want to depend on that, and not cache
the dialog too.

On the other hand, if the client did cache
the dialog and it was removed from the server, then the client would get
a 404 and have to repost the prefill content anyway. 

So I don't really see any harm in keeping
or removing the clause, although it seems like reasonable advice to clients.
Anyone else have any thoughts?</jra> 

Section 6.4.7 I'm not sure what this means.  Is this stating that
a prefilled dialogue URI should be treated as opaque by clients?  If
it is about ways to support prefill other than by POSTing a resource representation
to the dialog descriptor, how would a client know what those parameters
were or how to discover that the server supported this mechanism? 
<jra>This means the client can either
POST and entity request body with the prefill contents, or use URI query
parameters in the POST to the dialog descriptor URI, not the prefilled
dialog URI. Servers would have to provide some other means of describing
the query parameters and allowed values for these URIs, possibly using
published REST services through Swagger.io. This seems useful, but somewhat
under-specified. </jra>



Apppendix A does not indicate the use of oslc:usage - it should be
zero-or-many. I expect this has been omitted deliberately, but I'll raise
it anyway just to be sure because I can't think why.  oslc:resourceShape
was oslc:Range oslc:ResourceShape in 2.0 - was there a deliberate decision
for this to be oslc:Any in 3.0? 
<jra>I added it back for OSLC2
compatibility</jra>



best wishes,
   -ian

ian.green@uk.ibm.com (Ian Green1/UK/IBM@IBMGB)
IBM
Unless stated otherwise above:
IBM United Kingdom Limited - Registered in England and Wales with number
741598. 
Registered office: PO Box 41, North Harbour, Portsmouth, Hampshire PO6
3AU