Difference between revisions of "Updox HMAC Authentication"

From Updox API
Jump to: navigation, search
(Outline)
Line 13: Line 13:
 
1. updox-timestamp - the current time in the format "yyyy-MM-dd HH:mm:ss (z)".
 
1. updox-timestamp - the current time in the format "yyyy-MM-dd HH:mm:ss (z)".
  
2. Authorization - "HMAC:" + the Base64 encoded HMAC SHA1 hash of the message with the secret key.
+
2. Authorization - "HMAC " + the Base64 encoded HMAC SHA1 hash of the message with the secret key.  Note the <SPACE> character following the letters HMAC.
  
 
The message is defined as: [vendorId]:[vendorPassword]:[updox-timestamp]
 
The message is defined as: [vendorId]:[vendorPassword]:[updox-timestamp]

Revision as of 10:44, 13 December 2013

Contents

Description

For enhanced security, Updox provides an additional layer of authentication using a keyed-hash message authentication code (HMAC) with SHA1 as the cryptographic hash function. This document outlines how to use the Updox HMAC-SHA1 authentication.

Note: Updox HMAC-SHA1 enhances the Individual and Application Authorization schemes, it does not replace it. The auth header in the body of the post is still required for authorizing as a vendor, account, and user.



Outline

The Updox HMAC-SHA1 authentication layer requires two http header fields for every request:

1. updox-timestamp - the current time in the format "yyyy-MM-dd HH:mm:ss (z)".

2. Authorization - "HMAC " + the Base64 encoded HMAC SHA1 hash of the message with the secret key. Note the <SPACE> character following the letters HMAC.

The message is defined as: [vendorId]:[vendorPassword]:[updox-timestamp]

Verification

Updox will verify two things:

1. The timestamp header (updox-timestamp) is within the minutes defined for the vendor (e.g. 10 minutes).

2. The hash passed in matches the hash we compute (therefore, the message was signed with the secret key).

Code Samples

Language Source Code Examples
C#


      public void setHmacHeaders(HttpWebRequest request)
       {
           string applicationId = "vendor-id";
           string applicationPassword = "vendor-password";
           string accountId = "accountId";
           string userId = "userId";
           string apiSecret = "vendor-private-secret-key"; 
 
           // Create the date string
           String timestampString = DateTime.UtcNow.ToString("yyyy-MM-dd HH:mm:ss") + " (GMT)"
  
           // Build authentication string
           string message = 
                applicationId + ":" + 
                applicationPassword + ":" + 
                accountId + ":" + 
                userId + ":" + 
                timestampString; 
 
           // Create the athentication hash - note the intentional <space> after HMAC
           string auth = "HMAC " + hmacSha1ToBase64(message, apiSecret);  //
 
           // Set the request headers
           request.Headers.Add("updox-timestamp", timestampString);
           request.Headers.Add("Authorization", auth);
       }
 
       public string hmacSha1ToBase64(String value, String key)
       {
           // Get an hmac_sha1 key from the raw key bytes
           byte[] keyBytes = Encoding.UTF8.GetBytes(key);
           byte[] valueBytes = Encoding.UTF8.GetBytes(value);
               
             
           // Get an hmac_sha1 Mac instance and initialize with the signing key
           HMACSHA1 myhmacsha1 = new HMACSHA1();
 
           myhmacsha1.Key = keyBytes;
 
           byte[] final = myhmacsha1.ComputeHash(valueBytes);
 
           // Covert array of Hex bytes to a String
           return Convert.ToBase64String(final);
       }
Java


   public static void generateHmacHeaders(HttpURLConnection connection, String applicationId, String applicationPassword, String accountId, String userId) throws Exception{
       final SimpleDateFormat d = new SimpleDateFormat("yyyy-MM-dd HH:mm:ss (z)");
       d.setTimeZone(TimeZone.getTimeZone("GMT"));
       final String timestampString = d.format(new Date());
       final String message = 
          (applicationId == null ? "" : applicationId) + ":" + 
          (applicationPassword == null ? "" : applicationPassword) + ":" + 
          (accountId == null ? "" : accountId) + ":" + 
          (userId == null ? "" : userId) + ":" + 
          timestampString;
       final String auth = "HMAC " + hmacSha1ToBase64(message, apiSecret); //note space after HMAC
       connection.setRequestProperty("updox-timestamp", timestampString);  
       connection.setRequestProperty("Authorization", auth);
   }
   
   public static String hmacSha1ToBase64(String value, String key) throws Exception{
       byte[] keyBytes = key.getBytes();
       SecretKeySpec signingKey = new SecretKeySpec(keyBytes, "HmacSHA1");
       Mac mac = Mac.getInstance("HmacSHA1");
       mac.init(signingKey);
       byte[] rawHmac = mac.doFinal(value.getBytes());
       byte[] base64Bytes = Base64.encodeBase64(rawHmac);
       return new String(base64Bytes, "UTF-8");
   }



Messages

Destination Address

 https://updoxqa.com/io/pingWithAuth



Sample Request and Response

Headers

updox-timestamp: 2013-11-20 17:36:00 (EST)

Authorization: fH2JyYwiERQbwXL4XF6ZvtLjRvQ=

Request

{
    "auth": {
        "applicationId": "updox",
        "applicationPassword": "password",
        "accountId": "100",
        "userId": "100"
    }
}

Response

{
    "successful": true,
    "responseMessage": "OK",
    "responseCode": 2000
}

Relevant Response Codes

In addition to the General Error Set, this method may return the following values in the responseCode and responseMessage fields:

responseCode responseMessage
4010 Unauthorized