Planning out OCapN URIs

[Christopher Lemmer Webber]

Hello,

Just thinking out loud here. I've drafted a few variations of the OCapN
URI schemes, and here's where I'm currently sitting. (OCapN standing
for "OCap Network", more or less the generation of CapTP and friends I'm
drafting and hoping to converge on w/ the Agoric folks later, equivalent
to the Pluribus suite of network protocols of yore.)

There are four conceptual key URI types, all encoded uner the `ocapn:`
uri scheme:

- MachineLocators
- Sturdyrefs
- Certificates
- CertBears (Certificates + a key to use them, making these into bearer
instrument equivalents, similar to a sturdyref)

There's some abstraction nesting here. In other words:

-+> MachineLocators
|--> SturdyRefs
'-+> Cert(ificate)s
'--> CertBears

One can thus always attenuate CertBears into Certificates, and attenuate
either Certificates or SturdyRefs into MachineLocators.

These are URI types so they can be copy-pasted around for legacy
systems, including at the REPL, in a browser application (?), etc.

Implementations of and applications using OCapN SHOULD decode URIs to
internal datastructures early and encode late.

To avoid shoulder-surfing attacks and etc, GUIs using OCapN URIs SHOULD
encapsulate them *wherever possible* (with interfaces similar to "right
click to show URI" or something), though to some degree we know this
will not be done. (Admonishment for violating this principle is
encouraged.)


MachineLocators
===============

An OCapN "machine" (which could just be a solo vat):
ocapn:<transport>:<location>[?<hint-key1>=<hint-val1>&<hint-key2>=<hint-val2>...]
eg:
ocapn:onion:wy46gxdweyqn5m7ntzwlxinhdia2jjanlsh37gxklwhfec7yxqr4k3qd
ocapn:captpigeon:abpoiyaspodyoiapsdyiopbasyop?geox=23.0&geoy=42.8

Datastructure-wise, this decodes into:
<machine-locator $transport $location {$hint-key1: $hint-key2, ...}>

The meaning of $location is $transport specific. This will align with
the "Macine Communication Transport Layer" interface specifications, etc
I'm working on writing up.

Equality checks on machine-locators strip off hints. Hints are only
applicable to a particular transport. One might include a key-value
pair that is a signature, using some location-specific key information,
that signs that this location believes this to be a valid set of hint
information. Aside from hints, query parameters are otherwise unused in
OCapN URIs; make new objects if you want to curry arguments instead.


Sturdyrefs
==========

An OCapN sturdyref (yes, we can debate if we want these later, since
we also have CertBears):
ocapn:<transport>.<location>/sref/<swiss-num>[?hints...]
eg:
ocapn:onion:wy46gxdweyqn5m7ntzwlxinhdia2jjanlsh37gxklwhfec7yxqr4k3qd/sref/b303690b55c74964acd0b2c44435bd939a59992def834ee499d015a5

Datastructure-wise this decodes into:
<sturdyref <machine-locator $transport $location
{$hint-key1: $hint-key2, ...}>
$swiss-num>


Cert(ificate)s
==============

Basically we can encode a certificate right onto a URI like so:
ocapn:<transport>.<location>/cert/<encoded-cert>[?hints...]
eg:
ocapn:onion:wy46gxdweyqn5m7ntzwlxinhdia2jjanlsh37gxklwhfec7yxqr4k3qd/cert/PDEwJ291dGVyLWNlcnQ0J3llYWg0J21vcmU0J2RhdGEzImZvcjMndGhlNCJkYXRhNCdnb2RzezQnZGF0YTQiISEhITQnd2l0aDkiaW1hZ2luYXJ5NydleGFtcGxlMTEiY2VydGlmaWNhdGV9Pg

Datastructure-wise this decodes into:
<cert <machine-locator $transport $location
{$hint-key1: $hint-key2, ...}>
$decoded-cert>



We'll ignore what `decoded-cert` decodes to for now. ;)


CertBears
=========

Just stick the key material as the fragment on the cert:
ocapn:<transport>:<location>/cert/<encoded-cert>#<encoded-key>[?hints...]
eg:
ocapn:onion:wy46gxdweyqn5m7ntzwlxinhdia2jjanlsh37gxklwhfec7yxqr4k3qd/cert/PDEwJ291dGVyLWNlcnQ0J3llYWg0J21vcmU0J2RhdGEzImZvcjMndGhlNCJkYXRhNCdnb2RzezQnZGF0YTQiISEhITQnd2l0aDkiaW1hZ2luYXJ5NydleGFtcGxlMTEiY2VydGlmaWNhdGV9Pg#PDEzJ2tleS10eXBlLWhlcmUzMjqzeUDXDQkQreDGup-U1MNOqXBfOW2bN_7agYzy_7xq4D4

<cert-bear <cert <machine-locator $transport $location
{$hint-key1: $hint-key2, ...}>
$decoded-cert>
$decoded-key>

We'll also ignore what `decoded-key` decodes to for now. ;)


Thoughts?
- Chris

[Christopher Lemmer Webber]

Christopher Lemmer Webber writes:

> These are URI types so they can be copy-pasted around for legacy
> systems, including at the REPL, in a browser application (?), etc.

Oops, I meant a specific kind of REPL, a command-line style shell.

> Implementations of and applications using OCapN SHOULD decode URIs to
> internal datastructures early and encode late.

If that's done, most language style REPLs should already be able to do
the right thing... :)

[John Kemp]

I know I’m stepping into a conversation I haven’t previously been a part of, so I risk not having understood what is going on here, but I do have some history with web architecture. 

As far as I can tell, this is a misuse of a Uniform Resource *Identifier*. That is to say, a URI is an identifier for a resource, not the resource that it identifies. You may be able to (depending on the URI scheme) dereference the URI, certainly (follow the link if it’s a URL). What is the point to the URI here, and what does the ‘ocap’ scheme do?

I remember the Waterken URLs with a (secret?) fragment ID, and those URLs make sense in web architecture, being as they may be dereferenced appropriately. Google Doc sharing being the more common example of a capability model. 

From past experience though, parsing URIs sucks (or at least, is brittle). Is there a specification of the ocap scheme?

- johnk

[Ian Denhardt]

Quoting John Kemp (2021-02-11 12:46:02)

> As far as I can tell, this is a misuse of a Uniform Resource
> *Identifier*. That is to say, a URI is an identifier for a resource,
> not the resource that it identifies. You may be able to (depending on
> the URI scheme) dereference the URI, certainly (follow the link if it's
> a URL). What is the point to the URI here, and what does the `ocap'
> scheme do?

I suspect it would probably be more correct to call these URLs than
URIs. Indeed, URIs that are not also URLs inherently violate the
"central dogma" for capabilities: Don't separate designation from
authority.

> From past experience though, parsing URIs sucks (or at least, is
> brittle). Is there a specification of the ocap scheme?

I wonder, is there a strong reason to come up with custom ad-hoc syntax
for ocap URLs at all? As an alternative, why not just:

ocapn:$(base64(<serialized datatype>))

Where <serialized datatype> is the serialized form of some data type
that is in-line with what you'd pass around on the wire when speaking
captp itself?

-Ian

[Christopher Lemmer Webber]

Ian Denhardt writes:

> Quoting John Kemp (2021-02-11 12:46:02)
>
>> As far as I can tell, this is a misuse of a Uniform Resource
>> *Identifier*. That is to say, a URI is an identifier for a resource,
>> not the resource that it identifies. You may be able to (depending on
>> the URI scheme) dereference the URI, certainly (follow the link if it's
>> a URL). What is the point to the URI here, and what does the `ocap'
>> scheme do?
>
> I suspect it would probably be more correct to call these URLs than
> URIs. Indeed, URIs that are not also URLs inherently violate the
> "central dogma" for capabilities: Don't separate designation from
> authority.

At least one of the types shown, the certificate, is more URI than
URL... it really is data for an assembled certificate, but not the way
to invoke it (since it does not have the attached key, except for in the
composed CertBear abstraction).

>> From past experience though, parsing URIs sucks (or at least, is
>> brittle). Is there a specification of the ocap scheme?
>
> I wonder, is there a strong reason to come up with custom ad-hoc syntax
> for ocap URLs at all?

As I wrote:

These are URI types so they can be copy-pasted around for legacy
systems, including at the REPL, in a browser application (?), etc.

Implementations of and applications using OCapN SHOULD decode URIs to
internal datastructures early and encode late.

Inside of captp, there's no need even to have a stringy URI. More
efficient representations that map to the same abstract record structure
I indicated are possible.

I have a few applications in progress where I am demonstrating starting
up a session by a user suppling some kind of capability they presumably
got over an out-of-band environment. For example, a chat program.

> As an alternative, why not just:
>
> ocapn:$(base64(<serialized datatype>))
>
> Where <serialized datatype> is the serialized form of some data type
> that is in-line with what you'd pass around on the wire when speaking
> captp itself?

Note that there are four different types of URIs here. I wanted them to
be visually distinct. In fact, in my first iteration they looked *very*
visually distinct, where after the ocapn: there would be a marker like:

;; Ocapn machine type URI:
;;
;; ocapn:m.<transport>.<transport-location>[.<transport-hints>]

;; Ocapn swissnum URI:
;;
;; ocapn:s.<transport>.<transport-location>/<swiss-num>

;; Ocapn certificate URI:
;;
;; ocapn:c.<transport>.<transport-location>/<cert>

;; Ocapn bearer certificate union URI:
;;
;; ocapn:b.<transport>.<transport-location>/<cert>/<key-type>.<private-key>

The awkward thing about this is that from a URI perspective, the
"location" would change every time, and this wasn't really accurate.
So instead I decided to use the path part of the URI structure to
distinguish between the last three.

Another option could be to put these all in the URI scheme:

ocapn-m:...
ocapn-s:...
ocapn-c:...
ocapn-b:...

but this seemed strange also. Maybe it's more correct to the proposed
nature of URI schemes though, dunno.

- Chris

[John Kemp]

On Feb 11, 2021, at 2:41 PM, Ian Denhardt <i...@zenhack.net> wrote:

I suspect it would probably be more correct to call these URLs than
URIs. Indeed, URIs that are not also URLs inherently violate the
"central dogma" for capabilities: Don't separate designation from
authority.

One could potentially dereference a URI too, depending on its scheme. URLs can be dereferenced because they are linked to the http(s) scheme. The capability to deference is (potentially) given along with the reference. Again, depending on the scheme. Of course, a reference could lead nowhere (404), be unauthorized (401) or forbidden (403)… 

What powers does the ocapn scheme give us?

- johnk

[Bill Frantz]

When we dereference the <mailto:f...@example.com> scheme, we
access a mail agent which is configured into the platform doing
the dereference. It's not linked to the HTTP scheme, but is
equally useful. Also note that the HTTP scheme frequently
dereferences to the same server (set) regardless of the platform
doing the dereference. MAILTO almost never does.

Cheers - Bill

-----------------------------------------------------------------------
Bill Frantz | Privacy is dead, get over | Periwinkle
(408)348-7900 | it. | 150 Rivermead
Rd #235
www.pwpconsult.com | - Scott McNealy (1999) | Peterborough,
NH 03458