Documentation for OpenSSL::HMAC class. (#4434)

akzhan · Martin Verzilli · commit e7caa7da8501 · 2017-06-02T11:34:47.000-03:00
diff --git a/src/openssl/hmac.cr b/src/openssl/hmac.cr
@@ -1,6 +1,27 @@
 require "./lib_crypto"
 
+# Allows computing Hash-based Message Authentication Code (HMAC).
+#
+# It is a type of message authentication code (MAC)
+# involving a hash function in combination with a key.
+#
+# HMAC can be used to verify the integrity of a message as well as the authenticity.
+#
+# See also [RFC2104](https://tools.ietf.org/html/rfc2104.html).
 class OpenSSL::HMAC
+  # Returns the HMAC digest of *data* using the secret *key*.
+  #
+  # It may contain non-ASCII bytes, including NUL bytes.
+  #
+  # *algorithm* is a `Symbol` of a supported digest algorithm:
+  # * `:md4`.
+  # * `:md5`.
+  # * `:ripemd160`.
+  # * `:sha1`.
+  # * `:sha224`.
+  # * `:sha256`.
+  # * `:sha384`.
+  # * `:sha512`.
   def self.digest(algorithm : Symbol, key, data) : Bytes
     evp = case algorithm
           when :md4       then LibCrypto.evp_md4
@@ -20,6 +41,11 @@ class OpenSSL::HMAC
     buffer[0, buffer_len.to_i]
   end
 
+  # Returns the HMAC digest of *data* using the secret *key*,
+  # formatted as a hexadecimal string. This is neccesary to safely transfer
+  # the digest where binary messages are not allowed.
+  #
+  # See also `#digest`.
   def self.hexdigest(algorithm : Symbol, key, data) : String
     digest(algorithm, key, data).hexstring
   end
