apps: allow empty attribute values with -subj

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

diff --git a/doc/man1/ca.pod b/doc/man1/ca.pod
index 26d648e924fbcbd3f48a159c4ca62e5da2ba0998..e998eabf83585c2e1dae1ec64625ff29a446d057 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,7 +52,10 @@ B<openssl> B<ca>
 [B<-subj arg>]
 [B<-utf8>]
 [B<-create_serial>]
+[B<-rand_serial>]
 [B<-multivalue-rdn>]
+[B<-rand file...>]
+[B<-writerand file>]
 
 =head1 DESCRIPTION
 
@@ -162,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>
 
@@ -176,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>
 
@@ -241,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>
 
@@ -256,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>
 
@@ -266,6 +284,19 @@ I</DC=org/DC=OpenSSL/DC=users/UID=123456+CN=John Doe>
 
 If -multi-rdn is not used then the UID value is I<123456+CN=John Doe>.
 
+=item B<-rand file...>
+
+A file or files containing random data used to seed the random number
+generator.
+Multiple files can be specified separated by an OS-dependent character.
+The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
+all others.
+
+=item [B<-writerand file>]
+
+Writes random data to the specified I<file> upon exit.
+This can be used with a subsequent B<-rand> flag.
+
 =back
 
 =head1 CRL OPTIONS
@@ -397,8 +428,8 @@ CA private key. Mandatory.
 
 =item B<RANDFILE>
 
-A file used to read and write random number seed information, or
-an EGD socket (see L<RAND_egd(3)>).
+At startup the specified file is loaded into the random number generator,
+and at exit 256 bytes will be written to it.
 
 =item B<default_days>
 
@@ -424,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>
 
@@ -441,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.
@@ -595,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
 
@@ -701,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)>,
@@ -708,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