sha3 0.1.1 → 0.2.0

data/.document

@@ -1,3 +1,4 @@
-- 
+-
+README.rdoc
 ChangeLog.rdoc
 LICENSE.txt

data/.gitignore

@@ -1,5 +1,6 @@
 *.gem
 *.rbc
+*.rbx
 .bundle
 .config
 coverage
@@ -17,10 +18,6 @@ tmp/
 _yardoc
 doc/
 
-install.sh
 *.lock
-
-*.bundle
-
-spec/bench.rb
-.rbx/
+*.so
+Makefile

data/.travis.yml

@@ -2,8 +2,14 @@ language: ruby
 rvm:
   - 1.9.3
   - 1.9.2
+  - 1.8.7
+  - ruby-head
   - rbx-18mode
   - rbx-19mode
-  - 1.8.7
+  - ree
+  
+gemfile: Gemfile.ci
 
-gemfile: Gemfile.ci
+branches:
+  only:
+    - master

data/.yardopts

@@ -1 +1 @@
---markup rdoc --title "sha3 Documentation" --protected
+lib/**/*.rb ext/**/_sha3.c --markup rdoc --title "sha3 Documentation" --protected

data/ChangeLog.rdoc

@@ -6,3 +6,6 @@
 
 * Replaced Keccak reference code with optimized (~10x faster)
 
+=== 0.2.0 / 2012-11-1
+
+* SHA3::Digest: A proper ::Digest subclass.

data/README.rdoc

@@ -1,44 +1,105 @@
-= sha3 {<img src="https://secure.travis-ci.org/johanns/sha3.png" alt="Build Status" />}[http://travis-ci.org/johanns/sha3]
+= sha3 
 
-* {Homepage}[https://github.com/johanns/sha3#readme]
-* {Issues}[https://github.com/johanns/sha3/issues]
-* {Documentation}[http://rubydoc.info/gems/sha3/frames]
+{<img src="https://secure.travis-ci.org/johanns/sha3.png" alt="Build Status" />}[http://travis-ci.org/johanns/sha3]
+Home :: https://github.com/johanns/sha3#readme
+Issues :: https://github.com/johanns/sha3/issues
+Documentation :: http://rubydoc.info/gems/sha3/frames
 
 == Description
 
-A native SHA3 Ruby gem.
+<em>SHA3 for Ruby</em> is a native (C) implementation of Keccak (SHA3) cryptographic hashing algorithm.
 
-== Features/Status/Etc.
++SHA3::Digest+ is a *Digest*[http://www.ruby-doc.org/stdlib-1.9.3/libdoc/digest/rdoc/Digest.html] compliant _subclass_ with complete interface support.
 
-4th Oct. 2012: This is very alpha quality code, and not suitable for production.
++SHA3::Digest.compute()+ method provides support for bit-length hashing.
 
-== Install
+== Releases
+
+*0.1.x* :: Alpha code, and not suitable for production.
+*0.2.0* :: Production worthy, but breaks API compatibility with 0.1.x. Backward-compatibility will be maintained henceforth.
+
+== Installation
 
   $ gem install sha3
 
-== Examples
+== Usage
 
   require 'sha3'
 
-  # Basic usage
-  SHA3::digest_224("Crazy Man's Utopia")
-  => "\xF8\x1A4\xACW6\v\x01A \x99\x11i\x91\xB3q\xB5\xF5\x04\xD4\x88fn\xC6\xA7\xEA\xBBb"
+Valid hash bit-lengths are: *224*, *256*, *384*, *512*. You may also use corresponding symbols when instantiating a new instance or calling the +compute()+ method: 
+  
+  :sha224
+  :sha256 
+  :sha384
+  :sha512
+
+=== Basics
+  
+  # Instantiate a new SHA3::Digest class with 256 bit length
+  s = SHA3::Digest.new(:sha256)
+  # => #<SHA3::Digest: c5d2460186f7233c927e7db2dcc703c0e500b653ca82273b7bfad8045d85a470>
+
+  # Update hash state, and compute new value
+  s.update "Compute Me"
+  # => #<SHA3::Digest: c5d2460186f7233c927e7db2dcc703c0e500b653ca82273b7bfad8045d85a470>
+  
+  # << is an .update() alias
+  s << "Me too"
+  # => #<SHA3::Digest: e26f539eee3a05c52eb1f9439652d23343adea9764f011da232d24cd6d19924a>
+  
+  # Print digest bytes string
+  puts s.digest
+  
+  # Print digest hex string
+  puts s.hexdigest
+
+=== Hashing a file
+
+  # Compute the hash value for given file, and return the result as hex
+  s = SHA3::Digest.new(224).file("my_fantastical_file.bin").hexdigest
+
+=== Bit-length hashing
+  
+  # Compute hash of "011"
+  SHA3::Digest.compute(:sha224, "\xC0", 3).unpack("H*")
+  # => ["2b695a6fd92a2b3f3ce9cfca617d22c9bb52815dd59a9719b01bad25"]
+
+== Development
 
-  # A bit more advanced
-  SHA3::digest("Crazy Man's Utopia", 36, 512).unpack("H*")
-  => ["bc9d6cea2083c219c80d2f3...884059103313040bcf73562"]
+* Native build tools (e.g., GCC, Minigw, etc.)
+* Gems: rubygems-tasks, rake, rspec, yard
 
-== Requirements
+== RSpec
 
-Native build environment (GCC 4.x).
+Call +rake+ to run the included RSpec tests.
 
-Tested with Rubies (see build status up-top):
+Please note that only a small subset of test vectors are included in this source repository; however, the complete test vectors suite is available for download. Simply run the +test.sh+ shell script (available in the root of source directory) to generate full bit-length RSpec test files.
 
-  - 1.9.3
-  - 1.9.2
-  - 1.8.7
+  sh test.sh
+
+== Rubies
+
+Tested with Rubies:
+
+  - MRI 1.9.3
+  - MRI 1.9.2
+  - MRI 1.8.7
+  - MRI Ruby-Head
   - Rubinius (18mode)
   - Rubinius (19mode)
+  - ree
+
+On:
+
+  - Ubuntu 12.04, 12.10
+  - Windows 7, 8
+  - Mac OS X 10.8
+
+== TO DO:
+
+* Documentation (resolve order issue with Yard)!
+* Add support for arbitrary length hashes.
+* Add hex output support to compute method.
 
 == Copyright
 

data/Rakefile

@@ -47,7 +47,7 @@ begin
     ext.name = 'sha3_n'
     ext.ext_dir = 'ext/sha3'
     ext.tmp_dir = 'tmp'
-    ext.source_pattern = "*.{c,cpp}"
+    ext.source_pattern = "*.{c}"
   end
 rescue LoadError => e
   task :compile do

data/ext/sha3/KeccakF-1600-reference.c-arch

@@ -0,0 +1,300 @@
+/*
+The Keccak sponge function, designed by Guido Bertoni, Joan Daemen,
+Michaël Peeters and Gilles Van Assche. For more information, feedback or
+questions, please refer to our website: http://keccak.noekeon.org/
+
+Implementation by the designers,
+hereby denoted as "the implementer".
+
+To the extent possible under law, the implementer has waived all copyright
+and related or neighboring rights to the source code in this file.
+http://creativecommons.org/publicdomain/zero/1.0/
+*/
+
+#include <stdio.h>
+#include <string.h>
+#include "brg_endian.h"
+#include "displayIntermediateValues.h"
+#include "KeccakNISTInterface.h"
+#include "KeccakF-1600-interface.h"
+
+typedef unsigned char UINT8;
+typedef unsigned long long int UINT64;
+
+#define nrRounds 24
+UINT64 KeccakRoundConstants[nrRounds];
+#define nrLanes 25
+unsigned int KeccakRhoOffsets[nrLanes];
+
+void KeccakPermutationOnWords(UINT64 *state);
+void theta(UINT64 *A);
+void rho(UINT64 *A);
+void pi(UINT64 *A);
+void chi(UINT64 *A);
+void iota(UINT64 *A, unsigned int indexRound);
+
+void fromBytesToWords(UINT64 *stateAsWords, const unsigned char *state)
+{
+    unsigned int i, j;
+
+    for(i=0; i<(KeccakPermutationSize/64); i++) {
+        stateAsWords[i] = 0;
+        for(j=0; j<(64/8); j++)
+            stateAsWords[i] |= (UINT64)(state[i*(64/8)+j]) << (8*j);
+    }
+}
+
+void fromWordsToBytes(unsigned char *state, const UINT64 *stateAsWords)
+{
+    unsigned int i, j;
+
+    for(i=0; i<(KeccakPermutationSize/64); i++)
+        for(j=0; j<(64/8); j++)
+            state[i*(64/8)+j] = (stateAsWords[i] >> (8*j)) & 0xFF;
+}
+
+void KeccakPermutation(unsigned char *state)
+{
+#if (PLATFORM_BYTE_ORDER != IS_LITTLE_ENDIAN)
+    UINT64 stateAsWords[KeccakPermutationSize/64];
+#endif
+
+    displayStateAsBytes(1, "Input of permutation", state);
+#if (PLATFORM_BYTE_ORDER == IS_LITTLE_ENDIAN)
+    KeccakPermutationOnWords((UINT64*)state);
+#else
+    fromBytesToWords(stateAsWords, state);
+    KeccakPermutationOnWords(stateAsWords);
+    fromWordsToBytes(state, stateAsWords);
+#endif
+    displayStateAsBytes(1, "State after permutation", state);
+}
+
+void KeccakPermutationAfterXor(unsigned char *state, const unsigned char *data, unsigned int dataLengthInBytes)
+{
+    unsigned int i;
+
+    for(i=0; i<dataLengthInBytes; i++)
+        state[i] ^= data[i];
+    KeccakPermutation(state);
+}
+
+void KeccakPermutationOnWords(UINT64 *state)
+{
+    unsigned int i;
+
+    displayStateAs64bitWords(3, "Same, with lanes as 64-bit words", state);
+
+    for(i=0; i<nrRounds; i++) {
+        displayRoundNumber(3, i);
+
+        theta(state);
+        displayStateAs64bitWords(3, "After theta", state);
+
+        rho(state);
+        displayStateAs64bitWords(3, "After rho", state);
+
+        pi(state);
+        displayStateAs64bitWords(3, "After pi", state);
+
+        chi(state);
+        displayStateAs64bitWords(3, "After chi", state);
+
+        iota(state, i);
+        displayStateAs64bitWords(3, "After iota", state);
+    }
+}
+
+#define index(x, y) (((x)%5)+5*((y)%5))
+#define ROL64(a, offset) ((offset != 0) ? ((((UINT64)a) << offset) ^ (((UINT64)a) >> (64-offset))) : a)
+
+void theta(UINT64 *A)
+{
+    unsigned int x, y;
+    UINT64 C[5], D[5];
+
+    for(x=0; x<5; x++) {
+        C[x] = 0; 
+        for(y=0; y<5; y++) 
+            C[x] ^= A[index(x, y)];
+    }
+    for(x=0; x<5; x++)
+        D[x] = ROL64(C[(x+1)%5], 1) ^ C[(x+4)%5];
+    for(x=0; x<5; x++)
+        for(y=0; y<5; y++)
+            A[index(x, y)] ^= D[x];
+}
+
+void rho(UINT64 *A)
+{
+    unsigned int x, y;
+
+    for(x=0; x<5; x++) for(y=0; y<5; y++)
+        A[index(x, y)] = ROL64(A[index(x, y)], KeccakRhoOffsets[index(x, y)]);
+}
+
+void pi(UINT64 *A)
+{
+    unsigned int x, y;
+    UINT64 tempA[25];
+
+    for(x=0; x<5; x++) for(y=0; y<5; y++)
+        tempA[index(x, y)] = A[index(x, y)];
+    for(x=0; x<5; x++) for(y=0; y<5; y++)
+        A[index(0*x+1*y, 2*x+3*y)] = tempA[index(x, y)];
+}
+
+void chi(UINT64 *A)
+{
+    unsigned int x, y;
+    UINT64 C[5];
+
+    for(y=0; y<5; y++) { 
+        for(x=0; x<5; x++)
+            C[x] = A[index(x, y)] ^ ((~A[index(x+1, y)]) & A[index(x+2, y)]);
+        for(x=0; x<5; x++)
+            A[index(x, y)] = C[x];
+    }
+}
+
+void iota(UINT64 *A, unsigned int indexRound)
+{
+    A[index(0, 0)] ^= KeccakRoundConstants[indexRound];
+}
+
+int LFSR86540(UINT8 *LFSR)
+{
+    int result = ((*LFSR) & 0x01) != 0;
+    if (((*LFSR) & 0x80) != 0)
+        // Primitive polynomial over GF(2): x^8+x^6+x^5+x^4+1
+        (*LFSR) = ((*LFSR) << 1) ^ 0x71;
+    else
+        (*LFSR) <<= 1;
+    return result;
+}
+
+void KeccakInitializeRoundConstants()
+{
+    UINT8 LFSRstate = 0x01;
+    unsigned int i, j, bitPosition;
+
+    for(i=0; i<nrRounds; i++) {
+        KeccakRoundConstants[i] = 0;
+        for(j=0; j<7; j++) {
+            bitPosition = (1<<j)-1; //2^j-1
+            if (LFSR86540(&LFSRstate))
+                KeccakRoundConstants[i] ^= (UINT64)1<<bitPosition;
+        }
+    }
+}
+
+void KeccakInitializeRhoOffsets()
+{
+    unsigned int x, y, t, newX, newY;
+
+    KeccakRhoOffsets[index(0, 0)] = 0;
+    x = 1;
+    y = 0;
+    for(t=0; t<24; t++) {
+        KeccakRhoOffsets[index(x, y)] = ((t+1)*(t+2)/2) % 64;
+        newX = (0*x+1*y) % 5;
+        newY = (2*x+3*y) % 5;
+        x = newX;
+        y = newY;
+    }
+}
+
+void KeccakInitialize()
+{
+    KeccakInitializeRoundConstants();
+    KeccakInitializeRhoOffsets();
+}
+
+void displayRoundConstants(FILE *f)
+{
+    unsigned int i;
+
+    for(i=0; i<nrRounds; i++) {
+        fprintf(f, "RC[%02i][0][0] = ", i);
+        fprintf(f, "%08X", (unsigned int)(KeccakRoundConstants[i] >> 32));
+        fprintf(f, "%08X", (unsigned int)(KeccakRoundConstants[i] & 0xFFFFFFFFULL));
+        fprintf(f, "\n");
+    }
+    fprintf(f, "\n");
+}
+
+void displayRhoOffsets(FILE *f)
+{
+    unsigned int x, y;
+
+    for(y=0; y<5; y++) for(x=0; x<5; x++) {
+        fprintf(f, "RhoOffset[%i][%i] = ", x, y);
+        fprintf(f, "%2i", KeccakRhoOffsets[index(x, y)]);
+        fprintf(f, "\n");
+    }
+    fprintf(f, "\n");
+}
+
+void KeccakInitializeState(unsigned char *state)
+{
+    memset(state, 0, KeccakPermutationSizeInBytes);
+}
+
+#ifdef ProvideFast576
+void KeccakAbsorb576bits(unsigned char *state, const unsigned char *data)
+{
+    KeccakPermutationAfterXor(state, data, 72);
+}
+#endif
+
+#ifdef ProvideFast832
+void KeccakAbsorb832bits(unsigned char *state, const unsigned char *data)
+{
+    KeccakPermutationAfterXor(state, data, 104);
+}
+#endif
+
+#ifdef ProvideFast1024
+void KeccakAbsorb1024bits(unsigned char *state, const unsigned char *data)
+{
+    KeccakPermutationAfterXor(state, data, 128);
+}
+#endif
+
+#ifdef ProvideFast1088
+void KeccakAbsorb1088bits(unsigned char *state, const unsigned char *data)
+{
+    KeccakPermutationAfterXor(state, data, 136);
+}
+#endif
+
+#ifdef ProvideFast1152
+void KeccakAbsorb1152bits(unsigned char *state, const unsigned char *data)
+{
+    KeccakPermutationAfterXor(state, data, 144);
+}
+#endif
+
+#ifdef ProvideFast1344
+void KeccakAbsorb1344bits(unsigned char *state, const unsigned char *data)
+{
+    KeccakPermutationAfterXor(state, data, 168);
+}
+#endif
+
+void KeccakAbsorb(unsigned char *state, const unsigned char *data, unsigned int laneCount)
+{
+    KeccakPermutationAfterXor(state, data, laneCount*8);
+}
+
+#ifdef ProvideFast1024
+void KeccakExtract1024bits(const unsigned char *state, unsigned char *data)
+{
+    memcpy(data, state, 128);
+}
+#endif
+
+void KeccakExtract(const unsigned char *state, unsigned char *data, unsigned int laneCount)
+{
+    memcpy(data, state, laneCount*8);
+}