apps/x509.c: Major code, user guidance, and documentation cleanup

This brings the options in help output and doc in reasonable order
and fixes various corner cases of option use combinations

Reviewed-by: Tomas Mraz <tomas@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/13711)

2 files changed, 593 insertions, 541 deletions

diff --git a/apps/x509.c b/apps/x509.c
index 642078971b..8012475341 100644
--- a/apps/x509.c
+++ b/apps/x509.c
@@ -28,7 +28,8 @@
 
 #undef POSTFIX
 #define POSTFIX ".srl"
-#define DEF_DAYS        30
+#define DEFAULT_DAYS    30 /* default cert validity period in days */
+#define UNSET_DAYS      -2 /* -1 is used for testing expiration checks */
 
 static int callb(int ok, X509_STORE_CTX *ctx);
 static int sign(X509 *x, EVP_PKEY *pkey, X509 *issuer,
@@ -36,12 +37,13 @@ static int sign(X509 *x, EVP_PKEY *pkey, X509 *issuer,
                 int days, int clrext,
                 const EVP_MD *digest, CONF *conf, const char *section,
                 int preserve_dates);
-static int x509_certify(X509_STORE *ctx, const char *CAfile, const EVP_MD *digest,
+static int x509_certify(X509_STORE *ctx, const char *CAfile,
+                        const EVP_MD *digest,
                         X509 *x, X509 *xca, EVP_PKEY *pkey,
-                        STACK_OF(OPENSSL_STRING) *sigopts, const char *serialfile,
-                        int create, int days, int clrext, CONF *conf,
-                        const char *section, ASN1_INTEGER *sno, int reqfile,
-                        int preserve_dates);
+                        STACK_OF(OPENSSL_STRING) *sigopts,
+                        const char *serialfile, int create,
+                        int days, int clrext, CONF *conf, const char *section,
+                        ASN1_INTEGER *sno, int preserve_dates);
 static int purpose_print(BIO *bio, X509 *cert, X509_PURPOSE *pt);
 static int print_x509v3_exts(BIO *bio, X509 *x, const char *exts);
 
@@ -67,97 +69,117 @@ typedef enum OPTION_choice {
 const OPTIONS x509_options[] = {
     OPT_SECTION("General"),
     {"help", OPT_HELP, '-', "Display this summary"},
-#ifndef OPENSSL_NO_ENGINE
-    {"engine", OPT_ENGINE, 's', "Use engine, possibly a hardware device"},
-#endif
 
-    {"inform", OPT_INFORM, 'f',
-     "CSR input format (DER or PEM) - default PEM"},
-    {"in", OPT_IN, '<', "Input file - default stdin"},
+    {"in", OPT_IN, '<',
+     "Certificate input (default stdin), or CSR input file with -req"},
     {"passin", OPT_PASSIN, 's', "Private key and cert file pass-phrase source"},
+    {"new", OPT_NEW, '-', "Generate a certificate from scratch"},
+    {"x509toreq", OPT_X509TOREQ, '-',
+     "Output a certification request (rather than a certificate)"},
+    {"req", OPT_REQ, '-', "Input is a CSR file (rather than a certificate)"},
+    {"inform", OPT_INFORM, 'f',
+     "CSR input file format (DER or PEM) - default PEM"},
+    {"vfyopt", OPT_VFYOPT, 's', "CSR verification parameter in n:v form"},
+    {"signkey", OPT_SIGNKEY, 's',
+     "Key used to self-sign certificate or cert request"},
+    {"keyform", OPT_KEYFORM, 'E',
+     "Key input format (ENGINE, other values ignored)"},
+    {"out", OPT_OUT, '>', "Output file - default stdout"},
     {"outform", OPT_OUTFORM, 'f',
      "Output format (DER or PEM) - default PEM"},
-    {"out", OPT_OUT, '>', "Output file - default stdout"},
-    {"keyform", OPT_KEYFORM, 'E', "Private key format (ENGINE, other values ignored)"},
-    {"req", OPT_REQ, '-', "Input is a certificate request, sign and output"},
-    {"vfyopt", OPT_VFYOPT, 's', "Verification parameter in n:v form"},
+    {"nocert", OPT_NOCERT, '-',
+     "No cert output (except for requested printing)"},
+    {"noout", OPT_NOOUT, '-', "No output (except for requested printing)"},
 
-    OPT_SECTION("Output"),
+    OPT_SECTION("Certificate printing"),
+    {"text", OPT_TEXT, '-', "Print the certificate in text form"},
+    {"certopt", OPT_CERTOPT, 's', "Various certificate text printing options"},
+    {"fingerprint", OPT_FINGERPRINT, '-', "Print the certificate fingerprint"},
+    {"alias", OPT_ALIAS, '-', "Print certificate alias"},
     {"serial", OPT_SERIAL, '-', "Print serial number value"},
-    {"subject_hash", OPT_HASH, '-', "Print subject hash value"},
-    {"issuer_hash", OPT_ISSUER_HASH, '-', "Print issuer hash value"},
-    {"hash", OPT_HASH, '-', "Synonym for -subject_hash"},
+    {"startdate", OPT_STARTDATE, '-', "Print the notBefore field"},
+    {"enddate", OPT_ENDDATE, '-', "Print the notAfter field"},
+    {"dates", OPT_DATES, '-', "Print both notBefore and notAfter fields"},
     {"subject", OPT_SUBJECT, '-', "Print subject DN"},
     {"issuer", OPT_ISSUER, '-', "Print issuer DN"},
+    {"nameopt", OPT_NAMEOPT, 's',
+     "Certificate subject/issuer name printing options"},
     {"email", OPT_EMAIL, '-', "Print email address(es)"},
-    {"purpose", OPT_PURPOSE, '-', "Print out certificate purposes"},
-    {"modulus", OPT_MODULUS, '-', "Print the RSA key modulus"},
-    {"pubkey", OPT_PUBKEY, '-', "Output the public key"},
-    {"fingerprint", OPT_FINGERPRINT, '-', "Print the certificate fingerprint"},
-    {"alias", OPT_ALIAS, '-', "Output certificate alias"},
-    {"noout", OPT_NOOUT, '-', "No output, just status"},
-    {"ocspid", OPT_OCSPID, '-',
-     "Print OCSP hash values for the subject name and public key"},
-    {"ocsp_uri", OPT_OCSP_URI, '-', "Print OCSP Responder URL(s)"},
-    {"nocert", OPT_NOCERT, '-', "No certificate output"},
-    {"trustout", OPT_TRUSTOUT, '-', "Output a trusted certificate"},
-    {"x509toreq", OPT_X509TOREQ, '-',
-     "Output a certification request object"},
-    {"checkend", OPT_CHECKEND, 'M',
-     "Check whether the cert expires in the next arg seconds"},
-    {OPT_MORE_STR, 1, 1, "Exit 1 if so, 0 if not"},
-    {"text", OPT_TEXT, '-', "Print the certificate in text form"},
-    {"ext", OPT_EXT, 's', "Print various X509V3 extensions"},
+    {"hash", OPT_HASH, '-', "Synonym for -subject_hash (for backward compat)"},
+    {"subject_hash", OPT_HASH, '-', "Print subject hash value"},
 #ifndef OPENSSL_NO_MD5
     {"subject_hash_old", OPT_SUBJECT_HASH_OLD, '-',
      "Print old-style (MD5) subject hash value"},
+#endif
+    {"issuer_hash", OPT_ISSUER_HASH, '-', "Print issuer hash value"},
+#ifndef OPENSSL_NO_MD5
     {"issuer_hash_old", OPT_ISSUER_HASH_OLD, '-',
      "Print old-style (MD5) issuer hash value"},
 #endif
-    {"nameopt", OPT_NAMEOPT, 's', "Certificate subject/issuer name printing options"},
+    {"ext", OPT_EXT, 's', "Print the specified X509V3 extensions"},
+    {"ocspid", OPT_OCSPID, '-',
+     "Print OCSP hash values for the subject name and public key"},
+    {"ocsp_uri", OPT_OCSP_URI, '-', "Print OCSP Responder URL(s)"},
+    {"purpose", OPT_PURPOSE, '-', "Print out certificate purposes"},
+    {"pubkey", OPT_PUBKEY, '-', "Print the public key in PEM format"},
+    {"modulus", OPT_MODULUS, '-', "Print the RSA key modulus"},
 
-    OPT_SECTION("Certificate"),
-    {"startdate", OPT_STARTDATE, '-', "Set notBefore field"},
-    {"enddate", OPT_ENDDATE, '-', "Set notAfter field"},
-    {"dates", OPT_DATES, '-', "Both Before and After dates"},
-    {"clrtrust", OPT_CLRTRUST, '-', "Clear all trusted purposes"},
-    {"clrext", OPT_CLREXT, '-', "Clear all certificate extensions"},
-    {"addtrust", OPT_ADDTRUST, 's', "Trust certificate for a given purpose"},
-    {"addreject", OPT_ADDREJECT, 's',
-     "Reject certificate for a given purpose"},
-    {"setalias", OPT_SETALIAS, 's', "Set certificate alias"},
-    {"days", OPT_DAYS, 'n',
-     "How long till expiry of a signed certificate - def 30 days"},
-    {"signkey", OPT_SIGNKEY, 's', "Sign cert with arg"},
-    {"set_serial", OPT_SET_SERIAL, 's', "Serial number to use"},
-    {"extensions", OPT_EXTENSIONS, 's', "Section from config file to use"},
-    {"certopt", OPT_CERTOPT, 's', "Various certificate text options"},
+    OPT_SECTION("Certificate checking"),
+    {"checkend", OPT_CHECKEND, 'M',
+     "Check whether cert expires in the next arg seconds"},
+    {OPT_MORE_STR, 1, 1, "Exit 1 (failure) if so, 0 if not"},
     {"checkhost", OPT_CHECKHOST, 's', "Check certificate matches host"},
     {"checkemail", OPT_CHECKEMAIL, 's', "Check certificate matches email"},
     {"checkip", OPT_CHECKIP, 's', "Check certificate matches ipaddr"},
-    {"force_pubkey", OPT_FORCE_PUBKEY, '<', "Place the given key in new certificate"},
+
+    OPT_SECTION("Certificate output"),
+    {"set_serial", OPT_SET_SERIAL, 's',
+     "Serial number to use, overrides -CAserial"},
+    {"next_serial", OPT_NEXT_SERIAL, '-',
+     "Increment current certificate serial number"},
+    {"days", OPT_DAYS, 'n',
+     "Number of days until newly generated certificate expires - default 30"},
+    {"preserve_dates", OPT_PRESERVE_DATES, '-',
+     "Preserve existing validity dates"},
     {"subj", OPT_SUBJ, 's', "Set or override certificate subject (and issuer)"},
+    {"force_pubkey", OPT_FORCE_PUBKEY, '<',
+     "Place the given key in new certificate"},
+    {"clrext", OPT_CLREXT, '-', "Clear all certificate extensions"},
+    {"extfile", OPT_EXTFILE, '<', "Config file with X509V3 extensions to add"},
+    {"extensions", OPT_EXTENSIONS, 's',
+     "Section of extfile to use - default: unnamed section"},
+    {"sigopt", OPT_SIGOPT, 's', "Signature parameter in n:v form"},
+    {"badsig", OPT_BADSIG, '-',
+     "Corrupt last byte of certificate signature (for test)"},
+    {"", OPT_MD, '-', "Any supported digest, used for signing and printing"},
 
-    OPT_SECTION("CA"),
-    {"CA", OPT_CA, '<', "Set the CA certificate, must be PEM format"},
-    {"CAkey", OPT_CAKEY, 's',
-     "The CA key, must be PEM format; if not in CAfile"},
-    {"extfile", OPT_EXTFILE, '<', "File with X509V3 extensions to add"},
-    OPT_R_OPTIONS,
-    OPT_PROV_OPTIONS,
+    OPT_SECTION("Micro-CA"),
+    {"CA", OPT_CA, '<',
+     "Use the given CA certificate, conflicts with -signkey"},
     {"CAform", OPT_CAFORM, 'F', "CA cert format (PEM/DER/P12); has no effect"},
-    {"CAkeyform", OPT_CAKEYFORM, 'E', "CA key format (ENGINE, other values ignored)"},
-    {"sigopt", OPT_SIGOPT, 's', "Signature parameter in n:v form"},
+    {"CAkey", OPT_CAKEY, 's', "The corresponding CA key; default is -CA arg"},
+    {"CAkeyform", OPT_CAKEYFORM, 'E',
+     "CA key format (ENGINE, other values ignored)"},
+    {"CAserial", OPT_CASERIAL, 's',
+     "File that keeps track of CA-generated serial number"},
     {"CAcreateserial", OPT_CACREATESERIAL, '-',
-     "Create serial number file if it does not exist"},
-    {"CAserial", OPT_CASERIAL, 's', "Serial file"},
-    {"new", OPT_NEW, '-', "Generate a certificate from scratch"},
-    {"next_serial", OPT_NEXT_SERIAL, '-', "Increment current certificate serial number"},
+     "Create CA serial number file if it does not exist"},
+
+    OPT_SECTION("Certificate trust output"),
+    {"trustout", OPT_TRUSTOUT, '-', "Mark certificate PEM output as trusted"},
+    {"setalias", OPT_SETALIAS, 's', "Set certificate alias (nickname)"},
+    {"clrtrust", OPT_CLRTRUST, '-', "Clear all trusted purposes"},
+    {"addtrust", OPT_ADDTRUST, 's', "Trust certificate for a given purpose"},
     {"clrreject", OPT_CLRREJECT, '-',
      "Clears all the prohibited or rejected uses of the certificate"},
-    {"badsig", OPT_BADSIG, '-', "Corrupt last byte of certificate signature (for test)"},
-    {"", OPT_MD, '-', "Any supported digest"},
-    {"preserve_dates", OPT_PRESERVE_DATES, '-', "preserve existing dates when signing"},
+    {"addreject", OPT_ADDREJECT, 's',
+     "Reject certificate for a given purpose"},
+
+    OPT_R_OPTIONS,
+#ifndef OPENSSL_NO_ENGINE
+    {"engine", OPT_ENGINE, 's', "Use engine, possibly a hardware device"},
+#endif
+    OPT_PROV_OPTIONS,
     {NULL}
 };
 
@@ -167,7 +189,7 @@ int x509_main(int argc, char **argv)
     ASN1_OBJECT *objtmp = NULL;
     BIO *out = NULL;
     CONF *extconf = NULL;
-    EVP_PKEY *Upkey = NULL, *CApkey = NULL, *fkey = NULL;
+    EVP_PKEY *signkey = NULL, *CAkey = NULL, *pubkey = NULL;
     int newcert = 0;
     char *subj = NULL;
     X509_NAME *fsubj = NULL;
@@ -179,17 +201,18 @@ int x509_main(int argc, char **argv)
     X509_REQ *req = NULL, *rq = NULL;
     X509_STORE *ctx = NULL;
     const EVP_MD *digest = NULL;
-    char *CAkeyfile = NULL, *CAserial = NULL, *fkeyfile = NULL, *alias = NULL;
+    char *CAkeyfile = NULL, *CAserial = NULL, *pubkeyfile = NULL, *alias = NULL;
     char *checkhost = NULL, *checkemail = NULL, *checkip = NULL, *exts = NULL;
     char *extsect = NULL, *extfile = NULL, *passin = NULL, *passinarg = NULL;
-    char *infile = NULL, *outfile = NULL, *keyfile = NULL, *CAfile = NULL;
+    char *infile = NULL, *outfile = NULL, *signkeyfile = NULL, *CAfile = NULL;
     char *prog;
-    int x509req = 0, days = DEF_DAYS, modulus = 0, pubkey = 0, pprint = 0;
+    int days = UNSET_DAYS; /* not explicitly set */
+    int x509toreq = 0, modulus = 0, print_pubkey = 0, pprint = 0;
     int CAformat = FORMAT_PEM, CAkeyformat = FORMAT_PEM;
     int fingerprint = 0, reqfile = 0, checkend = 0;
     int informat = FORMAT_PEM, outformat = FORMAT_PEM, keyformat = FORMAT_PEM;
     int next_serial = 0, subject_hash = 0, issuer_hash = 0, ocspid = 0;
-    int noout = 0, sign_flag = 0, CA_flag = 0, CA_createserial = 0, email = 0;
+    int noout = 0, CA_createserial = 0, email = 0;
     int ocsp_uri = 0, trustout = 0, clrtrust = 0, clrreject = 0, aliasout = 0;
     int ret = 1, i, num = 0, badsig = 0, clrext = 0, nocert = 0;
     int text = 0, serial = 0, subject = 0, issuer = 0, startdate = 0, ext = 0;
@@ -263,9 +286,12 @@ int x509_main(int argc, char **argv)
                 goto opthelp;
             break;
         case OPT_DAYS:
-            if (preserve_dates)
-                goto opthelp;
             days = atoi(opt_arg());
+            if (days < -1) {
+                BIO_printf(bio_err, "%s: -days parameter arg must be >= -1\n",
+                           prog);
+                goto end;
+            }
             break;
         case OPT_PASSIN:
             passinarg = opt_arg();
@@ -285,12 +311,10 @@ int x509_main(int argc, char **argv)
             extsect = opt_arg();
             break;
         case OPT_SIGNKEY:
-            keyfile = opt_arg();
-            sign_flag = ++num;
+            signkeyfile = opt_arg();
             break;
         case OPT_CA:
             CAfile = opt_arg();
-            CA_flag = ++num;
             break;
         case OPT_CAKEY:
             CAkeyfile = opt_arg();
@@ -310,7 +334,7 @@ int x509_main(int argc, char **argv)
             newcert = 1;
             break;
         case OPT_FORCE_PUBKEY:
-            fkeyfile = opt_arg();
+            pubkeyfile = opt_arg();
             break;
         case OPT_SUBJ:
             subj = opt_arg();
@@ -373,10 +397,10 @@ int x509_main(int argc, char **argv)
             modulus = ++num;
             break;
         case OPT_PUBKEY:
-            pubkey = ++num;
+            print_pubkey = ++num;
             break;
         case OPT_X509TOREQ:
-            x509req = ++num;
+            x509toreq = 1;
             break;
         case OPT_TEXT:
             text = ++num;
@@ -479,8 +503,6 @@ int x509_main(int argc, char **argv)
             checkip = opt_arg();
             break;
         case OPT_PRESERVE_DATES:
-            if (days != DEF_DAYS)
-                goto opthelp;
             preserve_dates = 1;
             break;
         case OPT_MD:
@@ -494,6 +516,13 @@ int x509_main(int argc, char **argv)
     if (argc != 0)
         goto opthelp;
 
+    if (preserve_dates && days != UNSET_DAYS) {
+        BIO_printf(bio_err, "Cannot use -preserve_dates with -days option\n");
+        goto end;
+    }
+    if (days == UNSET_DAYS)
+        days = DEFAULT_DAYS;
+
     if (!app_passwd(passinarg, NULL, &passin, NULL)) {
         BIO_printf(bio_err, "Error getting password\n");
         goto end;
@@ -504,37 +533,60 @@ int x509_main(int argc, char **argv)
         goto end;
 
     if (newcert && infile != NULL) {
-        BIO_printf(bio_err, "The -in option must not be used since -new is set\n");
+        BIO_printf(bio_err, "The -in option cannot be used with -new\n");
+        goto end;
+    }
+    if (newcert && reqfile) {
+        BIO_printf(bio_err,
+                   "The -req option cannot be used with -new\n");
         goto end;
     }
-    if (fkeyfile != NULL) {
-        fkey = load_pubkey(fkeyfile, keyformat, 0, NULL, e, "forced key");
-        if (fkey == NULL)
+    if (signkeyfile != NULL) {
+        signkey = load_key(signkeyfile, keyformat, 0, passin, e, "private key");
+        if (signkey == NULL)
+            goto end;
+    }
+    if (pubkeyfile != NULL) {
+        if ((pubkey = load_pubkey(pubkeyfile, keyformat, 0, NULL, e,
+                                  "explicitly set public key")) == NULL)
             goto end;
     }
 
-    if (newcert && subj == NULL) {
-        BIO_printf(bio_err,
-                   "The -new option requires a subject to be set using -subj\n");
-        goto end;
+    if (newcert) {
+        if (subj == NULL) {
+            BIO_printf(bio_err,
+                       "The -new option requires a subject to be set using -subj\n");
+            goto end;
+        }
+        if (signkeyfile == NULL && pubkeyfile == NULL) {
+            BIO_printf(bio_err,
+                       "The -new option without -signkey requires using -force_pubkey\n");
+            goto end;
+        }
     }
     if (subj != NULL
             && (fsubj = parse_name(subj, chtype, multirdn, "subject")) == NULL)
         goto end;
 
-    if (CAkeyfile == NULL && CA_flag && CAformat == FORMAT_PEM) {
+    if (CAkeyfile == NULL)
         CAkeyfile = CAfile;
-    } else if (CA_flag && CAkeyfile == NULL) {
-        BIO_printf(bio_err,
-                   "Need to specify a CAkey if using the CA command\n");
-        goto end;
-    } else if (!CA_flag && CAkeyfile != NULL) {
+    if (CAfile != NULL) {
+        if (signkeyfile != NULL) {
+            BIO_printf(bio_err, "Cannot use both -signkey and -CA option\n");
+            goto end;
+        }
+    } else if (CAkeyfile != NULL) {
         BIO_printf(bio_err,
-                   "Ignoring -CAkey option since no -CA option is given\n");
+                   "Warning: ignoring -CAkey option since no -CA option is given\n");
     }
 
-    if (extfile != NULL) {
+    if (extfile == NULL) {
+        if (extsect != NULL)
+            BIO_printf(bio_err,
+                       "Warning: ignoring -extensions option without -extfile\n");
+    } else {
         X509V3_CTX ctx2;
+
         if ((extconf = app_load_config(extfile)) == NULL)
             goto end;
         if (extsect == NULL) {
@@ -566,15 +618,16 @@ int x509_main(int argc, char **argv)
         }
         i = do_X509_REQ_verify(req, pkey, vfyopts);
         if (i < 0) {
-            BIO_printf(bio_err, "Request self-signature verification error\n");
+            BIO_printf(bio_err,
+                       "Error while verifying certificate request self-signature\n");
             goto end;
         }
         if (i == 0) {
             BIO_printf(bio_err,
-                       "Request self-signature did not match the certificate request\n");
+                       "Certificate request self-signature did not match the contents\n");
             goto end;
         } else {
-            BIO_printf(bio_err, "Request self-signature ok\n");
+            BIO_printf(bio_err, "Certificate request self-signature ok\n");
         }
 
         print_name(bio_err, "subject=", X509_REQ_get_subject_name(req),
@@ -582,16 +635,17 @@ int x509_main(int argc, char **argv)
     }
 
     if (reqfile || newcert) {
-        X509_NAME *n;
-
-        if (!sign_flag && CAkeyfile == NULL) {
+        if (preserve_dates)
+            BIO_printf(bio_err,
+                       "Warning: ignoring -preserve_dates option with -req or -new\n");
+        preserve_dates = 0;
+        if (signkeyfile == NULL && CAkeyfile == NULL) {
             BIO_printf(bio_err,
-                       "We need a private key to sign with, use -signkey or -CAkey or -CA <file> with private key\n");
+                       "We need a private key to sign with, use -signkey or -CAkey or -CA with private key\n");
             goto end;
         }
         if ((x = X509_new_ex(app_get0_libctx(), app_get0_propq())) == NULL)
             goto end;
-
         if (sno == NULL) {
             sno = ASN1_INTEGER_new();
             if (sno == NULL || !rand_serial(NULL, sno))
@@ -603,28 +657,23 @@ int x509_main(int argc, char **argv)
         } else if (!X509_set_serialNumber(x, sno)) {
             goto end;
         }
-
-        n = req == NULL ? fsubj : X509_REQ_get_subject_name(req);
-        if (!X509_set_issuer_name(x, n) || !X509_set_subject_name(x, n))
-            goto end;
-        if (!set_cert_times(x, NULL, NULL, days))
-            goto end;
-
-        if ((fkey != NULL || req != NULL)
-            && !X509_set_pubkey(x, fkey != NULL ? fkey :
-                                X509_REQ_get0_pubkey(req)))
-            goto end;
+        /* TODO: (optionally) copy X.509 extensions from req */
     } else {
         x = load_cert_pass(infile, 1, passin, "certificate");
         if (x == NULL)
             goto end;
-        if (fkey != NULL && !X509_set_pubkey(x, fkey))
-            goto end;
-        if (fsubj != NULL && !X509_set_subject_name(x, fsubj))
-            goto end;
     }
+    if ((fsubj != NULL || req != NULL)
+        && !X509_set_subject_name(x, fsubj != NULL ? fsubj :
+                                  X509_REQ_get_subject_name(req)))
+        goto end;
+    if ((pubkey != NULL || signkey != NULL || req != NULL)
+        && !X509_set_pubkey(x, pubkey != NULL ? pubkey :
+                            signkey != NULL ? signkey :
+                            X509_REQ_get0_pubkey(req)))
+        goto end;
 
-    if (CA_flag) {
+    if (CAfile != NULL) {
         xca = load_cert_pass(CAfile, 1, passin, "CA certificate");
         if (xca == NULL)
             goto end;
@@ -636,6 +685,7 @@ int x509_main(int argc, char **argv)
 
     if (!noout || text || next_serial)
         OBJ_create("2.99999.3", "SET.ex3", "SET x509v3 extension 3");
+    /* TODO: why is this strange object created (and no error checked)? */
 
     if (alias)
         X509_alias_set1(x, (unsigned char *)alias, -1);
@@ -661,6 +711,57 @@ int x509_main(int argc, char **argv)
         objtmp = NULL;
     }
 
+    if (x509toreq) { /* also works but makes little sense together with -req */
+        if (signkey == NULL) {
+            BIO_printf(bio_err, "Must specify request key using -signkey\n");
+            goto end;
+        }
+
+        if ((rq = X509_to_X509_REQ(x, signkey, digest)) == NULL)
+            goto end;
+        /* TODO: (optionally) copy X.509 extensions from x */
+        if (!noout) {
+            if (outformat == FORMAT_ASN1) {
+                X509_REQ_print_ex(out, rq, get_nameopt(), X509_FLAG_COMPAT);
+                i = i2d_X509_bio(out, x);
+            } else {
+                i = PEM_write_bio_X509_REQ(out, rq);
+            }
+            if (!i) {
+                BIO_printf(bio_err,
+                           "Unable to write certificate request\n");
+                goto end;
+            }
+        }
+        noout = 1;
+    } else if (signkey != NULL) {
+        if (!sign(x, signkey, x /* self-issuing */, sigopts, days, clrext,
+                  digest, extconf, extsect, preserve_dates))
+            goto end;
+    } else if (CAfile != NULL) {
+        if (!reqfile && !newcert) { /* certificate should be self-signed */
+            X509_STORE_CTX *xsc = X509_STORE_CTX_new();
+
+            if (xsc == NULL || !X509_STORE_CTX_init(xsc, ctx, x, NULL)) {
+                BIO_printf(bio_err, "Error initialising X509 store\n");
+                X509_STORE_CTX_free(xsc);
+                goto end;
+            }
+            X509_STORE_CTX_set_cert(xsc, x);
+            X509_STORE_CTX_set_flags(xsc, X509_V_FLAG_CHECK_SS_SIGNATURE);
+            i = X509_verify_cert(xsc);
+            X509_STORE_CTX_free(xsc);
+            if (i <= 0)
+                goto end;
+        }
+        if ((CAkey = load_key(CAkeyfile, CAkeyformat,
+                              0, passin, e, "CA private key")) == NULL)
+            goto end;
+        if (!x509_certify(ctx, CAfile, digest, x, xca, CAkey, sigopts,
+                          CAserial, CA_createserial, days, clrext,
+                          extconf, extsect, sno, preserve_dates))
+            goto end;
+    }
     if (badsig) {
         const ASN1_BIT_STRING *signature;
 
@@ -668,10 +769,12 @@ int x509_main(int argc, char **argv)
         corrupt_signature(signature);
     }
 
-    if (num) {
+    if (num) { /* TODO remove this needless guard and extra indentation below */
+        /* Process print options in the given order, as indicated by index i */
         for (i = 1; i <= num; i++) {
             if (issuer == i) {
-                print_name(out, "issuer=", X509_get_issuer_name(x), get_nameopt());
+                print_name(out, "issuer=", X509_get_issuer_name(x),
+                           get_nameopt());
             } else if (subject == i) {
                 print_name(out, "subject=",
                            X509_get_subject_name(x), get_nameopt());
@@ -695,8 +798,9 @@ int x509_main(int argc, char **argv)
                 ASN1_INTEGER_free(ser);
                 BIO_puts(out, "\n");
             } else if (email == i || ocsp_uri == i) {
-                int j;
                 STACK_OF(OPENSSL_STRING) *emlst;
+                int j;
+
                 if (email == i)
                     emlst = X509_get1_email(x);
                 else
@@ -707,6 +811,7 @@ int x509_main(int argc, char **argv)
                 X509_email_free(emlst);
             } else if (aliasout == i) {
                 unsigned char *alstr;
+
                 alstr = X509_alias_get0(x, NULL);
                 if (alstr)
                     BIO_printf(out, "%s\n", alstr);
@@ -714,23 +819,20 @@ int x509_main(int argc, char **argv)
                     BIO_puts(out, "<No Alias>\n");
             } else if (subject_hash == i) {
                 BIO_printf(out, "%08lx\n", X509_subject_name_hash(x));
-            }
 #ifndef OPENSSL_NO_MD5
-            else if (subject_hash_old == i) {
+            } else if (subject_hash_old == i) {
                 BIO_printf(out, "%08lx\n", X509_subject_name_hash_old(x));
-            }
 #endif
-            else if (issuer_hash == i) {
+            } else if (issuer_hash == i) {
                 BIO_printf(out, "%08lx\n", X509_issuer_name_hash(x));
-            }
 #ifndef OPENSSL_NO_MD5
-            else if (issuer_hash_old == i) {
+            } else if (issuer_hash_old == i) {
                 BIO_printf(out, "%08lx\n", X509_issuer_name_hash_old(x));
-            }
 #endif
-            else if (pprint == i) {
+            } else if (pprint == i) {
                 X509_PURPOSE *ptmp;
                 int j;
+
                 BIO_printf(out, "Certificate purposes:\n");
                 for (j = 0; j < X509_PURPOSE_get_count(); j++) {
                     ptmp = X509_PURPOSE_get0(j);
@@ -741,7 +843,8 @@ int x509_main(int argc, char **argv)
 
                 pkey = X509_get0_pubkey(x);
                 if (pkey == NULL) {
-                    BIO_printf(bio_err, "Modulus=unavailable\n");
+                    BIO_printf(bio_err,
+                               "Modulus unavailable: cannot get key\n");
                     goto end;
                 }
                 BIO_printf(out, "Modulus=");
@@ -760,10 +863,10 @@ int x509_main(int argc, char **argv)
                     BN_print(out, dsapub);
                     BN_free(dsapub);
                 } else {
-                    BIO_printf(out, "Wrong Algorithm type");
+                    BIO_printf(out, "No modulus for this public key type");
                 }
                 BIO_printf(out, "\n");
-            } else if (pubkey == i) {
+            } else if (print_pubkey == i) {
                 EVP_PKEY *pkey;
 
                 pkey = X509_get0_pubkey(x);
@@ -801,57 +904,6 @@ int x509_main(int argc, char **argv)
                     BIO_printf(out, "%02X%c", md[j], (j + 1 == (int)n)
                                ? '\n' : ':');
                 }
-            }
-
-            /* should be in the library */
-            else if (sign_flag == i && x509req == 0) {
-                if (Upkey == NULL) {
-                    Upkey = load_key(keyfile, keyformat, 0,
-                                     passin, e, "private key");
-                    if (Upkey == NULL)
-                        goto end;
-                }
-                if (fkey == NULL && !X509_set_pubkey(x, Upkey))
-                    goto end;
-                if (!sign(x, Upkey, x /* self-issuing */, sigopts, days, clrext,
-                          digest, extconf, extsect, preserve_dates)) {
-                    goto end;
-                }
-            } else if (CA_flag == i) {
-                if (CAkeyfile != NULL) {
-                    CApkey = load_key(CAkeyfile, CAkeyformat,
-                                      0, passin, e, "CA private key");
-                    if (CApkey == NULL)
-                        goto end;
-                }
-
-                if (!x509_certify(ctx, CAfile, digest, x, xca,
-                                  CApkey, sigopts,
-                                  CAserial, CA_createserial, days, clrext,
-                                  extconf, extsect, sno, reqfile, preserve_dates))
-                    goto end;
-            } else if (x509req == i) {
-                EVP_PKEY *pk;
-
-                if (keyfile == NULL) {
-                    BIO_printf(bio_err, "No request key file specified\n");
-                    goto end;
-                } else {
-                    pk = load_key(keyfile, keyformat, 0,
-                                  passin, e, "request key");
-                    if (pk == NULL)
-                        goto end;
-                }
-
-                rq = X509_to_X509_REQ(x, pk, digest);
-                EVP_PKEY_free(pk);
-                if (rq == NULL)
-                    goto end;
-                if (!noout) {
-                    X509_REQ_print_ex(out, rq, get_nameopt(), X509_FLAG_COMPAT);
-                    PEM_write_bio_X509_REQ(out, rq);
-                }
-                noout = 1;
             } else if (ocspid == i) {
                 X509_ocspid_print(out, x);
             } else if (ext == i) {
@@ -907,9 +959,9 @@ int x509_main(int argc, char **argv)
     X509_REQ_free(req);
     X509_free(x);
     X509_free(xca);
-    EVP_PKEY_free(Upkey);
-    EVP_PKEY_free(CApkey);
-    EVP_PKEY_free(fkey);
+    EVP_PKEY_free(signkey);
+    EVP_PKEY_free(CAkey);
+    EVP_PKEY_free(pubkey);
     sk_OPENSSL_STRING_free(sigopts);
     sk_OPENSSL_STRING_free(vfyopts);
     X509_REQ_free(rq);
@@ -957,50 +1009,27 @@ static ASN1_INTEGER *x509_load_serial(const char *CAfile,
     return bs;
 }
 
-static int x509_certify(X509_STORE *ctx, const char *CAfile, const EVP_MD *digest,
+static int x509_certify(X509_STORE *ctx, const char *CAfile,
+                        const EVP_MD *digest,
                         X509 *x, X509 *xca, EVP_PKEY *pkey,
                         STACK_OF(OPENSSL_STRING) *sigopts,
                         const char *serialfile, int create,
                         int days, int clrext, CONF *conf, const char *section,
-                        ASN1_INTEGER *sno, int reqfile, int preserve_dates)
+                        ASN1_INTEGER *sno, int preserve_dates)
 {
     int ret = 0;
     ASN1_INTEGER *bs = NULL;
-    X509_STORE_CTX *xsc = NULL;
-    EVP_PKEY *upkey;
 
-    upkey = X509_get0_pubkey(xca);
-    if (upkey == NULL) {
-        BIO_printf(bio_err, "Error obtaining CA X509 public key\n");
+    if (!X509_check_private_key(xca, pkey)) {
+        BIO_printf(bio_err,
+                   "CA certificate and CA private key do not match\n");
         goto end;
     }
-    EVP_PKEY_copy_parameters(upkey, pkey);
 
-    xsc = X509_STORE_CTX_new();
-    if (xsc == NULL || !X509_STORE_CTX_init(xsc, ctx, x, NULL)) {
-        BIO_printf(bio_err, "Error initialising X509 store\n");
-        goto end;
-    }
     if (sno)
         bs = sno;
     else if ((bs = x509_load_serial(CAfile, serialfile, create)) == NULL)
         goto end;
-
-    /*
-     * NOTE: this certificate can/should be self-signed, unless it was a
-     * certificate request in which case it is not.
-     */
-    X509_STORE_CTX_set_cert(xsc, x);
-    X509_STORE_CTX_set_flags(xsc, X509_V_FLAG_CHECK_SS_SIGNATURE);
-    if (!reqfile && X509_verify_cert(xsc) <= 0)
-        goto end;
-
-    if (!X509_check_private_key(xca, pkey)) {
-        BIO_printf(bio_err,
-                   "CA certificate and CA private key do not match\n");
-        goto end;
-    }
-
     if (!X509_set_serialNumber(x, bs))
         goto end;
 
@@ -1010,7 +1039,6 @@ static int x509_certify(X509_STORE *ctx, const char *CAfile, const EVP_MD *diges
 
     ret = 1;
  end:
-    X509_STORE_CTX_free(xsc);
     if (!sno)
         ASN1_INTEGER_free(bs);
     return ret;
diff --git a/doc/man1/openssl-x509.pod.in b/doc/man1/openssl-x509.pod.in
index e708486508..1540162ba6 100644
--- a/doc/man1/openssl-x509.pod.in
+++ b/doc/man1/openssl-x509.pod.in
@@ -9,70 +9,70 @@ openssl-x509 - Certificate display and signing command
 
 B<openssl> B<x509>
 [B<-help>]
+[B<-in> I<filename>|I<uri>]
+[B<-passin> I<arg>]
+[B<-new>]
+[B<-x509toreq>]
+[B<-req>]
 [B<-inform> B<DER>|B<PEM>]
-[B<-outform> B<DER>|B<PEM>]
+[B<-vfyopt> I<nm>:I<v>]
+[B<-signkey> I<filename>|I<uri>]
 [B<-keyform> B<DER>|B<PEM>|B<P12>|B<ENGINE>]
-[B<-CAform> B<DER>|B<PEM>|B<P12>]
-[B<-CAkeyform> B<DER>|B<PEM>|B<P12>|B<ENGINE>]
-[B<-in> I<filename>]
 [B<-out> I<filename>]
+[B<-outform> B<DER>|B<PEM>]
+[B<-nocert>]
+[B<-noout>]
+[B<-text>]
+[B<-certopt> I<option>]
+[B<-fingerprint>]
+[B<-alias>]
 [B<-serial>]
+[B<-startdate>]
+[B<-enddate>]
+[B<-dates>]
+[B<-subject>]
+[B<-issuer>]
+{- $OpenSSL::safe::opt_name_synopsis -}
+[B<-email>]
 [B<-hash>]
 [B<-subject_hash>]
 [B<-subject_hash_old>]
 [B<-issuer_hash>]
 [B<-issuer_hash_old>]
+[B<-ext> I<extensions>]
 [B<-ocspid>]
-[B<-subject>]
-[B<-issuer>]
-[B<-email>]
 [B<-ocsp_uri>]
-[B<-startdate>]
-[B<-enddate>]
 [B<-purpose>]
-[B<-dates>]
-[B<-checkend> I<num>]
-[B<-modulus>]
 [B<-pubkey>]
-[B<-fingerprint>]
-[B<-alias>]
-[B<-noout>]
-[B<-trustout>]
-[B<-clrtrust>]
-[B<-clrreject>]
-[B<-addtrust> I<arg>]
-[B<-addreject> I<arg>]
-[B<-setalias> I<arg>]
-[B<-days> I<arg>]
-[B<-set_serial> I<n>]
-[B<-signkey> I<filename>|I<uri>]
-[B<-badsig>]
-[B<-passin> I<arg>]
-[B<-x509toreq>]
-[B<-req>]
-[B<-CA> I<filename>]
-[B<-CAkey> I<filename>|I<uri>]
-[B<-CAcreateserial>]
-[B<-CAserial> I<filename>]
-[B<-new>]
-[B<-next_serial>]
-[B<-nocert>]
-[B<-force_pubkey> I<filename>]
-[B<-subj> I<arg>]
-[B<-text>]
-[B<-ext> I<extensions>]
-[B<-certopt> I<option>]
+[B<-modulus>]
+[B<-checkend> I<num>]
 [B<-checkhost> I<host>]
 [B<-checkemail> I<host>]
 [B<-checkip> I<ipaddr>]
-[B<-I<digest>>]
+[B<-set_serial> I<n>]
+[B<-next_serial>]
+[B<-days> I<arg>]
+[B<-preserve_dates>]
+[B<-subj> I<arg>]
+[B<-force_pubkey> I<filename>]
 [B<-clrext>]
 [B<-extfile> I<filename>]
 [B<-extensions> I<section>]
 [B<-sigopt> I<nm>:I<v>]
-[B<-vfyopt> I<nm>:I<v>]
-[B<-preserve_dates>]
-{- $OpenSSL::safe::opt_name_synopsis -}
+[B<-badsig>]
+[B<-I<digest>>]
+[B<-CA> I<filename>|I<uri>]
+[B<-CAform> B<DER>|B<PEM>|B<P12>]
+[B<-CAkey> I<filename>|I<uri>]
+[B<-CAkeyform> B<DER>|B<PEM>|B<P12>|B<ENGINE>]
+[B<-CAserial> I<filename>]
+[B<-CAcreateserial>]
+[B<-trustout>]
+[B<-setalias> I<arg>]
+[B<-clrtrust>]
+[B<-addtrust> I<arg>]
+[B<-clrreject>]
+[B<-addreject> I<arg>]
 {- $OpenSSL::safe::opt_r_synopsis -}
 {- $OpenSSL::safe::opt_engine_synopsis -}{- $OpenSSL::safe::opt_provider_synopsis -}
 
@@ -80,10 +80,11 @@ B<openssl> B<x509>
 
 =head1 DESCRIPTION
 
-This command is a multi-purposes certificate command. It can
-be used to display certificate information, convert certificates to
-various forms, sign certificate requests like a "mini CA" or edit
-certificate trust settings.
+This command is a multi-purposes certificate handling command.
+It can be used to print certificate information,
+convert certificates to various forms, edit certificate trust settings,
+generate certificates from scratch or from certificating requests
+and then self-signing them or signing them like a "micro CA".
 
 Since there are a large number of options they will split up into
 various sections.
@@ -98,356 +99,369 @@ various sections.
 
 Print out a usage message.
 
+=item B<-in> I<filename>|I<uri>
+
+If the B<-req> option is not used this specifies the input
+to read a certificate from or standard input if this option is not specified.
+With the B<-req> option this specifies a certificate request file.
+
+=item B<-passin> I<arg>
+
+The key and certificate file password source.
+For more information about the format of I<arg>
+see L<openssl-passphrase-options(1)>.
+
+=item B<-new>
+
+Generate a certificate from scratch, not using an input certificate
+or certificate request. So the B<-in> option must not be used in this case.
+Instead, the B<-subj> option needs to be given.
+The public key to include can be given with the B<-force_pubkey> option
+and defaults to the key given with the B<-signkey> option,
+which implies self-signature.
+
+=item B<-x509toreq>
+
+Output a certificate request (rather than a certificate).
+The B<-signkey> option must be used to provide the private key for self-signing;
+the corresponding public key is placed in the subjectPKInfo field.
+
+Any X.509 extensions included in an input file are ignored.
+X.509 extensions to be added can be specified using the B<-extfile> option.
+
+=item B<-req>
+
+By default a certificate is expected on input.
+With this option a certificate request is expected instead,
+which is transformed into a certificate.
+
+Any X.509 extensions included in the request file are ignored.
+X.509 extensions to be added can be specified using the B<-extfile> option.
+
 =item B<-inform> B<DER>|B<PEM>
 
-The CSR input format; the default is B<PEM>.
+The CSR input file format; the default is B<PEM>.
 See L<openssl-format-options(1)> for details.
 
-The input is normally an X.509 certificate file of any format,
-but this can change if other options such as B<-req> are used.
+=item B<-vfyopt> I<nm>:I<v>
 
-B<-outform> B<DER>|B<PEM>
+Pass options to the signature algorithm during verify operations.
+Names and values of these options are algorithm-specific.
 
-The output format; the default is B<PEM>.
-See L<openssl-format-options(1)> for details.
+=item B<-signkey> I<filename>|I<uri>
 
-=item B<-in> I<filename>
+This option causes the new certificate or certificate request
+to be self-signed using the supplied private key.
+This cannot be used in conjunction with the B<-CA> option.
 
-This specifies the input filename to read a certificate from or standard input
-if this option is not specified.
+It sets the issuer name to the subject name (i.e., makes it self-issued)
+and changes the public key to the supplied value (unless overridden
+by B<-force_pubkey>).
+Unless the B<-preserve_dates> option is supplied,
+it sets the validity start date to the current time
+and the end date to a value determined by the B<-days> option.
+Unless the B<-clrext> option is supplied, it retains all certificate extensions
+except for any subject identifier and authority key identifier.
+For those, new values are generated unless prohibited by configuration.
 
-=item B<-out> I<filename>
+=item B<-keyform> B<DER>|B<PEM>|B<P12>|B<ENGINE>
 
-This specifies the output filename to write to or standard output by
-default.
+The key input format; the default is B<PEM>.
+The only value with effect is B<ENGINE>; all others have become obsolete.
+See L<openssl-format-options(1)> for details.
 
-=item B<-I<digest>>
+=item B<-out> I<filename>
 
-The digest to use.
-This affects any signing or display option that uses a message
-digest, such as the B<-fingerprint>, B<-signkey> and B<-CA> options.
-Any digest supported by the L<openssl-dgst(1)> command can be used.
-If not specified then SHA1 is used with B<-fingerprint> or
-the default digest for the signing algorithm is used, typically SHA256.
+This specifies the output filename to write to or standard output by default.
 
-=item B<-preserve_dates>
+=item B<-outform> B<DER>|B<PEM>
 
-When signing a certificate, preserve the "notBefore" and "notAfter" dates
-instead of adjusting them to current time and duration.
-Cannot be used with the B<-days> option.
+The output format; the default is B<PEM>.
+See L<openssl-format-options(1)> for details.
 
-{- $OpenSSL::safe::opt_r_synopsis -}
+=item B<-nocert>
 
-{- $OpenSSL::safe::opt_engine_item -}
+Do not output a certificate (except for printing as requested by below options).
 
-{- $OpenSSL::safe::opt_provider_item -}
+=item B<-noout>
+
+This option prevents output except for printing as requested by below options.
 
 =back
 
-=head2 Display Options
+=head2 Certificate Printing Options
 
-Note: the B<-alias> and B<-purpose> options are also display options
+Note: the B<-alias> and B<-purpose> options are also printing options
 but are described in the L</Trust Settings> section.
 
 =over 4
 
 =item B<-text>
 
-Prints out the certificate in text form. Full details are output including the
+Prints out the certificate in text form. Full details are printed including the
 public key, signature algorithms, issuer and subject names, serial number
 any extensions present and any trust settings.
 
-=item B<-ext> I<extensions>
-
-Prints out the certificate extensions in text form. Extensions are specified
-with a comma separated string, e.g., "subjectAltName,subjectKeyIdentifier".
-See the L<x509v3_config(5)> manual page for the extension names.
-
 =item B<-certopt> I<option>
 
-Customise the output format used with B<-text>. The I<option> argument
-can be a single option or multiple options separated by commas. The
-B<-certopt> switch may be also be used more than once to set multiple
-options. See the L</Text Options> section for more information.
-
-=item B<-checkhost> I<host>
+Customise the print format used with B<-text>. The I<option> argument
+can be a single option or multiple options separated by commas.
+The B<-certopt> switch may be also be used more than once to set multiple
+options. See the L</Text Printing Flags> section for more information.
 
-Check that the certificate matches the specified host.
+=item B<-fingerprint>
 
-=item B<-checkemail> I<email>
+Calculates and prints the digest of the DER encoded version of the entire
+certificate (see digest options).
+This is commonly called a "fingerprint". Because of the nature of message
+digests, the fingerprint of a certificate is unique to that certificate and
+two certificates with the same fingerprint can be considered to be the same.
 
-Check that the certificate matches the specified email address.
+=item B<-alias>
 
-=item B<-checkip> I<ipaddr>
+Prints the certificate "alias" (nickname), if any.
 
-Check that the certificate matches the specified IP address.
+=item B<-serial>
 
-=item B<-noout>
+Prints the certificate serial number.
 
-This option prevents output of the encoded version of the certificate.
+=item B<-startdate>
 
-=item B<-pubkey>
+Prints out the start date of the certificate, that is the notBefore date.
 
-Outputs the certificate's SubjectPublicKeyInfo block in PEM format.
+=item B<-enddate>
 
-=item B<-modulus>
+Prints out the expiry date of the certificate, that is the notAfter date.
 
-This option prints out the value of the modulus of the public key
-contained in the certificate.
+=item B<-dates>
 
-=item B<-serial>
+Prints out the start and expiry dates of a certificate.
 
-Outputs the certificate serial number.
+=item B<-subject>
 
-=item B<-subject_hash>
+Prints the subject name.
 
-Outputs the "hash" of the certificate subject name. This is used in OpenSSL to
-form an index to allow certificates in a directory to be looked up by subject
-name.
+=item B<-issuer>
 
-=item B<-issuer_hash>
+Prints the issuer name.
 
-Outputs the "hash" of the certificate issuer name.
+{- $OpenSSL::safe::opt_name_item -}
 
-=item B<-ocspid>
+=item B<-email>
 
-Outputs the OCSP hash values for the subject name and public key.
+Prints the email address(es) if any.
 
 =item B<-hash>
 
 Synonym for "-subject_hash" for backward compatibility reasons.
 
+=item B<-subject_hash>
+
+Prints the "hash" of the certificate subject name. This is used in OpenSSL to
+form an index to allow certificates in a directory to be looked up by subject
+name.
+
 =item B<-subject_hash_old>
 
-Outputs the "hash" of the certificate subject name using the older algorithm
+Prints the "hash" of the certificate subject name using the older algorithm
 as used by OpenSSL before version 1.0.0.
 
+=item B<-issuer_hash>
+
+Prints the "hash" of the certificate issuer name.
+
 =item B<-issuer_hash_old>
 
-Outputs the "hash" of the certificate issuer name using the older algorithm
+Prints the "hash" of the certificate issuer name using the older algorithm
 as used by OpenSSL before version 1.0.0.
 
-=item B<-subject>
+=item B<-ext> I<extensions>
 
-Outputs the subject name.
+Prints out the certificate extensions in text form. Extensions are specified
+with a comma separated string, e.g., "subjectAltName,subjectKeyIdentifier".
+See the L<x509v3_config(5)> manual page for the extension names.
 
-=item B<-issuer>
+=item B<-ocspid>
 
-Outputs the issuer name.
+Prints the OCSP hash values for the subject name and public key.
 
-{- $OpenSSL::safe::opt_name_item -}
+=item B<-ocsp_uri>
 
-=item B<-email>
+Prints the OCSP responder address(es) if any.
 
-Outputs the email address(es) if any.
+=item B<-purpose>
 
-=item B<-ocsp_uri>
+This option performs tests on the certificate extensions and prints
+the results. For a more complete description see the
+L</CERTIFICATE EXTENSIONS> section.
 
-Outputs the OCSP responder address(es) if any.
+=item B<-pubkey>
 
-=item B<-startdate>
+Prints the certificate's SubjectPublicKeyInfo block in PEM format.
 
-Prints out the start date of the certificate, that is the notBefore date.
+=item B<-modulus>
 
-=item B<-enddate>
+This option prints out the value of the modulus of the public key
+contained in the certificate.
 
-Prints out the expiry date of the certificate, that is the notAfter date.
+=back
 
-=item B<-dates>
+=head2 Certificate Checking Options
 
-Prints out the start and expiry dates of a certificate.
+=over 4
 
 =item B<-checkend> I<arg>
 
 Checks if the certificate expires within the next I<arg> seconds and exits
 nonzero if yes it will expire or zero if not.
 
-=item B<-fingerprint>
+=item B<-checkhost> I<host>
 
-Calculates and outputs the digest of the DER encoded version of the entire
-certificate (see digest options).
-This is commonly called a "fingerprint". Because of the nature of message
-digests, the fingerprint of a certificate is unique to that certificate and
-two certificates with the same fingerprint can be considered to be the same.
+Check that the certificate matches the specified host.
 
-=back
+=item B<-checkemail> I<email>
 
-=head2 Trust Settings
+Check that the certificate matches the specified email address.
 
-A B<trusted certificate> is an ordinary certificate which has several
-additional pieces of information attached to it such as the permitted
-and prohibited uses of the certificate and an "alias".
+=item B<-checkip> I<ipaddr>
 
-Normally when a certificate is being verified at least one certificate
-must be "trusted". By default a trusted certificate must be stored
-locally and must be a root CA: any certificate chain ending in this CA
-is then usable for any purpose.
+Check that the certificate matches the specified IP address.
 
-Trust settings currently are only used with a root CA. They allow a finer
-control over the purposes the root CA can be used for. For example a CA
-may be trusted for SSL client but not SSL server use.
+=back
 
-See the description in L<openssl-verify(1)> for more information
-on the meaning of trust settings.
+=head2 Certificate Output Options
 
-Future versions of OpenSSL will recognize trust settings on any
-certificate: not just root CAs.
+=over 4
 
+=item B<-set_serial> I<n>
 
-=over 4
+Specifies the serial number to use. This option can be used with either
+the B<-signkey> or B<-CA> options. If used in conjunction with the B<-CA> option
+the serial number file (as specified by the B<-CAserial> option) is not used.
 
-=item B<-trustout>
+The serial number can be decimal or hex (if preceded by C<0x>).
 
-Output a B<trusted> certificate rather than an ordinary. An ordinary
-or trusted certificate can be input but by default an ordinary
-certificate is output and any trust settings are discarded. With the
-B<-trustout> option a trusted certificate is output. A trusted
-certificate is automatically output if any trust settings are modified.
+=item B<-next_serial>
 
-=item B<-setalias> I<arg>
+Set the serial to be one more than the number in the certificate.
 
-Sets the alias of the certificate. This will allow the certificate
-to be referred to using a nickname for example "Steve's Certificate".
+=item B<-days> I<arg>
 
-=item B<-alias>
+Specifies the number of days until a newly generated certificate expires.
+The default is 30.
+Cannot be used together with the B<-preserve_dates> option.
 
-Outputs the certificate alias, if any.
+=item B<-preserve_dates>
 
-=item B<-clrtrust>
+When signing a certificate, preserve "notBefore" and "notAfter" dates of any
+input certificate instead of adjusting them to current time and duration.
+Cannot be used together with the B<-days> option.
 
-Clears all the permitted or trusted uses of the certificate.
+=item B<-subj> I<arg>
 
-=item B<-clrreject>
+When a certificate is created set its subject name to the given value.
+When the certificate is self-signed the issuer name is set to the same value.
 
-Clears all the prohibited or rejected uses of the certificate.
+The arg must be formatted as C</type0=value0/type1=value1/type2=...>.
+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 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:
 
-=item B<-addtrust> I<arg>
+C</DC=org/DC=OpenSSL/DC=users/UID=123456+CN=John Doe>
 
-Adds a trusted certificate use.
-Any object name can be used here but currently only B<clientAuth> (SSL client
-use), B<serverAuth> (SSL server use), B<emailProtection> (S/MIME email) and
-B<anyExtendedKeyUsage> are used.
-As of OpenSSL 1.1.0, the last of these blocks all purposes when rejected or
-enables all purposes when trusted.
-Other OpenSSL applications may define additional uses.
+This option can be used in conjunction with the B<-force_pubkey> option
+to create a certificate even without providing an input certificate
+or certificate request.
 
-=item B<-addreject> I<arg>
+=item B<-force_pubkey> I<filename>
 
-Adds a prohibited use. It accepts the same values as the B<-addtrust>
-option.
+When a certificate is created set its public key to the key in I<filename>
+instead of the key contained in the input or given with the B<-signkey> option.
 
-=item B<-purpose>
+This option is useful for creating self-issued certificates that are not
+self-signed, for instance when the key cannot be used for signing, such as DH.
+It can also be used in conjunction with b<-new> and B<-subj> to directly
+generate a certificate containing any desired public key.
 
-This option performs tests on the certificate extensions and outputs
-the results. For a more complete description see the
-L</CERTIFICATE EXTENSIONS> section.
+=item B<-clrext>
 
-=back
+Delete any extensions from a certificate. This option is used when a
+certificate is being created from another certificate (for example with
+either the B<-signkey> or the B<-CA> option).
+Normally all extensions are retained.
 
-=head2 Signing Options
+=item B<-extfile> I<filename>
 
-This command can be used to sign certificates and requests: it
-can thus behave like a "mini CA".
+Configuration file containing certificate extensions to add.
 
-=over 4
+=item B<-extensions> I<section>
 
-=item B<-signkey> I<filename>|I<uri>
+The section in the extfile to add certificate extensions from.
+If this option is not
+specified then the extensions should either be contained in the unnamed
+(default) section or the default section should contain a variable called
+"extensions" which contains the section to use.
+See the L<x509v3_config(5)> manual page for details of the
+extension section format.
 
-This option causes the input file to be self signed using the supplied
-private key.
+=item B<-sigopt> I<nm>:I<v>
 
-It sets the issuer name to the subject name (i.e., makes it self-issued)
-and changes the public key to the supplied value (unless overridden by
-B<-force_pubkey>). It sets the validity start date to the current time
-and the end date to a value determined by the B<-days> option.
-It retains any certificate extensions unless the B<-clrext> option is supplied;
-this includes, for example, any existing key identifier extensions.
+Pass options to the signature algorithm during sign operations.
+Names and values of these options are algorithm-specific.
 
 =item B<-badsig>
 
 Corrupt the signature before writing it; this can be useful
 for testing.
 
-=item B<-sigopt> I<nm>:I<v>
-
-Pass options to the signature algorithm during sign operations.
-Names and values of these options are algorithm-specific.
-
-=item B<-vfyopt> I<nm>:I<v>
+=item B<-I<digest>>
 
-Pass options to the signature algorithm during verify operations.
-Names and values of these options are algorithm-specific.
+The digest to use.
+This affects any signing or printing option that uses a message
+digest, such as the B<-fingerprint>, B<-signkey> and B<-CA> options.
+Any digest supported by the L<openssl-dgst(1)> command can be used.
+If not specified then SHA1 is used with B<-fingerprint> or
+the default digest for the signing algorithm is used, typically SHA256.
 
-=item B<-passin> I<arg>
+=back
 
-The key and certificate file password source.
-For more information about the format of I<arg>
-see L<openssl-passphrase-options(1)>.
+=head2 Micro-CA Options
 
-=item B<-clrext>
+=over 4
 
-Delete any extensions from a certificate. This option is used when a
-certificate is being created from another certificate (for example with
-the B<-signkey> or the B<-CA> options). Normally all extensions are
-retained.
+=item B<-CA> I<filename>|I<uri>
 
-=item B<-keyform> B<DER>|B<PEM>|B<P12>|B<ENGINE>
+Specifies the "CA" certificate to be used for signing.
+When present, this behaves like a "micro CA" as follows:
+The subject name of the "CA" certificate is placed as issuer name in the new
+certificate, which is then signed using the "CA" key given as detailed below.
 
-The key format; the default is B<PEM>.
-The only value with effect is B<ENGINE>; all others have become obsolete.
-See L<openssl-format-options(1)> for details.
+This option cannot be used in conjunction with the B<-signkey> option.
+This option is normally combined with the B<-req> option referencing a CSR.
+Without the B<-req> option the input must be a self-signed certificate
+unless the B<-new> option is given, which generates a certificate from scratch.
 
 =item B<-CAform> B<DER>|B<PEM>|B<P12>,
 
 The format for the CA certificate.
 This option has no effect and is retained for backward compatibility.
 
+=item B<-CAkey> I<filename>|I<uri>
+
+Sets the CA private key to sign a certificate with.
+The private key must match the public key of the certificate given with B<-CA>.
+If this option is not provided then the key must be present in the B<-CA> input.
+
 =item B<-CAkeyform> B<DER>|B<PEM>|B<P12>|B<ENGINE>
 
 The format for the CA key; the default is B<PEM>.
 The only value with effect is B<ENGINE>; all others have become obsolete.
 See L<openssl-format-options(1)> for details.
 
-=item B<-days> I<arg>
-
-Specifies the number of days to make a certificate valid for. The default
-is 30 days. Cannot be used with the B<-preserve_dates> option.
-
-=item B<-x509toreq>
-
-Converts a certificate into a certificate request. The B<-signkey> option
-is used to pass the required private key.
-
-=item B<-req>
-
-By default a certificate is expected on input. With this option a
-certificate request is expected instead.
-
-=item B<-set_serial> I<n>
-
-Specifies the serial number to use. This option can be used with either
-the B<-signkey> or B<-CA> options. If used in conjunction with the B<-CA>
-option the serial number file (as specified by the B<-CAserial> or
-B<-CAcreateserial> options) is not used.
-
-The serial number can be decimal or hex (if preceded by C<0x>).
-
-=item B<-CA> I<filename>
-
-Specifies the CA certificate to be used for signing. When this option is
-present, this command behaves like a "mini CA". The input file is signed by
-this CA using this option: that is its issuer name is set to the subject name
-of the CA and it is digitally signed using the CAs private key.
-
-This option is normally combined with the B<-req> option. Without the
-B<-req> option the input is a certificate which must be self signed.
-
-=item B<-CAkey> I<filename>|I<uri>
-
-Sets the CA private key to sign a certificate with. If this option is
-not specified then it is assumed that the CA private key is present in
-the CA certificate file.
-
 =item B<-CAserial> I<filename>
 
 Sets the CA serial number file to use.
@@ -470,81 +484,92 @@ have the 1 as its serial number. If the B<-CA> option is specified
 and the serial number file does not exist a random number is generated;
 this is the recommended practice.
 
-=item B<-extfile> I<filename>
+=back
 
-File containing certificate extensions to use. If not specified then
-no extensions are added to the certificate.
+=head2 Trust Settings
 
-=item B<-extensions> I<section>
+A B<trusted certificate> is an ordinary certificate which has several
+additional pieces of information attached to it such as the permitted
+and prohibited uses of the certificate and possibly an "alias" (nickname).
 
-The section to add certificate extensions from. If this option is not
-specified then the extensions should either be contained in the unnamed
-(default) section or the default section should contain a variable called
-"extensions" which contains the section to use. See the
-L<x509v3_config(5)> manual page for details of the
-extension section format.
+Normally when a certificate is being verified at least one certificate
+must be "trusted". By default a trusted certificate must be stored
+locally and must be a root CA: any certificate chain ending in this CA
+is then usable for any purpose.
 
-=item B<-new>
+Trust settings currently are only used with a root CA.
+They allow a finer control over the purposes the root CA can be used for.
+For example, a CA may be trusted for SSL client but not SSL server use.
 
-Generate a certificate from scratch, not using an input certificate
-or certificate request. So the B<-in> option must not be used in this case.
-Instead, the B<-subj> option needs to be given.
-The public key to include defaults to the key given with the B<-signkey> option,
-which implies self-signature.
-It may also be given explicity using the B<-force_pubkey> option.
+See the description in L<openssl-verify(1)> for more information
+on the meaning of trust settings.
 
-=item B<-next_serial>
+Future versions of OpenSSL will recognize trust settings on any
+certificate: not just root CAs.
 
-Set the serial to be one more than the number in the certificate.
+=over 4
 
-=item B<-nocert>
+=item B<-trustout>
 
-Do not generate or output a certificate.
+Mark any certificate PEM output as <trusted> certificate rather than ordinary.
+An ordinary or trusted certificate can be input but by default an ordinary
+certificate is output and any trust settings are discarded.
+With the B<-trustout> option a trusted certificate is output. A trusted
+certificate is automatically output if any trust settings are modified.
 
-=item B<-force_pubkey> I<filename>
+=item B<-setalias> I<arg>
 
-When a certificate is created set its public key to the key in I<filename>
-instead of the key contained in the input or given with the B<-signkey> option.
+Sets the "alias" of the certificate. This will allow the certificate
+to be referred to using a nickname for example "Steve's Certificate".
 
-This option is useful for creating self-issued certificates that are not
-self-signed, for instance when the key cannot be used for signing, such as DH.
-It can also be used in conjunction with b<-new> and B<-subj> to directly
-generate a certificate containing any desired public key.
+=item B<-clrtrust>
 
-=item B<-subj> I<arg>
+Clears all the permitted or trusted uses of the certificate.
 
-When a certificate is created set its subject name to the given value.
+=item B<-addtrust> I<arg>
 
-The arg must be formatted as C</type0=value0/type1=value1/type2=...>.
-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 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:
+Adds a trusted certificate use.
+Any object name can be used here but currently only B<clientAuth> (SSL client
+use), B<serverAuth> (SSL server use), B<emailProtection> (S/MIME email)
+and B<anyExtendedKeyUsage> are used.
+As of OpenSSL 1.1.0, the last of these blocks all purposes when rejected or
+enables all purposes when trusted.
+Other OpenSSL applications may define additional uses.
 
-C</DC=org/DC=OpenSSL/DC=users/UID=123456+CN=John Doe>
+=item B<-clrreject>
 
-Unless the B<-CA> option is given the issuer is set to the same value.
+Clears all the prohibited or rejected uses of the certificate.
 
-This option can be used in conjunction with the B<-force_pubkey> option
-to create a certificate even without providing an input certificate
-or certificate request.
+=item B<-addreject> I<arg>
+
+Adds a prohibited use.
+It accepts the same values as the B<-addtrust> option.
 
 =back
 
-=head2 Text Options
+=head2 Generic options
+
+=over 4
+
+{- $OpenSSL::safe::opt_r_item -}
+
+{- $OpenSSL::safe::opt_engine_item -}
 
-As well as customising the name output format, it is also possible to
-customise the actual fields printed using the B<certopt> options when
+{- $OpenSSL::safe::opt_provider_item -}
+
+=back
+
+=head2 Text Printing Flags
+
+As well as customising the name printing format, it is also possible to
+customise the actual fields printed using the B<certopt> option when
 the B<text> option is present. The default behaviour is to print all fields.
 
 =over 4
 
 =item B<compatible>
 
-Use the old format. This is equivalent to specifying no output options at all.
+Use the old format. This is equivalent to specifying no printing options at all.
 
 =item B<no_header>
 
@@ -620,36 +645,36 @@ B<no_header>, and B<no_version>.
 Note: in these examples the '\' means the example should be all on one
 line.
 
-Display the contents of a certificate:
+Print the contents of a certificate:
 
  openssl x509 -in cert.pem -noout -text
 
-Display the "Subject Alternative Name" extension of a certificate:
+Print the "Subject Alternative Name" extension of a certificate:
 
  openssl x509 -in cert.pem -noout -ext subjectAltName
 
-Display more extensions of a certificate:
+Print more extensions of a certificate:
 
  openssl x509 -in cert.pem -noout -ext subjectAltName,nsCertType
 
-Display the certificate serial number:
+Print the certificate serial number:
 
  openssl x509 -in cert.pem -noout -serial
 
-Display the certificate subject name:
+Print the certificate subject name:
 
  openssl x509 -in cert.pem -noout -subject
 
-Display the certificate subject name in RFC2253 form:
+Print the certificate subject name in RFC2253 form:
 
  openssl x509 -in cert.pem -noout -subject -nameopt RFC2253
 
-Display the certificate subject name in oneline form on a terminal
+Print the certificate subject name in oneline form on a terminal
 supporting UTF8:
 
  openssl x509 -in cert.pem -noout -subject -nameopt oneline,-esc_msb
 
-Display the certificate SHA1 fingerprint:
+Print the certificate SHA1 fingerprint:
 
  openssl x509 -sha1 -in cert.pem -noout -fingerprint
 
@@ -661,7 +686,7 @@ Convert a certificate to a certificate request:
 
  openssl x509 -x509toreq -in cert.pem -out req.pem -signkey key.pem
 
-Convert a certificate request into a self signed certificate using
+Convert a certificate request into a self-signed certificate using
 extensions for a CA:
 
  openssl x509 -req -in careq.pem -extfile openssl.cnf -extensions v3_ca \
@@ -673,7 +698,6 @@ certificate extensions:
  openssl x509 -req -in req.pem -extfile openssl.cnf -extensions v3_usr \
         -CA cacert.pem -CAkey key.pem -CAcreateserial
 
-
 Set a certificate to be trusted for SSL client use and change set its alias to
 "Steve's Class 1 CA"
 
@@ -685,7 +709,7 @@ Set a certificate to be trusted for SSL client use and change set its alias to
 The conversion to UTF8 format used with the name options assumes that
 T61Strings use the ISO8859-1 character set. This is wrong but Netscape
 and MSIE do this as do many certificates. So although this is incorrect
-it is more likely to display the majority of certificates correctly.
+it is more likely to print the majority of certificates correctly.
 
 The B<-email> option searches the subject name and the subject alternative
 name extension. Only unique email addresses will be printed out: it will
@@ -713,9 +737,9 @@ because the certificate should really not be regarded as a CA: however
 it is allowed to be a CA to work around some broken software.
 
 If the certificate is a V1 certificate (and thus has no extensions) and
-it is self signed it is also assumed to be a CA but a warning is again
+it is self-signed it is also assumed to be a CA but a warning is again
 given: this is to work around the problem of Verisign roots which are V1
-self signed certificates.
+self-signed certificates.
 
 If the keyUsage extension is present then additional restraints are
 made on the uses of the certificate. A CA certificate B<must> have the