improve and move text on OPENSSL_TRACE from doc/man1/openssl.pod to doc/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/25540)

doc/man1/openssl.pod

@@ -691,114 +691,22 @@ See L<property(7)> for a more detailed description.
 
 =head1 ENVIRONMENT
 
-The OpenSSL library can be take some configuration parameters from the
+The OpenSSL libraries can take some configuration parameters from the
-environment.  Some of these variables are listed below.  For information
+environment.
-about specific commands, see L<openssl-engine(1)>,
+
-L<openssl-rehash(1)>, and L<tsget(1)>.
+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)>.
 
 For information about the use of environment variables in configuration,
 see L<config(5)/ENVIRONMENT>.
 
+For information about specific commands, see L<openssl-engine(1)>,
+L<openssl-rehash(1)>, and L<tsget(1)>.
+
 For information about querying or specifying CPU architecture flags, see
 L<OPENSSL_ia32cap(3)>, L<OPENSSL_s390xcap(3)> and L<OPENSSL_riscvcap(3)>.
 
-For information about all environment variables used by the OpenSSL libraries,
-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
-if OpenSSL was built without tracing support.
-
-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.
-
-=item B<HTTP>
-
-Traces the HTTP client and server, such as messages being sent and received.
-
-=back
-
-=back
-
 =head1 SEE ALSO
 
 L<openssl-asn1parse(1)>,

doc/man3/OSSL_HTTP_REQ_CTX.pod

@@ -241,7 +241,7 @@ with OSSL_HTTP_REQ_CTX_nbio() or OSSL_HTTP_REQ_CTX_exchange().
 When built with tracing enabled, OSSL_HTTP_REQ_CTX_nbio() and all functions
 using it, such as OSSL_HTTP_REQ_CTX_exchange() and L<OSSL_HTTP_transfer(3)>,
 may be traced using B<OSSL_TRACE_CATEGORY_HTTP>.
-See also L<OSSL_trace_enabled(3)> and L<openssl(1)/ENVIRONMENT>.
+See also L<OSSL_trace_enabled(3)> and L<openssl-env(7)>.
 
 =head1 RETURN VALUES
 
@@ -279,7 +279,7 @@ L<OSSL_HTTP_open(3)>,
 L<OSSL_HTTP_get(3)>,
 L<OSSL_HTTP_transfer(3)>,
 L<OSSL_HTTP_close(3)>,
-L<OSSL_trace_enabled(3)>
+L<OSSL_trace_enabled(3)>, and L<openssl-env(7)>.
 
 =head1 HISTORY
 

doc/man3/OSSL_HTTP_transfer.pod

@@ -262,7 +262,7 @@ other HTTP client implementations such as wget, curl, and git.
 
 When built with tracing enabled, OSSL_HTTP_transfer() and all functions using it
 may be traced using B<OSSL_TRACE_CATEGORY_HTTP>.
-See also L<OSSL_trace_enabled(3)> and L<openssl(1)/ENVIRONMENT>.
+See also L<OSSL_trace_enabled(3)> and L<openssl-env(7)>.
 
 =head1 RETURN VALUES
 
@@ -286,7 +286,7 @@ OSSL_HTTP_close() returns 0 if anything went wrong while disconnecting, else 1.
 L<OSSL_HTTP_parse_url(3)>, L<BIO_new_connect(3)>,
 L<ASN1_item_i2d_mem_bio(3)>, L<ASN1_item_d2i_bio(3)>,
 L<OSSL_HTTP_is_alive(3)>,
-L<OSSL_trace_enabled(3)>
+L<OSSL_trace_enabled(3)>, and L<openssl-env(7)>.
 
 =head1 HISTORY
 

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