Update Install and Release notes

weidai11 · Sep 10, 2016 · 222622e · 222622e
1 parent f55a109
commit 222622e
Show file tree

Hide file tree

Showing 3 changed files with 90 additions and 60 deletions.
diff --git a/Install.txt b/Install.txt
@@ -13,9 +13,9 @@ CONTENTS OF THIS FILE
 INTRODUCTION
 ------------
 
-Crypto++ Library is a free C++ class library of cryptographic algorithms and schemes. It was written and placed in public domain by Wei Dai. The library homepage is at http://www.cryptopp.com/. The latest library source code can be found at https://github.com/weidai11/cryptopp. For licensing and copyright information, please see License.txt.
+Crypto++ Library is a free C++ class library of cryptographic algorithms and schemes. It was written and placed in public domain by Wei Dai. The library homepage is at http://www.cryptopp.com/. The latest library source code can be found at http://github.com/weidai11/cryptopp. For licensing and copyright information, please see License.txt.
 
-These are general instructions for the BSDs, Linux, OS X, Solaris and Unix. On BSD you will likely have to use `gmake` to build the library. On Linux, OS X, Solaris and Unix, the system's make should be OK. On Windows, Crypto++ provides Borland and Visual Studio solutions.
+These are general instructions for the BSDs, Linux, OS X, Solaris and Unix. On BSD and Solaris you will likely have to use `gmake` to build the library. On Linux, OS X, Solaris and Unix, the system's make should be OK. On Windows, Crypto++ provides Borland and Visual Studio solutions. Cmake is available, but its still maturing.
 
 Crypto++ uses a GNU makefile, which combines configuration and a non-anemic make. You should look through the GNUmakefile and config.h to ensure settings look reasonable before building. Please pay particular attention to CRYPTOPP_NO_UNALIGNED_DATA_ACCESS in config.h.
 
@@ -34,7 +34,7 @@ In general, all you should have to do is open a terminal, and then:
 The command above builds the static library and cryptest.exe program. If you want to build the shared object, then issue:
 
     make static dynamic cryptest.exe
-	
+
 Or:
 
     make libcryptopp.a libcryptopp.so cryptest.exe
@@ -67,12 +67,12 @@ To install the library into a user selected directory, perform:
 
     make install PREFIX=/usr/local
 
+If you are going to run `make install PREFIX=/usr/local`, then you should build with '-DCRYPTOPP_DATA_DIR='\"$PREFIX/share/cryptopp/\"' to ensure cryptest.exe can locate the test data files and test vectors after installation. The trailing slash in the path is needed because simple preprocessor concatenation is used.
+
 During install, the makefile copies cryptest.exe into $PREFIX/bin, copies headers into $PREFIX/include/cryptopp, and copies libraries into $PREFIX/lib. If you only built a static or dynamic version of the library, then only one library is copied. The install recipe does not fail if the static library or shared object is not built.
 
 PREFIX is non-standard, but its retained for historical purposes. The makefile also responds to `prefix=<path>`.
 
-There are some open issues installing the library because cryptest.exe is not sympathetic to path changes of of its test vectors and test data. See the DataDir patch below to fix it.
-
 
 MAKEFILE TARGETS
 ----------------
@@ -87,21 +87,19 @@ The following are some of the targets provided by the GNU makefile.
 
 `make cryptest.exe` builds the library test harness.
 
-`make test` and `make check` are the same recipe and invoke the test harness with the the validation option. That is, it executes `cryptest.exe v`. 
+`make test` and `make check` are the same recipe and invoke the test harness with the the validation option. That is, it executes `cryptest.exe v`.
 
-`make install` installs the library. By default, the makefile copies into `/usr`. On OpenBSD, `make install` uses `/usr/local` by default because C++ headers should not be placed with the system headers.
+`make install` installs the library. By default, the makefile copies into `/usr/local` by default.
 
 `make clean` cleans most transient and temporary objects.
 
 `make disclean` cleans most objects that are not part of the original distribution.
 
-`make dist` and `make zip` build s ZIP file that is suitable for distribution.
+`make dist` and `make zip` builds ZIP file that is suitable for distribution.
 
+`make iso` builds an ISO on Linux or OS X that is suitable for alternate distribution.
 
-DATADIR PATCH
--------------
-
-The library offers a DataDir patch to help with post-installation issues regarding the location of the test vectors and test data. Its a patch provided by the community, so it must be applied manually. To acquire the patch, see http://www.cryptopp.com/wiki/DataDir.
+`make ubsan` and `make asan` builds the library with the respective sanitizer.
 
 
 DYNAMIC ANALYSIS
@@ -161,9 +159,11 @@ Fifth, the test harness provides a "test vector" option which uses many known te
     .................
     Tests complete. Total tests = 4094. Failed tests = 0.
 
+The library also offers its test script for those who want to use it. The test script is names cryptest.sh, and it repeatedly builds the library and exectues the tests under various configurations. It takes 2 to 4 hours to run on a semi-modern desktop or server; and days to run on an IoT gadget. Also see http://github.com/weidai11/cryptopp/blob/master/cryptest.sh and http://cryptopp.com/wiki/Cryptest.sh.
+
 REPORTING PROBLEMS
 ------------------
 
-Dirty compiles and failures in the validation suite or test vectors should be reported at the Crypto++ User Group. The User Group is located at https://groups.google.com/forum/#!forum/cryptopp-users.
+Dirty compiles and failures in the validation suite or test vectors should be reported at the Crypto++ User Group. The User Group is located at http://groups.google.com/forum/#!forum/cryptopp-users.
 
 Also see http://www.cryptopp.com/wiki/Bug_Report.
diff --git a/License.txt b/License.txt
@@ -1,6 +1,6 @@
 Compilation Copyright (c) 1995-2016 by Wei Dai.  All rights reserved.
-This copyright applies only to this software distribution package 
-as a compilation, and does not imply a copyright on any particular 
+This copyright applies only to this software distribution package
+as a compilation, and does not imply a copyright on any particular
 file in the package.
 
 All individual files in this compilation are placed in the public domain by

diff --git a/Readme.txt b/Readme.txt
@@ -1,14 +1,15 @@
 Crypto++: a C++ Class Library of Cryptographic Schemes
-Version 5.6.3 - NOV/20/2015
+Version 5.6.4 - SEPT/10/2016
 
 Crypto++ Library is a free C++ class library of cryptographic schemes.
 Currently the library contains the following algorithms:
 
                    algorithm type  name
 
  authenticated encryption schemes  GCM, CCM, EAX
-
-        high speed stream ciphers  Panama, Sosemanuk, Salsa20, XSalsa20
+
+        high speed stream ciphers  ChaCha (ChaCha8/12/20), Panama, Sosemanuk,
+                                   Salsa20, XSalsa20
 
            AES and AES candidates  AES (Rijndael), RC6, MARS, Twofish, Serpent,
                                    CAST-256
@@ -20,12 +21,13 @@ Currently the library contains the following algorithms:
   block cipher modes of operation  ECB, CBC, CBC ciphertext stealing (CTS),
                                    CFB, OFB, counter mode (CTR)
 
-     message authentication codes  VMAC, HMAC, GMAC, CMAC, CBC-MAC, DMAC, 
+     message authentication codes  VMAC, HMAC, GMAC, CMAC, CBC-MAC, DMAC,
                                    Two-Track-MAC
 
-                                   SHA-1, SHA-2 (SHA-224, SHA-256, SHA-384, and
-                   hash functions  SHA-512), SHA-3, Tiger, WHIRLPOOL, RIPEMD-128,
-                                   RIPEMD-256, RIPEMD-160, RIPEMD-320
+                                   BLAKE2 (BLAKE2b, BLAKE2s), SHA-1, SHA-2 (SHA-224,
+                   hash functions  SHA-256, SHA-384, and SHA-512), SHA-3, Tiger,
+                                   WHIRLPOOL, RIPEMD-128, RIPEMD-256, RIPEMD-160,
+                                   RIPEMD-320
 
                                    RSA, DSA, ElGamal, Nyberg-Rueppel (NR),
           public-key cryptography  Rabin-Williams (RW), LUC, LUCELG,
@@ -35,8 +37,8 @@ Currently the library contains the following algorithms:
                           systems  EMSA2 and EMSA5
 
                                    Diffie-Hellman (DH), Unified Diffie-Hellman
-            key agreement schemes  (DH2), Menezes-Qu-Vanstone (MQV), LUCDIF,
-                                   XTR-DH
+            key agreement schemes  (DH2), Menezes-Qu-Vanstone (MQV), Hashed MQV (HMQV),
+                                   Fully Hashed MQV (FHMQV), LUCDIF, XTR-DH
 
       elliptic curve cryptography  ECDSA, ECNR, ECIES, ECDH, ECMQV
 
@@ -49,7 +51,7 @@ Other features include:
 
   * pseudo random number generators (PRNG): ANSI X9.17 appendix C, RandomPool
   * password based key derivation functions: PBKDF1 and PBKDF2 from PKCS #5,
-    PBKDF from PKCS #12 appendix B
+    PBKDF from PKCS #12 appendix B, HKDF from RFC 5869
   * Shamir's secret sharing scheme and Rabin's information dispersal algorithm
     (IDA)
   * fast multi-precision integer (bignum) and polynomial operations
@@ -59,18 +61,20 @@ Other features include:
       + DEFLATE (RFC 1951) compression/decompression with gzip (RFC 1952) and
         zlib (RFC 1950) format support
       + hex, base-32, and base-64 coding/decoding
-      + 32-bit CRC and Adler32 checksum
-  * class wrappers for these operating system features (optional):
+      + 32-bit CRC, CRC-C and Adler32 checksum
+  * class wrappers for these platform and operating system features (optional):
       + high resolution timers on Windows, Unix, and Mac OS
       + Berkeley and Windows style sockets
       + Windows named pipes
       + /dev/random, /dev/urandom, /dev/srandom
       + Microsoft's CryptGenRandom on Windows
+      + VIA Padlock, Intel RDRAND and RDSEED
   * A high level interface for most of the above, using a filter/pipeline
     metaphor
   * benchmarks and validation testing
-  * x86, x86-64 (x64), MMX, and SSE2 assembly code for the most commonly used
-    algorithms, with run-time CPU feature detection and code selection
+  * x86, x86_64, MMX, SSE2, SSE4 assembly code for the most commonly used
+    algorithms, with run-time CPU feature detection and code selection.
+    Limited ARM NEON and ARMv8 ASIMD, CRC and Crypto extension support
   * some versions are available in FIPS 140-2 validated form
 
 You are welcome to use it for any purpose without paying me, but see
@@ -80,18 +84,19 @@ The following compilers are supported for this release. Please visit
 http://www.cryptopp.com the most up to date build instructions and porting notes.
 
   * MSVC 6.0 - 2015
-  * GCC 3.3 - 5.2
+  * GCC 3.3 - 7.0
+  * Clang 2.9 - 4.0
   * C++Builder 2010
   * Intel C++ Compiler 9 - 16.0
-  * Sun Studio 12u1, Express 11/08, Express 06/10
+  * Sun Studio 12u1 - 12.5
 
 *** Important Usage Notes ***
 
 1. If a constructor for A takes a pointer to an object B (except primitive
 types such as int and char), then A owns B and will delete B at A's
 destruction.  If a constructor for A takes a reference to an object B,
 then the caller retains ownership of B and should not destroy it until
-A no longer needs it. 
+A no longer needs it.
 
 2. Crypto++ is thread safe at the class level. This means you can use
 Crypto++ safely in a multithreaded application, but you must provide
@@ -108,11 +113,11 @@ form of the static library. MSVC project files are included to build
 all three forms, and sample applications using each of the three forms
 are also included.
 
-To compile Crypto++ with MSVC, open the "cryptest.dsw" (for MSVC 6 and MSVC .NET 
-2003) or "cryptest.sln" (for MSVC 2005 - 2010) workspace file and build one or 
-more of the following projects:
+To compile Crypto++ with MSVC, open  "cryptest.sln" (for MSVC 2005 - 2015)
+or "cryptest.dsw" (for MSVC 6 and MSVC .NET 2003) workspace file and build
+one or more of the following projects:
 
-cryptopp - This builds the DLL. Please note that if you wish to use Crypto++
+cryptdll - This builds the DLL. Please note that if you wish to use Crypto++
   as a FIPS validated module, you must use a pre-built DLL that has undergone
   the FIPS validation process instead of building your own.
 dlltest - This builds a sample application that only uses the DLL.
@@ -135,27 +140,27 @@ run-time libraries and calling conventions.
 
 *** DLL Memory Management ***
 
-Because it's possible for the Crypto++ DLL to delete objects allocated 
-by the calling application, they must use the same C++ memory heap. Three 
+Because it's possible for the Crypto++ DLL to delete objects allocated
+by the calling application, they must use the same C++ memory heap. Three
 methods are provided to achieve this.
-1.  The calling application can tell Crypto++ what heap to use. This method 
+1.  The calling application can tell Crypto++ what heap to use. This method
     is required when the calling application uses a non-standard heap.
-2.  Crypto++ can tell the calling application what heap to use. This method 
-    is required when the calling application uses a statically linked C++ Run 
-    Time Library. (Method 1 does not work in this case because the Crypto++ DLL 
+2.  Crypto++ can tell the calling application what heap to use. This method
+    is required when the calling application uses a statically linked C++ Run
+    Time Library. (Method 1 does not work in this case because the Crypto++ DLL
     is initialized before the calling application's heap is initialized.)
-3.  Crypto++ can automatically use the heap provided by the calling application's 
+3.  Crypto++ can automatically use the heap provided by the calling application's
     dynamically linked C++ Run Time Library. The calling application must
     make sure that the dynamically linked C++ Run Time Library is initialized
     before Crypto++ is loaded. (At this time it is not clear if it is possible
     to control the order in which DLLs are initialized on Windows 9x machines,
     so it might be best to avoid using this method.)
 
-When Crypto++ attaches to a new process, it searches all modules loaded 
-into the process space for exported functions "GetNewAndDeleteForCryptoPP" 
-and "SetNewAndDeleteFromCryptoPP". If one of these functions is found, 
-Crypto++ uses methods 1 or 2, respectively, by calling the function. 
-Otherwise, method 3 is used. 
+When Crypto++ attaches to a new process, it searches all modules loaded
+into the process space for exported functions "GetNewAndDeleteForCryptoPP"
+and "SetNewAndDeleteFromCryptoPP". If one of these functions is found,
+Crypto++ uses methods 1 or 2, respectively, by calling the function.
+Otherwise, method 3 is used.
 
 *** GCC-Specific Information ***
 
@@ -169,9 +174,10 @@ suite.
 Crypto++ is documented through inline comments in header files, which are
 processed through Doxygen to produce an HTML reference manual. You can find
 a link to the manual from http://www.cryptopp.com. Also at that site is
-the Crypto++ FAQ, which you should browse through before attempting to 
+the Crypto++ FAQ, which you should browse through before attempting to
 use this library, because it will likely answer many of questions that
-may come up.
+may come up. Finally, the site provide the wiki which has many topics
+and code examples.
 
 If you run into any problems, please try the Crypto++ mailing list.
 The subscription information and the list archive are available on
@@ -316,7 +322,7 @@ the mailing list.
     - changed SocketSource and SocketSink to use overlapped I/O on Microsoft Windows
     - grouped related classes inside structs to help templates, for example
       AESEncryption and AESDecryption are now AES::Encryption and AES::Decryption
-    - where possible, typedefs have been added to improve backwards 
+    - where possible, typedefs have been added to improve backwards
       compatibility when the CRYPTOPP_MAINTAIN_BACKWARDS_COMPATIBILITY macro is defined
     - changed Serpent, HAVAL and IDEA to use public domain code
     - implemented SSE2 optimizations for Integer operations
@@ -372,7 +378,7 @@ the mailing list.
 
 5.2.2 - added SHA-224
       - put SHA-256, SHA-384, SHA-512, RSASSA-PSS into DLL
-      
+
 5.2.3 - fixed issues with FIPS algorithm test vectors
       - put RSASSA-ISO into DLL
 
@@ -410,9 +416,9 @@ the mailing list.
       - fixed possible branch prediction analysis (BPA) vulnerability in
         MontgomeryReduce(), which may affect security of RSA, RW, LUC
       - fixed link error with MSVC 2003 when using "debug DLL" form of runtime library
-      - fixed crash in SSE2_Add on P4 machines when compiled with 
+      - fixed crash in SSE2_Add on P4 machines when compiled with
         MSVC 6.0 SP5 with Processor Pack
-      - ported to MSVC 2008, GCC 4.2, Sun CC 5.9, Intel C++ Compiler 10.0, 
+      - ported to MSVC 2008, GCC 4.2, Sun CC 5.9, Intel C++ Compiler 10.0,
         and Borland C++Builder 2007
 
 5.6.0 - added AuthenticatedSymmetricCipher interface class and Filter wrappers
@@ -421,7 +427,7 @@ the mailing list.
       - added OIDs for Brainpool elliptic curve parameters
       - improved AES and SHA-256 speed on x86 and x64
       - changed BlockTransformation interface to no longer assume data alignment
-      - fixed incorrect VMAC computation on message lengths 
+      - fixed incorrect VMAC computation on message lengths
         that are >64 mod 128 (x86 assembly version is not affected)
       - fixed compiler error in vmac.cpp on x86 with GCC -fPIC
       - fixed run-time validation error on x86-64 with GCC 4.3.2 -O2
@@ -451,6 +457,7 @@ the mailing list.
 
 5.6.3 - maintenance release, honored API/ABI/Versioning requirements
       - expanded processes to include community and its input
+          * 12 unique contributors for this release
       - fixed CVE-2015-2141
       - cleared most Undefined Behavior Sanitizer (UBsan) findings
       - cleared all Address Sanitizer (Asan) findings
@@ -490,10 +497,33 @@ the mailing list.
       - added additional Doxygen-based documentation
       - ported to MSVC 2015, Xcode 7.2, GCC 5.2, Clang 3.7, Intel C++ 16.00
 
-5.7  - nearly identical to 5.6.3
-     - minor breaks to the ABI and API
-     - cleared remaining Undefined Behavior Sanitizer (UBsan) findings
-     - cleared remaining GCC and Visual Studio warnings
-     - removed CRYPTOPP_MAINTAIN_BACKWARDS_COMPATIBILITY_562
+5.6.4 - maintenance release, honored API/ABI/Versioning requirements
+      - expanded community input and support
+          * 22 unique contributors for this release
+      - fixed CVE-2016-3995
+      - changed SHA3 to FIPS 202 (F1600, XOF d=0x01)
+      - added Keccak (F1600, XOF d=0x06)
+      - added ChaCha (ChaCha8/12/20)
+      - added HMQV and FHMQV
+          * Hashed and Fully Hashed MQV
+      - added BLAKE2 (BLAKE2s and BLAKE2b)
+          * C++, SSE2, SSE4, ARM NEON and ARMv8 ASIMD
+      - added CRC32-C
+          * C/C++, Intel CRC, and ARMv8 CRC
+      - improved GCM mode
+          * ARMv8 ASIMD using carry-less multiply
+      - improved MIPS, ARMv7 and ARMv8 support
+          * more IoT gadget testing
+      - improved build systems
+          * Visual Studio 2010 default
+          * added Cmake support
+          * archived VC++ 5/0/6.0 and VS2005 project files
+          * archived Borland project files
+      - improved Testing and QA
+          * additional platform and compiller support
+          * additional tests in cryptest.sh
+          * added C++11, C++17, C++14, C++17 testing
+          * added -O3, -O5, -Ofast and -Os testing
+      - ported to MSVC 2015 SP3, Xcode 9.0, GCC 7.0, Clang 4.0, Intel C++ 17.00
 
 Written by Wei Dai and the Crypto++ Project