Skip to main content
Ben Nadel at the New York ColdFusion User Group (Feb. 2009) with: Joakim Marner and Clark Valberg
Ben Nadel at the New York ColdFusion User Group (Feb. 2009) with: Joakim Marner Clark Valberg ( @clarkvalberg )

Hex-Encoding A Binary Value / Byte Array In ColdFusion

By on

When you start dealing with 3rd-party APIs, hex-encoding a byte array becomes a surprisingly common task. This is because 3rd-party APIs often require you to "sign" the request using your secret Key to produce a Hashed Message Authentication Code (Hmac). EmailYak uses the MD5 hashing algorithm; Pusher uses the Sha-256 hashing algorithm; and Twilio uses the Sha-1 hashing algorithm. Each of these hashes is returned as a byte array that has to be Hex-encoded before it can be attached to the API request. I've used a number of Hex-encoding approaches; but yesterday, I (re-)discovered that ColdFusion provides a super simple, built-in method for Hex-encoding binary values: binaryEncode().

NOTE: ColdFusion 10 now provides a built-in hmac() function for creating Hashed Message Authentication Codes; but that is beyond the scope of this post.

ColdFusion has so many built-in functions that if you don't use them on a regular basis, you can quickly forget that they exist. Such is the case with binaryEncode(). I don't believe I've used in about 6 years. As it turns out, though, it makes hex-encoding a binary value a one-line task.

Having re-discovered this yesterday, I wanted to quickly perform a functional comparison of binaryEncode() to some of the other hex-encoding approaches that I have used in the past. In the following code, I'm using a manual approach, a BigInteger approach, and a binaryEncode() approach to hex-encode a single byte array. This way, I can make sure that they all produce the same output:


	// I encode the binary value / byte array as a HEX value by
	// manually looping over the array, encoding each byte
	// individually.
	function encodeManually( Any bytes ){

		// Create a buffer to hold each encoded byte.
		var hexBuffer = [];

		// Get the length of the array so we don't have to keep
		// evaluating it for each loop iteration.
		var byteCount = arrayLen( bytes );

		// Use an index loop rather than a for-in loop because
		// ColdFusion seems to have some trouble with navigating a
		// non-stanard array.
		for (var i = 1 ; i <= byteCount ; i++){

			// Strip off any sign information - let's work with
			// only the last 8 bits of information.
			var unsignedByte = bitAnd( bytes[ i ], 255 );

			var hexValue = formatBaseN( unsignedByte, 16 );

			// Of any byte value less than or equal to 15, we only
			// need one-digit of HEX encoding; however, we want all
			// our encoding values to be 2-digits.
			if (unsignedByte <= 15){

				hexValue = ("0" & hexValue);


			arrayAppend( hexBuffer, hexValue );


		// Join the hex buffer and return the full hex-encoding.
			arrayToList( hexBuffer, "" )


	// ------------------------------------------------------ //
	// ------------------------------------------------------ //

	// I encode the binary value / byte array as a HEX value using
	// the BigInteger class.
	function encodeWithBigInt( Any bytes ){

		// Let's pretend that our byte array represents the bytes of
		// enormous integer value.
		var bigInt = createObject( "java", "java.math.BigInteger" ).init(
			javaCast( "int", 1 ),

		// Cast our enormous integer to a base16 string.
		var hexEncoding = bigInt.toString( javaCast( "int", 16 ) );

		// When converting to a HEX value, BigInteger will strip off
		// the leading zero. However, we want all of our HEX values to
		// be represented as a 2-digit hex. If the first byte is less
		// than or equal to 15, let's prepend the leading zero.
		var firstByte = bitAnd( bytes[ 1 ], 255 );

		if (firstByte <= 15){

			hexEncoding = ("0" & hexEncoding);


		// Return the hex-encoding.
		return( hexEncoding );


	// ------------------------------------------------------ //
	// ------------------------------------------------------ //

	// I encode the binary value / byte array as a HEX value using
	// the built-in binaryEncode() ColdFusion metho.
	function encodeWithBinaryEncode( Any bytes ){

		// Convert the binary to a hex-encoded string.
		var hexEncoding = binaryEncode( bytes, "hex" );

		// Lower-case the HEX value since none of the other methods
		// above use upper-case value (while ColdFusion does).
			lcase( hexEncoding )


	// ------------------------------------------------------ //
	// ------------------------------------------------------ //
	// ------------------------------------------------------ //
	// ------------------------------------------------------ //

	// I return a byte array. The byte array is built using values
	// at the low end of the ASCII table. This is done to ensure that
	// we run into a situation where our first HEX value is less than
	// 16. This will test the leading-zero situation.
	function getBytes(){

		// Let's built up an array of characters that will be
		// converted to binary.
		var charBuffer = [];

		// Build the array up using ASCII decimal values.
		for (var i = 9 ; i <= 32 ; i++){

			arrayAppend( charBuffer, chr( i ) );


		// Collapse the character array.
		var textValue = arrayToList( charBuffer, "" );

		// Return the string as binary data.
			toBinary( toBase64( textValue ) )


	// ------------------------------------------------------ //
	// ------------------------------------------------------ //

	bytes = getBytes();

	// Test the various encoding approaches.
	writeOutput( "Hex: " & encodeManually( bytes ) );
	writeOutput( "<br />" );
	writeOutput( "Hex: " & encodeWithBigInt( bytes ) );
	writeOutput( "<br />" );
	writeOutput( "Hex: " & encodeWithBinaryEncode( bytes ) );


As you can see, each of these approaches is less complex than the one before it, with binaryEncode() being the only one-liner. When we run the three algorithms in sequence, we get the following output:

Hex: 090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f20
Hex: 090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f20
Hex: 090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f20

In this case, I am using lcase() to convert the binaryEncode() value to lower-case. While case does not matter for HEX values, the first two approaches use lower-case characters. As such, I used lcase() simply to make them all look the same - it was easier to compare the outputs.

As you can see above, all three approaches produce the same Hex-encoding. And, obviously, ColdFusion's built-in binaryEncode() is by far the most straightforward approach. It's a shame that I forgot this function existed - it will definitely make dealing with 3rd party APIs much easier (when not using ColdFusion 10).

Want to use code from this post? Check out the license.

Reader Comments