ossl_hmac.c in rubysl-openssl-2.2.0

- old
+ new

@@ -60,10 +60,40 @@
 
 /*
  *  call-seq:
  *     HMAC.new(key, digest) -> hmac
  *
+ * Returns an instance of OpenSSL::HMAC set with the key and digest
+ * algorithm to be used. The instance represents the initial state of
+ * the message authentication code before any data has been processed.
+ * To process data with it, use the instance method #update with your
+ * data as an argument.
+ *
+ * === Example
+ *
+ *	key = 'key'
+ * 	digest = OpenSSL::Digest.new('sha1')
+ * 	instance = OpenSSL::HMAC.new(key, digest)
+ * 	#=> f42bb0eeb018ebbd4597ae7213711ec60760843f
+ * 	instance.class
+ * 	#=> OpenSSL::HMAC
+ *
+ * === A note about comparisons
+ *
+ * Two instances won't be equal when they're compared, even if they have the
+ * same value. Use #to_s or #hexdigest to return the authentication code that
+ * the instance represents. For example:
+ *
+ *	other_instance = OpenSSL::HMAC.new('key', OpenSSL::Digest.new('sha1'))
+ *  	#=> f42bb0eeb018ebbd4597ae7213711ec60760843f
+ *  	instance
+ *  	#=> f42bb0eeb018ebbd4597ae7213711ec60760843f
+ *  	instance == other_instance
+ *  	#=> false
+ *  	instance.to_s == other_instance.to_s
+ *  	#=> true
+ *
  */
 static VALUE
 ossl_hmac_initialize(VALUE self, VALUE key, VALUE digest)
 {
     HMAC_CTX *ctx;
@@ -93,10 +123,23 @@
 
 /*
  *  call-seq:
  *     hmac.update(string) -> self
  *
+ * Returns +self+ updated with the message to be authenticated.
+ * Can be called repeatedly with chunks of the message.
+ *
+ * === Example
+ *
+ *	first_chunk = 'The quick brown fox jumps '
+ * 	second_chunk = 'over the lazy dog'
+ *
+ * 	instance.update(first_chunk)
+ * 	#=> 5b9a8038a65d571076d97fe783989e52278a492a
+ * 	instance.update(second_chunk)
+ * 	#=> de7c9b85b8b78aa6bc8a7a36f70a90701c9db4d9
+ *
  */
 static VALUE
 ossl_hmac_update(VALUE self, VALUE data)
 {
     HMAC_CTX *ctx;
@@ -123,12 +166,21 @@
     HMAC_CTX_cleanup(&final);
 }
 
 /*
  *  call-seq:
- *     hmac.digest -> aString
+ *     hmac.digest -> string
  *
+ * Returns the authentication code an instance represents as a binary string.
+ *
+ * === Example
+ *
+ *	instance = OpenSSL::HMAC.new('key', OpenSSL::Digest.new('sha1'))
+ * 	#=> f42bb0eeb018ebbd4597ae7213711ec60760843f
+ * 	instance.digest
+ * 	#=> "\xF4+\xB0\xEE\xB0\x18\xEB\xBDE\x97\xAEr\x13q\x1E\xC6\a`\x84?"
+ *
  */
 static VALUE
 ossl_hmac_digest(VALUE self)
 {
     HMAC_CTX *ctx;
@@ -143,12 +195,15 @@
     return digest;
 }
 
 /*
  *  call-seq:
- *     hmac.hexdigest -> aString
+ *     hmac.hexdigest -> string
  *
+ * Returns the authentication code an instance represents as a hex-encoded
+ * string.
+ *
  */
 static VALUE
 ossl_hmac_hexdigest(VALUE self)
 {
     HMAC_CTX *ctx;
@@ -171,10 +226,24 @@
 
 /*
  *  call-seq:
  *     hmac.reset -> self
  *
+ * Returns +self+ as it was when it was first initialized, with all processed
+ * data cleared from it.
+ *
+ * === Example
+ *
+ *	data = "The quick brown fox jumps over the lazy dog"
+ * 	instance = OpenSSL::HMAC.new('key', OpenSSL::Digest.new('sha1'))
+ * 	#=> f42bb0eeb018ebbd4597ae7213711ec60760843f
+ *
+ * 	instance.update(data)
+ * 	#=> de7c9b85b8b78aa6bc8a7a36f70a90701c9db4d9
+ * 	instance.reset
+ * 	#=> f42bb0eeb018ebbd4597ae7213711ec60760843f
+ *
  */
 static VALUE
 ossl_hmac_reset(VALUE self)
 {
     HMAC_CTX *ctx;
@@ -187,10 +256,22 @@
 
 /*
  *  call-seq:
  *     HMAC.digest(digest, key, data) -> aString
  *
+ * Returns the authentication code as a binary string. The +digest+ parameter
+ * must be an instance of OpenSSL::Digest.
+ *
+ * === Example
+ *
+ *	key = 'key'
+ * 	data = 'The quick brown fox jumps over the lazy dog'
+ * 	digest = OpenSSL::Digest.new('sha1')
+ *
+ * 	hmac = OpenSSL::HMAC.digest(digest, key, data)
+ * 	#=> "\xDE|\x9B\x85\xB8\xB7\x8A\xA6\xBC\x8Az6\xF7\n\x90p\x1C\x9D\xB4\xD9"
+ *
  */
 static VALUE
 ossl_hmac_s_digest(VALUE klass, VALUE digest, VALUE key, VALUE data)
 {
     unsigned char *buf;
@@ -204,12 +285,24 @@
     return rb_str_new((const char *)buf, buf_len);
 }
 
 /*
  *  call-seq:
- *     HMAC.digest(digest, key, data) -> aString
+ *     HMAC.hexdigest(digest, key, data) -> aString
  *
+ * Returns the authentication code as a hex-encoded string. The +digest+
+ * parameter must be an instance of OpenSSL::Digest.
+ *
+ * === Example
+ *
+ *	key = 'key'
+ * 	data = 'The quick brown fox jumps over the lazy dog'
+ * 	digest = OpenSSL::Digest.new('sha1')
+ *
+ * 	hmac = OpenSSL::HMAC.hexdigest(digest, key, data)
+ * 	#=> "de7c9b85b8b78aa6bc8a7a36f70a90701c9db4d9"
+ *
  */
 static VALUE
 ossl_hmac_s_hexdigest(VALUE klass, VALUE digest, VALUE key, VALUE data)
 {
     unsigned char *buf;
@@ -235,9 +328,10 @@
  */
 void
 Init_ossl_hmac()
 {
 #if 0
+    /* :nodoc: */
     mOSSL = rb_define_module("OpenSSL"); /* let rdoc know about mOSSL */
 #endif
 
     eHMACError = rb_define_class_under(mOSSL, "HMACError", eOSSLError);
 