From 428836237f394b005f5810b672d83677c0d70186 Mon Sep 17 00:00:00 2001
From: "Dr. David von Oheimb" <dev@ddvo.net>
Date: Wed, 25 Sep 2024 12:18:12 +0200
Subject: [PATCH] doc backport: clean up and move doc of OPENSSL_TRACE from
 man1/openssl.pod to man7/openssl-env.pod

Reviewed-by: Tom Cosgrove <tom.cosgrove@arm.com>
Reviewed-by: Tomas Mraz <tomas@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/25650)

(cherry picked from commit e6c4d883dbcc402ba5a21c2725c738a4e6942689)
---
 doc/man1/openssl.pod     | 107 ++++-----------------------------------
 doc/man7/openssl-env.pod |  93 ++++++++++++++++++++++++++++++++++
 2 files changed, 102 insertions(+), 98 deletions(-)

diff --git a/doc/man1/openssl.pod b/doc/man1/openssl.pod
index 201428e870047..4865e5c33e6eb 100644
--- a/doc/man1/openssl.pod
+++ b/doc/man1/openssl.pod
@@ -653,111 +653,22 @@ See L<property(7)> for a more detailed description.
 
 =head1 ENVIRONMENT
 
-The OpenSSL library can be take some configuration parameters from the
-environment.  Some of these variables are listed below.  For information
-about specific commands, see L<openssl-engine(1)>,
-L<openssl-rehash(1)>, and L<tsget(1)>.
-
-For information about the use of environment variables in configuration,
-see L<config(5)/ENVIRONMENT>.
-
-For information about querying or specifying CPU architecture flags, see
-L<OPENSSL_ia32cap(3)>, and L<OPENSSL_s390xcap(3)>.
+The OpenSSL libraries can take some configuration parameters from the
+environment.
 
 For information about all environment variables used by the OpenSSL libraries,
+such as B<OPENSSL_CONF>, B<OPENSSL_MODULES>, and B<OPENSSL_TRACE>,
 see L<openssl-env(7)>.
 
-=over 4
-
-=item B<OPENSSL_TRACE=>I<name>[,...]
-
-Enable tracing output of OpenSSL library, by name.
-This output will only make sense if you know OpenSSL internals well.
-Also, it might not give you any output at all, depending on how
-OpenSSL was built.
-
-The value is a comma separated list of names, with the following
-available:
-
-=over 4
-
-=item B<TRACE>
-
-Traces the OpenSSL trace API itself.
-
-=item B<INIT>
-
-Traces OpenSSL library initialization and cleanup.
-
-=item B<TLS>
-
-Traces the TLS/SSL protocol.
-
-=item B<TLS_CIPHER>
-
-Traces the ciphers used by the TLS/SSL protocol.
-
-=item B<CONF>
-
-Show details about provider and engine configuration.
-
-=item B<ENGINE_TABLE>
-
-The function that is used by RSA, DSA (etc) code to select registered
-ENGINEs, cache defaults and functional references (etc), will generate
-debugging summaries.
-
-=item B<ENGINE_REF_COUNT>
-
-Reference counts in the ENGINE structure will be monitored with a line
-of generated for each change.
-
-=item B<PKCS5V2>
-
-Traces PKCS#5 v2 key generation.
-
-=item B<PKCS12_KEYGEN>
-
-Traces PKCS#12 key generation.
-
-=item B<PKCS12_DECRYPT>
-
-Traces PKCS#12 decryption.
-
-=item B<X509V3_POLICY>
-
-Generates the complete policy tree at various points during X.509 v3
-policy evaluation.
-
-=item B<BN_CTX>
-
-Traces BIGNUM context operations.
-
-=item B<CMP>
-
-Traces CMP client and server activity.
-
-=item B<STORE>
-
-Traces STORE operations.
-
-=item B<DECODER>
-
-Traces decoder operations.
-
-=item B<ENCODER>
-
-Traces encoder operations.
-
-=item B<REF_COUNT>
-
-Traces decrementing certain ASN.1 structure references.
+For information about the use of environment variables in configuration,
+see L<config(5)/ENVIRONMENT>.
 
-=back
+For information about specific commands, see L<openssl-engine(1)>,
+L<openssl-rehash(1)>, and L<tsget(1)>.
 
-=back
+For information about querying or specifying CPU architecture flags, see
+L<OPENSSL_ia32cap(3)>, and L<OPENSSL_s390xcap(3)>.
 
-=head1 SEE ALSO
 
 L<openssl-asn1parse(1)>,
 L<openssl-ca(1)>,
diff --git a/doc/man7/openssl-env.pod b/doc/man7/openssl-env.pod
index a2443d54d8229..c7dbd2277dc68 100644
--- a/doc/man7/openssl-env.pod
+++ b/doc/man7/openssl-env.pod
@@ -51,6 +51,99 @@ See L<OPENSSL_malloc(3)>.
 Specifies the directory from which cryptographic providers are loaded.
 Equivalently, the generic B<-provider-path> command-line option may be used.
 
+=item B<OPENSSL_TRACE>
+
+By default the OpenSSL trace feature is disabled statically.
+To enable it, OpenSSL must be built with tracing support,
+which may be configured like this: C<./config enable-trace>
+
+Unless OpenSSL tracing support is generally disabled,
+enable trace output of specific parts of OpenSSL libraries, by name.
+This output usually makes sense only if you know OpenSSL internals well.
+
+The value of this environment varialble is a comma-separated list of names,
+with the following available:
+
+=over 4
+
+=item B<TRACE>
+
+Traces the OpenSSL trace API itself.
+
+=item B<INIT>
+
+Traces OpenSSL library initialization and cleanup.
+
+=item B<TLS>
+
+Traces the TLS/SSL protocol.
+
+=item B<TLS_CIPHER>
+
+Traces the ciphers used by the TLS/SSL protocol.
+
+=item B<CONF>
+
+Show details about provider and engine configuration.
+
+=item B<ENGINE_TABLE>
+
+The function that is used by RSA, DSA (etc) code to select registered
+ENGINEs, cache defaults and functional references (etc), will generate
+debugging summaries.
+
+=item B<ENGINE_REF_COUNT>
+
+Reference counts in the ENGINE structure will be monitored with a line
+of generated for each change.
+
+=item B<PKCS5V2>
+
+Traces PKCS#5 v2 key generation.
+
+=item B<PKCS12_KEYGEN>
+
+Traces PKCS#12 key generation.
+
+=item B<PKCS12_DECRYPT>
+
+Traces PKCS#12 decryption.
+
+=item B<X509V3_POLICY>
+
+Generates the complete policy tree at various points during X.509 v3
+policy evaluation.
+
+=item B<BN_CTX>
+
+Traces BIGNUM context operations.
+
+=item B<CMP>
+
+Traces CMP client and server activity.
+
+=item B<STORE>
+
+Traces STORE operations.
+
+=item B<DECODER>
+
+Traces decoder operations.
+
+=item B<ENCODER>
+
+Traces encoder operations.
+
+=item B<REF_COUNT>
+
+Traces decrementing certain ASN.1 structure references.
+
+=item B<HTTP>
+
+Traces the HTTP client and server, such as messages being sent and received.
+
+=back
+
 =item B<OPENSSL_WIN32_UTF8>
 
 If set, then L<UI_OpenSSL(3)> returns UTF-8 encoded strings, rather than