Update NEWS file, including ABI issue.

diff --git a/NEWS b/NEWS
index feae6262caa4db2ebb486b880dd7ab257ca31786..99a67739efab30cbb1df9392f09c48aa32343729 100644 (file)
--- a/NEWS
+++ b/NEWS
@@ -1,5 +1,9 @@
 NEWS for the Nettle 3.4 release
 
+       This release fixes bugs and adds a few new features. It also
+       addresses an ABI compatibility issue affecting Nettle-3.1 and
+       later, see below.
+
        Bug fixes:
 
        * Fixed an improper use of GMP mpn_mul, breaking curve2559 and
@@ -11,6 +15,17 @@ NEWS for the Nettle 3.4 release
        * Fix compilation error with --enable-fat om ARM. Fix
          contributed by Andreas Schneider.
 
+       * Reorganized the way data items are made available in the
+         ABI.
+
+         Short version: Nettle header files now define the symbols
+         nettle_hashes, nettle_aeads, nettle_armors, as well as the
+         ecc curves nettle_secp_*, as preprocessor macros invoking a
+         corresponding function returning the address of the data
+         item. For backwards ABI compatibility, the symbols are still
+         present in the compiled libraries, and with the same sizes
+         as in nettle-3.3.
+
        New features:
 
        * Support for RSA-PSS signatures, contributed by Daiki Ueno.
@@ -27,6 +42,55 @@ NEWS for the Nettle 3.4 release
          architecture independent, except in --enable-mini-gmp
          configurations.
 
+       ABI issue:
+
+         Since the breakage was a bit subtle, let me document it here.
+         The nettle and hogweed libraries export a couple of data
+         symbols, and for some of these, the size was never intended to
+         be part of the api. E.g.,
+
+           extern const struct nettle_hash * const nettle_hashes[];
+
+         which is an NULL-terminated array, and
+
+           extern const struct ecc_curve nettle_secp_256r1;
+
+         where the ecc_curve struct is only forward declared in the
+         public headers.
+
+         It turns out the sizes nevertheless may leak into the ABI, and
+         that increasing the sizes can break old executables linked
+         with a newer version of the library.
+
+         When linking a classic non-PIE executable with a shared
+         library, we get ELF relocations of type R_X86_64_COPY for
+         references to data items. These mean that the linker allocates
+         space for the data item in the data segment of executable, at
+         a fixed address determined at link-time, and with size
+         extracted from the version of the .so-file seen when linking.
+
+         At load time, the run time linker then copies the contents of
+         the symbol from the .so file to that location, and uses the
+         copy instead of the version loaded with the .so-file. And if
+         the data item in the .so file used at load time is larger than
+         the data item seen at link time, it is silently truncated in
+         the process.
+
+         So when SHA3 hashes were was added to the nettle_hashes array
+         in the nettle-3.3 release, this way of linking produces a
+         truncated array at load time, no longer NULL-terminated.
+
+         In some future version, the plan is to add a leading
+         underscore to the name of the actual data items, e.g.,
+         nettle_hashes --> _nettle_hashes, breaking the ABI. While
+         keeping the nettle_get_hashes function and the nettle_hashes
+         macro as the supported ways to access it.
+
+       The shared library names are libnettle.so.6.4 and
+       libhogweed.so.4.4, with sonames still libnettle.so.6 and
+       libhogweed.so.4. It is intended to be fully binary compatible
+       with nettle-3.1.
+
 NEWS for the Nettle 3.3 release
 
        This release fixes a couple of bugs, and improves resistance