Community articleLookupHashAlgorithm function
Added by IBM contributorIBM on July 26, 2013
Rate this article 1 starsRate this article 2 starsRate this article 3 starsRate this article 4 starsRate this article 5 stars

Description

This function retrieves a hash object. Use the hash object to hash shared secrets for the ValidateHMACWithHashedSecret function.

Function

   Function LookupHashAlgorithm(
      algorithmName As String
      ) As IHash


Parameters

Table 1. lookup hash algorithm parameters
ExpressionTypeDescription
algorithmNameStringThe name of the hash algorithm you want to retrieve. The available hash algorithms are sha1 and md5.


Returns

A hash object, or throws an exception if an error occurs.

Example

The following function validates an HMAC signature using a hashed secret. First, the function uses DereferenceEx and GetLiteralByRefEx to locate the signature item in a form. It then uses GetEngineCertificateList and GetDataByPath to locate a server signing certificate. Next, it uses GetSignature and GetDataByPath to get the signer's common name and LookupHashAlgorith and Hash to create a hashed secret. Finally, it uses ValidateHMACWithHashedSecret to determine if the HMAC signature is valid, and returns "Valid" or "Invalid", as appropriate.
Note that this example also relies on a second function called StringToBinary. This function converts a string to a single-byte binary array, which is required for the hash function. This prevents COM from converting the string to a double-byte array before hashing it, which would produce an incorrect result.
   Function ValidateHMACSigHashed(Form)
 
      Dim SigObject, XFDL, HashObject, SecurityManager  ' objects
      Dim TheCerts  ' CertificateList
      Dim Cert, SigningCert  ' ICertificate
      Dim SignerName, SharedSecret, HashedSecret, CommonName, _
         SigItemRef  ' Strings
      Dim Validation  ' Integer
      Dim TempNode, SigNode  ' IFormNodeP
 
      Set TempNode = Form
 
      ' Get the SignatureButton node
 
      Set TempNode = Form.DereferenceEx(vbNullString, _
         "PAGE1.HMACSignatureButton", 0, UFL_ITEM_REFERENCE, Nothing)
 
      ' Get the name of the signature item
      SigItemRef = TempNode.GetLiteralByRefEx(vbNullString, "signature", _
         0, vbNullString, Nothing)
 
      ' Get the signature item node
 
      Set SigNode = TempNode.DereferenceEx(vbNullString, SigItemRef, 0, _
         UFL_ITEM_REFERENCE, Nothing)
 
      ' Get available server certificates for Generic RSA signing
 
      Set XFDL = CreateObject("PureEdge.xfdl_XFDL")
      Set TheCerts = XFDL.GetEngineCertificateList("Generic RSA", 1) 
         ' vbNull
 
      ' Locate the certificate that has a common name of "User1-CP.02.01".
      ' This is the certificate we will use when verifying the signature.
 
      For Each Cert in TheCerts
         CommonName = Cert.GetDataByPath("SigningCert: Subject: CN", _
            False, 1) ' vbNull
         If CommonName = "User1-CP.02.01" Then
            Set SigningCert = Cert
         End If
      Next
 
      ' Get the signature object from the signature node
 
      Set SigObject = SigNode.GetSignature
 
      ' Get the signer's name from the signature object
 
      SignerName = SigObject.GetDataByPath("SigningCert: Subject: CN", _
         False, 1) ' vbNull
 
      ' Include code that matches the signer's identity to a shared secret
      ' that is hashed, and sets SharedSecret to match. In most cases, this 
      ' would be a database lookup. For the purposes of this example, we will
      ' use the Hash function to assign a hashed value to HashedSecret.
      ' Get the Security Manager object
 
      Set SecurityManager = _
         CreateObject("PureEdge.security_SecurityManager")
 
      ' Get the Hash object
 
      Set HashObject = SecurityManager.LookupHashAlgorithm("sha1")
      ' Set the Hashed secret. First convert the secret to a single-byte
      ' binary array, then hash the secret.
 
      SharedSecret = StringToBinary("secret")      
      HashedSecret = HashObject.Hash(SharedSecret)
 
      ' Validate the signature
 
      Validation = SigNode.ValidateHMACWithHashedSecret(HashedSecret, _
         SigningCert, 1) ' vbNull
 
      ' Check the validation code and return either "Valid" or "Invalid"
 
      If Validation = UFL_DS_OK Then
         ValidateHMACSigHashed = "Valid"
      Else
         ValidateHMACSigHashed = "Invalid"
      End If
 
   End Function
 
   ' The following function is required to convert a string to a single-byte '  
   ' binary array before hashing that string. This prevents COM from converting  
   ' the string to a multi-byte format, which would produce an incorrect hash.
 
   Function StringToBinary(String)
 
      Dim Counter, Binary
 
      For Counter = 1 to len(String)
         Binary = Binary & ChrB(Asc(Mid(String, Counter, 1)))
      Next
      StringToBinary = Binary
 
   End Function