* ext/openssl/ossl_digest.c: Add documentation.

git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@31604 b2dd03c8-39d4-4d8f-98ff-823fe69b080e

ChangeLog

@@ -1,3 +1,7 @@
+Tue May 17 08:04:26 2011  Martin Bosslet  <Martin.Bosslet@googlemail.com>
+
+	* ext/openssl/ossl_digest.c: Add documentation.
+
 Tue May 17 07:14:58 2011  Eric Hodel  <drbrain@segment7.net>
 
 	* lib/net/http.rb:  Improve documentation of proxy configuration

ext/openssl/ossl_digest.c

@@ -88,7 +88,20 @@ VALUE ossl_digest_update(VALUE, VALUE);
 
 /*
  *  call-seq:
- *     Digest.new(string) -> digest
+ *     Digest.new(string [, data]) -> Digest
+ *
+ * Creates a Digest instance based on +string+, which is either the ln
+ * (long name) or sn (short name) of a supported digest algorithm.
+ * If +data+ (a +String+) is given, it is used as the initial input to the
+ * Digest instance, i.e.
+ *   digest = OpenSSL::Digest.new('sha256', 'digestdata')
+ * is equal to
+ *   digest = OpenSSL::Digest.new('sha256')
+ *   digest.update('digestdata')
+ *
+ * === Example
+ *   digest = OpenSSL::Digest.new('sha1')
+ *
  *
  */
 static VALUE
@@ -130,6 +143,9 @@ ossl_digest_copy(VALUE self, VALUE other)
  *  call-seq:
  *     digest.reset -> self
  *
+ * Resets the Digest in the sense that any Digest#update that has been
+ * performed is abandoned and the Digest is set to its initial state again.
+ *
  */
 static VALUE
 ossl_digest_reset(VALUE self)
@@ -146,6 +162,16 @@ ossl_digest_reset(VALUE self)
  *  call-seq:
  *     digest.update(string) -> aString
  *
+ * Not every message digest can be computed in one single pass. If a message
+ * digest is to be computed from several subsequent sources, then each may
+ * be passed individually to the Digest instance.
+ *
+ * === Example
+ *   digest = OpenSSL::Digest::SHA256.new
+ *   digest.update('First input')
+ *   digest << 'Second input' # equivalent to digest.update('Second input')
+ *   result = digest.digest
+ *
  */
 VALUE
 ossl_digest_update(VALUE self, VALUE data)
@@ -190,6 +216,12 @@ ossl_digest_finish(int argc, VALUE *argv, VALUE self)
  *  call-seq:
  *      digest.name -> string
  *
+ * Returns the sn of this Digest instance.
+ *
+ * === Example
+ *   digest = OpenSSL::Digest::SHA512.new
+ *   puts digest.name # => SHA512
+ *
  */
 static VALUE
 ossl_digest_name(VALUE self)
@@ -203,9 +235,15 @@ ossl_digest_name(VALUE self)
 
 /*
  *  call-seq:
- *      digest.digest_size -> integer
+ *      digest.digest_length -> integer
+ *
+ * Returns the output size of the digest, i.e. the length in bytes of the
+ * final message digest result.
+ *
+ * === Example
+ *   digest = OpenSSL::Digest::SHA1.new
+ *   puts digest.digest_length # => 20
  *
- *  Returns the output size of the digest.
  */
 static VALUE
 ossl_digest_size(VALUE self)
@@ -217,6 +255,18 @@ ossl_digest_size(VALUE self)
     return INT2NUM(EVP_MD_CTX_size(ctx));
 }
 
+/*
+ *  call-seq:
+ *      digest.block_length -> integer
+ *
+ * Returns the block length of the digest algorithm, i.e. the length in bytes
+ * of an individual block. Most modern partition a message to be digested into
+ * a sequence of fix-sized blocks that are processed consecutively.
+ *
+ * === Example
+ *   digest = OpenSSL::Digest::SHA1.new
+ *   puts digest.block_length # => 64
+ */
 static VALUE
 ossl_digest_block_length(VALUE self)
 {
@@ -239,7 +289,113 @@ Init_ossl_digest()
     mOSSL = rb_define_module("OpenSSL"); /* let rdoc know about mOSSL */
 #endif
 
+    /* Document-class: OpenSSL::Digest
+     *
+     * OpenSSL::Digest allows you to compute message digests (sometimes
+     * interchangeably called "hashes") of arbitrary data that are
+     * cryptographically secure, i.e. a Digest implements a secure one-way
+     * function.
+     *
+     * One-way functions offer some useful properties. E.g. given two
+     * distinct inputs the probability that both yield the same output
+     * is highly unlikely. Combined with the fact that every message digest
+     * algorithm has a fixed-length output of just a few bytes, digests are
+     * often used to create unique identifiers for arbitrary data. A common
+     * example is the creation of a unique id for binary documents that are
+     * stored in a database.
+     *
+     * Another useful characteristic of one-way functions (and thus the name)
+     * is that given a digest there is no indication about the original
+     * data that produced it, i.e. the only way to identify the original input
+     * is to "brute-force" through every possible combination of inputs.
+     *
+     * These characteristics make one-way functions also ideal companions
+     * for public key signature algorithms: instead of signing an entire
+     * document, first a hash of the document is produced with a considerably
+     * faster message digest algorithm and only the few bytes of its output
+     * need to be signed using the slower public key algorithm. To validate
+     * the integrity of a signed document, it suffices to re-compute the hash
+     * and verify that it is equal to that in the signature.
+     *
+     * Among the supported message digest algorithms are:
+     * * DSS, DSS1
+     * * MD2, MD4, MDC2 and MD5
+     * * RIPEMD160
+     * * SHA, SHA1, SHA224, SHA256, SHA384 and SHA512
+     *
+     * For each of these algorithms, there is a sub-class of Digest that
+     * can be instantiated as simply as e.g.
+     *
+     *   digest = OpenSSL::Digest::SHA1.new
+     *
+     * === Mapping between Digest class and sn/ln
+     *
+     * The sn (short names) and ln (long names) are defined in 
+     * <openssl/object.h> and <openssl/obj_mac.h>. They are textual 
+     * representations of ASN.1 OBJECT IDENTIFIERs. Each supported digest
+     * algorithm has an OBJECT IDENTIFIER associated to it and those again
+     * have short/long names assigned to them.
+     * E.g. the OBJECT IDENTIFIER for SHA-1 is 1.3.14.3.2.26 and its
+     * sn is "SHA1" and its ln is "sha1".
+     * ==== MD2
+     * * sn: MD2
+     * * ln: md2
+     * ==== MD4
+     * * sn: MD4
+     * * ln: md4
+     * ==== MD5
+     * * sn: MD5
+     * * ln: md5
+     * ==== SHA
+     * * sn: SHA
+     * * ln: SHA
+     * ==== SHA-1
+     * * sn: SHA1
+     * * ln: sha1
+     * ==== SHA-224
+     * * sn: SHA224
+     * * ln: sha224
+     * ==== SHA-256
+     * * sn: SHA256
+     * * ln: sha256
+     * ==== SHA-384
+     * * sn: SHA384
+     * * ln: sha384
+     * ==== SHA-512
+     * * sn: SHA512
+     * * ln: sha512
+     *
+     * "Breaking" a message digest algorithm means defying its one-way
+     * function characteristics, i.e. producing a collision or finding a way
+     * to get to the original data by means that are more efficient than
+     * brute-forcing etc. Most of the supported digest algorithms can be
+     * considered broken in this sense, even the very popular MD5 and SHA1
+     * algorithms. Should security be your highest concern, then you should
+     * probably rely on SHA224, SHA256, SHA384 or SHA512.
+     *
+     * === Hashing a file
+     *
+     *   data = File.read('document')
+     *   sha256 = OpenSSL::Digest::SHA256.new
+     *   digest = sha256.digest(data)
+     *
+     * === Hashing several pieces of data at once
+     *
+     *   data1 = File.read('file1')
+     *   data2 = File.read('file2')
+     *   data3 = File.read('file3')
+     *   sha256 = OpenSSL::Digest::SHA256.new
+     *   sha256 << data1
+     *   sha256 << data2
+     *   sha256 << data3
+     *   digest = sha256.digest
+     */
     cDigest = rb_define_class_under(mOSSL, "Digest", rb_path2class("Digest::Class"));
+    /* Document-class: OpenSSL::Digest::DigestError
+     *
+     * Generic Exception class that is raised if an error occurs during a
+     * Digest operation.
+     */
     eDigestError = rb_define_class_under(cDigest, "DigestError", eOSSLError);
 
     rb_define_alloc_func(cDigest, ossl_digest_alloc);