strip back openssl ca: in particular remove some excessively wordy sections,

move some other sections into more relevant places, and remove the example
ca file;

1 files changed, 120 insertions, 337 deletions

diff --git a/src/usr.bin/openssl/openssl.1 b/src/usr.bin/openssl/openssl.1
index 08769c56e4..184da99a49 100644
--- a/src/usr.bin/openssl/openssl.1
+++ b/src/usr.bin/openssl/openssl.1
@@ -1,4 +1,4 @@
-.\" $OpenBSD: openssl.1,v 1.34 2016/07/17 16:33:17 jmc Exp $
+.\" $OpenBSD: openssl.1,v 1.35 2016/07/19 20:02:47 jmc Exp $
 .\" ====================================================================
 .\" Copyright (c) 1998-2002 The OpenSSL Project.  All rights reserved.
 .\"
@@ -112,7 +112,7 @@
 .\"
 .\" OPENSSL
 .\"
-.Dd $Mdocdate: July 17 2016 $
+.Dd $Mdocdate: July 19 2016 $
 .Dt OPENSSL 1
 .Os
 .Sh NAME
@@ -309,13 +309,9 @@ This option can be used multiple times to
 .Qq drill down
 into a nested structure.
 .El
-.\"
-.\" CA
-.\"
 .Sh CA
 .nr nS 1
 .Nm "openssl ca"
-.Bk -words
 .Op Fl batch
 .Op Fl cert Ar file
 .Op Fl config Ar file
@@ -354,18 +350,16 @@ into a nested structure.
 .Op Fl subj Ar arg
 .Op Fl updatedb
 .Op Fl verbose
-.Ek
 .nr nS 0
 .Pp
 The
 .Nm ca
-command is a minimal CA application.
+command is a minimal certificate authority (CA) application.
 It can be used to sign certificate requests in a variety of forms
-and generate CRLs.
+and generate certificate revocation lists (CRLs).
 It also maintains a text database of issued certificates and their status.
 .Pp
-The options descriptions will be divided into each purpose.
-.Sh CA OPTIONS
+The options relevant to CAs are as follows:
 .Bl -tag -width "XXXX"
 .It Fl batch
 This sets the batch mode.
@@ -384,7 +378,7 @@ The format of the date is YYMMDDHHMMSSZ
 .It Fl extensions Ar section
 The section of the configuration file containing certificate extensions
 to be added when a certificate is issued (defaults to
-.Em x509_extensions
+.Cm x509_extensions
 unless the
 .Fl extfile
 option is used).
@@ -408,12 +402,8 @@ If present, this should be the last option; all subsequent arguments
 are assumed to be the names of files containing certificate requests.
 .It Fl key Ar keyfile
 The password used to encrypt the private key.
-Since on some systems the command line arguments are visible
-(e.g.\&
-.Ux
-with the
-.Xr ps 1
-utility) this option should be used with caution.
+Since on some systems the command line arguments are visible,
+this option should be used with caution.
 .It Fl keyfile Ar file
 The private key to sign requests with.
 .It Fl keyform Ar PEM
@@ -448,7 +438,7 @@ section).
 The DN of a certificate can contain the EMAIL field if present in the
 request DN, however it is good policy just having the email set into
 the
-.Em altName
+.Cm altName
 extension of the certificate.
 When this option is set, the EMAIL field is removed from the certificate's
 subject and set only in the, eventually present, extensions.
@@ -475,11 +465,20 @@ The key password source.
 This option defines the CA
 .Qq policy
 to use.
-This is a section in the configuration file which decides which fields
-should be mandatory or match the CA certificate.
-Check out the
-.Sx CA POLICY FORMAT
-section for more information.
+The policy section in the configuration file
+consists of a set of variables corresponding to certificate DN fields.
+The values may be one of
+.Qq match
+(the value must match the same field in the CA certificate),
+.Qq supplied
+(the value must be present), or
+.Qq optional
+(the value may be present).
+Any fields not mentioned in the policy section
+are silently deleted, unless the
+.Fl preserveDN
+option is set,
+but this can be regarded more of a quirk than intended behaviour.
 .It Fl preserveDN
 Normally, the DN order of a certificate is the same as the order of the
 fields in the relevant policy section.
@@ -491,9 +490,17 @@ This is not needed for Xenroll.
 .It Fl spkac Ar file
 A file containing a single Netscape signed public key and challenge,
 and additional field values to be signed by the CA.
-See the
-.Sx SPKAC FORMAT
-section for information on the required format.
+This will usually come from the
+KEYGEN tag in an HTML form to create a new private key.
+It is, however, possible to create SPKACs using the
+.Nm spkac
+utility.
+.Pp
+The file should contain the variable SPKAC set to the value of
+the SPKAC and also the required DN components as name value pairs.
+If it's necessary to include the same component twice,
+then it can be preceded by a number and a
+.Sq \&. .
 .It Fl ss_cert Ar file
 A single self-signed certificate to be signed by the CA.
 .It Fl startdate Ar date
@@ -501,14 +508,15 @@ This allows the start date to be explicitly set.
 The format of the date is YYMMDDHHMMSSZ
 .Pq the same as an ASN1 UTCTime structure .
 .It Fl status Ar serial
-Show status of certificate with serial number
+Show the status of the certificate with serial number
 .Ar serial .
 .It Fl updatedb
 Update database for expired certificates.
 .It Fl verbose
 This prints extra details about the operations being performed.
 .El
-.Sh CRL OPTIONS
+.Pp
+The options relevant to CRLs are as follows:
 .Bl -tag -width "XXXX"
 .It Fl crl_CA_compromise Ar time
 This is the same as
@@ -542,7 +550,7 @@ in delta CRLs which are not currently implemented.
 .It Fl crldays Ar num
 The number of days before the next CRL is due.
 This is the days from now to place in the CRL
-.Em nextUpdate
+.Cm nextUpdate
 field.
 .It Fl crlexts Ar section
 The
@@ -577,31 +585,22 @@ characters may be escaped by
 .Pq backslash ,
 no spaces are skipped.
 .El
-.Sh CA CONFIGURATION FILE OPTIONS
-The section of the configuration file containing options for
-.Nm ca
-is found as follows:
-If the
-.Fl name
-command line option is used, then it names the section to be used.
-Otherwise the section to be used must be named in the
-.Em default_ca
-option of the
-.Em ca
-section of the configuration file (or in the default section of the
-configuration file).
-Besides
-.Em default_ca ,
-the following options are read directly from the
-.Em ca
-section:
-.Pp
-.Bl -tag -width Ds -offset indent -compact
-.It preserve
-.It msie_hack
-.El
 .Pp
-This is probably a bug and may change in future releases.
+Many of the options can be set in the
+.Cm ca
+section of the configuration file
+(or in the default section of the configuration file),
+specified using
+.Cm default_ca
+or
+.Fl name .
+The options
+.Cm preserve
+and
+.Cm msie_hack
+are read directly from the
+.Cm ca
+section.
 .Pp
 Many of the configuration file options are identical to command line
 options.
@@ -612,44 +611,66 @@ the configuration file or the command line equivalent
 .Pq if any
 used.
 .Bl -tag -width "XXXX"
-.It Ar certificate
+.It Cm certificate
 The same as
 .Fl cert .
 It gives the file containing the CA certificate.
 Mandatory.
-.It Ar copy_extensions
+.It Cm copy_extensions
 Determines how extensions in certificate requests should be handled.
 If set to
-.Ar none
+.Cm none
 or this option is not present, then extensions are
 ignored and not copied to the certificate.
 If set to
-.Ar copy ,
+.Cm copy ,
 then any extensions present in the request that are not already present
 are copied to the certificate.
 If set to
-.Ar copyall ,
+.Cm copyall ,
 then all extensions in the request are copied to the certificate:
 if the extension is already present in the certificate it is deleted first.
-See the
-.Sx CA WARNINGS
-section before using this option.
+.Pp
+The
+.Cm copy_extensions
+option should be used with caution.
+If care is not taken, it can be a security risk.
+For example, if a certificate request contains a
+.Cm basicConstraints
+extension with CA:TRUE and the
+.Cm copy_extensions
+value is set to
+.Cm copyall
+and the user does not spot
+this when the certificate is displayed, then this will hand the requestor
+a valid CA certificate.
+.Pp
+This situation can be avoided by setting
+.Cm copy_extensions
+to
+.Cm copy
+and including
+.Cm basicConstraints
+with CA:FALSE in the configuration file.
+Then if the request contains a
+.Cm basicConstraints
+extension, it will be ignored.
 .Pp
 The main use of this option is to allow a certificate request to supply
 values for certain extensions such as
-.Em subjectAltName .
-.It Ar crl_extensions
+.Cm subjectAltName .
+.It Cm crl_extensions
 The same as
 .Fl crlexts .
-.It Ar crlnumber
+.It Cm crlnumber
 A text file containing the next CRL number to use in hex.
 The CRL number will be inserted in the CRLs only if this file exists.
 If this file is present, it must contain a valid CRL number.
-.It Ar database
+.It Cm database
 The text database file to use.
 Mandatory.
 This file must be present, though initially it will be empty.
-.It Ar default_crl_hours , default_crl_days
+.It Cm default_crl_hours , default_crl_days
 The same as the
 .Fl crlhours
 and
@@ -657,32 +678,32 @@ and
 options.
 These will only be used if neither command line option is present.
 At least one of these must be present to generate a CRL.
-.It Ar default_days
+.It Cm default_days
 The same as the
 .Fl days
 option.
 The number of days to certify a certificate for.
-.It Ar default_enddate
+.It Cm default_enddate
 The same as the
 .Fl enddate
 option.
 Either this option or
-.Ar default_days
+.Cm default_days
 .Pq or the command line equivalents
 must be present.
-.It Ar default_md
+.It Cm default_md
 The same as the
 .Fl md
 option.
 The message digest to use.
 Mandatory.
-.It Ar default_startdate
+.It Cm default_startdate
 The same as the
 .Fl startdate
 option.
 The start date to certify a certificate for.
 If not set, the current time is used.
-.It Ar email_in_dn
+.It Cm email_in_dn
 The same as
 .Fl noemailDN .
 If the EMAIL field is to be removed from the DN of the certificate,
@@ -690,10 +711,10 @@ simply set this to
 .Qq no .
 If not present, the default is to allow for the EMAIL field in the
 certificate's DN.
-.It Ar msie_hack
+.It Cm msie_hack
 The same as
 .Fl msie_hack .
-.It Ar name_opt , cert_opt
+.It Cm name_opt , cert_opt
 These options allow the format used to display the certificate details
 when asking the user to confirm signing.
 All the options supported by the
@@ -703,38 +724,38 @@ utilities'
 and
 .Fl certopt
 switches can be used here, except that
-.Ar no_signame
+.Cm no_signame
 and
-.Ar no_sigdump
+.Cm no_sigdump
 are permanently set and cannot be disabled
 (this is because the certificate signature cannot be displayed because
 the certificate has not been signed at this point).
 .Pp
 For convenience, the value
-.Em ca_default
+.Cm ca_default
 is accepted by both to produce a reasonable output.
 .Pp
 If neither option is present, the format used in earlier versions of
-.Nm OpenSSL
+.Nm openssl
 is used.
 Use of the old format is
 .Em strongly
 discouraged because it only displays fields mentioned in the
-.Ar policy
+.Cm policy
 section,
 mishandles multicharacter string types and does not display extensions.
-.It Ar new_certs_dir
+.It Cm new_certs_dir
 The same as the
 .Fl outdir
 command line option.
 It specifies the directory where new certificates will be placed.
 Mandatory.
-.It Ar oid_file
+.It Cm oid_file
 This specifies a file containing additional object identifiers.
 Each line of the file should consist of the numerical form of the
 object identifier followed by whitespace, then the short name followed
 by whitespace and finally the long name.
-.It Ar oid_section
+.It Cm oid_section
 This specifies a section in the configuration file containing extra
 object identifiers.
 Each line should consist of the short name of the object identifier
@@ -742,283 +763,38 @@ followed by
 .Sq =
 and the numerical form.
 The short and long names are the same when this option is used.
-.It Ar policy
+.It Cm policy
 The same as
 .Fl policy .
 Mandatory.
-See the
-.Sx CA POLICY FORMAT
-section for more information.
-.It Ar preserve
+.It Cm preserve
 The same as
 .Fl preserveDN .
-.It Ar private_key
+.It Cm private_key
 Same as the
 .Fl keyfile
 option.
 The file containing the CA private key.
 Mandatory.
-.It Ar serial
+.It Cm serial
 A text file containing the next serial number to use in hex.
 Mandatory.
 This file must be present and contain a valid serial number.
-.It Ar unique_subject
+.It Cm unique_subject
 If the value
-.Ar yes
+.Cm yes
 is given, the valid certificate entries in the
 database must have unique subjects.
 If the value
-.Ar no
+.Cm no
 is given,
 several valid certificate entries may have the exact same subject.
 The default value is
-.Ar yes .
-.It Ar x509_extensions
+.Cm yes .
+.It Cm x509_extensions
 The same as
 .Fl extensions .
 .El
-.Sh CA POLICY FORMAT
-The policy section consists of a set of variables corresponding to
-certificate DN fields.
-If the value is
-.Qq match ,
-then the field value must match the same field in the CA certificate.
-If the value is
-.Qq supplied ,
-then it must be present.
-If the value is
-.Qq optional ,
-then it may be present.
-Any fields not mentioned in the policy section
-are silently deleted, unless the
-.Fl preserveDN
-option is set,
-but this can be regarded more of a quirk than intended behaviour.
-.Sh SPKAC FORMAT
-The input to the
-.Fl spkac
-command line option is a Netscape signed public key and challenge.
-This will usually come from the
-.Em KEYGEN
-tag in an HTML form to create a new private key.
-It is, however, possible to create SPKACs using the
-.Nm spkac
-utility.
-.Pp
-The file should contain the variable SPKAC set to the value of
-the SPKAC and also the required DN components as name value pairs.
-If it's necessary to include the same component twice,
-then it can be preceded by a number and a
-.Sq \&. .
-.Sh CA EXAMPLES
-.Sy Note :
-these examples assume that the
-.Nm ca
-directory structure is already set up and the relevant files already exist.
-This usually involves creating a CA certificate and private key with
-.Cm req ,
-a serial number file and an empty index file and placing them in
-the relevant directories.
-.Pp
-To use the sample configuration file below, the directories
-.Pa demoCA ,
-.Pa demoCA/private
-and
-.Pa demoCA/newcerts
-would be created.
-The CA certificate would be copied to
-.Pa demoCA/cacert.pem
-and its private key to
-.Pa demoCA/private/cakey.pem .
-A file
-.Pa demoCA/serial
-would be created containing, for example,
-.Qq 01
-and the empty index file
-.Pa demoCA/index.txt .
-.Pp
-Sign a certificate request:
-.Pp
-.Dl $ openssl ca -in req.pem -out newcert.pem
-.Pp
-Sign a certificate request, using CA extensions:
-.Pp
-.Dl $ openssl ca -in req.pem -extensions v3_ca -out newcert.pem
-.Pp
-Generate a CRL:
-.Pp
-.Dl $ openssl ca -gencrl -out crl.pem
-.Pp
-Sign several requests:
-.Pp
-.Dl $ openssl ca -infiles req1.pem req2.pem req3.pem
-.Pp
-Certify a Netscape SPKAC:
-.Pp
-.Dl $ openssl ca -spkac spkac.txt
-.Pp
-A sample SPKAC file
-.Pq the SPKAC line has been truncated for clarity :
-.Bd -literal -offset indent
-SPKAC=MIG0MGAwXDANBgkqhkiG9w0BAQEFAANLADBIAkEAn7PDhCeV/xIxUg8V70YRxK
-CN=Steve Test
-emailAddress=steve@openssl.org
-0.OU=OpenSSL Group
-1.OU=Another Group
-.Ed
-.Pp
-A sample configuration file with the relevant sections for
-.Nm ca :
-.Bd -literal
-\& [ ca ]
-\& default_ca      = CA_default            # The default ca section
-
-\& [ CA_default ]
-
-\& dir            = ./demoCA              # top dir
-\& database       = $dir/index.txt        # index file
-\& new_certs_dir  = $dir/newcerts         # new certs dir
-
-\& certificate    = $dir/cacert.pem       # The CA cert
-\& serial         = $dir/serial           # serial no file
-\& private_key    = $dir/private/cakey.pem# CA private key
-
-\& default_days   = 365                   # how long to certify for
-\& default_crl_days= 30                   # how long before next CRL
-\& default_md     = md5                   # md to use
-
-\& policy         = policy_any            # default policy
-\& email_in_dn    = no                    # Don't add the email into cert DN
-
-\& name_opt        = ca_default           # Subject name display option
-\& cert_opt        = ca_default           # Certificate display option
-\& copy_extensions = none                 #Don't copy extensions from request
-
-\& [ policy_any ]
-\& countryName            = supplied
-\& stateOrProvinceName    = optional
-\& organizationName       = optional
-\& organizationalUnitName = optional
-\& commonName             = supplied
-\& emailAddress           = optional
-.Ed
-.Sh CA FILES
-.Sy Note :
-the location of all files can change either by compile time options,
-configuration file entries, environment variables, or command line options.
-The values below reflect the default values.
-.Bd -literal -offset indent
-/etc/ssl/openssl.cnf           - master configuration file
-\&./demoCA                       - main CA directory
-\&./demoCA/cacert.pem            - CA certificate
-\&./demoCA/private/cakey.pem     - CA private key
-\&./demoCA/serial                - CA serial number file
-\&./demoCA/serial.old            - CA serial number backup file
-\&./demoCA/index.txt             - CA text database file
-\&./demoCA/index.txt.old         - CA text database backup file
-\&./demoCA/certs                 - certificate output file
-.Ed
-.Sh CA ENVIRONMENT VARIABLES
-.Ev OPENSSL_CONF
-reflects the location of the master configuration file;
-it can be overridden by the
-.Fl config
-command line option.
-.Sh CA RESTRICTIONS
-The text database index file is a critical part of the process,
-and if corrupted it can be difficult to fix.
-It is theoretically possible to rebuild the index file from all the
-issued certificates and a current CRL; however there is no option to do this.
-.Pp
-V2 CRL features like delta CRLs are not currently supported.
-.Pp
-Although several requests can be input and handled at once, it is only
-possible to include one SPKAC or self-signed certificate.
-.Sh CA BUGS
-The use of an in-memory text database can cause problems when large
-numbers of certificates are present because, as the name implies,
-the database has to be kept in memory.
-.Pp
-It is not possible to certify two certificates with the same DN; this
-is a side effect of how the text database is indexed and it cannot easily
-be fixed without introducing other problems.
-Some S/MIME clients can use two certificates with the same DN for separate
-signing and encryption keys.
-.Pp
-The
-.Nm ca
-command really needs rewriting or the required functionality
-exposed at either a command or interface level so a more friendly utility
-.Pq perl script or GUI
-can handle things properly.
-.Pp
-Any fields in a request that are not present in a policy are silently
-deleted.
-This does not happen if the
-.Fl preserveDN
-option is used.
-To enforce the absence of the EMAIL field within the DN, as suggested
-by RFCs, regardless of the contents of the request's subject the
-.Fl noemailDN
-option can be used.
-The behaviour should be more friendly and configurable.
-.Pp
-Cancelling some commands by refusing to certify a certificate can
-create an empty file.
-.Sh CA WARNINGS
-The
-.Nm ca
-command is quirky and at times downright unfriendly.
-.Pp
-The
-.Nm ca
-utility was originally meant as an example of how to do things in a CA.
-It was not supposed to be used as a full blown CA itself:
-nevertheless some people are using it for this purpose.
-.Pp
-The
-.Nm ca
-command is effectively a single user command: no locking is done on the
-various files, and attempts to run more than one
-.Nm ca
-command on the same database can have unpredictable results.
-.Pp
-The
-.Ar copy_extensions
-option should be used with caution.
-If care is not taken, it can be a security risk.
-For example, if a certificate request contains a
-.Em basicConstraints
-extension with CA:TRUE and the
-.Ar copy_extensions
-value is set to
-.Ar copyall
-and the user does not spot
-this when the certificate is displayed, then this will hand the requestor
-a valid CA certificate.
-.Pp
-This situation can be avoided by setting
-.Ar copy_extensions
-to
-.Ar copy
-and including
-.Em basicConstraints
-with CA:FALSE in the configuration file.
-Then if the request contains a
-.Em basicConstraints
-extension, it will be ignored.
-.Pp
-It is advisable to also include values for other extensions such
-as
-.Ar keyUsage
-to prevent a request supplying its own values.
-.Pp
-Additional restrictions can be placed on the CA certificate itself.
-For example if the CA certificate has:
-.Pp
-.D1 basicConstraints = CA:TRUE, pathlen:0
-.Pp
-then even if a certificate is issued with CA:TRUE it will not be valid.
 .\"
 .\" CIPHERS
 .\"
@@ -9352,6 +9128,13 @@ This can be used to send the data via a pipe for example.
 .It Ar stdin
 Read the password from standard input.
 .El
+.Sh ENVIRONMENT
+The following environment variables affect the execution of
+.Nm openssl :
+.Bl -tag -width "OPENSSL_CONFXXX"
+.It Ev OPENSSL_CONF
+The location of the master configuration file.
+.El
 .\"
 .\" FILES
 .\"