Configure: disable new trace api by default
authorDr. Matthias St. Pierre <Matthias.St.Pierre@ncp-e.com>
Wed, 13 Mar 2019 22:16:29 +0000 (23:16 +0100)
committerDr. Matthias St. Pierre <Matthias.St.Pierre@ncp-e.com>
Thu, 14 Mar 2019 09:32:58 +0000 (10:32 +0100)
Fixes #8472

Reviewed-by: Richard Levitte <levitte@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/8474)

CHANGES
Configure
INSTALL
doc/man3/OSSL_trace_enabled.pod
doc/man3/OSSL_trace_set_channel.pod

diff --git a/CHANGES b/CHANGES
index d977c76..0f7b77a 100644 (file)
--- a/CHANGES
+++ b/CHANGES
@@ -9,9 +9,14 @@
 
  Changes between 1.1.1 and 3.0.0 [xx XXX xxxx]
 
-  *) Added support for enabling instrumentation through trace output.
-     This is left to application control, by allowing it to register BIOs as
-     channels for a number of tracing and debugging categories.
+  *) Added a new generic trace API which provides support for enabling
+     instrumentation through trace output. This feature is mainly intended
+     as an aid for developers and is disabled by default. To utilize it,
+     OpenSSL needs to be configured with the `enable-trace` option.
+
+     If the tracing API is enabled, the application can activate trace output
+     by registering BIOs as trace channels for a number of tracing and debugging
+     categories.
 
      The 'openssl' application has been expanded to enable any of the types
      available via environment variables defined by the user, and serves as
index 8818d58..6b533f4 100755 (executable)
--- a/Configure
+++ b/Configure
@@ -464,6 +464,7 @@ our %disabled = ( # "what"         => "comment"
                  "ssl-trace"           => "default",
                  "ssl3"                => "default",
                  "ssl3-method"         => "default",
+                 "trace"               => "default",
                   "ubsan"              => "default",
                  "unit-test"           => "default",
                  "weak-ssl-ciphers"    => "default",
diff --git a/INSTALL b/INSTALL
index d8c5dc5..cffa241 100644 (file)
--- a/INSTALL
+++ b/INSTALL
                    require additional system-dependent options! See "Note on
                    multi-threading" below.
 
+  enable-trace
+                   Build with support for the integrated tracing api. See manual pages
+                   OSSL_trace_set_channel(3) and OSSL_trace_enabled(3) for details.
+
   no-ts
                    Don't build Time Stamping Authority support.
 
index ecb88ab..db3f99c 100644 (file)
@@ -20,7 +20,7 @@ The functions described here are mainly interesting for those who provide
 OpenSSL functionality, either in OpenSSL itself or in engine modules
 or similar.
 
-If operational (see L</NOTES> below), these functions are used to
+If tracing is enabled (see L</NOTES> below), these functions are used to
 generate free text tracing output.
 
 The tracing output is divided into types which are enabled
@@ -110,10 +110,11 @@ OSSL_trace_enabled() before generating any output, for example:
         OSSL_trace_end(OSSL_TRACE_CATEGORY_TLS, trace);
     }
 
-=head2 Tracing disabled
+=head2 Configure Tracing
 
-The OpenSSL library may be built with tracing disabled, which makes
-everything documented here inoperational.
+By default, the OpenSSL library is built with tracing disabled. To
+use the tracing functionality documented here, it is therefore
+necessary to configure and build OpenSSL with the 'enable-trace' option.
 
 When the library is built with tracing disabled:
 
index 6981dbc..fb680a5 100644 (file)
@@ -261,10 +261,11 @@ The output is almost the same as for the simple example above.
 
 =head1 NOTES
 
-=head2 Tracing disabled
+=head2 Configure Tracing
 
-The OpenSSL library may be built with tracing disabled, which makes
-everything documented here inoperational.
+By default, the OpenSSL library is built with tracing disabled. To
+use the tracing functionality documented here, it is therefore
+necessary to configure and build OpenSSL with the 'enable-trace' option.
 
 When the library is built with tracing disabled, the macro
 C<OPENSSL_NO_TRACE> is defined in C<openssl/opensslconf.h> and all