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]
 
 
  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
 
      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",
                  "ssl-trace"           => "default",
                  "ssl3"                => "default",
                  "ssl3-method"         => "default",
+                 "trace"               => "default",
                   "ubsan"              => "default",
                  "unit-test"           => "default",
                  "weak-ssl-ciphers"    => "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.
 
                    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.
 
   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.
 
 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
 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);
     }
 
         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:
 
 
 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
 
 
 =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
 
 When the library is built with tracing disabled, the macro
 C<OPENSSL_NO_TRACE> is defined in C<openssl/opensslconf.h> and all