From 814c1adec7d20b74b9499cb2c1b37e12b1b04681 Mon Sep 17 00:00:00 2001 From: hsbt Date: Thu, 20 Oct 2016 07:57:30 +0000 Subject: * ext/digest/digest.c: Add documentation for Digest. [Feature #10452][ruby-core:66001][ci skip] * 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. git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@56455 b2dd03c8-39d4-4d8f-98ff-823fe69b080e --- 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(-) (limited to 'ext/digest') 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 # =># + * 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 # =># + * 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 # =># + * 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 # =># + # 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 -- cgit v1.2.3