From: Niels Möller <nisse@lysator.liu.se>
Date: Sun, 5 Nov 2017 22:23:42 +0000 (+0100)
Subject: Update NEWS file, including ABI issue.
X-Git-Tag: nettle_3.4rc1~7
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=380e5d30e72696f94c98dbb38a4eb50157de8d5d;p=thirdparty%2Fnettle.git

Update NEWS file, including ABI issue.
---

diff --git a/NEWS b/NEWS
index feae6262..99a67739 100644
--- 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