B<openssl> B<ca>
[B<-help>]
[B<-verbose>]
+[B<-quiet>]
[B<-config> I<filename>]
[B<-name> I<section>]
[B<-section> I<section>]
[B<-crl_hold> I<instruction>]
[B<-crl_compromise> I<time>]
[B<-crl_CA_compromise> I<time>]
+[B<-crl_lastupdate> I<date>]
+[B<-crl_nextupdate> I<date>]
[B<-crldays> I<days>]
[B<-crlhours> I<hours>]
[B<-crlsec> I<seconds>]
[B<-crlexts> I<section>]
[B<-startdate> I<date>]
+[B<-not_before> I<date>]
[B<-enddate> I<date>]
+[B<-not_after> I<date>]
[B<-days> I<arg>]
[B<-md> I<arg>]
[B<-policy> I<arg>]
-[B<-keyfile> I<arg>]
+[B<-keyfile> I<filename>|I<uri>]
[B<-keyform> B<DER>|B<PEM>|B<P12>|B<ENGINE>]
[B<-key> I<arg>]
[B<-passin> I<arg>]
[B<-inform> B<DER>|<PEM>]
[B<-out> I<file>]
[B<-notext>]
+[B<-dateopt>]
[B<-outdir> I<dir>]
[B<-infiles>]
[B<-spkac> I<file>]
[B<-rand_serial>]
[B<-multivalue-rdn>]
{- $OpenSSL::safe::opt_r_synopsis -}
-{- $OpenSSL::safe::opt_engine_synopsis -}
-{- $OpenSSL::safe::opt_provider_synopsis -}
+{- $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 generates certificates bearing X.509 version 3.
+Unless specified otherwise,
+key identifier extensions are included as described in L<x509v3_config(5)>.
+
+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
This prints extra details about the operations being performed.
+=item B<-quiet>
+
+This prints fewer details about the operations being performed, which may
+be handy during batch scripts or pipelines.
+
=item B<-config> I<filename>
Specifies the configuration file to use.
=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 to use when loading certificate request (CSR) input files;
+by default PEM is tried first.
+See L<openssl-format-options(1)> for details.
=item B<-ss_cert> I<filename>
written to a filename consisting of the serial number in hex with
F<.pem> appended.
-=item B<-cert>
+=item B<-cert> I<filename>
-The CA certificate file.
+The CA certificate, which must match with B<-keyfile>.
=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>
+=item B<-keyfile> I<filename>|I<uri>
-The private key to sign requests with.
+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>
systems the command line arguments are visible (e.g., when using
L<ps(1)> on Unix),
this option should be used with caution.
+Better use B<-passin>.
+
+=item B<-passin> I<arg>
+
+The key password source for key files and certificate PKCS#12 files.
+For more information about the format of B<arg>
+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
serial number counter as all other certificates sign with the
self-signed certificate.
-=item B<-passin> I<arg>
-
-The key password source. For more information about the format of B<arg>
-see L<openssl(1)/Pass Phrase Options>.
-
=item B<-notext>
Don't output the text form of a certificate to the output file.
-=item B<-startdate> I<date>
+=item B<-dateopt>
+
+Specify the date output format. Values are: rfc_822 and iso_8601.
+Defaults to rfc_822.
+
+=item B<-startdate> I<date>, B<-not_before> I<date>
This allows the start date to be explicitly set. The format of the
date is YYMMDDHHMMSSZ (the same as an ASN1 UTCTime structure), or
YYYYMMDDHHMMSSZ (the same as an ASN1 GeneralizedTime structure). In
both formats, seconds SS and timezone Z must be present.
+Alternatively, you can also use "today".
-=item B<-enddate> I<date>
+=item B<-enddate> I<date>, B<-not_after> I<date>
This allows the expiry date to be explicitly set. The format of the
date is YYMMDDHHMMSSZ (the same as an ASN1 UTCTime structure), or
YYYYMMDDHHMMSSZ (the same as an ASN1 GeneralizedTime structure). In
both formats, seconds SS and timezone Z must be present.
+Alternatively, you can also use "today".
+
+This overrides the B<-days> option.
=item B<-days> I<arg>
-The number of days to certify the certificate for.
+The number of days from today to certify the certificate for.
+
+Regardless of the option B<-not_before>, the days are always counted from
+today.
+When used together with the option B<-not_after>/B<-startdate>, the explicit
+expiry date takes precedence.
=item B<-md> I<alg>
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).
+
+See the L<x509v3_config(5)> manual page for details of the
extension section format.
=item B<-extfile> I<file>
=item B<-subj> I<arg>
Supersedes subject name given in the request.
+
The arg must be formatted as C</type0=value0/type1=value1/type2=...>.
-Keyword characters may be escaped by C<\> (backslash), and whitespace is
-retained.
+Special characters may be escaped by C<\> (backslash), whitespace is retained.
Empty values are permitted, but the corresponding type will not be included
in the resulting certificate.
+Giving a single C</> will lead to an empty sequence of RDNs (a NULL-DN).
+Multi-valued RDNs can be formed by placing a C<+> character instead of a C</>
+between the AttributeValueAssertions (AVAs) that specify the members of the set.
+Example:
+
+C</DC=org/DC=OpenSSL/DC=users/UID=123456+CN=John Doe>
=item B<-utf8>
=item B<-multivalue-rdn>
-This option causes the -subj argument to be interpreted with full
-support for multivalued RDNs. Example:
-
-C</DC=org/DC=OpenSSL/DC=users/UID=123456+CN=John Doe>
-
-If B<-multi-rdn> is not used then the UID value is C<123456+CN=John Doe>.
+This option has been deprecated and has no effect.
{- $OpenSSL::safe::opt_r_item -}
This option generates a CRL based on information in the index file.
+=item B<-crl_lastupdate> I<time>
+
+Allows the value of the CRL's lastUpdate field to be explicitly set; if
+this option is not present, the current time is used. Accepts times in
+YYMMDDHHMMSSZ format (the same as an ASN1 UTCTime structure) or
+YYYYMMDDHHMMSSZ format (the same as an ASN1 GeneralizedTime structure).
+
+=item B<-crl_nextupdate> I<time>
+
+Allows the value of the CRL's nextUpdate field to be explicitly set; if
+this option is present, any values given for B<-crldays>, B<-crlhours>
+and B<-crlsec> are ignored. Accepts times in the same formats as
+B<-crl_lastupdate>.
+
=item B<-crldays> I<num>
The number of days before the next CRL is due. That is the days from
=item B<default_days>
-The same as the B<-days> option. The number of days to certify
+The same as the B<-days> option. The number of days from today to certify
a certificate for.
=item B<default_startdate>
=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
+This 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>
command on the same database can have unpredictable results.
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
Since OpenSSL 1.1.1, the program follows RFC5280. Specifically,
certificate validity period (specified by any of B<-startdate>,
-B<-enddate> and B<-days>) will be encoded as UTCTime if the dates are
+B<-enddate> and B<-days>) and CRL last/next update time (specified by
+any of B<-crl_lastupdate>, B<-crl_nextupdate>, B<-crldays>, B<-crlhours>
+and B<-crlsec>) will be encoded as UTCTime if the dates are
earlier than year 2049 (included), and as GeneralizedTime if the dates
are in year 2050 or later.
The B<-section> option was added in OpenSSL 3.0.0.
-The B<-certform> option has become obsolete in OpenSSL 3.0.0 and has 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.
-All B<-keyform> values except B<ENGINE> have become obsolete in OpenSSL 3.0.0
-and have no effect.
+Since OpenSSL 3.2, generated certificates bear X.509 version 3,
+and key identifier extensions are included by default.
=head1 SEE ALSO
=head1 COPYRIGHT
-Copyright 2000-2020 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2000-2023 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
projects / openssl.git / blobdiff