summaryrefslogtreecommitdiff
path: root/ext
diff options
context:
space:
mode:
Diffstat (limited to 'ext')
-rw-r--r--ext/digest/digest.c64
-rw-r--r--ext/digest/md5/md5init.c20
-rw-r--r--ext/digest/rmd160/rmd160init.c20
-rw-r--r--ext/digest/sha1/sha1init.c22
-rw-r--r--ext/digest/sha2/lib/sha2.rb44
5 files changed, 159 insertions, 11 deletions
diff --git a/ext/digest/digest.c b/ext/digest/digest.c
index 012c0cc89d..a6d6265249 100644
--- a/ext/digest/digest.c
+++ b/ext/digest/digest.c
@@ -77,8 +77,8 @@ RUBY_EXTERN void Init_digest_base(void);
*
* Different digest algorithms (or hash functions) are available:
*
- * HMAC::
- * See FIPS PUB 198 The Keyed-Hash Message Authentication Code (HMAC).
+ * MD5::
+ * See RFC 1321 The MD5 Message-Digest Algorithm
* RIPEMD-160::
* As Digest::RMD160.
* See http://homes.esat.kuleuven.be/~bosselae/ripemd160.html.
@@ -501,6 +501,40 @@ rb_digest_class_init(VALUE self)
*
* This abstract class provides a common interface to message digest
* implementation classes written in C.
+ *
+ * ==Write a Digest subclass in C
+ * Digest::Base provides a common interface to message digest
+ * classes written in C. These classes must provide a struct
+ * of type rb_digest_metadata_t:
+ * typedef int (*rb_digest_hash_init_func_t)(void *);
+ * typedef void (*rb_digest_hash_update_func_t)(void *, unsigned char *, size_t);
+ * typedef int (*rb_digest_hash_finish_func_t)(void *, unsigned char *);
+ *
+ * typedef struct {
+ * int api_version;
+ * size_t digest_len;
+ * size_t block_len;
+ * size_t ctx_size;
+ * rb_digest_hash_init_func_t init_func;
+ * rb_digest_hash_update_func_t update_func;
+ * rb_digest_hash_finish_func_t finish_func;
+ * } rb_digest_metadata_t;
+ *
+ * This structure must be set as an instance variable named +metadata+
+ * (without the +@+ in front of the name). By example:
+ * static const rb_digest_metadata_t sha1 = {
+ * RUBY_DIGEST_API_VERSION,
+ * SHA1_DIGEST_LENGTH,
+ * SHA1_BLOCK_LENGTH,
+ * sizeof(SHA1_CTX),
+ * (rb_digest_hash_init_func_t)SHA1_Init,
+ * (rb_digest_hash_update_func_t)SHA1_Update,
+ * (rb_digest_hash_finish_func_t)SHA1_Finish,
+ * };
+ *
+ *
+ * rb_ivar_set(cDigest_SHA1, rb_intern("metadata"),
+ * Data_Wrap_Struct(0, 0, 0, (void *)&sha1));
*/
static rb_digest_metadata_t *
@@ -596,7 +630,11 @@ rb_digest_base_copy(VALUE copy, VALUE obj)
return copy;
}
-/* :nodoc: */
+/*
+ * call-seq: digest_base.reset -> digest_base
+ *
+ * Reset the digest to its initial state and return +self+.
+ */
static VALUE
rb_digest_base_reset(VALUE self)
{
@@ -612,7 +650,13 @@ rb_digest_base_reset(VALUE self)
return self;
}
-/* :nodoc: */
+/*
+ * call-seq:
+ * digest_base.update(string) -> digest_base
+ * digest_base << string -> digest_base
+ *
+ * Update the digest using given _string_ and return +self+.
+ */
static VALUE
rb_digest_base_update(VALUE self, VALUE str)
{
@@ -651,7 +695,11 @@ rb_digest_base_finish(VALUE self)
return str;
}
-/* :nodoc: */
+/*
+ * call-seq: digest_base.digest_length -> Integer
+ *
+ * Return the length of the hash value in bytes.
+ */
static VALUE
rb_digest_base_digest_length(VALUE self)
{
@@ -662,7 +710,11 @@ rb_digest_base_digest_length(VALUE self)
return INT2NUM(algo->digest_len);
}
-/* :nodoc: */
+/*
+ * call-seq: digest_base.block_length -> Integer
+ *
+ * Return the block length of the digest in bytes.
+ */
static VALUE
rb_digest_base_block_length(VALUE self)
{
diff --git a/ext/digest/md5/md5init.c b/ext/digest/md5/md5init.c
index a6afedef69..41f966fa7b 100644
--- a/ext/digest/md5/md5init.c
+++ b/ext/digest/md5/md5init.c
@@ -22,9 +22,29 @@ static const rb_digest_metadata_t md5 = {
};
/*
+ * Document-class: Digest::MD5 < Digest::Base
* A class for calculating message digests using the MD5
* Message-Digest Algorithm by RSA Data Security, Inc., described in
* RFC1321.
+ *
+ * MD5 calculates a digest of 128 bits (16 bytes).
+ *
+ * == Examples
+ * require 'digest'
+ *
+ * # Compute a complete digest
+ * Digest::MD5.hexdigest 'abc' #=> "90015098..."
+ *
+ * # Compute digest by chunks
+ * md5 = Digest::MD5.new # =>#<Digest::MD5>
+ * md5.update "ab"
+ * md5 << "c" # alias for #update
+ * md5.hexdigest # => "90015098..."
+ *
+ * # Use the same object to compute another digest
+ * md5.reset
+ * md5 << "message"
+ * md5.hexdigest # => "c13557f2..."
*/
void
Init_md5(void)
diff --git a/ext/digest/rmd160/rmd160init.c b/ext/digest/rmd160/rmd160init.c
index c1e753cc11..fbd6d5a938 100644
--- a/ext/digest/rmd160/rmd160init.c
+++ b/ext/digest/rmd160/rmd160init.c
@@ -20,9 +20,29 @@ static const rb_digest_metadata_t rmd160 = {
};
/*
+ * Document-class: Digest::RMD160 < Digest::Base
* A class for calculating message digests using RIPEMD-160
* cryptographic hash function, designed by Hans Dobbertin, Antoon
* Bosselaers, and Bart Preneel.
+ *
+ * RMD160 calculates a digest of 160 bits (20 bytes).
+ *
+ * == Examples
+ * require 'digest'
+ *
+ * # Compute a complete digest
+ * Digest::RMD160.hexdigest 'abc' #=> "8eb208f7..."
+ *
+ * # Compute digest by chunks
+ * rmd160 = Digest::RMD160.new # =>#<Digest::RMD160>
+ * rmd160.update "ab"
+ * rmd160 << "c" # alias for #update
+ * rmd160.hexdigest # => "8eb208f7..."
+ *
+ * # Use the same object to compute another digest
+ * rmd160.reset
+ * rmd160 << "message"
+ * rmd160.hexdigest # => "1dddbe1b..."
*/
void
Init_rmd160(void)
diff --git a/ext/digest/sha1/sha1init.c b/ext/digest/sha1/sha1init.c
index 1f8b89e276..44dda3f9fa 100644
--- a/ext/digest/sha1/sha1init.c
+++ b/ext/digest/sha1/sha1init.c
@@ -22,9 +22,31 @@ static const rb_digest_metadata_t sha1 = {
};
/*
+ * Document-class: Digest::SHA1 < Digest::Base
* A class for calculating message digests using the SHA-1 Secure Hash
* Algorithm by NIST (the US' National Institute of Standards and
* Technology), described in FIPS PUB 180-1.
+ *
+ * See Digest::Instance for digest API.
+ *
+ * SHA-1 calculates a digest of 160 bits (20 bytes).
+ *
+ * == Examples
+ * require 'digest'
+ *
+ * # Compute a complete digest
+ * Digest::SHA1.hexdigest 'abc' #=> "a9993e36..."
+ *
+ * # Compute digest by chunks
+ * sha1 = Digest::SHA1.new # =>#<Digest::SHA1>
+ * sha1.update "ab"
+ * sha1 << "c" # alias for #update
+ * sha1.hexdigest # => "a9993e36..."
+ *
+ * # Use the same object to compute another digest
+ * sha1.reset
+ * sha1 << "message"
+ * sha1.hexdigest # => "6f9b9af3..."
*/
void
Init_sha1(void)
diff --git a/ext/digest/sha2/lib/sha2.rb b/ext/digest/sha2/lib/sha2.rb
index 58ff9f5cf0..e5a44ff0d4 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
generated by cgit v1.2.3 (git 2.25.1) at 2024-04-16 10:47:44 +0000