From 4792d33a544c0dd8e19e982ecb35d44b0195c1e0 Mon Sep 17 00:00:00 2001 From: kovan Date: Thu, 29 Jan 2026 13:46:46 +0100 Subject: [PATCH] doc: clarify -cipher option syntax in man pages Users reading the documentation for the - option often misunderstand the syntax. The notation "B<-I>" 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 Reviewed-by: Shane Lontis Reviewed-by: Frederik Wedel-Heinen MergeDate: Fri Feb 13 14:52:00 2026 (Merged from https://github.com/openssl/openssl/pull/29843) --- doc/man1/openssl-enc.pod.in | 4 +++- doc/man1/openssl-genpkey.pod.in | 13 +++++++++---- doc/man1/openssl-pkey.pod.in | 8 +++++--- 3 files changed, 17 insertions(+), 8 deletions(-) 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> -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 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. =item B<-I> -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 to see the available ciphers. =item B<-algorithm> I 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 and L for details. =item B<-I> -Encrypt the PEM encoded private key with the supplied cipher. Any algorithm -name accepted by EVP_get_cipherbyname() is acceptable such as B. +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 output form encryption is supported only in the default B -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 to see the available ciphers. =item B<-passout> I -- 2.47.3