{- $OpenSSL::safe::opt_engine_synopsis -}{- $OpenSSL::safe::opt_provider_synopsis -}
[I<certreq>...]
-=for openssl ifdef engine
-
=head1 DESCRIPTION
-This command is a minimal CA application. It can be used
-to sign certificate requests in a variety of forms and generate
-CRLs. It also maintains a text database of issued certificates
-and their status.
-When signing certificates, a single certificate request can be specified
+This command emulates a CA application.
+See the B<WARNINGS> especially when considering to use it productively.
+It can be used to sign certificate requests (CSRs) in a variety of forms
+and generate certificate revocation lists (CRLs).
+It also maintains a text database of issued certificates and their status.
+When signing certificates, a single request can be specified
with the B<-in> option, or multiple requests can be processed by
specifying a set of B<certreq> files after all options.
-The options descriptions will be divided into each purpose.
+Note that there are also very lean ways of generating certificates:
+the B<req> and B<x509> commands can be used for directly creating certificates.
+See L<openssl-req(1)> and L<openssl-x509(1)> for details.
+
+The descriptions of the B<ca> command options are divided into each purpose.
=head1 OPTIONS
=item B<-in> I<filename>
-An input filename containing a single certificate request to be
+An input filename containing a single certificate request (CSR) to be
signed by the CA.
=item B<-inform> B<DER>|B<PEM>
-The format of the data in CSR input files.
-The default is PEM.
+The format of the data in certificate request input files;
+unspecified by default.
+See L<openssl-format-options(1)> for details.
=item B<-ss_cert> I<filename>
=item B<-certform> B<DER>|B<PEM>|B<P12>
-The format of the data in certificate input files.
-This option has no effect and is retained for backward compatibility only.
+The format of the data in certificate input files; unspecified by default.
+See L<openssl-format-options(1)> for details.
=item B<-keyfile> I<filename>|I<uri>
-The CA private key to sign requests with. This must match with B<-cert>.
+The CA private key to sign certificate requests with.
+This must match with B<-cert>.
=item B<-keyform> B<DER>|B<PEM>|B<P12>|B<ENGINE>
-The format of the private key input file; the default is B<PEM>.
-The only value with effect is B<ENGINE>; all others have become obsolete.
-See L<openssl(1)/Format Options> for details.
+The format of the private key input file; unspecified by default.
+See L<openssl-format-options(1)> for details.
=item B<-sigopt> I<nm>:I<v>
Pass options to the signature algorithm during verify operations.
Names and values of these options are algorithm-specific.
-This often needs to be given while signing too, because the input
-certificate signature request is verified against its own public key,
+This often needs to be given while signing too, because the self-signature of
+a certificate signing request (CSR) is verified against the included public key,
and that verification may need its own set of options.
=item B<-key> I<password>
The key password source for key files and certificate PKCS#12 files.
For more information about the format of B<arg>
-see L<openssl(1)/Pass Phrase Options>.
+see L<openssl-passphrase-options(1)>.
=item B<-selfsign>
Indicates the issued certificates are to be signed with the key
the certificate requests were signed with (given with B<-keyfile>).
-Certificate requests signed with a different key are ignored. If
-B<-spkac>, B<-ss_cert> or B<-gencrl> are given, B<-selfsign> is
-ignored.
+Certificate requests signed with a different key are ignored.
+If B<-spkac>, B<-ss_cert> or B<-gencrl> are given, B<-selfsign> is ignored.
A consequence of using B<-selfsign> is that the self-signed
certificate appears among the entries in the certificate database
The section of the configuration file containing certificate extensions
to be added when a certificate is issued (defaults to B<x509_extensions>
-unless the B<-extfile> option is used). If no extension section is
-present then, a V1 certificate is created. If the extension section
-is present (even if it is empty), then a V3 certificate is created. See the
-L<x509v3_config(5)> manual page for details of the
+unless the B<-extfile> option is used).
+If no X.509 extensions are specified then a V1 certificate is created,
+else a V3 certificate is created.
+See the L<x509v3_config(5)> manual page for details of the
extension section format.
=item B<-extfile> I<file>
=item B<x509_extensions>
-The same as B<-extensions>.
+A fallback to the B<-extensions> option.
=item B<crl_extensions>
-The same as B<-crlexts>.
+A fallback to the B<-crlexts> option.
=item B<preserve>
=head1 BUGS
+This command is quirky and at times downright unfriendly.
+
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.
=head1 WARNINGS
-This command is quirky and at times downright unfriendly.
-
-This command 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.
+This command was originally meant as an example of how to do things in a CA.
+Its code does not have production quality.
+It was not supposed to be used as a full blown CA itself,
+nevertheless some people are using it for this purpose at least internally.
+When doing so, specific care should be taken to
+properly secure the private key(s) used for signing certificates.
+It is advisable to keep them in a secure HW storage such as a smart card or HSM
+and access them via a suitable engine or crypto provider.
This command command is effectively a single user command: no locking
is done on the various files and attempts to run more than one B<openssl ca>
B<copy_extensions> value is set to B<copyall> and the user does not spot
this when the certificate is displayed then this will hand the requester
a valid CA certificate.
-
This situation can be avoided by setting B<copy_extensions> to B<copy>
and including basicConstraints with CA:FALSE in the configuration file.
Then if the request contains a basicConstraints extension it will be
The B<-section> option was added in OpenSSL 3.0.0.
-The B<-certform> and B<-multivalue-rdn> options
-have become obsolete in OpenSSL 3.0.0 and have no effect.
-
-All B<-keyform> values except B<ENGINE> have become obsolete in OpenSSL 3.0.0
-and have no effect.
+The B<-multivalue-rdn> option has become obsolete in OpenSSL 3.0.0 and
+has no effect.
The B<-engine> option was deprecated in OpenSSL 3.0.
=head1 COPYRIGHT
-Copyright 2000-2020 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2000-2021 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the Apache License 2.0 (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy