Commit e75138ab authored by Rich Salz's avatar Rich Salz
Browse files

Doc fixes 



Write missing prime.pod and srp.pod
Implement -c in find-doc-nits (for command options)
Other fixes to some manpages
Use B<-I<digest|cipher>> notation
Split up multiple flags into a single entry in the synopsis.
Add -1 and missing-help to list command.

Reviewed-by: default avatarAndy Polyakov <appro@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/4144)
parent bc5145e3

apps/openssl.c

+61 −18
Original line number Diff line number Diff line
@@ -52,7 +52,7 @@ static LHASH_OF(FUNCTION) *prog_init(void); 
static int do_cmd(LHASH_OF(FUNCTION) *prog, int argc, char *argv[]);

static void list_pkey(void);

static void list_pkey_meth(void);

static void list_type(FUNC_TYPE ft);

static void list_type(FUNC_TYPE ft, int one);

static void list_disabled(void);

char *default_config_file = NULL;
@@ -292,28 +292,57 @@ static void list_missing_help(void) 
    const OPTIONS *o;



    for (fp = functions; fp->name != NULL; fp++) {

        if ((o = fp->help) == NULL) {

            BIO_printf(bio_out, "%s *\n", fp->name);

            continue;

        }

        if ((o = fp->help) != NULL) {

            /* If there is help, list what flags are not documented. */

            for ( ; o->name != NULL; o++) {

                if (o->helpstr == NULL)

                    BIO_printf(bio_out, "%s %s\n", fp->name, o->name);

            }

        } else if (fp->func != dgst_main) {

            /* If not aliased to the dgst command, */

            BIO_printf(bio_out, "%s *\n", fp->name);

        }

    }

}



static void list_options_for_command(const char *command)

{

    const FUNCTION *fp;

    const OPTIONS *o;



    for (fp = functions; fp->name != NULL; fp++)

        if (strcmp(fp->name, command) == 0)

            break;

    if (fp->name == NULL) {

        BIO_printf(bio_err, "Invalid command '%s'; type \"help\" for a list.\n",

                command);

        return;

    }



    if ((o = fp->help) == NULL)

        return;



    for ( ; o->name != NULL; o++) {

        if (o->name == OPT_HELP_STR

                || o->name == OPT_MORE_STR

                || o->name[0] == '\0')

            continue;

        BIO_printf(bio_out, "%s %c\n", o->name, o->valtype);

    }

}





/* Unified enum for help and list commands. */

typedef enum HELPLIST_CHOICE {

    OPT_ERR = -1, OPT_EOF = 0, OPT_HELP,

    OPT_COMMANDS, OPT_DIGEST_COMMANDS,

    OPT_ERR = -1, OPT_EOF = 0, OPT_HELP, OPT_ONE,

    OPT_COMMANDS, OPT_DIGEST_COMMANDS, OPT_OPTIONS,

    OPT_DIGEST_ALGORITHMS, OPT_CIPHER_COMMANDS, OPT_CIPHER_ALGORITHMS,

    OPT_PK_ALGORITHMS, OPT_PK_METHOD, OPT_DISABLED, OPT_MISSING_HELP

} HELPLIST_CHOICE;



const OPTIONS list_options[] = {

    {"help", OPT_HELP, '-', "Display this summary"},

    {"1", OPT_ONE, '-', "List in one column"},

    {"commands", OPT_COMMANDS, '-', "List of standard commands"},

    {"digest-commands", OPT_DIGEST_COMMANDS, '-',

     "List of message digest commands"},
@@ -330,6 +359,8 @@ const OPTIONS list_options[] = { 
     "List of disabled features"},

    {"missing-help", OPT_MISSING_HELP, '-',

     "List missing detailed help strings"},

    {"options", OPT_OPTIONS, 's',

     "List options for specified command"},

    {NULL}

};
@@ -337,7 +368,7 @@ int list_main(int argc, char **argv) 
{

    char *prog;

    HELPLIST_CHOICE o;

    int done = 0;

    int one = 0, done = 0;



    prog = opt_init(argc, argv, list_options);

    while ((o = opt_next()) != OPT_EOF) {
@@ -349,17 +380,20 @@ int list_main(int argc, char **argv) 
        case OPT_HELP:

            opt_help(list_options);

            break;

        case OPT_ONE:

            one = 1;

            break;

        case OPT_COMMANDS:

            list_type(FT_general);

            list_type(FT_general, one);

            break;

        case OPT_DIGEST_COMMANDS:

            list_type(FT_md);

            list_type(FT_md, one);

            break;

        case OPT_DIGEST_ALGORITHMS:

            EVP_MD_do_all_sorted(list_md_fn, bio_out);

            break;

        case OPT_CIPHER_COMMANDS:

            list_type(FT_cipher);

            list_type(FT_cipher, one);

            break;

        case OPT_CIPHER_ALGORITHMS:

            EVP_CIPHER_do_all_sorted(list_cipher_fn, bio_out);
@@ -376,6 +410,9 @@ int list_main(int argc, char **argv) 
        case OPT_MISSING_HELP:

            list_missing_help();

            break;

        case OPT_OPTIONS:

            list_options_for_command(opt_arg());

            break;

        }

        done = 1;

    }
@@ -458,17 +495,23 @@ int exit_main(int argc, char **argv) 
    return EXIT_THE_PROGRAM;

}



static void list_type(FUNC_TYPE ft)

static void list_type(FUNC_TYPE ft, int one)

{

    FUNCTION *fp;

    int i = 0;



    for (fp = functions; fp->name != NULL; fp++)

        if (fp->type == ft) {

            if ((i++ % COLUMNS) == 0)

    for (fp = functions; fp->name != NULL; fp++) {

        if (fp->type != ft)

            continue;

        if (one) {

            BIO_printf(bio_out, "%s\n", fp->name);

        } else {

            if ((i++ % COLUMNS) == 0 && fp != functions)

                BIO_printf(bio_out, "\n");

            BIO_printf(bio_out, FORMAT, fp->name);

        }

    }

    if (!one)

        BIO_printf(bio_out, "\n");

}

doc/man1/cms.pod

+4 −4
Original line number Diff line number Diff line
@@ -67,9 +67,9 @@ B<openssl> B<cms> 
[B<-verify_name name>]

[B<-x509_strict>]

[B<-md digest>]

[B<-[cipher]>]

[B<-I<cipher>>]

[B<-nointern>]

[B<-no_signer_cert_verify>]

[B<-noverify>]

[B<-nocerts>]

[B<-noattr>]

[B<-nosmimecap>]
@@ -298,7 +298,7 @@ Do not load the trusted CA certificates from the default directory location 
Digest algorithm to use when signing or resigning. If not present then the

default digest algorithm for the signing key will be used (usually SHA1).



=item B<-[cipher]>

=item B<-I<cipher>>



The encryption algorithm to use. For example triple DES (168 bits) - B<-des3>

or 256 bit AES - B<-aes256>. Any standard algorithm name (as used by the
@@ -316,7 +316,7 @@ the message are searched for the signing certificate. With this option 
only the certificates specified in the B<-certfile> option are used.

The supplied certificates can still be used as untrusted CAs however.



=item B<-no_signer_cert_verify>

=item B<-noverify>



Do not verify the signers certificate of a signed message.

doc/man1/dgst.pod

+5 −6
Original line number Diff line number Diff line
@@ -2,13 +2,14 @@ 


=head1 NAME



dgst, sha, sha1, mdc2, ripemd160, sha224, sha256, sha384, sha512, md4, md5, blake2b, blake2s - message digests

dgst

- perform digest operations



=head1 SYNOPSIS



B<openssl> B<dgst>

[B<-help>]

B<openssl dgst>

[B<-I<digest>>]

[B<-help>]

[B<-c>]

[B<-d>]

[B<-hex>]
@@ -28,9 +29,7 @@ B<openssl> B<dgst> 
[B<-engine_impl>]

[B<file...>]



B<openssl>

[I<digest>]

[B<...>]

B<openssl> I<digest> [B<...>]



=head1 DESCRIPTION

doc/man1/enc.pod

+8 −4
Original line number Diff line number Diff line
@@ -6,7 +6,7 @@ enc - symmetric cipher routines 


=head1 SYNOPSIS



B<openssl enc -ciphername>

B<openssl enc -I<cipher>>

[B<-help>]

[B<-ciphers>]

[B<-in filename>]
@@ -14,7 +14,8 @@ B<openssl enc -ciphername> 
[B<-pass arg>]

[B<-e>]

[B<-d>]

[B<-a/-base64>]

[B<-a>]

[B<-base64>]

[B<-A>]

[B<-k password>]

[B<-kfile filename>]
@@ -35,6 +36,8 @@ B<openssl enc -ciphername> 
[B<-writerand file>]

[B<-engine id>]



B<openssl> I<[cipher]> [B<...>]



=head1 DESCRIPTION



The symmetric cipher commands allow data to be encrypted or decrypted
@@ -184,10 +187,11 @@ This can be used with a subsequent B<-rand> flag. 


=head1 NOTES



The program can be called either as B<openssl ciphername> or

B<openssl enc -ciphername>. The first form doesn't work with

The program can be called either as B<openssl cipher> or

B<openssl enc -cipher>. The first form doesn't work with

engine-provided ciphers, because this form is processed before the

configuration file is read and any ENGINEs loaded.

Use the B<list> command to get a list of supported ciphers.



Engines which provide entirely new encryption algorithms (such as the ccgost

engine which provides gost89 algorithm) should be configured in the

doc/man1/genpkey.pod

+2 −2
Original line number Diff line number Diff line
@@ -11,7 +11,7 @@ B<openssl> B<genpkey> 
[B<-out filename>]

[B<-outform PEM|DER>]

[B<-pass arg>]

[B<-cipher>]

[B<-I<cipher>>]

[B<-engine id>]

[B<-paramfile file>]

[B<-algorithm alg>]
@@ -45,7 +45,7 @@ This specifies the output format DER or PEM. The default format is PEM. 
The output file password source. For more information about the format of B<arg>

see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>.



=item B<-cipher>

=item B<-I<cipher>>



This option encrypts the private key with the supplied cipher. Any algorithm

name accepted by EVP_get_cipherbyname() is acceptable such as B<des3>.