Commit 4792d33a54 for openssl.org

commit 4792d33a544c0dd8e19e982ecb35d44b0195c1e0
Author: kovan <xaum.io@gmail.com>
Date:   Thu Jan 29 13:46:46 2026 +0100

    doc: clarify -cipher option syntax in man pages

    Users reading the documentation for the -<cipher> option often
    misunderstand the syntax. The notation "B<-I<cipher>>" renders as
    "-cipher" with "cipher" in italics, leading users to think they
    should type "-cipher aes-128-cbc" when the correct usage is
    "-aes-128-cbc" (the cipher name directly as the option).

    Update the documentation in openssl-genpkey, openssl-enc, and
    openssl-pkey to explicitly state that the cipher name is prepended
    with a hyphen and used directly as the option, not as an argument
    to a "-cipher" flag.

    Also add a reference to "openssl list -cipher-algorithms" to help
    users discover available ciphers, and fix a typo in openssl-pkey
    ("and and" -> "and").

    Fixes #26089

    Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

    Reviewed-by: Shane Lontis <shane.lontis@oracle.com>
    Reviewed-by: Frederik Wedel-Heinen <fwh.openssl@gmail.com>
    MergeDate: Fri Feb 13 14:52:00 2026
    (Merged from https://github.com/openssl/openssl/pull/29843)

diff --git a/doc/man1/openssl-enc.pod.in b/doc/man1/openssl-enc.pod.in
index fd05d777c9..da491be3c6 100644
--- a/doc/man1/openssl-enc.pod.in
+++ b/doc/man1/openssl-enc.pod.in
@@ -61,7 +61,9 @@ either by itself or in addition to the encryption or decryption.

 =item B<-I<cipher>>

-The cipher to use.
+The cipher to use. This option is specified by prepending a hyphen to the
+cipher name (e.g., B<-aes-256-cbc>), not as an argument to a C<-cipher> flag.
+Use C<openssl list -cipher-algorithms> to see the available ciphers.

 =item B<-help>

diff --git a/doc/man1/openssl-genpkey.pod.in b/doc/man1/openssl-genpkey.pod.in
index 434ed2a8b5..883d4b9d01 100644
--- a/doc/man1/openssl-genpkey.pod.in
+++ b/doc/man1/openssl-genpkey.pod.in
@@ -74,10 +74,15 @@ see L<openssl-passphrase-options(1)>.

 =item B<-I<cipher>>

-Encrypts the private key using the specified algorithm. The algorithm can be
-specified using a name that is accepted by the EVP_get_cipherbyname() function.
-For example, use the syntax B<-aes-128-cbc> to specify the AES encryption
-algorithm with a 128-bit key in CBC mode.
+Encrypts the private key with the specified cipher. This option is specified
+by prepending a hyphen to the cipher name. For example, to encrypt with
+AES-128 in CBC mode, use B<-aes-128-cbc>. To encrypt with AES-256 in CBC mode,
+use B<-aes-256-cbc>.
+
+Note: the cipher name is used directly as the option (e.g., B<-aes-256-cbc>),
+not as an argument to a C<-cipher> flag.
+
+Use C<openssl list -cipher-algorithms> to see the available ciphers.

 =item B<-algorithm> I<alg>

diff --git a/doc/man1/openssl-pkey.pod.in b/doc/man1/openssl-pkey.pod.in
index 1bd0cdfb6d..ea417cdc28 100644
--- a/doc/man1/openssl-pkey.pod.in
+++ b/doc/man1/openssl-pkey.pod.in
@@ -130,10 +130,12 @@ See L<EVP_PKEY-ML-DSA(7)> and L<EVP_PKEY-ML-KEM(7)> for details.

 =item B<-I<cipher>>

-Encrypt the PEM encoded private key with the supplied cipher. Any algorithm
-name accepted by EVP_get_cipherbyname() is acceptable such as B<aes128>.
+Encrypt the PEM encoded private key with the supplied cipher. This option is
+specified by prepending a hyphen to the cipher name (e.g., B<-aes-256-cbc>
+or B<-aes128>), not as an argument to a C<-cipher> flag.
 In B<DER> output form encryption is supported only in the default B<PKCS#8>
-form and and is not available when the B<-traditional> option is used.
+form and is not available when the B<-traditional> option is used.
+Use C<openssl list -cipher-algorithms> to see the available ciphers.

 =item B<-passout> I<arg>