summaryrefslogtreecommitdiff
path: root/ext/openssl/ossl_digest.c
diff options
context:
space:
mode:
authoremboss <emboss@b2dd03c8-39d4-4d8f-98ff-823fe69b080e>2011-05-16 23:07:58 +0000
committeremboss <emboss@b2dd03c8-39d4-4d8f-98ff-823fe69b080e>2011-05-16 23:07:58 +0000
commit60fdd0f0f56747b0bf0f91903636f9989e8fd577 (patch)
treee8176089b0afd41bd71345a184b758af847ab591 /ext/openssl/ossl_digest.c
parent13ae409e1ee96cb191d223e475cb563405dcec83 (diff)
* ext/openssl/ossl_digest.c: Add documentation.
git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@31604 b2dd03c8-39d4-4d8f-98ff-823fe69b080e
Diffstat (limited to 'ext/openssl/ossl_digest.c')
-rw-r--r--ext/openssl/ossl_digest.c162
1 files changed, 159 insertions, 3 deletions
diff --git a/ext/openssl/ossl_digest.c b/ext/openssl/ossl_digest.c
index 2b76fe7..e86fb91 100644
--- a/ext/openssl/ossl_digest.c
+++ b/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);