RE: [sarif] Change draft for #113 (hostname guidance)

TL;DR: I believe our thinking so far is valid (not off-track). I will change my recommendation on the form of a file URI with no authority, I will add more examples, and I will scrub the spec’s code samples as you suggest.

With regard to using "//" when the host name is omitted:

The forms "file:/dir/file.c" and "file:///dir/file.c" are both permitted by the grammar of RFC 8089. Appendix A, “Differences from Previous Specifications”, emphasizes this:

According to the definition in [RFC1738], a file URL always started

with the token "file://", followed by an (optionally blank) host name

and a "/".  The syntax given in Section 2 makes the entire authority

component, including the double slashes "//", optional.

But RFC 8089 also says:

As a special case, the "file-auth" rule can match the string

"localhost" that is interpreted as "the machine from which the URI is

being interpreted," exactly as if no authority were present. Some

current usages of the scheme incorrectly interpret all values in the

authority of a file URI, including "localhost", as non-local. Yet

others interpret any value as local, even if the "host" does not

resolve to the local machine. To maximize compatibility with

previous specifications, users MAY choose to include an "auth-path"

with no "file-auth" when creating a URI.

If you follow the grammar through, that means to prefer the form "file:///dir/file.c" after all, so I’ll change the spec to say that.

With regard to Windows file paths with drive letters:

The blog you cite is from 2006. It states:

The standard for the file scheme doesn’t give specific instructions on how to convert a file system path for a specific operating system into a file URI. While the standard defines the syntax of the file scheme, it leaves the conversion from file system path to file URI up to the implementers.

But RFC 8089, dated February 2017, does offer guidance:

D.2.  DOS- and Windows-Like Systems

   When mapping a DOS- or Windows-like file path to a file URI, the

   drive letter (e.g., "c:") is typically mapped into the first path

   segment.

So "file:///c:/dir/file.c" is valid. It’s not just a file name “crammed into a URI”. The grammar in RFC 3986 is explicit on this point:

path-absolute = "/" [ segment-nz *( "/" segment ) ]

segment-nz    = 1*pchar

segment       = *pchar

pchar         = unreserved / pct-encoded / sub-delims / ":" / "@"

That is, a path segment can include a colon.

In summary, any of these are valid:

"file:///c:/root/dir/file.c" # A local file.

"file://MYMACHINE/c:/root/dir/file.c" # A file on another machine.

"file://MYMACHINE/shared/dir/file.c" # A UNC path; "c:\root" was shared out with share name "shared".
"file://MYMACHINE/c$/root/dir/file.c" # A UNC path using the conventional share name for the C drive.

Note that in the last form, "c$" is a valid segment because "$" is one of the "sub-delims".

Larry

From: Michael Fanning <Michael.Fanning@microsoft.com>
Sent: Friday, April 13, 2018 9:02 AM
To: Larry Golding (Comcast) <larrygolding@comcast.net>; sarif@lists.oasis-open.org
Subject: RE: [sarif] Change draft for #113 (hostname guidance)

Comments:

If you emit the host name you should still include the // in the examples, so prefer file:///c:/file.cpp over your example file:/c:/file.cpp.

In practice, your example works.

I am beginning to wonder if we’re not off-track in our thinking. If you are rendering a Windows file path (which according to the blog below is not a URI but can be delivered as a URI), then the host name should not be included. The host name is included if the file is actually being referenced as a UNC path.

https://blogs.msdn.microsoft.com/ie/2006/12/06/file-uris-in-windows/

Consider this example, a file that exists in c:\public\file.cpp on MYMACHINE. Assume that c:\public is shared across the network. These renderings are acceptable:

// No host name. Why? We are referencing the content as a local windows file path, crammed into a URI

file:///c:/public/file.cpp

// An actual file URI. No drive letter, this file comes across that network from a shared location

file://MYMACHINE/public/file.cpp

// By convention, Windows shares drives automatically as C$, D$, etc. This is a valid URI. If you have access to this implicitly shared thing (available to admins), you can access this file

file://MYMACHINE/c$/public/file.cpp

ALSO:

Whatever we do next, we should be sure to look at all file paths in examples to make sure they follow current guidance
Also suggest scrubbing ‘larry-dev’ from examples. You can use contoso where required as a host/domain name, as a well-established fictional term.

From: sarif@lists.oasis-open.org <sarif@lists.oasis-open.org> On Behalf Of Larry Golding (Comcast)
Sent: Thursday, April 5, 2018 9:42 AM
To: sarif@lists.oasis-open.org
Subject: [sarif] Change draft for #113 (hostname guidance)
Importance: High

The change draft for Issue #113: “Provide guidance on including a hostname in a uriBaseIdValue” is available:

Documents/ChangeDrafts/Active/sarif-v2.0-issue-113-hostname-guidance.docx

I’ll move its adoption at the next TC meeting.

Thanks,

Larry

sarif message