search

pyca / cryptography

cryptography is a package designed to expose cryptographic primitives and recipes to Python developers.
https://cryptography.io
Other
6.66k stars 1.53k forks source link

Improve CSR Generation Docs #2158

Closed reaperhulk closed 7 years ago

reaperhulk commented 9 years ago

The body of @glyph's comment from #2154:

"One thing about the CertificateSigningRequestBuilder is that it seems to put the wrong thing first. OID_COUNTRY_NAME, OID_STATE_OR_PROVINCE_NAME, etc, are never verified and rarely presented to users. Instead, I would make a CSR with just one DNSName first.

I also feel like there ought to be a clearly linked reference document. How do I know what attributes are available to a Name? Is order important or is this actually a set? What other OIDs can I use? Which ones can I leave out? Can I put things other than a NameAttribute into a name? If a CA requires my technical administrator's email address to be in the CSR, where does that go? Why hashes.SHA256(), what other hashes might be good, and why do I need to make a decision about that rather than getting a default? (Actually, serialization.BestAvailableEncryption might be a good pattern to follow for hashes, too.) Et cetera, et cetera, et cetera.

The structure of a CSR (as the structure of a certificate itself) is deeply complicated and weird, and I think that this tutorial needs to have a good exploration of building up from something minimal to something more complex, and it should do this in a way that explains how to look up more information about each step. One of the big problems with "do SSL on your server" tutorials is that they copy-paste around huge numbers of unnecessary fields, and people think they are ritualistically necessary. My favorite side-effect of this is that following only recommended instructions from trusted CAs, I have more than once operated a server with a signed certificate belonging to "Internet Widgets Pty. Ltd."

Personally, I like starting with a StartSSL-style CA, so you can show a CSR that basically has nothing in it but a key, and then build up more identifying information from there, one element at a time, so that people will end up with something that suits their needs, and not a template that has every SSL-secured site in the world claiming to be from "My Company" in San Francisco CA."

reaperhulk commented 8 years ago

@glyph interested in putting in a doc PR for this? :)

glyph commented 8 years ago

@reaperhulk Yes, although it is unlikely I'm going to get to it very soon :). (Thanks for writing this up.)

ralienpp commented 8 years ago

@reaperhulk, I could write a guide that covers these questions concerning the CSR, though I'd like to clarify a few things.

It would be great if you could list various questions that you expect the guide to answer, I will then write a draft version that attempts to cover that.

ralienpp commented 8 years ago

Ping @reaperhulk , I don't want to be a nuisance, but if I get some feedback today - I can prepare the first draft this week (-:

I hesitate to get started and send a PR without first making sure we're on the same page.

reaperhulk commented 8 years ago

I am probably not the right person to answer this question as my view on how this all works is colored by knowing too much. @glyph since this is your proposal do you have some brief guidance? (For now cryptography is PKCS10 only btw, and diagrams are fine as long as they render well on mobile viewports)

glyph commented 8 years ago

I keep coming back to this ticket to answer @reaperhulk's question, and then getting stalled when I look at the list of questions since I'm not really sure.

does the library support SPKAC and CRMF, besides PKCS#10 requests?

I don't know what SPKAC or CRMF are, so, I can't say I care.

who is the expected reader? From the initial message I get the impression that we're doing this for a web-site administrator who wants to get HTTPS (hence the emphasis is on DNSName); but the reader may just as well be someone who runs a CA that issues certificates to citizens of a country - so for them, all of the OIDs related to identifying a human actually matter.

I imagine that site admins who want HTTPS will probably just use LE these days. So, the people implementing LE are one audience, but the main audience, by number of direct users of the API rather than indirect users of tools which rely on it, I would anticipate to be people trying to implement automatic mutual TLS schemes internal to some custom overlay network or rotation protocol.

how do we ensure that this guide doesn't become a kitchen sink of cryptographic knowledge? For example, I could address the question why SHA256?, but isn't it better to have that information on the page about hashing instead? There are some things that matter when this is intended for use in a browser (e.g. some might not "understand" a certificate that uses certain algorithms) - but this would make the doc HTTPS-centric.

Just recommend current best practices. Better yet, have a recipe that addresses those best practices and will update in future versions of cryptography. One way to capture the tension between recentness and security would be to provide constants for known idiosyncrasies of various versions of software, so you can say "give me a CSR that will be compatible with firefox, chrome, IE back to version 9, Safari back to Yosemite" or something like that, in a human-readable way.

so far I haven't seen any drawings in the documentation, would it be OK to augment the text with some sequence diagrams? (I prefer them to be in ASCII, see http://plantuml.com/ascii_art.html)

No opinion here.

reaperhulk commented 7 years ago

We've had this issue open for 2 years with little traction. I'm going to close. Obviously anyone is welcome to open a PR improving our documentation at any time!