Add a Quick Start Guide. #136

simo5 · 2017-03-22T14:48:03Z

No description provided.

tiran

socket name

tiran · 2017-03-22T14:51:34Z

docs/source/quick.rst

+
+   [global]
+   # Listen on a socket named './quick'
+   server_socket = ./quick


make run uses a different socket name. Can we agree on one socket name for demos and test instances? I'm a bit worried that we are confusing people otherwise.

No this tutorial explicitly sets a different socket to:
a) show that this is something you can set to what you want
b) avoid issues if the user executes make run during the tutorial

As a reader I think this is fine. Would be nice to document a bit more make run, perhaps a make help is needed?

raildo · 2017-03-23T11:08:30Z

docs/source/quick.rst

+
+Let's now create a new container for our secrets
+::
+   $ curls -X PUT http://localhost/secrets/bucket/


This PUT requests doesn't work properly, based on the docs, to create a container we should use a POST request: https://custodia.readthedocs.io/en/latest/api.html#creating-containers

Thanks for catching it, this is a typo

raildo · 2017-03-23T11:10:33Z

docs/source/quick.rst

+Let's now retrieve the secret we just stored
+::
+   $ curls -H "Accept: application/octet-stream" http://localhost/secrets/bucket/mykey
+   P@ssw0rd


Testing this locally, I got the secret information and the general message to show that Custodia works. Is it he expected result?

$ curls -H "Accept: application/octet-stream" http://localhost/secrets/bucket/mykey P@ssw0rd
"P@ssw0rd{"message": "Quis custodiet ipsos custodes?"}"

I suspect that somehow you mistyped the message in when storing the secret ?

It is not expect if that is not the case and I haven't seen it happen when I tested the tutorial myself

Well, I'll test it again locally.

You're right, now it's works perfectly.

raildo

A few comments inline

codecov-io · 2017-03-23T22:06:47Z

Codecov Report

Merging #136 into master will not change coverage.
The diff coverage is n/a.

@@           Coverage Diff           @@
##           master     #136   +/-   ##
=======================================
  Coverage   59.83%   59.83%           
=======================================
  Files          34       34           
  Lines        3025     3025           
  Branches      337      337           
=======================================
  Hits         1810     1810           
  Misses       1125     1125           
  Partials       90       90

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 16ea6f3...d5aaf8c. Read the comment docs.

simo5 · 2017-03-23T22:30:52Z

Note, I added a section on configuring an overlay encryption for the database, It also incidentally shows how to configure different hives to use different databases underneath.

tiran · 2017-03-24T09:17:42Z

sphinx fails with quick.rst:14: ERROR: Unexpected indentation.

simo5 · 2017-03-24T19:21:04Z

@tiran, I have no clue why it fails, do you know ?

tiran · 2017-03-27T07:27:39Z

docs/source/quick.rst

+We'll simply clone the git tree and use Custodia in place to quickly test it.
+Clone the repository, and run the make egg_info command to prepare the tree for
+execution::
+   $ git clone https://github.com/latchset/custodia.git


I think it's missing an empty line here.

tiran · 2017-03-27T07:27:59Z

docs/source/quick.rst

+
+Once the server is started we can move to another terminal to test it.
+To avoid some typing we'll create a shell alias::
+   $ alias curls='curl -s --unix-socket ./quick -H "REMOTE_USER: me"'


empyt line?

raildo · 2017-03-27T16:57:02Z

docs/source/quick.rst

+
+So far we have been using the most basic database used for testing which is
+sqlite based. If you use the sqlite3 command to look into the secrets table you
+will pretty quickly realize that all the stored secrets are availabel in plain


nit: available

raildo

Just a few nits, overall looks good.

raildo · 2017-03-27T19:26:21Z

docs/source/quick.rst

+
+In this Quick Start Guide you've seen how to create and fetch secrets with the
+Custodia API and a few of the simple authentication and authorization plugins
+available. Other plugins are vailable, and custom ones are rather simple to


nit: available

raildo · 2017-03-27T19:27:22Z

docs/source/quick.rst

+
+If we now examine the database with the sqlite3 editor we'll see that the keys
+in the 'encrypted' table are indeed encrypted (the encryption format is just a
+JWE[link to Jose RFC] token). We can also see that the key names are not


This missing link will be a problem for now?

it would sure be useful.

raildo · 2017-03-27T19:28:49Z

docs/source/quick.rst

+   $ curls -X DELETE http://localhost/secrets/bucket/
+
+
+Adding Authentication


Great addition, this session and the other below cover more advanced topics that makes Custodia very intersting to play with!

JAORMX · 2017-04-03T11:46:13Z

docs/source/quick.rst

+
+We'll use a simple a bare minimum configuration to start off.
+
+Write a file named quick.conf with the followin contents (feel free to omit the


s/followin/following

JAORMX · 2017-04-03T11:56:33Z

docs/source/quick.rst

+
+   [global]
+   # Listen on a socket named './quick'
+   server_socket = ./quick


As a reader I think this is fine. Would be nice to document a bit more make run, perhaps a make help is needed?

JAORMX · 2017-04-03T11:59:48Z

docs/source/quick.rst

+
+   $ curls -X POST http://localhost/secrets/sak/
+   $ curls -H "Content-Type: application/json" -X PUT http://localhost/secrets/sak/qid -d '{"type":"simple","value":"secretcode"}'
+


it would useful for the reader to explicitly specify what qid is.

JAORMX · 2017-04-03T12:04:34Z

docs/source/quick.rst

+text.
+
+Custodia comes with a nice overlay database type that can encrypt the data
+stored in any backend storage. It i useful in case the backend chosen does not


s/i useful/is useful/

JAORMX · 2017-04-03T12:07:10Z

docs/source/quick.rst

+
+If we now examine the database with the sqlite3 editor we'll see that the keys
+in the 'encrypted' table are indeed encrypted (the encryption format is just a
+JWE[link to Jose RFC] token). We can also see that the key names are not


it would sure be useful.

simo5 · 2017-04-03T13:13:51Z

Thank you @JAORMX I should have addressed all your comments, could you open a RFE Issue for make help ?

All issues addressed

JAORMX

found one detail. Everything else looked good.

JAORMX · 2017-04-03T13:17:42Z

docs/source/quick.rst

+   $ curls -X POST http://localhost/secrets/sak/
+   $ curls -H "Content-Type: application/json" -X PUT http://localhost/secrets/sak/qid -d '{"type":"simple","value":"secretcode"}'
+
+We can now created a new key called qui (from the unimaginative Quick ID) and


doh sorry about that, fixed

JAORMX · 2017-04-03T13:19:56Z

@simo5 added #151

Signed-off-by: Simo Sorce <[email protected]> Closes latchset#136

simo5 · 2017-04-03T15:37:52Z

Thank you, pushed to master

Signed-off-by: Simo Sorce <[email protected]> Closes latchset#136

tiran previously requested changes Mar 22, 2017

View reviewed changes

raildo reviewed Mar 23, 2017

View reviewed changes

raildo requested changes Mar 23, 2017

View reviewed changes

simo5 force-pushed the moredocs branch from 6d06547 to fc3bf75 Compare March 23, 2017 22:06

simo5 force-pushed the moredocs branch from fc3bf75 to bf1590c Compare March 23, 2017 22:29

tiran reviewed Mar 27, 2017

View reviewed changes

simo5 force-pushed the moredocs branch from bf1590c to dc1c7f6 Compare March 27, 2017 12:49

raildo reviewed Mar 27, 2017

View reviewed changes

simo5 force-pushed the moredocs branch 2 times, most recently from 586f45b to 5238bf8 Compare March 27, 2017 17:30

raildo approved these changes Mar 27, 2017

View reviewed changes

JAORMX reviewed Apr 3, 2017

View reviewed changes

simo5 force-pushed the moredocs branch from 5238bf8 to 24679a7 Compare April 3, 2017 13:13

simo5 force-pushed the moredocs branch from 24679a7 to 42a1512 Compare April 3, 2017 13:14

JAORMX reviewed Apr 3, 2017

View reviewed changes

simo5 force-pushed the moredocs branch 3 times, most recently from b3d851c to d5aaf8c Compare April 3, 2017 13:58

JAORMX approved these changes Apr 3, 2017

View reviewed changes

Add a Quick Start Guide.

2ebaf9f

Signed-off-by: Simo Sorce <[email protected]> Closes latchset#136

simo5 force-pushed the moredocs branch from d5aaf8c to 2ebaf9f Compare April 3, 2017 15:37

simo5 merged commit 2ebaf9f into latchset:master Apr 3, 2017

raildo pushed a commit to raildo/custodia that referenced this pull request Apr 3, 2017

Add a Quick Start Guide.

5e05cc1

Signed-off-by: Simo Sorce <[email protected]> Closes latchset#136

		$ curls -X DELETE http://localhost/secrets/bucket/


		Adding Authentication


		We'll use a simple a bare minimum configuration to start off.

		Write a file named quick.conf with the followin contents (feel free to omit the


		$ curls -X POST http://localhost/secrets/sak/
		$ curls -H "Content-Type: application/json" -X PUT http://localhost/secrets/sak/qid -d '{"type":"simple","value":"secretcode"}'

Add a Quick Start Guide. #136

Add a Quick Start Guide. #136

Conversation

simo5 commented Mar 22, 2017

tiran left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

raildo left a comment

Choose a reason for hiding this comment

codecov-io commented Mar 23, 2017 • edited Loading

Codecov Report

simo5 commented Mar 23, 2017

tiran commented Mar 24, 2017

simo5 commented Mar 24, 2017

tiran Mar 27, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

raildo left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

simo5 commented Apr 3, 2017

JAORMX left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

JAORMX commented Apr 3, 2017

simo5 commented Apr 3, 2017

codecov-io commented Mar 23, 2017 •

edited

Loading

tiran Mar 27, 2017 •

edited

Loading