From: kovan <xaum.io@gmail.com>
Date: Thu, 29 Jan 2026 12:46:46 +0000 (+0100)
Subject: doc: clarify -cipher option syntax in man pages
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=4792d33a544c0dd8e19e982ecb35d44b0195c1e0;p=thirdparty%2Fopenssl.git

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 fd05d777c92..da491be3c6c 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 434ed2a8b5d..883d4b9d016 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 1bd0cdfb6db..ea417cdc284 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>