doc: clarify json-sign spec: camliSigner must be in 'O'

Thanks to Brett for pointing this out.

Change-Id: Icfcecbb83985ae4292d755af2a4cc830f05973b2

doc/json-signing/example/public-key.txt

@@ -0,0 +1,30 @@
+-----BEGIN PGP PUBLIC KEY BLOCK-----
+Version: GnuPG v1.4.11 (GNU/Linux)
+
+mQENBEzgoVsBCAC/56aEJ9BNIGV9FVP+WzenTAkg12k86YqlwJVAB/VwdMlyXxvi
+bCT1RVRfnYxscs14LLfcMWF3zMucw16mLlJCBSLvbZ0jn4h+/8vK5WuAdjw2YzLs
+WtBcjWn3lV6tb4RJz5gtD/o1w8VWxwAnAVIWZntKAWmkcChCRgdUeWso76+plxE5
+aRYBJqdT1mctGqNEISd/WYPMgwnWXQsVi3x4z1dYu2tD9uO1dkAff12z1kyZQIBQ
+rexKYRRRh9IKAayD4kgS0wdlULjBU98aeEaMz1ckuB46DX3lAYqmmTEL/Rl9cOI0
+Enpn/oOOfYFa5h0AFndZd1blMvruXfdAobjVABEBAAG0JUNhbWxpIFRlc3RlciA8
+Y2FtbGktdGVzdEBleGFtcGxlLmNvbT6JATgEEwECACIFAkzgoVsCGwMGCwkIBwMC
+BhUIAgkKCwQWAgMBAh4BAheAAAoJECkxpnwm9avaHE0IAJ/pMZgiURl3kefrFMAV
+7ei0XDfTekZOwDRcZWTVQ/A97phpzO8t78qLYbFeHuq3myNhrlVO9Gyp+2V904rN
+dudoHLhpegf5TNeHGmAGHBxcooMPMp0JyIDnUBxtCNGxgWfbKpEDRsQAjkCc7sR0
+H+OegzlEf6JZGzEhV5ohOioTsC1DmJNoQsRz5Kes7sLoAzpQCbCv4yv+1o+mnzgW
+9qPJXKxcScc0t2YTvcvpJ7LV8no1OP6vpYqB1A9Pzze6XFBlcXOUKbRKk0fEIV/u
+pU3ph1fF7wlyRgA4A3iPwDC4BgVmHYkz9nYPn+7IcT/dDig5SWU+n7WZgGeyv75y
+0Ue5AQ0ETOChWwEIALuHxKI+oSH+eeMSXhxcSUXnhp4cUeyvOV7oNPYcmsDclF0Y
+7y8NrSPiEZod9vSTEDMq7hd3BG+feCBqjgR4qtmoXguJhWcnJqDBk5iAMuuAph9O
+CC8QLACMJPhoxQ0UtDPKlpG4X8kLK1woHd716ulPl2KLjTgd6K4kCGj+CV5Ekn6u
+IJj+3IPbYDOwk1l06ksimwQAY4dA1CXOTviH1bVqR6CzuzVPg4hcryWDva1rEO5c
+LcOR8Wk/thANFLSNjqX8UgtGXhFZRWxKetFDQiX5f2BKoqTVYvD3pqt+zzyLNFAz
+xhMc3cyFfqM8yQdzdEey/DIWtMoDqZCSVMJ63N8AEQEAAYkBHwQYAQIACQUCTOCh
+WwIbDAAKCRApMaZ8JvWr2mHACACkco+fAfRK+gmprF2m8E0Bp1frwFH0g4RJVHXQ
+BUDbg7OZbWumzD4Br28si6XDVMP6fLOeyD0EHYb6LhAHDkBLqx6e3kKG1mQ8fMIV
+O4YMQfskYH2FJqlCtgMnM8N3oslPBTpZedNPSUq7HJh2pKr9GIDi1V+Hgc/qEigE
+dj9f2zSSaKZdC4eL73GvlQOh+4XqgaMnMiKfI+/2WlRaJs1KOgKmIp5yHt0qY0ef
+y+40BY/z9pMjyUvr/Wwp8KXArw0NAwzp8NUl5fNxRg9XWQWLn6hW8ydR20X3t2ym
+iNSWzNQiTT6k7fumOABCoSZsow/AJxQSxqKOJBjgpKjIKCgY
+=ru0J
+-----END PGP PUBLIC KEY BLOCK-----

doc/json-signing/example/signed.camli

@@ -1,5 +0,0 @@
-{
-  "camliType": "rating",
-  "stars": "4/5",
-  "camliAuthor": "......."
-}

doc/json-signing/example/signing-after.camli

@@ -1,5 +1,4 @@
-{
-  "camliType": "rating",
-  "stars": "4/5",
-  "camliAuthor": "......."
-,"camliSig":"iQEcBAABAgAGBQJMGYTsAAoJEFBHsvhU+KkU/BQIAJ6yVfyEmqyrzBgvChcRmCjcfJbip1cQzuEI7RVRiuzbOprY6yVtRfTTSWdakHrX7xKIWGxLbfH3wicLnoFitaDoJu4D+5NfmpK9XhzwLH+5eQd39WickeVr3TYu+wBPFzN4ItLqGF87piqVizTWMaB+1gUdFQMBshDDxPoFmeAmtoE0dYBJqnRsfdQw/UGK/DMRZq17uQ7GwS3/Mne6Q4nUQrgawPM8VfAMO/QYasrs7/5hBOJKupVI/cuiS+B4aKc1mlVeGVo/ucEAzhRk9F1fO9lqrYRUELKg3zQRnpluNZymI9nUPTiXLpCtL9dC3/IKvbNP9Q15/9SLieygSyQ==NiGO"}
+{"camliVersion": 1,
+  "camliSigner": "sha1-8616ebc5143efe038528c2ab8fa6582353805a7a",
+  "foo": "bar"
+,"camliSig":"iQEcBAABAgAGBQJO3/DNAAoJECkxpnwm9avaf6EH/3HVJC+6ybOJDTJIInQBum9YFzC1I8b6xNLN0yFdDtypZUotvW9pvU2pVpbfNSmcW/OL02eR2kgL55dHxbUjbN9CvXlvSb2QAy8IQMdA3721pMR41rNNn08w5bbAWgW/suiyN5z0pIKn3vPEHbguGeNQBStgOSq1WkgCozNBxPA7V5mcUx2rUOsWHYSmEY8foPdeDYcrw2pvxPN8kXk6zBrZilrtaY+Yx5zPLkq8trhHPgCdf4chL+Y2kmxXMKYjU+bkmJaNycUURdncZakTEv9YfbBp04kbHIaN6DttEoXuU96nTyuCFhIftmV+GPbvGpl3e2yhmae5hUUt1g0o8FE==aSCK"}

doc/json-signing/example/signing-before-J.camli

@@ -1,6 +1,4 @@
-{
-  "camliType": "rating",
-  "stars": "4/5",
-  "camliAuthor": "......."
+{"camliVersion": 1,
+  "camliSigner": "sha1-8616ebc5143efe038528c2ab8fa6582353805a7a",
+  "foo": "bar"
 }
-

doc/json-signing/example/signing-before.camli

@@ -1,4 +1,3 @@
-{
-  "camliType": "rating",
-  "stars": "4/5",
-  "camliAuthor": "......."
+{"camliVersion": 1,
+  "camliSigner": "sha1-8616ebc5143efe038528c2ab8fa6582353805a7a",
+  "foo": "bar"

doc/json-signing/example/signing-before.camli.detachsig

@@ -1,11 +1,11 @@
 -----BEGIN PGP SIGNATURE-----
-Version: GnuPG v1.4.10 (GNU/Linux)
+Version: GnuPG v1.4.11 (GNU/Linux)
 
-iQEcBAABAgAGBQJMGYTsAAoJEFBHsvhU+KkU/BQIAJ6yVfyEmqyrzBgvChcRmCjc
-fJbip1cQzuEI7RVRiuzbOprY6yVtRfTTSWdakHrX7xKIWGxLbfH3wicLnoFitaDo
-Ju4D+5NfmpK9XhzwLH+5eQd39WickeVr3TYu+wBPFzN4ItLqGF87piqVizTWMaB+
-1gUdFQMBshDDxPoFmeAmtoE0dYBJqnRsfdQw/UGK/DMRZq17uQ7GwS3/Mne6Q4nU
-QrgawPM8VfAMO/QYasrs7/5hBOJKupVI/cuiS+B4aKc1mlVeGVo/ucEAzhRk9F1f
-O9lqrYRUELKg3zQRnpluNZymI9nUPTiXLpCtL9dC3/IKvbNP9Q15/9SLieygSyQ=
-=NiGO
+iQEcBAABAgAGBQJO3/DNAAoJECkxpnwm9avaf6EH/3HVJC+6ybOJDTJIInQBum9Y
+FzC1I8b6xNLN0yFdDtypZUotvW9pvU2pVpbfNSmcW/OL02eR2kgL55dHxbUjbN9C
+vXlvSb2QAy8IQMdA3721pMR41rNNn08w5bbAWgW/suiyN5z0pIKn3vPEHbguGeNQ
+BStgOSq1WkgCozNBxPA7V5mcUx2rUOsWHYSmEY8foPdeDYcrw2pvxPN8kXk6zBrZ
+ilrtaY+Yx5zPLkq8trhHPgCdf4chL+Y2kmxXMKYjU+bkmJaNycUURdncZakTEv9Y
+fbBp04kbHIaN6DttEoXuU96nTyuCFhIftmV+GPbvGpl3e2yhmae5hUUt1g0o8FE=
+=aSCK
 -----END PGP SIGNATURE-----

doc/json-signing/example/signing-before.camli.sig

@@ -1,14 +0,0 @@
------BEGIN PGP MESSAGE-----
-Version: GnuPG v1.4.10 (GNU/Linux)
-
-owGbwMvMwMQY4L7pR8iPlSKMa1KSRIoz0/My89J1k1LT8otS9ZITc3MyfSRbmKq5
-FBSUwLyQyoJUJSsFpaLEEqBCJR2QRHFJYlExSNBE3xQiAlbqWFqSkV8EEteDACWu
-Wq5ORhkWBkYmBjZWJpDBDFycAjAXbO9l/ytgejba1Db0vdrRqftjnjtpGdm+SdKe
-WXrJflqUbtX1xfrmm7cpWxRE71tVkc7/ZeUPyWxOAQlm/dqaugmflRPFko8nXNz6
-68cbtW/Mz5PDz6Q3ZcldfSkjrq0+STvjhdgUg9pvWRm6efXPHxb/9ctm7fzVV69z
-yHw97wOlvUb3P93fan6+6sMGgxnzlglY2ks98kn/+/drS5bN1JolYd7tJbPWzdIN
-6VBW3p7dceD/gzuHFB6nb8lZ+Wwe51QOuwtqKbOWzWXr0si8tf4KH2vC0nscrUc6
-5N4zd6lenLtRN/1j0yEW5/uVljePzhJ0bJ+8Z5rKi6cmRmukYrnXnY+sP8D+6dNc
-tf03t+w+OxsA
-=/Cp6
------END PGP MESSAGE-----

doc/json-signing/json-signing.txt

@@ -69,11 +69,29 @@ SIGNING
 =======
 
 -- start with a JSON object (not an array) to be encoded and signed.
-   we'll call this data structure 'O'.
+   we'll call this data structure 'O'. While this signing technique
+   could be used for applications Camlistore, this document is specifically
+   about Camlistore, which requires that the JSON object 'O' contain
+   the following two key/value pairs:
+     "camliVersion": "1"
+     "camliSigner": "hashalg-xxxxxxxxxxx"  (blobref of ASCII-armored public key)
 
--- serialize it with whatever JSON serialization library you have
-   available.  internal or trailing whitespace doesn't matter.  we'll
-   call the JSON serialization of 'O' (defined in earlier step) 'J'
+-- To find your camliSigner value, you could use GPG like:
+
+   $ gpg --no-default-keyring --keyring=example/test-keyring.gpg --secret-keyring=example/test-secring.gpg \
+         --export --armor 26F5ABDA > example/public-key.txt
+
+   $ sha1sum example/public-key.txt
+   8616ebc5143efe038528c2ab8fa6582353805a7a
+
+   ... so the blobref value for camliSigner is "sha1-8616ebc5143efe038528c2ab8fa6582353805a7a".
+   Clients will use this value in the future to find the public key to verify
+   signtures.
+
+-- serialize in-memory JSON object 'O' with whatever JSON
+   serialization library you have available.  internal or trailing
+   whitespace doesn't matter.  we'll call the JSON serialization of
+   'O' (defined in earlier step) 'J'
    (e.g. doc/example/signing-before-J.camli)
 
 -- now remove any trailing whitespace and exactly and only one '}'