summaryrefslogtreecommitdiff
path: root/ext/digest/digest.c
diff options
context:
space:
mode:
authorhsbt <hsbt@b2dd03c8-39d4-4d8f-98ff-823fe69b080e>2016-10-20 07:57:30 +0000
committerhsbt <hsbt@b2dd03c8-39d4-4d8f-98ff-823fe69b080e>2016-10-20 07:57:30 +0000
commit814c1adec7d20b74b9499cb2c1b37e12b1b04681 (patch)
tree4953f1fd770b9b48945be09fa3cf808ed435d6e7 /ext/digest/digest.c
parentd74bb0958d0af93496f7ac030f134f9164518e30 (diff)
* 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
Diffstat (limited to 'ext/digest/digest.c')
-rw-r--r--ext/digest/digest.c64
1 files changed, 58 insertions, 6 deletions
diff --git a/ext/digest/digest.c b/ext/digest/digest.c
index 012c0cc..a6d6265 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)
{