Subject: [Uri-review] Review request for gittorrent: URI scheme

From: Chris Rebert <[email-masked]>
Date: Sun, 03 Apr 2016 20:10:09 -0700

Hello,

Per the advice of RFC 7595, I hereby present the following proposed
registration of the "gittorrent" provisional URI scheme for review.
Any feedback is greatly appreciated. Thanks.

Cheers,
Chris
****
http://chrisrebert.com
Browser 🐛 of the day: http://bugzil.la/1259972

********

Scheme name:  gittorrent

Status:  Provisional

Applications/protocols that use this scheme name:
  GitTorrent ("A decentralization of GitHub using BitTorrent and
  Bitcoin")

Contact:
  Scheme creator:
    Chris Ball <http://printf.net/>
  Registering party:
    Chris Rebert <[email-masked]>

Change controller:
  Either the scheme creator or the registering party.

References:
  Ball, C., "Announcing GitTorrent: A Decentralized GitHub", 29 May
  2015,
      <http://blog.printf.net/articles/2015/05/29/announcing-gittorrent-a-decentralized-github/>.
  Ball, C., "GitTorrent", 2016, <http://gittorrent.org/>.
  Ball, C., "GitTorrent", 2016, <https://github.com/cjb/GitTorrent>.
  Bernstein, D. J., Duif, N., Lange, T., Schwabe, P., and B. Yang,
      "Ed25519: high-speed high-security signatures", 27 September 2011,
      <https://ed25519.cr.yp.to/>.
  Bitcoin Project, "Bitcoin - Open source P2P money", 2016,
      <https://bitcoin.org/en/>.
  Bray, T., Ed., "The JavaScript Object Notation (JSON) Data Interchange
      Format", RFC 7159, March 2014.
  Cohen, B., "BEP 3: The BitTorrent Protocol Specification", 11 October
  2013,
      <http://www.bittorrent.org/beps/bep_0003.html>.
  Eastlake 3rd, D. and P. Jones, "US Secure Hash Algorithm 1 (SHA1)",
  RFC 3174,
      September 2001.
  "Git", 2016, <https://git-scm.com/>.

Scheme syntax:
  This scheme uses a profile of the RFC 3986 generic URI syntax.
  The "fragment" URI component is never permitted.

  A gittorrent URI may come in one of three forms:

    0. Where the "authority" component is a domain name
      Example:  gittorrent://github.com/cjb/recursers
      The "path" and "query" components have no extra restrictions.

    1. Where the "authority" component is a 40-byte hexadecimal number
    (the
       conventional representation of a SHA-1 hash digest)
      Example: 
      gittorrent://81e24205d4bac8496d3e13282c90ead5045f09ea/recursers
      In this case, the "query" component is not permitted, and
      the "path" component consists of exactly one segment (the Git
      repository
      name).

    2. Where the "authority" is a username
      Example:  gittorrent://cjb/foo
      In this case, the "query" component is not permitted, and
      the "path" component consists of exactly one segment (the Git
      repository
      name).

  There may be further restrictions on the format of usernames and
  repository
  names.

Scheme semantics:
  See the GitTorrent project for details.  The following is a summary of
  read-only usage.

  gittorrent URIs represent Git repositories and specify the metadata
  necessary
  to clone a repository, to read the repository's commits, and, with the
  necessary cryptographic key, to write commits to the repository.

  In URIs of type (0), the SHA-1 hash identifier of the latest commit of
  the
  primary branch is fetched via the git protocol, as if this had been a
  git:
  URI.  The actual data for that commit is then downloaded via
  BitTorrent.

  In URIs of type (1), the SHA-1 hash in the "authority" component is
  used as a
  key for a lookup in a BitTorrent DHT (distributed hash table).  The
  value
  obtained from the lookup is a JSON object representing a GitTorrent
  user
  profile, which includes the names of that user's repositories, the
  names of
  those repositories' git refs, and the SHA-1 hash identifiers of the
  commits
  that those refs currently point to.  The "path" component is the name
  of the
  repository, and is used to look up the corresponding SHA-1 hash commit
  identifier for the repository in the user profile.  The actual data
  for that
  commit is then downloaded via BitTorrent.

  In URIs of type (2), the username in the "authority" component is used
  for an
  OP_RETURN transaction lookup in Bitcoin's blockchain.  If successful,
  this
  lookup yields a SHA-1 hash which is then used as a key for a lookup in
  a
  BitTorrent DHT (distributed hash table).  The value obtained from the
  lookup
  is a JSON object representing a GitTorrent user profile (as described
  in the
  previous paragraph).  The "path" component is the name of the
  repository, and
  is used to look up the corresponding SHA-1 hash commit identifier for
  the
  repository in the user profile.  The actual data for that commit is
  then
  downloaded via BitTorrent.

Encoding considerations:
  Unknown, use with care.

Interoperability considerations:
  Not fully known, use with care.

  The "fragment" URI component has no known meaning or usage.  Unless it
  becomes meaningful in the future, omitting it is strongly advised.

Security considerations:
  Not fully known, use with care.

  GitTorrent normally uses public BitTorrent swarms, and thus doesn't
  ensure
  confidentiality of the Git data it stores.  Therefore it's normally
  unsuitable
  for Git repositories which contain unencrypted private data.  The
  confidentiality of the data when in transit between peers depends on
  the
  particular flavor of the BitTorrent protocol being used by the peers.

  Git and BitTorrent use SHA-1 hashes to ensure the integrity of the
  data.  The
  general security considerations for SHA-1 thus also apply to
  GitTorrent.
  GitTorrent uses Ed25519 as its digital signature scheme for ensuring
  the
  integrity and ownership of GitTorrent user profiles, and thus inherits
  the
  security considerations of Ed25519.

  gittorrent: URIs of type (0) refer to hosts using domain names.  The
  domain
  name resolution process is subject to its own set of security
  considerations
  (see RFC 4033).
  gittorrent: URIs of type (2) use GitTorrent usernames, which use the
  Bitcoin
  protocol/network for their registration infrastructure, and are thus
  subject
  to Bitcoin's security considerations.  Users of type (2) URIs should
  keep in
  mind that GitTorrent usernames don't necessarily correspond to the
  usernames
  of other Git-related systems, other source code management systems, or
  other
  software project management systems in general.  Users should
  externally
  verify the identities associated with GitTorrent usernames before
  utilizing
  gittorrent: URIs involving those usernames.

  Beware of homograph attacks when dealing with gittorrent: URIs. 
  Attackers may
  register GitTorrent usernames which deliberately appear visually
  similar to
  other GitTorrent usernames in an attempt to fool unwary users. 
  Attackers may
  likewise upload Git repositories with names which deliberately appear
  visually
  similar to those of other Git repositories.

  It's currently unclear precisely how GitTorrent software
  differentiates
  between gittorrent: URIs of type (0) and type (2).  For example,
  without
  further restrictions on allowed domain names, the URI
  gittorrent://abc/xyz
  could potentially either reference the top-level domain "abc" or the
  GitTorrent username "abc".  Similarly, without further restrictions on
  allowed
  GitTorrent usernames, the URI gittorrent://abc.xyz/qwe could
  potentially
  either reference the domain "abc.xyz" or the GitTorrent username
  "abc.xyz".
  The usage of gittorrent: URIs with usernames that contain periods
  should
  therefore be avoided for the time being.
  Accessing GitTorrent URIs while on an untrusted network is thus
  potentially
  dangerous, since a malicious network operator might be able to
  influence which
  interpretation the GitTorrent software chooses by causing the
  "username" to
  unexpectedly resolve as a domain name or by causing the domain name to
  resolve
  to the IP address of an attacker-controlled server.
  Git's integrity assurance mechanisms may allow these attacks to be
  detected in
  certain cases, provided that the Git repository had been previously
  cloned via
  a trustworthy mechanism.

---

From: Graham Klyne <[email-masked]>
Date: Mon, 04 Apr 2016 08:51:06 +0100

I have two comments:

1. It is not the place of a URI scheme registration to prohibit the use of 
fragments.  I suggest dropping the sentence "The "fragment" URI component is 
never permitted" under section "semantics".  (The protocol may not allow 
fragments, but that's no different from HTTP - once a URI is dereferenced, it is 
the format of the resulting representation that determines how if and how 
fragments may be applied.)

2 The registration says "gittorrent URIs represent Git repositories".  Looking 
at the descriptions, it seems that the URI denotes one of three different 
things, depending on the form used:

Type 0: appears to denote the hash of the latest commit in the repository.

Type 1: appears to denote the repository itself, as accessed via a bittorrent stream

Type 2: appears to denote a bitcoin transaction element containing a reference 
to the repository per type 1.

I observe that there appears to be a tight coupling between the URIs and the 
resource representations associated with dereferencing of the URIs.  If this is 
seen as being part of Web architecture (else why use URIs?), then I'd be 
inclined to be less prescritive about representation details. These may be a 
feature of current implementations, but who knows how future implementations may 
evolve?

#g
--

On 04/04/2016 04:10, Chris Rebert wrote:
> _______________________________________________
> Uri-review mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/uri-review
>

---

From: Chris Rebert <[email-masked]>
Date: Tue, 05 Apr 2016 21:36:00 -0700

> fragments may be applied.)

Okay, dropped that sentence.

> feature of current implementations, but who knows how future

Not giving any details on interpreting the URIs seems unhelpfully vague
for implementors of other clients (there's currently only a reference
implementation). However, I've now added verbiage noting the de-facto
and fluid nature of the "specification". Hopefully that helps address
this concern?

Regards,
Chris

---

From: Chris Rebert <[email-masked]>
Date: Tue, 05 Apr 2016 21:41:13 -0700

> Any feedback is greatly appreciated. Thanks.

Here's a revised draft based on the feedback thus far.

Cheers,
Chris
****
http://chrisrebert.com
Browser 🐛 of the day:
https://developer.microsoft.com/en-us/microsoft-edge/platform/issues/7124038/

********

Scheme name:  gittorrent

Status:  Provisional

Contact:
  Scheme creator:

Change controller:

References:

Scheme syntax:

  At the time of writing this registration, a gittorrent URI comes in
  one of
  three forms:

  Given the youth of the GitTorrent project, additional gittorrent: URI
  forms
  might be defined in the future, and the interpretation of the existing
  forms
  could potentially be changed.  Implementors SHOULD consult the
  GitTorrent
  project for the most up-to-date information on gittorrent: URIs, as
  there is
  currently no de jure standard for them.  This third-party URI scheme
  registration is based on the GitTorrent reference implementation's
  documentation at the time of writing.

Scheme semantics:

  See the GitTorrent project for full details.
  The following is a summary of read-only usage when cloning the
  repository:

  In URIs of type (0), the SHA-1 hash identifier of the latest commit of
  the
  primary branch is fetched via the git protocol, as if this had been a
  git:
  URI.  The actual data for that commit (and its ancestors, if
  necessary) is
  then downloaded via BitTorrent.

  identifier of the primary branch of the repository in the user
  profile.  The
  actual data for that commit (and its ancestors, if necessary) is then

  In URIs of type (2), the username in the "authority" component is used
  for an
  OP_RETURN transaction lookup in Bitcoin's blockchain.  If successful,
  this
  lookup yields a SHA-1 hash which is then used as a key for a lookup in
  a
  BitTorrent DHT (distributed hash table).  The value obtained from the
  lookup
  is a JSON object representing a GitTorrent user profile (as described
  in the
  previous paragraph).  The "path" component is the name of the
  repository, and
  is used to look up the corresponding SHA-1 hash commit identifier for
  the
  primary branch of the repository in the user profile.  The actual data
  for
  that commit (and its ancestors, if necessary) is then downloaded via
  BitTorrent.

Encoding considerations:
  Unknown, use with care.

Security considerations:

---

From: Graham Klyne <[email-masked]>
Date: Wed, 06 Apr 2016 09:07:01 +0100

Hi Chris,

Thanks for your response.  I would like to clarify that none of my comments are 
blockers for a provisional registration, rather suggestions on the assumption 
that this work might progress to something more widespread.

With reference to 'verbiage noting the de-facto and fluid nature of the 
"specification"', that could help but it's difficult for me to offer a definite 
view without seeing it.  I could point out that a URI scheme registration is 
not, of itself, an implementers guide.

My comments have their roots in the idea that URIs are not _just_ protocol 
elements, but also part of a wider information infrastructure (the Web), and as 
such might be used in ways that are not anticipated by a particular protocol 
implementation.  The prescriptive elements I was pushing back against are, I 
think, more properly part of the actual "gittorrent" protocol specification than 
of the associated URI scheme.  My normal expectation is that a URI scheme 
registration will provide references to protocol descriptions and/or 
implementations that contribute to the meaning of the URI, but would not of 
itself attempt to be a protocol specification.

RFC3986 starts with this: "A Uniform Resource Identifier (URI) provides a simple 
and extensible means for identifying a resource."  Later 
(https://tools.ietf.org/html/rfc3986#section-1.1) it goes on to discuss 
identification in a little more detail; e.g.

"Nor should it be assumed that a system sing URIs will access the resource 
identified: in many cases, URIs are used to denote resources without any 
intention that they be accessed."

and

"URIs have a global scope and are interpreted consistently regardless of 
context, though the result of that interpretation may be in relation to the 
end-user's context."

etc.

None of this is to comment on the "gittorrent" protocol itself, or its 
applications, but simply to try and suggest a clearer separation between the 
identifying function of the URI and the protocol through which that 
identification might be realized.

To try and make this more concrete, consider the following (entirely 
speculative) example.  A developers' "intranet" might host a number of git 
repositories that are accessed and updated using gittorrent protocols from 
across the Internet.  The gittorrrent URIs could be the primary identifiers for 
these repositories, but local access could be via git HTTP protocol via a local 
HTTP caching proxy (similar to the way that HTTP proxying can be used locally to 
access FTP-served resources).  In this scenario, the gittorrent URI identifies 
the repository, and gains its meaning (i.e. what it references) via the 
gittorrent protocol, but is not necessarily invoked in local retrieval of 
repository data.

I don't think my comments need to be acted on immediately, and the provisional 
registration should probably go ahead pretty much as-is, but, looking ahead, in 
formulating specifications for wider interoperable public use they might be 
something to consider.

#g
--

---

From: "Roy T. Fielding" <[email-masked]>
Date: Wed, 6 Apr 2016 15:07:50 -0700

> On Apr 5, 2016, at 9:41 PM, Chris Rebert <[email-masked]> wrote:
> 

I think that is unnecessary and confusing.  Just use the git URI for identification
of this resource and something else (markup, configuration, command-line, ... another URI)
to indicate that BitTorrent is the protocol used to retrieve it.  This is no different
from the various schemes that can be proxied over HTTP by defining environment variables
or other config properties.

>  downloaded via BitTorrent.

The authority component is for identification of name-based authorities,
as in (0).  Using it two different ways for the same scheme would be a
very bad idea. Likewise, restricting the path to one name means it isn't
hierarchical, so there is no reason for it to be a path.  Just use

    gittorrent:81e24205d4bac8496d3e13282c90ead5045f09ea?recursers

to be distinct from other URI forms, or see below for a single format.

>  that commit (and its ancestors, if necessary) is then downloaded via

There is no need for this to be a separate type of URI.  Just do

    gittorrent:cjb?foo

and it is type (1) with a mechanical distinction (usernames are not hashes).

Alternatively, you can merge all three forms into a singular format that
is consistent with the generic URI syntax, as in

    "gittorrent:" [ "//" [ username "@" ] [ authority ] ] path [ "?" sha1 ]

and just exclude the parts that aren't needed for a given identifier.

Note that the above are just comments based on the registration.  IMO, the
system reflects a misunderstanding of how URIs ought to be used as identifiers,
and how representations (or redirections, if available) ought to refer to
other resources.  IOW, what you really should have is a media type definition
of the "JSON object representing a GitTorrent user profile" and then define various
ways of accessing such a representation in the form of schemes for torrent,
http(s), blockchain, etc.  In that case, a fragment can be used for the types
of indirection used above.

....Roy