doc: document OSSL_PKEY_PARAM_BITS meaning for each key type

The EVP_PKEY_get_bits() documentation states that "the definition
of cryptographic length is specific to the key cryptosystem" but
doesn't explain what this means for each key type.

Add a detailed list explaining what "bits" represents for RSA, DSA,
DH, EC, X25519, X448, Ed25519, Ed448, ML-DSA, SLH-DSA, and ML-KEM
key types to help users understand the return value.

Fixes #28337

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Reviewed-by: Dmitry Belyavskiy <beldmit@gmail.com>
Reviewed-by: Eugene Syromiatnikov <esyr@openssl.org>
Reviewed-by: Norbert Pocs <norbertp@openssl.org>
MergeDate: Wed Jun 10 11:15:17 2026
(Merged from https://github.com/openssl/openssl/pull/29790)

diff --git a/doc/man3/EVP_PKEY_get_size.pod b/doc/man3/EVP_PKEY_get_size.pod
index 0c49d65be0ec65a1a332f21f6bb4acb59a3abbab..392154a50884ee5c2f498de46fd742c8564745f2 100644 (file)
--- a/doc/man3/EVP_PKEY_get_size.pod
+++ b/doc/man3/EVP_PKEY_get_size.pod
@@ -40,7 +40,61 @@ receive that length), to avoid bugs.
 
 EVP_PKEY_get_bits() returns the cryptographic length of the cryptosystem
 to which the key in I<pkey> belongs, in bits.  Note that the definition
-of cryptographic length is specific to the key cryptosystem.
+of cryptographic length is specific to the key cryptosystem:
+
+=over 4
+
+=item B<RSA>
+
+The bit length of the modulus B<n>.
+
+=item B<DSA>
+
+The bit length of the prime B<p>.
+
+=item B<DH>
+
+The bit length of the prime B<p>.
+
+=item B<EC>
+
+The bit length of the group order.
+
+=item B<X25519>
+
+253 (fixed for the curve).
+
+=item B<X448>
+
+448 (fixed for the curve).
+
+=item B<Ed25519>
+
+256 (fixed for the curve).
+
+=item B<Ed448>
+
+456 (fixed for the curve).
+
+=item B<ML-DSA>
+
+The bit size of the public key (8 times the public key length in bytes).
+For B<ML-DSA-44>, B<ML-DSA-65>, and B<ML-DSA-87>, this is 10496, 15616, and
+20736 bits respectively.
+
+=item B<SLH-DSA>
+
+The bit size of the public key (8 times the public key length in bytes).
+For B<SLH-DSA*128*>, B<SLH-DSA*192*>, and B<SLH-DSA*256*> variants, this is
+256, 384, and 512 bits respectively.
+
+=item B<ML-KEM>
+
+The security strength indicator from the algorithm name: 512, 768, or 1024
+for B<ML-KEM-512>, B<ML-KEM-768>, and B<ML-KEM-1024> respectively.
+
+=back
+
 This length corresponds to the provider parameter B<OSSL_PKEY_PARAM_BITS>.
 
 EVP_PKEY_get_security_bits() returns the number of security bits of the given