diff options
| -rw-r--r-- | ChangeLog | 5 | ||||
| -rw-r--r-- | ext/digest/lib/digest.rb | 22 | ||||
| -rw-r--r-- | ext/digest/lib/digest/hmac.rb | 87 | ||||
| -rw-r--r-- | ext/digest/sha2/lib/sha2.rb | 49 |
4 files changed, 117 insertions, 46 deletions
@@ -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 b46cf9e2bd..4a98af2eae 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 98f98a69cf..470b0226d4 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 b8e4609478..3c5bf0c863 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 |