Change DH parameters to generate the order q subgroup instead of 2q

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

diff --git a/doc/man1/ca.pod b/doc/man1/ca.pod
index ab8ce7211fcf0a41cdc4f699fcdc1f3d339519fc..8438d1dccb7ce274646b7a5594a48b16fe8f7498 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
@@ -50,10 +51,14 @@ B<openssl> B<ca>
 [B<-engine id>]
 [B<-subj arg>]
 [B<-utf8>]
+[B<-sigopt nm:v>]
 [B<-create_serial>]
+[B<-rand_serial>]
 [B<-multivalue-rdn>]
 [B<-rand file...>]
 [B<-writerand file>]
+[B<-sm2-id string>]
+[B<-sm2-hex-id hex-string>]
 
 =head1 DESCRIPTION
 
@@ -132,6 +137,11 @@ The private key to sign requests with.
 The format of the data in the private key file.
 The default is PEM.
 
+=item B<-sigopt nm:v>
+
+Pass options to the signature algorithm during sign or verify operations.
+Names and values of these options are algorithm-specific.
+
 =item B<-key password>
 
 The password used to encrypt the private key. Since on some
@@ -166,14 +176,14 @@ Don't output the text form of a certificate to the output file.
 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 timzone Z must be present.
+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), or
 YYYYMMDDHHMMSSZ (the same as an ASN1 GeneralizedTime structure). In
-both formats, seconds SS and timzone Z must be present.
+both formats, seconds SS and timezone Z must be present.
 
 =item B<-days arg>
 
@@ -182,8 +192,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>
 
@@ -227,7 +238,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.
 
@@ -247,8 +258,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>
 
@@ -262,6 +275,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>
 
@@ -285,6 +305,16 @@ all others.
 Writes random data to the specified I<file> upon exit.
 This can be used with a subsequent B<-rand> flag.
 
+=item B<-sm2-id>
+
+Specify the ID string to use when verifying an SM2 certificate. The ID string is
+required by the SM2 signature algorithm for signing and verification.
+
+=item B<-sm2-hex-id>
+
+Specify a binary ID string to use when signing or verifying using an SM2
+certificate. The argument for this option is string of hexadecimal digits.
+
 =back
 
 =head1 CRL OPTIONS
@@ -443,7 +473,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>
 
@@ -460,6 +491,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.
@@ -577,6 +612,10 @@ Sign a certificate request:
 
  openssl ca -in req.pem -out newcert.pem
 
+Sign an SM2 certificate request:
+
+ openssl ca -in sm2.csr -out sm2.crt -md sm3 -sigopt "sm2_id:1234567812345678" -sm2-id "1234567812345678"
+
 Sign a certificate request, using CA extensions:
 
  openssl ca -in req.pem -extensions v3_ca -out newcert.pem
@@ -614,6 +653,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
 
@@ -735,9 +775,9 @@ L<config(5)>, L<x509v3_config(5)>
 
 =head1 COPYRIGHT
 
-Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2000-2019 The OpenSSL Project Authors. All Rights Reserved.
 
-Licensed under the OpenSSL license (the "License").  You may not use
+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
 in the file LICENSE in the source distribution or at
 L<https://www.openssl.org/source/license.html>.