Android build: fix usage of NDK home variable ($ndk_var)

[openssl.git] / doc / man1 / ca.pod

diff --git a/doc/man1/ca.pod b/doc/man1/ca.pod
index 4a5970892c5f7a93446976dc1b38811e130cb891..1b5f6573187861987823a8988e471c76475fe44a 100644 (file)
--- a/doc/man1/ca.pod
+++ b/doc/man1/ca.pod
@@ -2,6 +2,7 @@
 
 =head1 NAME
 
+openssl-ca,
 ca - sample minimal CA application
 
 =head1 SYNOPSIS
@@ -51,6 +52,7 @@ B<openssl> B<ca>
 [B<-subj arg>]
 [B<-utf8>]
 [B<-create_serial>]
+[B<-rand_serial>]
 [B<-multivalue-rdn>]
 [B<-rand file...>]
 [B<-writerand file>]
@@ -164,12 +166,16 @@ Don't output the text form of a certificate to the output file.
 =item B<-startdate date>
 
 This allows the start date to be explicitly set. The format of the
-date is YYMMDDHHMMSSZ (the same as an ASN1 UTCTime structure).
+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.
 
 =item B<-enddate date>
 
 This allows the expiry date to be explicitly set. The format of the
-date is YYMMDDHHMMSSZ (the same as an ASN1 UTCTime structure).
+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.
 
 =item B<-days arg>
 
@@ -178,8 +184,9 @@ The number of days to certify the certificate for.
 =item B<-md alg>
 
 The message digest to use.
-Any digest supported by the OpenSSL B<dgst> command can be used.
-This option also applies to CRLs.
+Any digest supported by the OpenSSL B<dgst> command can be used. For signing
+algorithms that do not support a digest (i.e. Ed25519 and Ed448) any message
+digest that is set is ignored. This option also applies to CRLs.
 
 =item B<-policy arg>
 
@@ -223,7 +230,7 @@ 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:w
+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
 extension section format.
 
@@ -243,8 +250,10 @@ for all available algorithms.
 =item B<-subj arg>
 
 Supersedes subject name given in the request.
-The arg must be formatted as I</type0=value0/type1=value1/type2=...>,
-characters may be escaped by \ (backslash), no spaces are skipped.
+The arg must be formatted as I</type0=value0/type1=value1/type2=...>.
+Keyword characters may be escaped by \ (backslash), and whitespace is retained.
+Empty values are permitted, but the corresponding type will not be included
+in the resulting certificate.
 
 =item B<-utf8>
 
@@ -258,6 +267,13 @@ configuration file, must be valid UTF8 strings.
 If reading serial from the text file as specified in the configuration
 fails, specifying this option creates a new random serial to be used as next
 serial number.
+To get random serial numbers, use the B<-rand_serial> flag instead; this
+should only be used for simple error-recovery.
+
+=item B<-rand_serial>
+
+Generate a large random number to use as the serial number.
+This overrides any option or configuration to use a serial number file.
 
 =item B<-multivalue-rdn>
 
@@ -439,7 +455,8 @@ least one of these must be present to generate a CRL.
 
 =item B<default_md>
 
-The same as the B<-md> option. Mandatory.
+The same as the B<-md> option. Mandatory except where the signing algorithm does
+not require a digest (i.e. Ed25519 and Ed448).
 
 =item B<database>
 
@@ -456,6 +473,10 @@ versions of OpenSSL.  However, to make CA certificate roll-over easier,
 it's recommended to use the value B<no>, especially if combined with
 the B<-selfsign> command line option.
 
+Note that it is valid in some circumstances for certificates to be created
+without any subject. In the case where there are multiple certificates without
+subjects this does not count as a duplicate. 
+
 =item B<serial>
 
 A text file containing the next serial number to use in hex. Mandatory.
@@ -610,6 +631,7 @@ A sample configuration file with the relevant sections for B<ca>:
 
  certificate    = $dir/cacert.pem       # The CA cert
  serial         = $dir/serial           # serial no file
+ #rand_serial    = yes                  # for random serial#'s
  private_key    = $dir/private/cakey.pem# CA private key
  RANDFILE       = $dir/private/.rand    # random number file
 
@@ -716,6 +738,14 @@ For example if the CA certificate has:
 
 then even if a certificate is issued with CA:TRUE it will not be valid.
 
+=head1 HISTORY
+
+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
+earlier than year 2049 (included), and as GeneralizedTime if the dates
+are in year 2050 or later.
+
 =head1 SEE ALSO
 
 L<req(1)>, L<spkac(1)>, L<x509(1)>, L<CA.pl(1)>,
@@ -723,7 +753,7 @@ L<config(5)>, L<x509v3_config(5)>
 
 =head1 COPYRIGHT
 
-Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2000-2018 The OpenSSL Project Authors. All Rights Reserved.
 
 Licensed under the OpenSSL license (the "License").  You may not use
 this file except in compliance with the License.  You can obtain a copy