MAC calculation for webflow signing requests

This documentation describes how to generate a secure URL to the signing webflow on www.egreement.com for a specific agreement.

Introduction

Generating a URL for the signing webflow is most commonly used when creating agreements using the Egreement API. The alternative is to let the user access the signing webflow by clicking the link in the mail notification that can be sent when creating the agreement.

This document describes how to generate a secure and unique URL that takes the end user to the web flow that handles signing of agreements. When creating the URL it is also possible to configure it to require identification by eID to access the agreement.

The webflow URL

The webflow URL will take the user to the start of the agreement signing webflow. The URL is constructed by adding parameters to the base URL.

Production Base URL: https://www.egreement.com/webflow.html

Integration Base URL: https://prodtest.egreement.com/webflow.html

Parameters Description

rejectedCallbackUrl

If the user choose to reject signing the agreement the user will be forwarded to this URL.

failedSigningCallbackUrl

If there is a failure during signing the agreement the user will be forwarded to this URL.

signedCallbackUrl

After successfully signing the agreement the user will be forwarded to this URL.

referenceNumber

The agreement reference number that identifies the specific agreement that shall be signed.

loginRequired

By default accessing the webflow requires the user to log in using eID. Default value is TRUE if this parameter is not supplied.

enableRejection

By default reject button is hidden on webflow during signing. To enable reject button in webflow, this field needs to be set as TRUE along with loginRequired. Default value is FALSE if this parameter is not supplied.

registrationRequired

(Optional)By default a user needs to be registered in egreement system before signing, but registration can be avoided by passing a false value in registrationRequired parameter.

mac

The MAC calculated by using the private key.

mac

The MAC calculated by using the private key.

orgNo

Swedish organization number. Only used if the signing party is a company.

party

Unique Id generated for each party configured with sign-method as ["SMS_OTP"] or ["EMAIL_OTP"]

Mandatory only if the sign-method of the party is configured as ["SMS_OTP"] or ["EMAIL_OTP"]

Party unique id can recieved from the Create/Get Agreement API Response.

If party is private, party = ${parties.privates.id} from the API response

If party is company, party = ${parties.companies.id} from the API response

  •                                         https://www.egreement.com/webflow.html?rejectedCallbackUrl=http%3A%2F%2Fyahoo.com&failedSigningCallbackUrl=http%3A%2F%2Fgmail.com&signedCallbackUrl=http%3A%2F%2Fgoogle.com&referenceNumber=160900027159&loginRequired=false&mac=198D7CF2AC2A3B25BEB8DC2C4BF41B55&party=592C4BF41B558D7C
                                        
  •                                         https://www.egreement.com/webflow.html?rejectedCallbackUrl=http%3A%2F%2Fyahoo.com&failedSigningCallbackUrl=http%3A%2F%2Fgmail.com&signedCallbackUrl=http%3A%2F%2Fgoogle.com&referenceNumber=161100027231&loginRequired=false&mac=E48B7B09BA018A10336B4AA6A413D626&orgNo=5555555555
                                        

Instructions for calculating MAC

  1. Sort all applicable parameters for your scenario by name in alphabetical order. I.e., all mandatory parameters and additional parameters if applicable.
  2. Serialize the values using '&' as separator, i.e., <value_1>&<value_2>&...&<value_N>
  3. Compute a HMAC MD5 based on the result from step 2 and the API-key.
  4. Convert the result from step 3 to an upper-case hex string.

Based on applicable parameters and the API-Key (a.k.a. privateKey) that's been provided to you, MAC will be calculated as mentioned below. Assume that parameters used in the examples are required.

  •                                         data=failedSigningCallbackUrl+'&'+party+'&'+referenceNumber+'&'+rejectedCallbackUrl+'&'+signedCallbackUrl;mac=MacUtility.calculateHMAC(data, privatekey);
                                        
  •                                         import javax.crypto.Mac;import javax.crypto.spec.SecretKeySpec;import java.security.SignatureException;import java.util.Formatter;// STARTclass MacUtility {  public static final String HMAC_MD5_ALGORITHM = 'HmacMD5';  public static String calculateHMAC(String data, String key) throws SignatureException {    try {SecretKeySpec signingKey = new SecretKeySpec(key.getBytes(),HMAC_MD5_ALGORITHM);    Mac mac = Mac.getInstance(HMAC_MD5_ALGORITHM);    mac.init(signingKey);    byte[] rawHMAC = mac.doFinal(data.getBytes());    return asHex(rawHMAC).toUpperCase();    } catch (Exception e) {        throw new SignatureException('Failed to generate HMAC : ' + e.getMessage());    }  }  private static String asHex(byte[] buffer) {    Formatter formatter = new Formatter();    for (byte b : buffer) {       formatter.format('%02x', b);    }    return formatter.toString();  }// END}
                                        
  •                                         $data=$failedSigningCallbackUrl.'&'.$party.'&'.$referenceNumber'&'.$rejectedCallbackUrl.'&'.$signedCallbackUrl;$mac=hmac($data, $privatekey);
                                        
  • If you are using PHP4, define the function like:

                                            function hmac ($data, $key){    $b = 64; // byte length for md5    if (strlen($key) > $b) {        $key = pack('H*',md5($key));    }    $key = str_pad($key, $b, chr(0x00));    $ipad = str_pad('', $b, chr(0x36));    $opad = str_pad('', $b, chr(0x5c));    return strtoupper(md5($k_opad . pack('H*',md5($k_ipad . $data))));}
                                        

    If you are using PHP5, define the function like:

                                            function hmac ($data, $key){    return strtoupper(hash_hmac('md5', $data, $key));}
                                        

Different scenarios require different parameters to be included in MAC calculation. Check next section for instructions on which parameters to include.

Different webflow signing scenarios

1. Private mode signing

Applicable MAC parameters:

  • failedSigningCallbackUrl
  • referenceNumber
  • rejectedCallbackUrl
  • signedCallbackUrl
  • party (Applicable only if the party is configured with sign-method as "SMS_OTP" or "EMAIL_OTP")

2. Private mode signing with loginRequired set to 'false'

The parameter loginRequired should only be included if its value is set to 'false'.

Applicable MAC parameters:

  • failedSigningCallbackUrl
  • loginRequired
  • referenceNumber
  • rejectedCallbackUrl
  • signedCallbackUrl
  • party (Applicable only if the party is configured with sign-method as "SMS_OTP" or "EMAIL_OTP")

3. Company mode signing

In this scenario the parameter orgNo will be included.

Applicable MAC parameters:

  • failedSigningCallbackUrl
  • orgNo
  • referenceNumber
  • rejectedCallbackUrl
  • signedCallbackUrl
  • party (Applicable only if the party is configured with sign-method as "SMS_OTP" or "EMAIL_OTP")

4. Company mode signing with loginRequired set to 'false'

In this scenario the parameters orgNo and loginRequired will be included.

Applicable MAC parameters:

  • failedSigningCallbackUrl
  • loginRequired
  • orgNo
  • referenceNumber
  • rejectedCallbackUrl
  • signedCallbackUrl
  • party (Applicable only if the party is configured with sign-method as "SMS_OTP" or "EMAIL_OTP")
Return to Top