perkeep/website/content/docs/sharing

<h1>Sharing</h1>

<p><b>TODO:</b> finish documenting this. In particular, add example with camget -shared.</p>

<p>The basic summary is that you create
a <a href="/docs/terms#claim">claim</a> that a user has access to
something, and then your blobserver's public frontend authenticates
(if applicable) a remote user and gives them access as permitted by
your claim.</p>

<p>Reproducing an email from <a
href="http://groups.google.com/group/camlistore/browse_thread/thread/a4920d6a1c5fc3ce">this
thread</a> for some background:</p>

<center>*</center>

<div style='font-style: italic'>

<p>This is an example walk-though of (working) sharing on Camlistore.   Brett and I got this working last night (the basic "have a link" use case with no addition auth)</p>

<p>Let's say I have a private blobserver:</p>

<a href="http://camlistore.org:3179/">http://camlistore.org:3179/</a>

<p>And I have a file, "Hi.txt".</p>

<p>Its bytes are blob <code>sha1-3dc1d1cfe92fce5f09d194ba73a0b023102c9b25</code><br />
Its metadata (inode, filename, etc) is blob <code>sha1-0e5e60f367cc8156ae48198c496b2b2ebdf5313d</code></p>

<p>You don't have access to those, even though you know their names.  Verify the 401 errors:</p>

<p><a href="http://camlistore.org:3179/camli/sha1-3dc1d1cfe92fce5f09d194ba73a0b023102c9b25">http://camlistore.org:3179/camli/sha1-3dc1d1cfe92fce5f09d194ba73a0b023102c9b25</a><br />
<a href="http://camlistore.org:3179/camli/sha1-0e5e60f367cc8156ae48198c496b2b2ebdf5313d">http://camlistore.org:3179/camli/sha1-0e5e60f367cc8156ae48198c496b2b2ebdf5313d</a></p>

<p>(hm, those are returning Unauthorized errors, but no Content Body... will fix later)</p>

<p>Note also that any errors you get from my private blob server always delay for at least 200 ms to mask timing attacks that could otherwise reveal the existence or non-existence of a blob on my private server.</p>

<p>Note that in order to have all of the following working, your server needs to have a share handler, so you need to have the line</br>
<b><code>"shareHandler"</code></b>: true,</br>
in your server <a href="/docs/server-config">config</a>.</p>

<p>Now I want to share Hi.txt with you, so I create a share blob (e.g <code><a href="/cmd/camput">camput</a> share --transitive sha1-0e5e60f367cc8156ae48198c496b2b2ebdf5313d</code>).</p>

<p>I've created this, and its name is <code>sha1-102758fb54521cb6540d256098e7c0f1625b33e3</code></p>

<p>Note that you can fetch it without authentication, because you're using the url prefix <code>/share/</code>, which delegates the task to the share handler, and because the share handler checks that it's a share blob that doesn't require auth (<code>authType</code> == "haveref" ... like "Share with others that have the link")</p>

<p>Here's you getting the blob:</p>

<pre class='sty' style='overflow: auto'>$ curl <a href="http://camlistore.org:3179/share/sha1-102758fb54521cb6540d256098e7c0f1625b33e3">http://camlistore.org:3179/share/sha1-102758fb54521cb6540d256098e7c0f1625b33e3</a>
{"camliVersion": 1,
  "authType": "haveref",
  "camliSigner": "sha1-3bee195d0dada92a9d88e67f731124238e65a916",
  "camliType": "claim",
  "claimDate": "2013-06-24T14:17:02.791613849Z",
  "claimType": "share",
  "target": "sha1-0e5e60f367cc8156ae48198c496b2b2ebdf5313d",
  "transitive": true
,"camliSig":"wsBcBAABCAAQBQJRyFTeCRApy/NNAr6GZgAAKmgIAGbCCn1YPoZuqz+mcMaLN09J3rJYZPnjICp9at9UL7fFJ6izzDFLi6gq9ae/Kou51VRnuLYvRXGvqgZ9HCTTJiGaET8I6c3gBvQWMC/NOS/B9Y+CcZ5qEsz84Dk2D6zMIC9adQjN4yjtcsVtKYDVDQ5SCkCE6sOaUebGBS22TOhZMXPalIyzf2EPSiXdeEKtsMwg+sbd4EmpQHeE3XqzI8gbcsUX6VdCp6zU81Y71pNuYdmEVBPY5gVch2Xe1gJQICOatiAi4W/1nrTLB73sKEeulzRMbIDB4rgWooKKmnBPI1ZOTyg/fkKmfWfuJKSU0ySiPwVHn4aPFwCGrBRladE==KjfB"}</pre>

<p>Note the "target" and "transitive".</p>

<p>Now we present this proof of access in subsequent requests in the "via" parameter, with the in-order path of access.</p>

<p>Here's the first hop to the metadata, in which we discover the blobRef of the bytes of the file (in this case, just one part is the whole file bytes...)  I already told you this earlier in the email, but assume you're just discovering this now.</p>

<pre class='sty' style='overflow: auto'>$ curl <a href="http://camlistore.org:3179/share/sha1-0e5e60f367cc8156ae48198c496b2b2ebdf5313d?via=sha1-102758fb54521cb6540d256098e7c0f1625b33e3">http://camlistore.org:3179/share/sha1-0e5e60f367cc8156ae48198c496b2b2ebdf5313d<b>?via=</b>sha1-102758fb54521cb6540d256098e7c0f1625b33e3</a>
{"camliVersion": 1,
  "camliType": "file",
  "contentParts": [
    {
      "blobRef": "sha1-3dc1d1cfe92fce5f09d194ba73a0b023102c9b25",
      "size": 14
    }
  ],
  "fileName": "Hi.txt",
  "size": 14,
  "unixGroup": "camli",
  "unixGroupId": 1000,
  "unixMtime": "2011-01-26T21:11:22.152868825Z",
  "unixOwner": "camli",
  "unixOwnerId": 1000,
  "unixPermission": "0644"
}</pre>

<p>Now let's get the final bytes of the file:</p>

<pre class='sty' style='overflow: auto'>$ curl <a href="http://camlistore.org:3179/share/sha1-3dc1d1cfe92fce5f09d194ba73a0b023102c9b25?via=sha1-102758fb54521cb6540d256098e7c0f1625b33e3,sha1-0e5e60f367cc8156ae48198c496b2b2ebdf5313d">http://camlistore.org:3179/share/sha1-3dc1d1cfe92fce5f09d194ba73a0b023102c9b25<b>?via=</b>sha1-102758fb54521cb6540d256098e7c0f1625b33e3,sha1-0e5e60f367cc8156ae48198c496b2b2ebdf5313d</a>
Hello, Camli!</pre>

<p>That's it.</p>

<p>Now imagine different <code>authType</code> parameters (passwords, SSL
certs, SSH, openid, oauth, facebook, membership in a group,
whatever... )</p>

</div>