From 8b488da670f4433f634ff195dc8a290928eea46c Mon Sep 17 00:00:00 2001 From: Sylvain Daubert Date: Wed, 29 Oct 2014 15:58:21 +0100 Subject: [PATCH] * ext/digest/digest.c: - remove HMAC from list of digest algorithms, - add MD5 in list of digest algorithms, - add information about writing a C digest implementation using Digest::Base, - add documentation for Digest::Base public methods. * ext/digest/md5/md5init.c: add examples for MD5. * ext/digest/rmd160/rmd160init.c: add examples for Digest::RMD160. * ext/digest/sha1/sha1init.c: add examples for Digest::SHA1. --- ext/digest/digest.c | 64 ++++++++++++++++++++++++++++++++++++++---- ext/digest/md5/md5init.c | 20 +++++++++++++ ext/digest/rmd160/rmd160init.c | 20 +++++++++++++ ext/digest/sha1/sha1init.c | 22 +++++++++++++++ ext/digest/sha2/lib/sha2.rb | 44 +++++++++++++++++++++++++---- 5 files changed, 159 insertions(+), 11 deletions(-) diff --git a/ext/digest/digest.c b/ext/digest/digest.c index b177881..db2d83a 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. @@ -499,6 +499,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 * @@ -595,7 +629,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) { @@ -611,7 +649,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) { @@ -649,7 +693,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) { @@ -660,7 +708,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 3cf0c1a..89db828 100644 --- a/ext/digest/md5/md5init.c +++ b/ext/digest/md5/md5init.c @@ -19,9 +19,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 # =># + * 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 572638b..5e5307e 100644 --- a/ext/digest/rmd160/rmd160init.c +++ b/ext/digest/rmd160/rmd160init.c @@ -19,9 +19,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 # =># + * 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 56ae0fa..db491be 100644 --- a/ext/digest/sha1/sha1init.c +++ b/ext/digest/sha1/sha1init.c @@ -19,9 +19,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 # =># + * 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 58d12e9..a36dcb3 100644 --- a/ext/digest/sha2/lib/sha2.rb +++ b/ext/digest/sha2/lib/sha2.rb @@ -16,11 +16,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 # =># + # 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) @@ -40,7 +74,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 @@ -50,7 +84,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 @@ -66,7 +100,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 @@ -81,7 +115,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 -- 2.1.1