Keyed Hashing for Message Authentication (HMAC)

This article explains how the [Encrypt_HMAC] tag can be used to created HMAC codes for use in e-commerce and secure communications. HMAC codes help ensure the integrity and authenticity of messages during server to server communications.

Introduction

Secure communications on the Internet are very important for some applications such as e-commerce. If you are transmitting orders or credit card information to a payment gateway like Google Checkout then you want to ensure that the information which is received is verified as coming from a valid source and that it hasn't been modified in transit.

HMAC codes are used by Google Checkout and other payment gateways to ensure that orders which are placed actually come from your Web site and that they haven't been modified in transit.

Hash Functions

A hash function can be used to generate a token which will be passed along with a message and will let the receiver know that it hasn't been modified in transit. For example, I can pass the entire preceding paragraph into the MD5 algorithm to get the following string. You could then pass the paragraph through the same function and make sure that the hashed value is the same.

  [Encrypt_MD5: 'Secure ... transit.']

  cce163a0d174f287d9f9a99648f8444e

Hash functions are often provided with downloads so that the recipient can confirm that the download was received properly. If any bytes have been changed in transit then the hash value will be different and the recipient will know that they need to download the file again.

Hash functions used in this way help ensure the integrity of the downloaded file, however they don't protect against a malicious modification of the file while it is in transit. If somebody wanted to modify the file as it passed through an intermediate server they would simply need to adjust the hash to make sure that it corresponded with the changes they had made.

The most popular hash functions are MD5 and SHA-1. MD5 has been in use for a long time, but is no longer considered secure since some techniques have been discovered which make it easy to reverse engineer the original message from the hash. Most new applications makes uses of the SHA-1 hash function.

HMAC

HMAC aims to ensure both the integrity of the message and to allow the recipient to verify that it was sent by a particular sender.

The basic idea is to use the hash function multiple times to generate a value which the recipient is going to be able to generate, but will be difficult for any other party to generate. The password and the message are concatenated together and run through the hash function. The password and the result are concatenated and then run through the hash function again. This result is the HMAC code for the message.

The HMAC code for the paragraph starting this section can be generated using the [Encrypt_HMAC] tag with a -Password. The -Cram option outputs the results in the same format as the [Encrypt_MD5] tag.

  [Encrypt_HMAC: 'Secure ... transit.',

    -Password='My Secret Password', -Cram]

    e83197f2112b733f44485498eac868c2

If an HMAC code is provided with a download and the password for the HMAC code is known only to the server and to the recipient then it is impossible for someone to modify the file in transit and to generate a new HMAC code. The recipient can now be confident that the downloaded file was received properly and that it was not modified in transit.

Note - See the RFC for the details of the algorithm. The implementation of the [Encrypt_HMAC] function can be found in the email/encode_crammd5.inc file in the source code for Startup.LassoApp.

http://www.faqs.org/rfcs/rfc2104.html

[Encrypt_HMAC]

The [Encrypt_HMAC] tag is included with Lasso Professional 8.5.1 and higher. It was originally introduced in a Google Checkout tip of the week which is linked above.

The [Encrypt_HMAC] tag returns the HMAC code for a given message. The tag requires two parameters: the message for which the HMAC code should be generate and the -Password which should be used to generate the code. By default the [Encrpt_HMAC] tag uses the MD5 hash algorithm.

The following tag generates the HMAC-MD5 code for the specified message with the specified password.

  [Encrypt_HMAC: 'message', -Password='My Secret Password']

Output Formats

The output of [Encrypt_HMAC] is a byte stream by default. This can be useful for some low-level communications, but high-level communications generally require that the HMAC code be encoded in either hexadecimal or using Base64 encoding.

-Cram outputs the HMAC code using a common hexadecimal format which uses lowercase letters and does not include an 0x prefix. This is the same format which is output by [Encrypt_MD5]. If you need uppercase hexadecimal numbers you can pass this output through [String_Uppercase].

  [Encrypt_HMAC: 'message', -Password='My Secret Password', -Cram]

   6dff7c6a46ca11c9ccdaff60449c229a

-Hex output the HMAC code in hexadecimal format.

  [Encrypt_HMAC: 'message', -Password='My Secret Password', -Hex]

   0x6dff7c6a46ca11c9ccdaff60449c229a

-Base64 outputs the HMC code using Base64 encoding.

  [Encrypt_HMAC: 'message', -Password='My Secret Password', -Base64]

   bf98akbKEcnM2v9gRJwimg==

Hash Algorithms

[Encrypt_HMAC] can use any of the hash algorithms which are available in your installation of Lasso. These will generally include MD5 and SHA-1, but may include others as well. The desired digest should be selected using the -Digest parameter.

[Cipher_List: -Digest] can be used to list the available algorithms. On my Mac OS X test machine this tag returns the following list. However, the list may vary on Windows, Red Hat Linux, and even on different machines on the same platform depending on what version of the OS is installed.

  [Cipher_List: -Digest]

   array: (MD2), (MD4), (MD5), (SHA), (SHA1),

  (DSA-SHA), (DSA), (MDC2), (RIPEMD160)

For example, the HMAC-SHA1 code for a message can be generated using this tag and the HMAC-RIPEMD code for a message can be generated using the subsequent tag.

  [Encrypt_HMAC: 'message', -Password='My Secret Password',

  -Cram, -Digest='sha1']

   41d0ba5ff14bb2cb537623c95dcd3ace5403e4a1

  [Encrypt_HMAC: 'message', -Password='My Secret Password',

  -Cram, -Digest='ripemd160']

   f9cc687338aa3030073db173bc6dec97eca4063a

More Information

More information about the tags used in this tip of the week can be found in the Lasso Language Guide or online in the Lasso Reference.

 

Author: Fletcher Sandbeck
Created: 18 Feb 2008
Last Modified: 16 Mar 2011