Docs explaining some of the Notary design decisions

notaryproject / notary

Notary is a project that allows anyone to have trust over arbitrary collections of data

Apache License 2.0

3.23k stars 511 forks source link

Docs explaining some of the Notary design decisions #828

Open endophage opened 8 years ago

endophage commented 8 years ago

Topics that needs docs:

[ ] The use of x.509 and the trust pinning mechanism
[ ] Trust bootstrapping in general
[ ] The use of registry auth
[ ] The client/server/signer architecture
[ ] The changeset format and general approach to staging
[ ] Storing old public keys in the root metadata after rotation
[ ] RethinkDB support

cc @ecordell

HuKeping commented 8 years ago

Great to see this! I'd like to pick up the The use of registry auth if it was not in a hurry. It is one of the use case from production I've been asked for.

achandak123 commented 8 years ago

Also, more details on what does various metadata signing keys mean? Like snapshot, target n all? Also, to push into a trusted collection, AFAIK, you need to have the root keys (in ~/.docker/trust). How do we share the root keys across users?

cyli commented 8 years ago

@achandak123 The various signing keys are explained by the TUF spec that Notary implements - this doc is more about design decisions beyond the TUF spec, but yes we agree we should definitely list what is covered by the spec and what isn't.

Also, yes we need to document our recommendations regarding key management for different use cases.

cyli commented 8 years ago

@HuKeping That would be awesome, thank you!

innocentme1 commented 8 years ago

@endophage I also think we need to some documentations on using Notary CLI. I dont there are any. I understand that this is thread is more for Notary "design" decisions but I feel we also need to add Notary CLI docs (Do we have one? Am I missing? )

riyazdf commented 8 years ago

@innocentme1 https://github.com/docker/notary#getting-started-with-the-notary-cli, https://github.com/docker/notary/blob/master/docs/getting_started.md, and https://github.com/docker/notary/blob/master/docs/advanced_usage.md come to mind - is there a particular topic that you think we should add more documentation around for the CLI?

innocentme1 commented 8 years ago

@riyazdf I somehow missed one of these links. I think they are pretty nice. Thanks for sharing!

Also, I feel maybe we can add a good example to rotating keys too? just as you guys did for others. Maybe take a example collection and show command by command to users for rotating keys? Rotating keys is really important and I feel it would be nice to see that but if you feel its not necessary - then okay :)

riyazdf commented 8 years ago

@innocentme1 we have a key management subsection in the Advanced Usage docs that covers key rotation (also on the docs website).

I totally agree with you that rotating keys is an important piece of documentation, so if you have a particular example in mind that you think we could include beyond that explanation we would be very open to including it.