summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--ChangeLog5
-rw-r--r--ext/digest/lib/digest.rb22
-rw-r--r--ext/digest/lib/digest/hmac.rb87
-rw-r--r--ext/digest/sha2/lib/sha2.rb49
4 files changed, 117 insertions, 46 deletions
diff --git a/ChangeLog b/ChangeLog
index 7db62d1..089ded2 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,8 @@
+Tue May 17 05:52:30 2011 Eric Hodel <drbrain@segment7.net>
+
+ * ext/digest: Improve documentation of Digest, Digest::HMAC and
+ Digest::SHA2. Patch by Pete Higgins. [Ruby 1.9 - Bug #4702]
+
Tue May 17 03:51:42 2011 Eric Hodel <drbrain@segment7.net>
* lib/abbrev.rb: Hide copyright and revision information from RDoc.
diff --git a/ext/digest/lib/digest.rb b/ext/digest/lib/digest.rb
index b46cf9e..4a98af2 100644
--- a/ext/digest/lib/digest.rb
+++ b/ext/digest/lib/digest.rb
@@ -1,7 +1,7 @@
require 'digest.so'
module Digest
- def self.const_missing(name)
+ def self.const_missing(name) # :nodoc:
case name
when :SHA256, :SHA384, :SHA512
lib = 'digest/sha2.so'
@@ -23,8 +23,8 @@ module Digest
class ::Digest::Class
# creates a digest object and reads a given file, _name_.
#
- # p Digest::SHA256.file("X11R6.8.2-src.tar.bz2").hexdigest
- # # => "f02e3c85572dc9ad7cb77c2a638e3be24cc1b5bea9fdbb0b0299c9668475c534"
+ # p Digest::SHA256.file("X11R6.8.2-src.tar.bz2").hexdigest
+ # # => "f02e3c85572dc9ad7cb77c2a638e3be24cc1b5bea9fdbb0b0299c9668475c534"
def self.file(name)
new.file(name)
end
@@ -53,8 +53,8 @@ module Digest
# If none is given, returns the resulting hash value of the digest
# in a base64 encoded form, keeping the digest's state.
#
- # If a _string_ is given, returns the hash value for the given
- # _string_ in a base64 encoded form, resetting the digest to the
+ # If a +string+ is given, returns the hash value for the given
+ # +string+ in a base64 encoded form, resetting the digest to the
# initial state before and after the process.
#
# In either case, the return value is properly padded with '=' and
@@ -71,6 +71,18 @@ module Digest
end
end
+# call-seq:
+# Digest(name) -> digest_subclass
+#
+# Returns a Digest subclass by +name+.
+#
+# require 'digest'
+#
+# Digest("MD5")
+# # => Digest::MD5
+#
+# Digest("Foo")
+# # => LoadError: library not found for class Digest::Foo -- digest/foo
def Digest(name)
Digest.const_get(name)
end
diff --git a/ext/digest/lib/digest/hmac.rb b/ext/digest/lib/digest/hmac.rb
index 98f98a6..470b022 100644
--- a/ext/digest/lib/digest/hmac.rb
+++ b/ext/digest/lib/digest/hmac.rb
@@ -1,34 +1,3 @@
-# = digest/hmac.rb
-#
-# An implementation of HMAC keyed-hashing algorithm
-#
-# == Overview
-#
-# CAUTION: Use of this library is discouraged, because this
-# implementation was meant to be experimental but somehow got into the
-# 1.9 series without being noticed. Please use OpenSSL::HMAC in the
-# "openssl" library instead.
-#
-# This library adds a method named hmac() to Digest classes, which
-# creates a Digest class for calculating HMAC digests.
-#
-# == Examples
-#
-# require 'digest/hmac'
-#
-# # one-liner example
-# puts Digest::HMAC.hexdigest("data", "hash key", Digest::SHA1)
-#
-# # rather longer one
-# hmac = Digest::HMAC.new("foo", Digest::RMD160)
-#
-# buf = ""
-# while stream.read(16384, buf)
-# hmac.update(buf)
-# end
-#
-# puts hmac.bubblebabble
-#
# == License
#
# Copyright (c) 2006 Akinori MUSHA <knu@iDaemons.org>
@@ -46,7 +15,38 @@ warn "use of the experimetal library 'digest/hmac' is discouraged; require 'open
require 'digest'
module Digest
+ # = digest/hmac.rb
+ #
+ # An experimental implementation of HMAC keyed-hashing algorithm
+ #
+ # == Overview
+ #
+ # CAUTION: Use of this library is discouraged, because this
+ # implementation was meant to be experimental but somehow got into the
+ # 1.9 series without being noticed. Please use OpenSSL::HMAC in the
+ # "openssl" library instead.
+ #
+ # == Examples
+ #
+ # require 'digest/hmac'
+ #
+ # # one-liner example
+ # puts Digest::HMAC.hexdigest("data", "hash key", Digest::SHA1)
+ #
+ # # rather longer one
+ # hmac = Digest::HMAC.new("foo", Digest::RMD160)
+ #
+ # buf = ""
+ # while stream.read(16384, buf)
+ # hmac.update(buf)
+ # end
+ #
+ # puts hmac.bubblebabble
+ #
class HMAC < Digest::Class
+
+ # Creates a Digest::HMAC instance.
+
def initialize(key, digester)
@md = digester.new
@@ -70,23 +70,32 @@ module Digest
@md.update(@ipad)
end
- def initialize_copy(other)
+ def initialize_copy(other) # :nodoc:
@md = other.instance_eval { @md.clone }
end
+ # call-seq:
+ # hmac.update(string) -> hmac
+ # hmac << string -> hmac
+ #
+ # Updates the hmac using a given +string+ and returns self.
def update(text)
@md.update(text)
self
end
alias << update
+ # call-seq:
+ # hmac.reset -> hmac
+ #
+ # Resets the hmac to the initial state and returns self.
def reset
@md.reset
@md.update(@ipad)
self
end
- def finish
+ def finish # :nodoc:
d = @md.digest!
@md.update(@opad)
@md.update(d)
@@ -94,14 +103,26 @@ module Digest
end
private :finish
+ # call-seq:
+ # hmac.digest_length -> Integer
+ #
+ # Returns the length in bytes of the hash value of the digest.
def digest_length
@md.digest_length
end
+ # call-seq:
+ # hmac.block_length -> Integer
+ #
+ # Returns the block length in bytes of the hmac.
def block_length
@md.block_length
end
+ # call-seq:
+ # hmac.inspect -> string
+ #
+ # Creates a printable version of the hmac object.
def inspect
sprintf('#<%s: key=%s, digest=%s>', self.class.name, @key.inspect, @md.inspect.sub(/^\#<(.*)>$/) { $1 });
end
diff --git a/ext/digest/sha2/lib/sha2.rb b/ext/digest/sha2/lib/sha2.rb
index b8e4609..3c5bf0c 100644
--- a/ext/digest/sha2/lib/sha2.rb
+++ b/ext/digest/sha2/lib/sha2.rb
@@ -18,9 +18,11 @@ module Digest
#
class SHA2 < Digest::Class
# call-seq:
- # Digest::SHA2.new(bitlen = 256) -> digest_obj
+ # Digest::SHA2.new(bitlen = 256) -> digest_obj
#
# Creates a new SHA2 hash object with a given bit length.
+ #
+ # Valid bit lengths are 256, 384 and 512.
def initialize(bitlen = 256)
case bitlen
when 256
@@ -35,39 +37,70 @@ module Digest
@bitlen = bitlen
end
- # :nodoc:
+ # call-seq:
+ # digest_obj.reset -> digest_obj
+ #
+ # Resets the digest to the initial state and returns self.
def reset
@sha2.reset
self
end
- # :nodoc:
+ # call-seq:
+ # digest_obj.update(string) -> digest_obj
+ # digest_obj << string -> digest_obj
+ #
+ # Updates the digest using a given _string_ and returns self.
def update(str)
@sha2.update(str)
self
end
alias << update
- def finish
+ def finish # :nodoc:
@sha2.digest!
end
private :finish
+
+ # call-seq:
+ # digest_obj.block_length -> Integer
+ #
+ # Returns the block length of the digest in bytes.
+ #
+ # Digest::SHA256.new.digest_length * 8
+ # # => 512
+ # Digest::SHA384.new.digest_length * 8
+ # # => 1024
+ # Digest::SHA512.new.digest_length * 8
+ # # => 1024
def block_length
@sha2.block_length
end
+ # call-seq:
+ # digest_obj.digest_length -> Integer
+ #
+ # Returns the length of the hash value of the digest in bytes.
+ #
+ # Digest::SHA256.new.digest_length * 8
+ # # => 256
+ # Digest::SHA384.new.digest_length * 8
+ # # => 384
+ # Digest::SHA512.new.digest_length * 8
+ # # => 512
+ #
+ # For example, digests produced by Digest::SHA256 will always be 32 bytes
+ # (256 bits) in size.
def digest_length
@sha2.digest_length
end
- # :nodoc:
- def initialize_copy(other)
+ def initialize_copy(other) # :nodoc:
@sha2 = other.instance_eval { @sha2.clone }
end
- # :nodoc:
- def inspect
+ def inspect # :nodoc:
"#<%s:%d %s>" % [self.class.name, @bitlen, hexdigest]
end
end