-.\" $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.
.\"
.\"
.\" OPENSSL
.\"
-.Dd $Mdocdate: July 17 2016 $
+.Dd $Mdocdate: July 19 2016 $
.Dt OPENSSL 1
.Os
.Sh NAME
.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
.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.
.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).
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
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.
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.
.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
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
.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
.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.
.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
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,
.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
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
.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
.\"
.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
.\"
projects / openbsd / commitdiff