From 02ccb5d139c58b1ada882762987c8ec0a9bba659 Mon Sep 17 00:00:00 2001 From: "Pierre R. Mai" Date: Wed, 14 Sep 2016 16:55:42 +0200 Subject: [PATCH] Adjust documentation for release 1.1.0, adjust copyrights. --- COPYING | 2 +- NEWS | 14 ++++++++++++++ README | 44 +++++++++++++++++++++++++++++++++++-------- common.lisp | 2 +- keccak-16bit.lisp | 2 +- keccak-32bit.lisp | 2 +- keccak-64bit.lisp | 2 +- keccak-reference.lisp | 2 +- pkgdef.lisp | 2 +- sha3.asd | 4 ++-- sha3.lisp | 2 +- 11 files changed, 60 insertions(+), 18 deletions(-) mode change 100644 => 100755 COPYING mode change 100644 => 100755 NEWS mode change 100644 => 100755 README mode change 100644 => 100755 keccak-16bit.lisp mode change 100644 => 100755 keccak-32bit.lisp mode change 100644 => 100755 keccak-64bit.lisp mode change 100644 => 100755 keccak-reference.lisp mode change 100644 => 100755 pkgdef.lisp mode change 100644 => 100755 sha3.asd diff --git a/COPYING b/COPYING old mode 100644 new mode 100755 index 13d39e7..b364f0d --- a/COPYING +++ b/COPYING @@ -1,4 +1,4 @@ - Copyright (C) 2012 PMSF IT Consulting Pierre R. Mai + Copyright (C) 2012 -- 2016 PMSF IT Consulting Pierre R. Mai Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/NEWS b/NEWS old mode 100644 new mode 100755 index f01cbad..d0bb8f5 --- a/NEWS +++ b/NEWS @@ -1,3 +1,17 @@ +Release 1.1.0 +============= + + * Change sha3 functions to match the final FIPS 202 SHA3 standard, + by appending a 01 suffix to messages prior to digest calculation. + The old Keccak submission behavior can be retained by passing in + the new raw-keccak-p keyword argument with true to the relevant + functions. Thanks to David McClain for prompting this change. + + * Fixes a bug in the bug fix of release 1.0.2 for the sha3-update + handling of not completely filled buffers reported by David McClain, + which could lead to out-of-bounds accesses in calls to the + pad-message-to-width function. + Release 1.0.2 ============= diff --git a/README b/README old mode 100644 new mode 100755 index 2a8e763..53ec22e --- a/README +++ b/README @@ -10,6 +10,16 @@ therefore erroneous message digests being generated. Uses with only one call to sha3-update and the high-level routines were not affected by this bug. +NOTE that prior to release 1.1.0 this package computed digests +based on the Keccak submission to the SHA-3 contest and did not +yet take into account the added suffix that the FIPS 202 SHA-3 +final standard adds to messages prior to calculating the digest, +since this was not part of the Keccak submission. Starting with +1.1.0 the functions in the sha3 package do by default calculate +disgests that match the FIPS 202 standard, and will calculate +the old pre-standard digests only if the new optional keyword +argument :raw-keccak-p is passed with a true value. + The code should be portable across nearly all ANSI compliant CL implementations with specialized versions tuned for implementations that offer unboxed 64bit arithmetic, unboxed 32bit arithmetic and for @@ -51,11 +61,14 @@ The mid-level interfaces to the digest routines are the functions simple-array with element-type (unsigned-byte 8), bounded by `start' and `end', which must be numeric bounding-indices. -- sha3:sha3-final state &key output-bit-length +- sha3:sha3-final state &key output-bit-length raw-keccak-p If the given SHA-3 state `state' has not already been finalized, finalize it by processing any remaining input in its buffer, with - suitable padding as specified by the SHA-3 standard. Returns the + the specified suffix of 01 and suitable padding as specified by the + SHA-3 standard (the specified SHA-3 suffix can be elided with the + optional keyword argument `raw-keccak-p' to generate digests as the + initial Keccak submission would have generated). Returns the message digest as a simple-array of (unsigned-byte 8). The length of the returned digest is determined either by the output bit length or bit rate specified on state creation, or for the special case of @@ -67,28 +80,43 @@ For convenience the following high-level functions produce digests in one step from 1d simple-arrays and streams with element-type (unsigned-byte 8), as well as files: -- sha3:sha3-digest-vector vector &key (start 0) end (output-bit-length 512) +- sha3:sha3-digest-vector vector &key (start 0) end (output-bit-length 512) raw-keccak-p Calculate an SHA-3 message-digest of data in `vector', which should be a 1d simple-array with element type (unsigned-byte 8), bounded by `start' and `end'. The bit length of the message digest produced is controlled by `output-bit-length', which can take on the values 224, - 256, 288, 384 and 512, which is the default value. + 256, 288, 384 and 512, which is the default value. Using the optional + `raw-keccak-p' keyword argument the SHA-3 mandated 01 suffix that is + appended to the actual message prior to padding can be elided to yield + message digests that match the original Keccak submission instead of + the actual SHA-3 standard. Use this option only for compatibility + with historical implementations. -- sha3:sha3-digest-stream stream &key (output-bit-length 512) +- sha3:sha3-digest-stream stream &key (output-bit-length 512) raw-keccak-p Calculate an SHA-3 message-digest of data read from `stream', which should be a stream with element type (unsigned-byte 8). The bit length of the message digest produced is controlled by `output-bit-length', which can take on the values 224, 256, 288, 384 - and 512, which is the default value. + and 512, which is the default value. Using the optional `raw-keccak-p' + keyword argument the SHA-3 mandated 01 suffix that is appended to the + actual message prior to padding can be elided to yield message digests + that match the original Keccak submission instead of the actual SHA-3 + standard. Use this option only for compatibility with historical + implementations. -- sha3:sha3-digest-file pathname &key (output-bit-length 512) +- sha3:sha3-digest-file pathname &key (output-bit-length 512) raw-keccak-p Calculate an SHA-3 message-digest of the file specified by `pathname'. The bit length of the message digest produced is controlled by `output-bit-length', which can take on the values 224, - 256, 288, 384 and 512, which is the default value. + 256, 288, 384 and 512, which is the default value. Using the optional + `raw-keccak-p' keyword argument the SHA-3 mandated 01 suffix that is + appended to the actual message prior to padding can be elided to yield + message digests that match the original Keccak submission instead of + the actual SHA-3 standard. Use this option only for compatibility + with historical implementations. Note that in order to generate a message digest of a string it will have to be converted to a simple-array with element-type diff --git a/common.lisp b/common.lisp index 1ec0fb2..217f364 100755 --- a/common.lisp +++ b/common.lisp @@ -1,6 +1,6 @@ ;;;; SHA3 --- Secure Hash Algorithm 3 (Keccak) Implementation ;;;; -;;;; Copyright (C) 2012 PMSF IT Consulting Pierre R. Mai. +;;;; Copyright (C) 2012 -- 2016 PMSF IT Consulting Pierre R. Mai. ;;;; ;;;; Permission is hereby granted, free of charge, to any person obtaining ;;;; a copy of this software and associated documentation files (the diff --git a/keccak-16bit.lisp b/keccak-16bit.lisp old mode 100644 new mode 100755 index 014426d..6b2b765 --- a/keccak-16bit.lisp +++ b/keccak-16bit.lisp @@ -1,6 +1,6 @@ ;;;; SHA3 --- Secure Hash Algorithm 3 (Keccak) Implementation ;;;; -;;;; Copyright (C) 2012 PMSF IT Consulting Pierre R. Mai. +;;;; Copyright (C) 2012 -- 2016 PMSF IT Consulting Pierre R. Mai. ;;;; ;;;; Permission is hereby granted, free of charge, to any person obtaining ;;;; a copy of this software and associated documentation files (the diff --git a/keccak-32bit.lisp b/keccak-32bit.lisp old mode 100644 new mode 100755 index ddd18ef..63fecf2 --- a/keccak-32bit.lisp +++ b/keccak-32bit.lisp @@ -1,6 +1,6 @@ ;;;; SHA3 --- Secure Hash Algorithm 3 (Keccak) Implementation ;;;; -;;;; Copyright (C) 2012 PMSF IT Consulting Pierre R. Mai. +;;;; Copyright (C) 2012 -- 2016 PMSF IT Consulting Pierre R. Mai. ;;;; ;;;; Permission is hereby granted, free of charge, to any person obtaining ;;;; a copy of this software and associated documentation files (the diff --git a/keccak-64bit.lisp b/keccak-64bit.lisp old mode 100644 new mode 100755 index 914851b..78c58db --- a/keccak-64bit.lisp +++ b/keccak-64bit.lisp @@ -1,6 +1,6 @@ ;;;; SHA3 --- Secure Hash Algorithm 3 (Keccak) Implementation ;;;; -;;;; Copyright (C) 2012 PMSF IT Consulting Pierre R. Mai. +;;;; Copyright (C) 2012 -- 2016 PMSF IT Consulting Pierre R. Mai. ;;;; ;;;; Permission is hereby granted, free of charge, to any person obtaining ;;;; a copy of this software and associated documentation files (the diff --git a/keccak-reference.lisp b/keccak-reference.lisp old mode 100644 new mode 100755 index 4258fb8..27eac0d --- a/keccak-reference.lisp +++ b/keccak-reference.lisp @@ -1,6 +1,6 @@ ;;;; SHA3 --- Secure Hash Algorithm 3 (Keccak) Implementation ;;;; -;;;; Copyright (C) 2012 PMSF IT Consulting Pierre R. Mai. +;;;; Copyright (C) 2012 -- 2016 PMSF IT Consulting Pierre R. Mai. ;;;; ;;;; Permission is hereby granted, free of charge, to any person obtaining ;;;; a copy of this software and associated documentation files (the diff --git a/pkgdef.lisp b/pkgdef.lisp old mode 100644 new mode 100755 index 3449bca..1709e1a --- a/pkgdef.lisp +++ b/pkgdef.lisp @@ -1,6 +1,6 @@ ;;;; SHA3 --- Secure Hash Algorithm 3 (Keccak) Implementation ;;;; -;;;; Copyright (C) 2012 PMSF IT Consulting Pierre R. Mai. +;;;; Copyright (C) 2012 -- 2016 PMSF IT Consulting Pierre R. Mai. ;;;; ;;;; Permission is hereby granted, free of charge, to any person obtaining ;;;; a copy of this software and associated documentation files (the diff --git a/sha3.asd b/sha3.asd old mode 100644 new mode 100755 index 007f23b..94d55a8 --- a/sha3.asd +++ b/sha3.asd @@ -1,6 +1,6 @@ ;;;; SHA3 --- Secure Hash Algorithm 3 (Keccak) Implementation ;;;; -;;;; Copyright (C) 2012 PMSF IT Consulting Pierre R. Mai. +;;;; Copyright (C) 2012 -- 2016 PMSF IT Consulting Pierre R. Mai. ;;;; ;;;; Permission is hereby granted, free of charge, to any person obtaining ;;;; a copy of this software and associated documentation files (the @@ -42,7 +42,7 @@ :author "Pierre R. Mai " :maintainer "Pierre R. Mai " :licence "MIT/X11" - :version "1.0.2" + :version "1.1.0" #+sbcl :depends-on #+sbcl ("sb-rotate-byte") :components ((:file "pkgdef") (:file "common" :depends-on ("pkgdef")) diff --git a/sha3.lisp b/sha3.lisp index 6edc0e7..cb9a439 100755 --- a/sha3.lisp +++ b/sha3.lisp @@ -1,6 +1,6 @@ ;;;; SHA3 --- Secure Hash Algorithm 3 (Keccak) Implementation ;;;; -;;;; Copyright (C) 2012 PMSF IT Consulting Pierre R. Mai. +;;;; Copyright (C) 2012 -- 2016 PMSF IT Consulting Pierre R. Mai. ;;;; ;;;; Permission is hereby granted, free of charge, to any person obtaining ;;;; a copy of this software and associated documentation files (the