summaryrefslogtreecommitdiff
path: root/ext/digest/sha2/lib/sha2.rb
diff options
context:
space:
mode:
Diffstat (limited to 'ext/digest/sha2/lib/sha2.rb')
-rw-r--r--ext/digest/sha2/lib/sha2.rb44
1 files changed, 39 insertions, 5 deletions
diff --git a/ext/digest/sha2/lib/sha2.rb b/ext/digest/sha2/lib/sha2.rb
index 58ff9f5..e5a44ff 100644
--- a/ext/digest/sha2/lib/sha2.rb
+++ b/ext/digest/sha2/lib/sha2.rb
@@ -17,11 +17,45 @@ module Digest
#
# A meta digest provider class for SHA256, SHA384 and SHA512.
#
+ # FIPS 180-2 describes SHA2 family of digest algorithms. It defines
+ # three algorithms:
+ # * one which works on chunks of 512 bits and returns a 256-bit
+ # digest (SHA256),
+ # * one which works on chunks of 1024 bits and returns a 384-bit
+ # digest (SHA384),
+ # * and one which works on chunks of 1024 bits and returns a 512-bit
+ # digest (SHA512).
+ #
+ # ==Examples
+ # require 'digest'
+ #
+ # # Compute a complete digest
+ # Digest::SHA2.hexdigest 'abc' # => "ba7816bf8..."
+ # Digest::SHA2.new(256).hexdigest 'abc' # => "ba7816bf8..."
+ # Digest::SHA256.hexdigest 'abc' # => "ba7816bf8..."
+ #
+ # Digest::SHA2.new(384).hexdigest 'abc' # => "cb00753f4..."
+ # Digest::SHA384.hexdigest 'abc' # => "cb00753f4..."
+ #
+ # Digest::SHA2.new(512).hexdigest 'abc' # => "ddaf35a19..."
+ # Digest::SHA512.hexdigest 'abc' # => "ddaf35a19..."
+ #
+ # # Compute digest by chunks
+ # sha2 = Digest::SHA2.new # =>#<Digest::SHA2:256>
+ # sha2.update "ab"
+ # sha2 << "c" # alias for #update
+ # sha2.hexdigest # => "ba7816bf8..."
+ #
+ # # Use the same object to compute another digest
+ # sha2.reset
+ # sha2 << "message"
+ # sha2.hexdigest # => "ab530a13e..."
+ #
class SHA2 < Digest::Class
# call-seq:
# Digest::SHA2.new(bitlen = 256) -> digest_obj
#
- # Creates a new SHA2 hash object with a given bit length.
+ # Create a new SHA2 hash object with a given bit length.
#
# Valid bit lengths are 256, 384 and 512.
def initialize(bitlen = 256)
@@ -41,7 +75,7 @@ module Digest
# call-seq:
# digest_obj.reset -> digest_obj
#
- # Resets the digest to the initial state and returns self.
+ # Reset the digest to the initial state and return self.
def reset
@sha2.reset
self
@@ -51,7 +85,7 @@ module Digest
# digest_obj.update(string) -> digest_obj
# digest_obj << string -> digest_obj
#
- # Updates the digest using a given _string_ and returns self.
+ # Update the digest using a given _string_ and return self.
def update(str)
@sha2.update(str)
self
@@ -67,7 +101,7 @@ module Digest
# call-seq:
# digest_obj.block_length -> Integer
#
- # Returns the block length of the digest in bytes.
+ # Return the block length of the digest in bytes.
#
# Digest::SHA256.new.block_length * 8
# # => 512
@@ -82,7 +116,7 @@ module Digest
# call-seq:
# digest_obj.digest_length -> Integer
#
- # Returns the length of the hash value of the digest in bytes.
+ # Return the length of the hash value (the digest) in bytes.
#
# Digest::SHA256.new.digest_length * 8
# # => 256