ruby-changes:19563
From: emboss <ko1@a...>
Date: Tue, 17 May 2011 08:09:19 +0900 (JST)
Subject: [ruby-changes:19563] emboss:r31604 (trunk): * ext/openssl/ossl_digest.c: Add documentation.
emboss 2011-05-17 08:07:58 +0900 (Tue, 17 May 2011) New Revision: 31604 http://svn.ruby-lang.org/cgi-bin/viewvc.cgi?view=rev&revision=31604 Log: * ext/openssl/ossl_digest.c: Add documentation. Modified files: trunk/ChangeLog trunk/ext/openssl/ossl_digest.c Index: ChangeLog =================================================================== --- ChangeLog (revision 31603) +++ ChangeLog (revision 31604) @@ -1,3 +1,7 @@ +Tue May 17 08:04:26 2011 Martin Bosslet <Martin.Bosslet@g...> + + * ext/openssl/ossl_digest.c: Add documentation. + Tue May 17 07:14:58 2011 Eric Hodel <drbrain@s...> * lib/net/http.rb: Improve documentation of proxy configuration Index: ext/openssl/ossl_digest.c =================================================================== --- ext/openssl/ossl_digest.c (revision 31603) +++ ext/openssl/ossl_digest.c (revision 31604) @@ -88,8 +88,21 @@ /* * 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 ossl_digest_initialize(int argc, VALUE *argv, VALUE self) @@ -130,6 +143,9 @@ * 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 @@ * 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 @@ * 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 @@ /* * call-seq: - * digest.digest_size -> integer + * digest.digest_length -> integer * - * Returns the output size of the digest. + * 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 + * */ static VALUE ossl_digest_size(VALUE self) @@ -217,6 +255,18 @@ 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 @@ 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); -- ML: ruby-changes@q... Info: http://www.atdot.net/~ko1/quickml/