sha3 0.1.1 → 0.2.0

data/ext/sha3/_sha3.c

@@ -1,38 +1,306 @@
-#include <ruby.h>
-#include "KeccakNISTInterface.h"
+#include "_sha3.h"
 
-#define MAX_DIGEST_SIZE 64
+/* Document-module: SHA3 
+ * SHA3
+ */
 
-VALUE mSHA3;
-
-/* @overload digest(data, data_len, hashbit_len)
+/* Document-class: SHA3::Digest < Digest::Class
+ * SHA3::Digest allows you to compute message digests
+ * (interchangeably called "hashes") of arbitrary data that are
+ * cryptographically secure using SHA3 (Keccak) algorithm.
+ *  
+ * == Usage
+ *
+ *  require 'sha3'
  * 
- * @param data        [String] The DATA!
- * @param data_len    [String] The number of input bits provided in the input data.
- * @param hashbit_len [Fixnum] The desired number of output bits (i.e., 224, 256, 384, 512).
+ * === 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_awesome_file.bin").hexdigest
  *
- * @return [String] Computed hash
-*/
-VALUE m_sha3_digest(VALUE self, VALUE data, VALUE datalen, VALUE hashbitlen)
+ * === Bit operation
+ *     
+ *  # Compute hash of "011"
+ *  SHA3::Digest.compute(:sha224, "\xC0", 3).unpack("H*")
+ *  # => ["2b695a6fd92a2b3f3ce9cfca617d22c9bb52815dd59a9719b01bad25"]
+ *
+ * == Notes
+ *  
+ *    ::Digest::Class call sequence ->
+ *    | .alloc() ->
+ *    | .new() ->
+ *    | .update() ->
+ *    | .digest or .hexdigest or .inspect -> (Instance.digest or .hexdigest()) ->
+ *    --| .alloc() ->
+ *      | .copy() ->
+ *      | .finish() ->
+ *  
+ */
+
+static int get_hlen(VALUE obj)
+{
+  int hlen;
+
+  if (TYPE(obj) == T_SYMBOL) {
+    ID symid;
+
+    symid = SYM2ID(obj);
+
+    if (rb_intern("sha224") == symid)
+      hlen = 224;
+    else if (rb_intern("sha256") == symid)
+      hlen = 256;
+    else if (rb_intern("sha384") == symid)
+      hlen = 384;
+    else if (rb_intern("sha512") == symid)
+      hlen = 512;
+    else
+      rb_raise(eDigestError, "invalid hash bit symbol (should be: :sha224, :sha256, :sha384, or :sha512");
+  }
+  else if (TYPE(obj) == T_FIXNUM) {
+    hlen = NUM2INT(obj);
+
+    if ((hlen != 224) && (hlen != 256) && (hlen != 384) && (hlen != 512))
+      rb_raise(rb_eArgError, "invalid hash bit length (should be: 224, 256, 384, or 512)");
+  }
+  else
+    rb_raise(eDigestError, "unknown type value");
+
+  return hlen;
+}
+
+static void free_allox(MDX *mdx) 
+{
+  if (mdx) {
+    if (mdx->state)
+      free(mdx->state);
+
+    free(mdx);
+  } 
+
+  return;
+}
+
+static VALUE c_digest_alloc(VALUE klass) 
 {
-  int hlen = NUM2INT(hashbitlen);
+  MDX *mdx;
+  VALUE obj;
 
-  if ((hlen != 224) && (hlen != 256) && (hlen != 384) && (hlen != 512))
-    rb_raise(rb_eArgError, "invalid hashbit_len given (valid options: 224, 256, 384, or 512)");
+  mdx = (MDX *) malloc(sizeof(*mdx));
+  if (!mdx)
+    rb_raise(eDigestError, "failed to allocate object memory");
+
+  mdx->state = (hashState *) malloc(sizeof(*mdx->state));
+  memset(mdx->state, 0, sizeof(*mdx->state));
+  
+  if (!mdx->state)
+    rb_raise(eDigestError, "failed to allocate state memory");
+
+  obj = Data_Wrap_Struct(klass, 0, free_allox, mdx);
+
+  return obj;
+}
+
+static VALUE c_digest_update(VALUE, VALUE);
+
+// SHA3::Digest.new(type, [data]) -> self
+static VALUE c_digest_init(int argc, VALUE *argv, VALUE self)
+{ 
+  MDX *mdx;
+  VALUE hlen, data;
+
+  rb_scan_args(argc, argv, "02", &hlen, &data);
+  GETMDX(self, mdx);
+
+  if (!NIL_P(hlen))
+    mdx->hashbitlen = get_hlen(hlen);
+  else
+    mdx->hashbitlen = 256;
+
+  if (Init(mdx->state, mdx->hashbitlen) != SUCCESS)
+    rb_raise(eDigestError, "failed to initialize algorithm state");
+
+  if (!NIL_P(data))
+    return c_digest_update(self, data);
+
+  return self;
+}
+
+// SHA3::Digest.update(data) -> self
+static VALUE c_digest_update(VALUE self, VALUE data) 
+{
+  MDX *mdx;
+  DataLength dlen;
 
   StringValue(data);
+  GETMDX(self, mdx);
 
-  VALUE s = rb_str_new(0, hlen / 8);
+  dlen = (RSTRING_LEN(data) * 8);
 
-  if (Hash(hlen, RSTRING_PTR(data), NUM2ULL(datalen), RSTRING_PTR(s)) != SUCCESS)
-    rb_raise(rb_eException, "unable to generate hash");
+  if (Update(mdx->state, RSTRING_PTR(data), dlen) != SUCCESS)
+    rb_raise(eDigestError, "failed to update hash data");
 
-  return s;
+  return self;
+}
+
+// SHA3::Digest.reset() -> self
+static VALUE c_digest_reset(VALUE self) 
+{
+  MDX *mdx;
+
+  GETMDX(self, mdx);
+
+  memset(mdx->state, 0, sizeof(*mdx->state));
+
+  if (Init(mdx->state, mdx->hashbitlen) != SUCCESS)
+    rb_raise(eDigestError, "failed to reset internal state");
+
+  return self;
+}
+
+// SHA3::Digest.copy(obj) -> self
+static VALUE c_digest_copy(VALUE self, VALUE obj) 
+{
+  MDX *mdx1, *mdx2;
+
+  rb_check_frozen(self);
+  if (self == obj)
+    return self;
+
+  GETMDX(self, mdx1);
+  SAFEGETMDX(obj, mdx2);
+
+  memcpy(mdx1->state, mdx2->state, sizeof(hashState));
+  mdx1->hashbitlen = mdx2->hashbitlen;
+ 
+  // Fetch the data again to make sure it was copied
+  GETMDX(self, mdx1);
+  SAFEGETMDX(obj, mdx2);
+  if ((mdx1->state != mdx2->state) && (mdx1->hashbitlen != mdx2->hashbitlen))
+    rb_raise(eDigestError, "failed to copy state");
+
+  return self;
+}
+
+// SHA3::Digest.digest_length -> Integer
+static VALUE c_digest_length(VALUE self) 
+{
+  MDX *mdx;
+  GETMDX(self, mdx);
+
+  return ULL2NUM(mdx->hashbitlen / 8);
+}
+
+// SHA3::Digest.block_length -> Integer
+static VALUE c_digest_block_length(VALUE self) 
+{
+  MDX *mdx;
+  GETMDX(self, mdx);
+
+  return ULL2NUM(200 - (2 * (mdx->hashbitlen / 8)));
+}
+
+// SHA3::Digest.name -> String
+static VALUE c_digest_name(VALUE self) 
+{
+  return rb_str_new2("SHA3");
+}
+
+// SHA3::Digest.finish() -> String
+static VALUE c_digest_finish(int argc, VALUE *argv, VALUE self) 
+{
+  MDX *mdx;
+  VALUE str;
+
+  rb_scan_args(argc, argv, "01", &str);
+  GETMDX(self, mdx);
+
+  if (NIL_P(str)) {
+    str = rb_str_new(0, mdx->hashbitlen / 8);
+  } 
+  else {
+    StringValue(str);
+    rb_str_resize(str, mdx->hashbitlen / 8);
+  }
+
+  if (Final(mdx->state, RSTRING_PTR(str)) != SUCCESS)
+    rb_raise(eDigestError, "failed to finalize digest");
+
+  return str;
+}
+
+// SHA3::Digest.compute(type, data, [datalen]) -> String (bytes)
+// TO-DO: styled output (hex)
+VALUE c_digest_compute(int argc, VALUE *argv, VALUE self)
+{
+  VALUE hlen, data, dlen, str;
+  int hashbitlen;
+  DataLength datalen;
+
+  rb_scan_args(argc, argv, "21", &hlen, &data, &dlen);
+
+  hashbitlen = get_hlen(hlen);
+
+  StringValue(data);
+  
+  if (!NIL_P(dlen))
+    datalen = NUM2ULL(dlen);
+  else
+    datalen = (RSTRING_LEN(data) * 8);
+
+  str = rb_str_new(0, hashbitlen / 8);
+
+  if (Hash(hashbitlen, RSTRING_PTR(data), datalen, RSTRING_PTR(str)) != SUCCESS)
+    rb_raise(eDigestError, "failed to generate hash");
+
+  return str;
 }
 
 void Init_sha3_n()
 {
+  rb_require("digest");
+
   mSHA3 = rb_define_module("SHA3");
+  /* SHA3::Digest (class) */
+  cDigest = rb_define_class_under(mSHA3, "Digest", rb_path2class("Digest::Class"));
+  /* SHA3::Digest::DigestError (class) */ 
+  eDigestError = rb_define_class_under(cDigest, "DigestError", rb_eStandardError);
+
+  // SHA3::Digest (class) methods
+  rb_define_alloc_func(cDigest, c_digest_alloc);
+  rb_define_method(cDigest, "initialize", c_digest_init, -1);
+  rb_define_method(cDigest, "update", c_digest_update, 1);
+  rb_define_method(cDigest, "reset", c_digest_reset, 0);
+  rb_define_method(cDigest, "initialize_copy", c_digest_copy, 1);
+  rb_define_method(cDigest, "digest_length", c_digest_length, 0);
+  rb_define_method(cDigest, "block_length", c_digest_block_length, 0);
+  rb_define_method(cDigest, "name", c_digest_name, 0);
+  rb_define_private_method(cDigest, "finish", c_digest_finish, -1);
+
+  rb_define_alias(cDigest, "<<", "update");
+  
+  // SHA3 (module) functions (support bit operations)
+  rb_define_singleton_method(cDigest, "compute", c_digest_compute, -1);
 
-  rb_define_module_function(mSHA3, "digest", m_sha3_digest, 3);
+  return;
 }

data/ext/sha3/_sha3.h

@@ -0,0 +1,32 @@
+#ifndef __SHA3_H_
+#define __SHA3_H_
+
+#include <ruby.h>
+#include "KeccakNISTInterface.h"
+
+// From ruby/ext/openssl/ossl_digest.c
+#define GETMDX(obj, mdx) do {                                    \
+  Data_Get_Struct((obj), MDX, (mdx));                            \
+  if (!(mdx)) {                                                  \
+    rb_raise(rb_eRuntimeError, "Digest data not initialized!");  \
+  }                                                              \
+} while (0)
+
+#define SAFEGETMDX(obj, mdx) do {                                \
+  if (!rb_obj_is_kind_of(obj, cDigest)) {                        \
+    rb_raise(rb_eTypeError, "wrong argument (%s)! (expected %s)",\
+             rb_obj_classname(obj), rb_class2name(cDigest));     \
+  }                                                              \
+  GETMDX(obj, mdx);                                              \
+} while(0)
+
+VALUE mSHA3;
+VALUE cDigest;
+VALUE eDigestError;
+
+typedef struct {
+  hashState *state;
+  int hashbitlen;
+} MDX;
+
+#endif

data/ext/sha3/extconf.rb

@@ -1,9 +1,12 @@
 require 'mkmf'
 
-if 1.size == 4
+case 1.size
+when 4 # 32bit optimized code
   FileUtils.cp "#{$srcdir}/KeccakF-1600-opt32.c-arch", "#{$srcdir}/KeccakF-1600-opt.c"
-elsif
+when 8 # 64bit optimized code
   FileUtils.cp "#{$srcdir}/KeccakF-1600-opt64.c-arch", "#{$srcdir}/KeccakF-1600-opt.c"
+else # Ha? Use reference code
+  FileUtils.cp "#{$srcdir}/KeccakF-1600-reference.c-arch", "#{$srcdir}/KeccakF-1600-opt.c"
 end
 
 $CFLAGS = ' -fomit-frame-pointer -O3 -g0 -march=nocona '

data/lib/sha3.rb

@@ -1,22 +1,2 @@
-require 'sha3/version'
 require 'sha3_n'
-
-module SHA3
-  extend self
-
-  def digest_224(data)
-    SHA3::digest(data, data.length * 8, 224)
-  end
-
-  def digest_256(data)
-    SHA3::digest(data, data.length * 8, 256)
-  end
-
-  def digest_384(data)
-    SHA3::digest(data, data.length * 8, 384)
-  end
-
-  def digest_512(data)
-    SHA3::digest(data, data.length * 8, 512)
-  end
-end
+require 'sha3/version'

data/lib/sha3/version.rb

@@ -1,4 +1,8 @@
 module SHA3
+  extend self
+  
   # sha3 version
-  VERSION = "0.1.1"
+  VERSION = "0.2.0"
+  KECCAK_VERSION = "3.2"
 end
+

data/sha3.gemspec

@@ -6,7 +6,7 @@ Gem::Specification.new do |gem|
   gem.name          = "sha3"
   gem.version       = SHA3::VERSION
   gem.summary       = %q{SHA3 for Ruby}
-  gem.description   = %q{A native SHA3 gem}
+  gem.description   = %q{SHA3 for Ruby is a native (C) implementation of Keccak (SHA3) cryptographic hashing algorithm. See https://github.com/johanns/sha3#readme for details.}
   gem.license       = "MIT"
   gem.authors       = ["Johanns Gregorian"]
   gem.email         = "io+sha3@jsani.com"

data/spec/generate_tests.rb

@@ -0,0 +1,84 @@
+# Based on python-sha3's / digest-sha3 test generator.
+
+FILES = [
+  ['data/ShortMsgKAT_224.txt', 224],
+  ['data/ShortMsgKAT_256.txt', 256],
+  ['data/ShortMsgKAT_384.txt', 384],
+  ['data/ShortMsgKAT_512.txt', 512],
+  ['data/LongMsgKAT_224.txt', 224],
+]
+
+def gen_digest_byte_tests
+  FILES.each do |path, hashlen|
+    name = File.basename(path).split('.')[0]
+
+    f = File.new("sha3_digest_#{name}_spec.rb", "w")
+    f.puts(
+%Q{require 'spec_helper'
+require 'sha3'
+
+describe "SHA3::Digest.new(#{hashlen})" do
+  it "should match byte-length test vectors (#{name})." do
+})
+    contents = File.read(path).split('Len = ')
+    contents.each do |test|
+      lines = test.split("\n")
+      if !lines.empty? && lines[0] !~ /^#/
+        length = lines[0].to_i
+        if length % 8 == 0 && length != 0
+          msg_raw = [lines[1].split(' = ').last].pack("H*")
+          md = lines[2].split(' = ').last.downcase
+          f.puts(
+%Q{   SHA3::Digest.new(#{hashlen}, #{msg_raw.inspect}).hexdigest.should(eq("#{md}"))
+})
+        end
+      end
+    end
+    f.puts(
+%Q{ end
+end
+})
+    f.close
+  end
+end
+
+def gen_compute_bit_tests
+  FILES.each do |path, hashlen|
+    name = File.basename(path).split('.')[0]
+
+    f = File.new("sha3_compute_#{name}_spec.rb", "w")
+    f.puts(
+%Q{require 'spec_helper'
+require 'sha3'
+
+describe "SHA3::Digest.compute(#{hashlen})" do
+  it "should match bit-length test vectors (#{name})." do
+})
+    contents = File.read(path).split('Len = ')
+    contents.each do |test|
+      lines = test.split("\n")
+      if !lines.empty? && lines[0] !~ /^#/
+        length = lines[0].to_i
+        if length != 0
+          msg_raw = [lines[1].split(' = ').last].pack("H*")
+          md = lines[2].split(' = ').last.downcase
+          f.puts(
+%Q{   SHA3::Digest.compute(#{hashlen}, #{msg_raw.inspect}, #{length}).unpack("H*").first.should(eq("#{md}"))
+})
+        end
+      end
+    end
+    f.puts(
+%Q{ end
+end
+})
+    f.close
+  end
+end
+
+def setup
+  
+end
+
+gen_digest_byte_tests
+gen_compute_bit_tests