RT4194: Restore old engine parameter parsing.

Allow initial engine names as first parameters before flags.
Also add engine param to help summary

Wrote manpage
Reviewed-by: NViktor Dukhovni <viktor@openssl.org>

apps/engine.c

@@ -72,13 +72,16 @@ typedef enum OPTION_choice {
 } OPTION_CHOICE;
 
 OPTIONS engine_options[] = {
+    {OPT_HELP_STR, 1, '-', "Usage: %s [options] engine...\n"},
+    {OPT_HELP_STR, 1, '-',
+        "  engine... Engines to load\n"},
     {"help", OPT_HELP, '-', "Display this summary"},
-    {"vvvv", OPT_VVVV, '-', "Also show internal input flags"},
-    {"vvv", OPT_VVV, '-', "Also add the input flags for each command"},
+    {"v", OPT_V, '-', "List 'control commands' For each specified engine"},
     {"vv", OPT_VV, '-', "Also display each command's description"},
-    {"v", OPT_V, '-', "For each engine, list its 'control commands'"},
-    {"c", OPT_C, '-', "List the capabilities of each engine"},
-    {"t", OPT_T, '-', "Check that each engine is available"},
+    {"vvv", OPT_VVV, '-', "Also add the input flags for each command"},
+    {"vvvv", OPT_VVVV, '-', "Also show internal input flags"},
+    {"c", OPT_C, '-', "List the capabilities of specified engine"},
+    {"t", OPT_T, '-', "Check that specified engine is available"},
     {"tt", OPT_TT, '-', "Display error trace for unavailable engines"},
     {"pre", OPT_PRE, 's', "Run command against the ENGINE before loading it"},
     {"post", OPT_POST, 's', "Run command against the ENGINE after loading it"},
@@ -89,19 +92,18 @@ OPTIONS engine_options[] = {
 
 static void identity(char *ptr)
 {
-    return;
 }
 
-static int append_buf(char **buf, const char *s, int *size, int step)
+static int append_buf(char **buf, int *size, const char *s)
 {
     if (*buf == NULL) {
-        *size = step;
+        *size = 256;
         *buf = app_malloc(*size, "engine buffer");
         **buf = '\0';
     }
 
     if (strlen(*buf) + strlen(s) >= (unsigned int)*size) {
-        *size += step;
+        *size += 256;
         *buf = OPENSSL_realloc(*buf, *size);
     }
 
@@ -313,11 +315,23 @@ int engine_main(int argc, char **argv)
     const char *indent = "     ";
     OPTION_CHOICE o;
     char *prog;
+    char *argv1;
 
     out = dup_bio_out(FORMAT_TEXT);
-    prog = opt_init(argc, argv, engine_options);
-    if (!engines || !pre_cmds || !post_cmds)
+    if (engines == NULL || pre_cmds == NULL || post_cmds == NULL)
         goto end;
+
+    /* Remember the original command name, parse/skip any leading engine
+     * names, and then setup to parse the rest of the line as flags. */
+    prog = argv[0];
+    while ((argv1 = argv[1]) != NULL && *argv1 != '-') {
+        sk_OPENSSL_STRING_push(engines, argv1);
+        argc--;
+        argv++;
+    }
+    argv[0] = prog;
+    opt_init(argc, argv, engine_options);
+
     while ((o = opt_next()) != OPT_EOF) {
         switch (o) {
         case OPT_EOF:
@@ -353,10 +367,19 @@ int engine_main(int argc, char **argv)
             break;
         }
     }
+
+    /* Allow any trailing parameters as engine names. */
     argc = opt_num_rest();
     argv = opt_rest();
-    for ( ; *argv; argv++)
+    for ( ; *argv; argv++) {
+        if (**argv == '-') {
+            BIO_printf(bio_err, "%s: Cannot mix flags and engine names.\n",
+                       prog);
+            BIO_printf(bio_err, "%s: Use -help for summary.\n", prog);
+            goto end;
+        }
         sk_OPENSSL_STRING_push(engines, *argv);
+    }
 
     if (sk_OPENSSL_STRING_num(engines) == 0) {
         for (e = ENGINE_get_first(); e != NULL; e = ENGINE_get_next(e)) {
@@ -387,16 +410,16 @@ int engine_main(int argc, char **argv)
                 ENGINE_PKEY_METHS_PTR fn_pk;
 
                 if (ENGINE_get_RSA(e) != NULL
-                    && !append_buf(&cap_buf, "RSA", &cap_size, 256))
+                    && !append_buf(&cap_buf, &cap_size, "RSA"))
                     goto end;
                 if (ENGINE_get_DSA(e) != NULL
-                    && !append_buf(&cap_buf, "DSA", &cap_size, 256))
+                    && !append_buf(&cap_buf, &cap_size, "DSA"))
                     goto end;
                 if (ENGINE_get_DH(e) != NULL
-                    && !append_buf(&cap_buf, "DH", &cap_size, 256))
+                    && !append_buf(&cap_buf, &cap_size, "DH"))
                     goto end;
                 if (ENGINE_get_RAND(e) != NULL
-                    && !append_buf(&cap_buf, "RAND", &cap_size, 256))
+                    && !append_buf(&cap_buf, &cap_size, "RAND"))
                     goto end;
 
                 fn_c = ENGINE_get_ciphers(e);
@@ -404,8 +427,7 @@ int engine_main(int argc, char **argv)
                     goto skip_ciphers;
                 n = fn_c(e, NULL, &nids, 0);
                 for (k = 0; k < n; ++k)
-                    if (!append_buf(&cap_buf,
-                                    OBJ_nid2sn(nids[k]), &cap_size, 256))
+                    if (!append_buf(&cap_buf, &cap_size, OBJ_nid2sn(nids[k])))
                         goto end;
 
  skip_ciphers:
@@ -414,8 +436,7 @@ int engine_main(int argc, char **argv)
                     goto skip_digests;
                 n = fn_d(e, NULL, &nids, 0);
                 for (k = 0; k < n; ++k)
-                    if (!append_buf(&cap_buf,
-                                    OBJ_nid2sn(nids[k]), &cap_size, 256))
+                    if (!append_buf(&cap_buf, &cap_size, OBJ_nid2sn(nids[k])))
                         goto end;
 
  skip_digests:
@@ -424,8 +445,7 @@ int engine_main(int argc, char **argv)
                     goto skip_pmeths;
                 n = fn_pk(e, NULL, &nids, 0);
                 for (k = 0; k < n; ++k)
-                    if (!append_buf(&cap_buf,
-                                    OBJ_nid2sn(nids[k]), &cap_size, 256))
+                    if (!append_buf(&cap_buf, &cap_size, OBJ_nid2sn(nids[k])))
                         goto end;
  skip_pmeths:
                 if (cap_buf && (*cap_buf != '\0'))

doc/apps/engine.pod

+
+=pod
+
+=head1 NAME
+
+engine - load and query engines
+
+=head1 SYNOPSIS
+
+B<openssl engine>
+[ I<engine...> ]
+[B<-v>]
+[B<-vv>]
+[B<-vvv>]
+[B<-vvv>]
+[B<-vvv>]
+[B<-c>]
+[B<-t>]
+[B<-tt>]
+[B<-pre> I<command>]
+[B<-post> I<command>]
+[ I<engine...> ]
+
+=head1 DESCRIPTION
+
+The B<engine> command is used to query the status and capabilities
+of the specified B<engine>'s.
+Engines may be speicifed before and after all other command-line flags.
+Only those specified are queried.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-v> B<-vv> B<-vvv> B<-vvvv>
+
+Provides information about each specified engine. The first flag lists
+all the possible run-time control commands; the second adds a
+description of each command; the third adds the input flags, and the
+final option adds the internal input flags.
+
+=item B<-c>
+
+Lists the capabilities of each engine.
+
+=item B<-t>
+
+Tests if each specified engine is available, and displays the answer.
+
+=item B<-tt>
+
+Displays an error trace for any unavailable engine.
+
+=item B<-pre> I<command>
+=item B<-post> I<command>
+
+Command-line configuration of engines.
+The B<-pre> command is given to the engine before it is loaded and
+the B<-post> command is given after the engine is loaded.
+The I<command> is of the form I<cmd:val> where I<cmd> is the command,
+and I<val> is the value for the command.
+See the example below.
+
+=back
+
+=head1 EXAMPLE
+
+To list all the commands available to a dynamic engine:
+
+ % openssl engine -t -tt -vvvv dynamic
+ (dynamic) Dynamic engine loading support
+      [ unavailable ]
+      SO_PATH: Specifies the path to the new ENGINE shared library
+           (input flags): STRING
+      NO_VCHECK: Specifies to continue even if version checking fails (boolean)
+           (input flags): NUMERIC
+      ID: Specifies an ENGINE id name for loading
+           (input flags): STRING
+      LIST_ADD: Whether to add a loaded ENGINE to the internal list (0=no,1=yes,2=mandatory)
+           (input flags): NUMERIC
+      DIR_LOAD: Specifies whether to load from 'DIR_ADD' directories (0=no,1=yes,2=mandatory)
+           (input flags): NUMERIC
+      DIR_ADD: Adds a directory from which ENGINEs can be loaded
+           (input flags): STRING
+      LOAD: Load up the ENGINE specified by other settings
+           (input flags): NO_INPUT
+
+To list the capabilities of the I<rsax> engine:
+
+ % openssl engine -c
+ (rsax) RSAX engine support
+  [RSA]
+ (dynamic) Dynamic engine loading support
+
+=cut

doc/apps/openssl.pod

@@ -399,7 +399,7 @@ read the password from standard input.
 L<asn1parse(1)>, L<ca(1)>, L<config(5)>,
 L<crl(1)>, L<crl2pkcs7(1)>, L<dgst(1)>,
 L<dhparam(1)>, L<dsa(1)>, L<dsaparam(1)>,
-L<enc(1)>, L<gendsa(1)>, L<genpkey(1)>,
+L<enc(1)>, L<engine(1), L<gendsa(1)>, L<genpkey(1)>,
 L<genrsa(1)>, L<nseq(1)>, L<openssl(1)>,
 L<passwd(1)>,
 L<pkcs12(1)>, L<pkcs7(1)>, L<pkcs8(1)>,