Got a couple of corrections/notes/suggestions (apologies for this possibly being longer than the actual blog post):
== HEADER Suggestion: Might be helpful to open with an explanation of the scope. That this document is intended to help users manually generate certificates when their organization doesn't already provide a (presumably more convenient) mechanism to do so. "Accumulo opted to not bundle any tools to automatically generate certificates for deployment." Note/Suggestion: Technically, I argued that we not bundle a custom tool to generate "secure" certificates. It was (and still is) an option to bundle an a contrib script to call an existing standard tool that already has all the features one needs. To improve this line, I'd suggest changing it from "Accumulo opted to not..." to "Accumulo expects the user to provide secure certificates, which can be generated by standard tools, like openssl, keytool, easy-rsa, and others." This wording encapsulates the decision with an explanation, and has the added benefit of conveying the user's responsibilities, which is the focus of the blog (helps establish the thesis of the blog). == Section: Generate a Certificate Authority "Only certificates which are signed by the same authority can create a secure connection." Correction: This line is incorrect (or at best, vague). Any certificate signed by an authority in the CA keystore can create a secure connection. This is true on both ends: any certificate the certificate the client uses must be signed by a CA trusted by the server, and any certificate the server uses must be signed by a CA trusted by the client (the client and server configure their keystores independently). Adding this explanation, and mapping it to the "truststore" (certificate store containing trusted CA public keys) and "keystore" (certificate store containing private key) configuration elements would greatly benefit the reader. If you explain that, then you could clarify that it is simpler to use the same CA to sign each certificate for each host, so the client only has to trust a single CA (which is what I think you were trying to say to begin with). Suggestion: For the code block, you should have comments for each line to explain what they do, eg. "generate private key for the CA", "generate a corresponding public key and create a self-signed certificate", "convert the public key to a binary format that keytool understands", etc. Suggestion: Add -des3 to the genrsa line, to encourage the good practice of encrypting private keys with a passphrase. (do this in the next section, also, but make sure to note that they should not have the same passphrase as the CA, because the CA should be treated with extra special care, since it has the authority to issue trusted certificates for everybody else) Suggestion: Drop -nodes in the "openssl req" command, because you're not outputting a private key and it's confusing. Besides, you almost never want that, even on commands that do output private keys, if you're concerned about protecting those keys. Note: If you don't need the base64 encoded ASCII version (PEM), you can use "-outform der" on the req command to output directly to the binary format, because it's simpler, but it's probably best to keep it in, because you do need the pem format in the next section (because, stupidly, the pkcs12 command doesn't understand der), so might as well be consistent and leave it in two steps. Suggestion: use the same alias in the JKS as the CN from the certificate. It'll help users distinguish between keystores, independent of file names (applies to the next section, also) == Section: Generate a certificate/keystore per host "By issuing individual certificates to each entity, it gives proper control to revoke/reissue certificates to clients as necessary, without widespread interruption." Note: This is true, and certainly the reason you want separate certificates, but you should mention that there is currently no feature in Accumulo to check a revocation list (we certainly don't expose a configuration item for it, I don't know of any built-in JSSE system property for it, and I Thrift has any mechanism built-in either... but it should, and we should expose it when it does). Suggestion: Be consistent with the filename extension. No need to do .crt here when you used .pem/.der earlier. Just stick to one or the other. Certificate formats are confusing enough. == Section: Configure Accumulo Servers Suggestion: You should mention chmod and file permissions to ensure only the services that need access to the files can read/alter them. This applies to the CA key also. == Section: Configure Accumulo Clients Suggestion: s/simple properties file/simple Java properties file (with link to file format description)/; "Java properties file" is very specific, vs. "properties file", which could describe anything. == FOOTER Suggestion: For added benefit, I'd suggest adding to the blog additional links to Wikipedia, and other explanations you can find about public-key basics, certificate chains, certificate formats, and man pages for referenced tools, and deferring to those wherever possible, to make the blog more succinct and easier to consume. -- Christopher L Tubbs II http://gravatar.com/ctubbsii On Thu, Aug 14, 2014 at 12:27 AM, Josh Elser <[email protected]> wrote: > Hi all, > > I authored a blog post after digging into how to use openssl and keytool > (after some help from Billie and Michael Berman) to generate the proper > certificates stored in Java KeyStores, for Accumulo to configure the Thrift > servers to run over SSL. At a high level, the steps create a certificate > authority, and then use that to generate certs for clients/servers, and > then load them into Java KeyStores for consumption. > > I just finished this up, so I'm not too worried about grammar at this > point, but I am very concerned about advertising something that is > inherently insecure. Any information about where I'm doing something "bad", > and what should be done instead, would be *greatly* appreciated. > > For those with a blogs/roller account, check out[1], and for everyone > else, use [2]. > > Thanks everyone! > > - Josh > > [1] https://blogs.apache.org/roller-ui/authoring/preview/ > accumulo/?previewEntry=generating_keystores_for_configuring_accumulo > [2] http://people.apache.org/~elserj/ssl-blog.html >
