sha3 0.2.2 → 0.2.3

data/.gitignore

@@ -1,7 +1,9 @@
 *.gem
 *.rbc
 *.rbx
-.bundle
+*.bundle
+*.so
+*.dll
 .config
 coverage
 InstalledFiles

data/.yardopts

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

data/ChangeLog.rdoc

@@ -9,3 +9,11 @@
 === 0.2.0 / 2012-11-1
 
 * SHA3::Digest: A proper ::Digest subclass.
+
+=== 0.2.2 / 2012-12-14
+
+* Added sub-class for each SHA3 supported bit-lengths (example: SHA3::Digest::SHA256). Minor bug fix.
+
+=== 0.2.3 / 2013-1-28
+
+* Added documentation file (decoupled form C source); refactored C source.

data/README.rdoc

@@ -1,23 +1,16 @@
-= sha3 
+= sha3  {<img src="https://secure.travis-ci.org/johanns/sha3.png" alt="Build Status" />}[http://travis-ci.org/johanns/sha3] {<img src="https://gemnasium.com/johanns/sha3.png" alt="Dependency Status" />}[https://gemnasium.com/johanns/sha3]
+
+<em>SHA3 for Ruby</em> is a native (C) implementation of Keccak (SHA3) cryptographic hashing algorithm. Platform optimized reference is used, wherever possible.
 
-{<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
-
-<em>SHA3 for Ruby</em> is a native (C) implementation of Keccak (SHA3) cryptographic hashing algorithm.
+== Module details
 
-+SHA3::Digest+: A standard *Digest* _subclass_. The interface, and operation of this class are parallel to digest classes (e.g.: Digest::SHA2, and OpenSSL::Digest) bundled with MRI-based Rubies. See *Digest* documentation for additional details (http://www.ruby-doc.org/stdlib-1.9.3/libdoc/digest/rdoc/Digest.html).
+<em>SHA3::Digest</em>: A standard *Digest* _subclass_. The interface, and operation of this class are parallel to digest classes bundled with MRI-based Rubies (e.g.: <em>Digest::SHA2</em>, and <em>OpenSSL::Digest</em>). See *Digest* documentation for additional details (http://www.ruby-doc.org/stdlib-1.9.3/libdoc/digest/rdoc/Digest.html).
 
-+SHA3::Digest.compute()+: A class-method with data bit-length hashing support.
-
-== 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.
-*0.2.1* :: Added sub-class for each SHA3 supported bit-lengths (example: SHA3::Digest::SHA256). Minor bug fix.
+<em>SHA3::Digest.compute()</em>: A class-method with data bit-length hashing support.
 
 == Installation
 
@@ -27,15 +20,12 @@ Documentation :: http://rubydoc.info/gems/sha3/frames
 
   require 'sha3'
 
-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: 
+Valid hash bit-lengths are: *224*, *256*, *384*, *512*. You may also use corresponding symbols when instantiating a new instance or calling the <em>SHA3::Digest.compute()</em> method: 
   
-  :sha224
-  :sha256 
-  :sha384
-  :sha512
-
-  # Example: SHA3::Digest.new(224) = SHA3::Digest.new(:sha224)
+  :sha224  :sha256  :sha384  :sha512
 
+  # SHA3::Digest.new(224) is SHA3::Digest.new(:sha224)
+  
 Alternatively, you can instantiate using one of four sub-classes:
 
   SHA3::Digest::SHA224.new() # 224 bits
@@ -66,7 +56,7 @@ Alternatively, you can instantiate using one of four sub-classes:
   s.hexdigest
   # => "bedf0dd9a15b6474208b624c4e8a1e672ce0f06498e3abd7cc37f0ae69759259"
 
-  # Digest class methods:
+  ### Digest class-methods: ###
   
   SHA3::Digest.hexdigest("Hash me, please", :sha224)
   # => "200e7bc18cd6132689eb8fa3f7c3a978d73215384a626c23e4508f33"
@@ -81,13 +71,13 @@ Alternatively, you can instantiate using one of four sub-classes:
 
   # Calling SHA3::Digest.file(...) defaults to SHA256
   s = SHA3::Digest.file("tests.sh")
-    # => #<SHA3::Digest: a9801db49389339bd8a62817f229f0f9394ca73b34fd7dbc7ec5ed7a99bc49f1>
+  # => #<SHA3::Digest: a9801db49389339bd8a62817f229f0f9394ca73b34fd7dbc7ec5ed7a99bc49f1>
 
 === Bit-length hashing
   
   # Compute hash of "011"
   SHA3::Digest.compute(:sha224, "\xC0", 3).unpack("H*")
-    # => ["2b695a6fd92a2b3f3ce9cfca617d22c9bb52815dd59a9719b01bad25"]
+  # => ["2b695a6fd92a2b3f3ce9cfca617d22c9bb52815dd59a9719b01bad25"]
 
 == Development
 
@@ -98,7 +88,7 @@ Alternatively, you can instantiate using one of four sub-classes:
 
 Call +rake+ to run the included RSpec tests.
 
-Only a small subset of test vectors are included in the 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.
+Only a small subset of test vectors are included in the source repository; however, the complete test vectors suite is available for download. Simply run the +tests.sh+ shell script (available in the root of source directory) to generate full bit-length RSpec test files.
 
   sh tests.sh
 
@@ -120,14 +110,20 @@ On:
   - Windows 7, 8
   - Mac OS X 10.8
 
+== 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.
+*0.2.2* :: Added sub-class for each SHA3 supported bit-lengths (example: SHA3::Digest::SHA256). Minor bug fix.
+*0.2.3* :: Added documentation file (decoupled form C source); refactored C source.
+
 == TO DO:
 
-* Documentation (resolve order issue with Yard)!
 * Add support for arbitrary length hashes.
 * Add hex output support to compute method.
 
 == Copyright
 
-Copyright (c) 2012 Johanns Gregorian
+Copyright (c) 2012 Johanns Gregorian (https://github.com/johanns)
 
 See LICENSE.txt for details.

data/ext/sha3/{_sha3.c → digest.c}

@@ -1,49 +1,9 @@
-#include "_sha3.h"
+#include "sha3.h"
 
-/* Document-module: SHA3 
- * SHA3
- */
+VALUE cDigest;
+VALUE eDigestError;
 
-/* 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'
- * 
- * === 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
- *
- * === Bit operation
- *     
- *  # Compute hash of "011"
- *  SHA3::Digest.compute(:sha224, "\xC0", 3).unpack("H*")
- *  # => ["2b695a6fd92a2b3f3ce9cfca617d22c9bb52815dd59a9719b01bad25"]
- *
+/*
  * == Notes
  *  
  *    ::Digest::Class call sequence ->
@@ -57,38 +17,6 @@
  *  
  */
 
-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) {
@@ -102,15 +30,15 @@ static void free_allox(MDX *mdx)
 }
 
 static VALUE c_digest_alloc(VALUE klass) 
-{
+{ 
   MDX *mdx;
   VALUE obj;
 
-  mdx = (MDX *) malloc(sizeof(*mdx));
+  mdx = (MDX *) malloc(sizeof(MDX));
   if (!mdx)
     rb_raise(eDigestError, "failed to allocate object memory");
 
-  mdx->state = (hashState *) malloc(sizeof(*mdx->state));  
+  mdx->state = (hashState *) malloc(sizeof(hashState));  
   if (!mdx->state) {
     free_allox(mdx);
     rb_raise(eDigestError, "failed to allocate state memory");
@@ -118,7 +46,7 @@ static VALUE c_digest_alloc(VALUE klass)
 
   obj = Data_Wrap_Struct(klass, 0, free_allox, mdx);
 
-  memset(mdx->state, 0, sizeof(*mdx->state));
+  memset(mdx->state, 0, sizeof(hashState));
   mdx->hashbitlen = 0;
 
   return obj;
@@ -173,7 +101,7 @@ static VALUE c_digest_reset(VALUE self)
 
   GETMDX(self, mdx);
 
-  memset(mdx->state, 0, sizeof(*mdx->state));
+  memset(mdx->state, 0, sizeof(hashState));
 
   if (Init(mdx->state, mdx->hashbitlen) != SUCCESS)
     rb_raise(eDigestError, "failed to reset internal state");
@@ -254,7 +182,7 @@ static VALUE c_digest_finish(int argc, VALUE *argv, VALUE self)
 
 // SHA3::Digest.compute(type, data, [datalen]) -> String (bytes)
 // TO-DO: styled output (hex)
-VALUE c_digest_compute(int argc, VALUE *argv, VALUE self)
+static VALUE c_digest_compute(int argc, VALUE *argv, VALUE self)
 {
   VALUE hlen, data, dlen, str;
   int hashbitlen;
@@ -279,11 +207,10 @@ VALUE c_digest_compute(int argc, VALUE *argv, VALUE self)
   return str;
 }
 
-void Init_sha3_n()
+void Init_sha3_n_digest()
 {
   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) */ 

data/ext/sha3/{_sha3.h → digest.h}

@@ -1,8 +1,5 @@
-#ifndef __SHA3_H_
-#define __SHA3_H_
-
-#include <ruby.h>
-#include "KeccakNISTInterface.h"
+#ifndef _DIGEST_H_
+#define _DIGEST_H_
 
 // From ruby/ext/openssl/ossl_digest.c
 #define GETMDX(obj, mdx) do {                                    \
@@ -20,13 +17,14 @@
   GETMDX(obj, mdx);                                              \
 } while(0)
 
-VALUE mSHA3;
-VALUE cDigest;
-VALUE eDigestError;
+extern VALUE cDigest;
+extern VALUE eDigestError;
 
 typedef struct {
   hashState *state;
   int hashbitlen;
 } MDX;
 
+void Init_sha3_n_digest(void);
+
 #endif

data/ext/sha3/sha3.c

@@ -0,0 +1,44 @@
+#include "sha3.h"
+
+VALUE mSHA3;
+VALUE eSHA3Error;
+
+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(eSHA3Error, "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(eSHA3Error, "unknown type value");
+
+  return hlen;
+}
+
+void Init_sha3_n()
+{
+  mSHA3 = rb_define_module("SHA3");
+  eSHA3Error = rb_define_class_under(mSHA3, "SHA3Error", rb_eStandardError);
+
+  Init_sha3_n_digest();
+}

data/ext/sha3/sha3.h

@@ -0,0 +1,15 @@
+#ifndef _SHA3_H_
+#define _SHA3_H_
+
+#include <ruby.h>
+
+#include "KeccakNISTInterface.h"
+#include "digest.h"
+
+extern VALUE mSHA3;
+extern VALUE eSHA3Error;
+
+int get_hlen(VALUE);
+void Init_sha3_n(void);
+
+#endif

data/lib/sha3.rb

@@ -19,7 +19,7 @@ module SHA3
             raise ArgumentError,
               "wrong number of arguments (#{data.length} for 1)"
           end
-          
+
           super(key, data.first)
         }
       }

data/lib/sha3/doc.rb

@@ -0,0 +1,134 @@
+require 'digest'
+
+module SHA3
+  # A sub-class of (MRI Ruby based) Digest::Class, it implements SHA3 (Keccak) digest algorithm.
+  #  
+  # @note SHA3::Digest class provides a four sub-classes for the available hash bit lengths (types).
+  #   You can instantiate a new instance of Digest sub-class for a given type using the following sub-classes:
+  #   
+  #     SHA3::Digest::SHA224([data])
+  #     SHA3::Digest::SHA256([data])
+  #     SHA3::Digest::SHA384([data])
+  #     SHA3::Digest::SHA512([data])
+  #
+  #   The [data] parameter is optional.
+  class Digest < Digest::Class
+    # Creates a Digest instance based on given hash bit length (type).
+    # 
+    # @param type [Number, Symbol] optional parameter used to set hash bit length (type). 
+    #   Valid options are: 
+    #   
+    #       Number: 224, 256, 384, or 512
+    #     Symobols: :sha224, :sha256, :sha384, or :sha512
+    #   
+    #   Default value: 256 (bits)
+    # @param data [String] optional parameter used to update initial instance state.
+    #     # 
+    # @return [Digest] self
+    # 
+    # @example
+    #   digest = SHA3::Digest.new      # => Defaults to 256 bits
+    #   digest = SHA3::Digest.new(224) # => Initialize a new 224 bit digest instance
+    #   digest = SHA3::Digest::SHA224  # => An alternate method for creating a digest class with 224 bit hash bit length
+    def initialize(type, data)
+      # See function: c_digest_init(...) in ext/sha3/_digest.c
+    end
+
+    # Updates, and recalculates Message Digest (state) with given data. If a message digest 
+    # is to be computed from several subsequent sources, then each may be passed individually 
+    # to the Digest instance.
+    # 
+    # @param data [String] data to compute
+    # 
+    # @return [Digest] self
+    # 
+    # @example 
+    #   digest = SHA3::Digest::SHA256.new
+    #   digest.update('hash me')
+    #   digest.update('me too')
+    def update(data)
+      # See function: c_digest_update(...) in ext/sha3/_digest.c
+    end
+
+    # Alias for update method
+    alias << :update
+
+    # Resets the Digest object to initial state, abandoning computed data.
+    #
+    # @return [Digest] self
+    def reset
+      # See function: c_digest_reset(...) in ext/sha3/_digest.c
+    end
+
+    # Returns message digest length in bytes.
+    # 
+    # @return [Number] message length in bytes.
+    # 
+    # @example
+    #   digest = SHA3::Digest::SHA256.new
+    #   digest.length # Result => 32 (or 256 bits)
+    def length
+      # See function: c_digest_length(...) in ext/sha3/_digest.c
+    end
+
+    # Returns digest block length in bytes.
+    # 
+    # @return [Number] digest block length in bytes.
+    # 
+    # @example
+    #   digest = SHA3::Digest::SHA384.new
+    #   digest.block_length # Result => 104
+    def block_length
+      # See function: c_digest_block_length(...) in ext/sha3/_digest.c
+    end
+
+    # Returns name of initialized digest
+    # 
+    # @return [String] name
+    def name
+      # See function: c_digest_name(...) in ext/sha3/_digest.c
+    end
+
+    # Returns computed hash value for given hash type, and data in hex (string).
+    # 
+    # @param type [Number, Symbol] See {#initialize} for valid type values.
+    # @param data [String] data to compute hash value
+    # 
+    # @return (String) computed hash as hex-encoded string
+    # 
+    # @example
+    #   SHA3::Digest.hexdigest(256, 'compute me, please')
+    #   SHA3::Digest::SHA256.hexdigest('compute me, please') # => Alternate syntax
+    def self.hexdigest(type, data)
+    end
+
+    # Returns computed hash value for given hash type, and data in bytes.
+    # 
+    # @param type [Number, Symbol] See {#initialize} for valid type values.
+    # @param data [String] data to compute hash value
+    # 
+    # @return [String] computed hash in bytes
+    # 
+    # @example
+    #   SHA3::Digest.digest(256, 'compute me, please')
+    #   SHA3::Digest::SHA256.digest('compute me, please') # => Alternate syntax
+    def self.digest(type, data)
+    end
+
+    # Returns computed hash value of bit-length data.
+    # 
+    # @param type [Number, Symbol] See {#initialize} for valid type values.
+    # @param data [String] data to compute hash value
+    # @param data_length [Number] data bit length
+    # 
+    # @return [String] computed hash in bytes
+    # 
+    # @example
+    #   SHA3::Digest.compute(:sha384, '\0C', 2)
+    def self.compute(type, data, data_length)
+    end
+  end
+
+  class DigestError < StandardError
+  end
+end

data/lib/sha3/version.rb

@@ -1,8 +1,10 @@
 module SHA3
   extend self
   
-  # sha3 version
-  VERSION = "0.2.2"
+  # sha3 release version
+  VERSION = "0.2.3"
+
+  # keccak version number
   KECCAK_VERSION = "3.2"
 end
 

data/spec/sha3_core_spec.rb

@@ -70,7 +70,9 @@ describe SHA3::Digest do
     sha.digest_length.should(eq(64))
     sha.block_length.should(eq(72))    
   end
-  
+end
+
+describe "SHA3::Digest::SHAxyz" do 
   it "should pass Digest.SHA224() usage test" do
     sha = SHA3::Digest::SHA224.new()
     sha.hexdigest.should eq("f71837502ba8e10837bdd8d365adb85591895602fc552b48b7390abd")

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sha3
 version: !ruby/object:Gem::Version
-  version: 0.2.2
+  version: 0.2.3
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-12-15 00:00:00.000000000 Z
+date: 2013-01-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake-compiler
@@ -114,13 +114,16 @@ files:
 - ext/sha3/KeccakNISTInterface.h
 - ext/sha3/KeccakSponge.c
 - ext/sha3/KeccakSponge.h
-- ext/sha3/_sha3.c
-- ext/sha3/_sha3.h
 - ext/sha3/brg_endian.h
+- ext/sha3/digest.c
+- ext/sha3/digest.h
 - ext/sha3/displayIntermediateValues.c
 - ext/sha3/displayIntermediateValues.h
 - ext/sha3/extconf.rb
+- ext/sha3/sha3.c
+- ext/sha3/sha3.h
 - lib/sha3.rb
+- lib/sha3/doc.rb
 - lib/sha3/version.rb
 - sha3.gemspec
 - spec/generate_tests.rb