Improves certificates HOWTO
authorAlok Menghrajani <alok@squareup.com>
Mon, 1 Dec 2014 03:21:31 +0000 (19:21 -0800)
committerRichard Levitte <levitte@openssl.org>
Mon, 22 Dec 2014 15:26:12 +0000 (16:26 +0100)
* adds links to various related documents.
* fixes a few typos.
* rewords a few sentences.

Reviewed-by: Richard Levitte <levitte@openssl.org>
Reviewed-by: Rich Salz <rsalz@openssl.org>
(cherry picked from commit 67472bd82bed9d5e481b0d75926aab93618902be)

doc/HOWTO/certificates.txt

index a8a34c7..65f8fc8 100644 (file)
@@ -3,22 +3,22 @@
 
 1. Introduction
 
-How you handle certificates depend a great deal on what your role is.
+How you handle certificates depends a great deal on what your role is.
 Your role can be one or several of:
 
-  - User of some client software
-  - User of some server software
+  - User of some client application
+  - User of some server application
   - Certificate authority
 
 This file is for users who wish to get a certificate of their own.
-Certificate authorities should read ca.txt.
+Certificate authorities should read https://www.openssl.org/docs/apps/ca.html.
 
 In all the cases shown below, the standard configuration file, as
 compiled into openssl, will be used.  You may find it in /etc/,
-/usr/local/ssl/ or somewhere else.  The name is openssl.cnf, and
-is better described in another HOWTO <config.txt?>.  If you want to
-use a different configuration file, use the argument '-config {file}'
-with the command shown below.
+/usr/local/ssl/ or somewhere else.  By default the file is named
+openssl.cnf and is described at https://www.openssl.org/docs/apps/config.html.
+You can specify a different configuration file using the
+'-config {file}' argument with the commands shown below.
 
 
 2. Relationship with keys
@@ -29,24 +29,26 @@ somewhere.  With OpenSSL, public keys are easily derived from private
 keys, so before you create a certificate or a certificate request, you
 need to create a private key.
 
-Private keys are generated with 'openssl genrsa' if you want a RSA
-private key, or 'openssl gendsa' if you want a DSA private key.
-Further information on how to create private keys can be found in
-another HOWTO <keys.txt?>.  The rest of this text assumes you have
-a private key in the file privkey.pem.
+Private keys are generated with 'openssl genrsa -out privkey.pem' if
+you want a RSA private key, or if you want a DSA private key:
+'openssl dsaparam -out dsaparam.pem 2048; openssl gendsa -out privkey.pem dsaparam.pem'.
+
+The private keys created by these commands are not passphrase protected;
+it might or might not be the desirable thing.  Further information on how to
+create private keys can be found at https://www.openssl.org/docs/HOWTO/keys.txt.
+The rest of this text assumes you have a private key in the file privkey.pem.
 
 
 3. Creating a certificate request
 
-To create a certificate, you need to start with a certificate
-request (or, as some certificate authorities like to put
-it, "certificate signing request", since that's exactly what they do,
-they sign it and give you the result back, thus making it authentic
-according to their policies).  A certificate request can then be sent
-to a certificate authority to get it signed into a certificate, or if
-you have your own certificate authority, you may sign it yourself, or
-if you need a self-signed certificate (because you just want a test
-certificate or because you are setting up your own CA).
+To create a certificate, you need to start with a certificate request
+(or, as some certificate authorities like to put it, "certificate
+signing request", since that's exactly what they do, they sign it and
+give you the result back, thus making it authentic according to their
+policies).  A certificate request is sent to a certificate authority
+to get it signed into a certificate. You can also sign the certificate
+yourself if you have your own certificate authority or create a
+self-signed certificate (typically for testing purpose).
 
 The certificate request is created like this:
 
@@ -55,12 +57,14 @@ The certificate request is created like this:
 Now, cert.csr can be sent to the certificate authority, if they can
 handle files in PEM format.  If not, use the extra argument '-outform'
 followed by the keyword for the format to use (see another HOWTO
-<formats.txt?>).  In some cases, that isn't sufficient and you will
-have to be more creative.
+<formats.txt?>).  In some cases, -outform does not let you output the
+certificate request in the right format and you will have to use one
+of the various other commands that are exposed by openssl (or get
+creative and use a combination of tools).
 
-When the certificate authority has then done the checks the need to
-do (and probably gotten payment from you), they will hand over your
-new certificate to you.
+The certificate authority performs various checks (according to their
+policies) and usually waits for payment from you. Once that is
+complete, they send you your new certificate.
 
 Section 5 will tell you more on how to handle the certificate you
 received.
@@ -68,11 +72,12 @@ received.
 
 4. Creating a self-signed test certificate
 
-If you don't want to deal with another certificate authority, or just
-want to create a test certificate for yourself.  This is similar to
-creating a certificate request, but creates a certificate instead of
-a certificate request.  This is NOT the recommended way to create a
-CA certificate, see ca.txt.
+You can create a self-signed certificate if you don't want to deal
+with a certificate authority, or if you just want to create a test
+certificate for yourself.  This is similar to creating a certificate
+request, but creates a certificate instead of a certificate request.
+This is NOT the recommended way to create a CA certificate, see
+https://www.openssl.org/docs/apps/ca.html.
 
   openssl req -new -x509 -key privkey.pem -out cacert.pem -days 1095
 
@@ -93,13 +98,13 @@ certificate and your key to various formats, most often also putting
 them together into one file.  The ways to do this is described in
 another HOWTO <formats.txt?>, I will just mention the simplest case.
 In the case of a raw DER thing in PEM format, and assuming that's all
-right for yor applications, simply concatenating the certificate and
+right for your applications, simply concatenating the certificate and
 the key into a new file and using that one should be enough.  With
 some applications, you don't even have to do that.
 
 
-By now, you have your cetificate and your private key and can start
-using the software that depend on it.
+By now, you have your certificate and your private key and can start
+using applications that depend on it.
 
 -- 
 Richard Levitte