MAC calculation

Without securing the transfer of information between the merchant and DIBS, the data could be maliciously altered or downright faked. By tampering with sensitive information such as price, currency and reference numbers, frauds could be performed

DIBS provides ways for securing the information transfer, that is strongly recommended to use. This is the DIBS MAC feature. The MAC feature is enabled by default. For more details on MAC configuration see the section below, Secret Key Configuration.

The algorithm

The solution is based on an algorithm that calculates a digest (or hash value) from a string of characters, the MAC base. When the digest algorithm is applied to the base string the output is a MAC for that specific base string. The MAC cannot be reverse engineered to produce the original string. By adding a secret key to the MAC base, the receiver can validate the MAC and thereby verify the sender's identity.

The choice of algorithm is up to the merchant. DIBS's system presently handles MD5 and SHA-1. MD5 is simpler and easier to implement, but SHA-1 provides stronger security. We strongly recommend using SHA-1.

A note about character set

DIBS uses the ISO-8859-1, or Latin 1, character set when a MAC is calculated. This means that any special characters (e.g. åäö) in the MAC base must always be encoded using ISO-8859-1. This is true for MACs sent to, as well as, from DIBS. The UTF-8 encoding is commonly used as well, but UTF-8 can not be used together with DIBS MAC feature.

Secret Key Configuration

The secret key used in the communication with DIBS is generated in DIBS Manager. Go to Security > DebiTech DefenderTM > MAC Configuration. Here you can generate keys and activate or deactivate the feature. The MAC feature is activated by default.

The MAC verification system can be configured in three different ways:

  • Not activated. When this setting is used no verification will be attempted. Note that if a MAC-parameter is sent, it will be ignored.
  • Active, MAC optional. When the mandatory setting is not checked the MAC-parameter is optional. If sent, it will be verified and if verification fails the purchase will not be processed. However, if the MAC-parameter is not sent there will be no verification and the purchase will be processed as usual. Note that this setting does not provide adequate security as a perpetrator might strip the MAC-parameter from the request and have a false request processed. This setting is intended to be used during setup and testing only.
  • Active, MAC Mandatory. When the mandatory setting is checked, all purchase calls to DIBS must contain a MAC-parameter, or the call will not be processed. This is the recommended production setting.

Copy the newly generated secret key from the browser window and save it in a secure location. The key should be accessible to as few people as possible. Please note that the secret key is never sent to DIBS, it is only used in the MAC calculation. DIBS already has a copy of the key, this copy will be used to verify the MAC.

To make changing keys seamless, two different keys may be active at the same time. In this way a new key can be generated and activated in Manager. Then the merchant can switch to the new key when convenient. When the switch is made, deactivate and delete the old key in Manager. Note that when two keys are active in Manager, the oldest of them is used when DIBS calculates return MACs. This key is also marked by a star in Manager. See ”Communication from DIBS to merchant” below for more information regarding return MACs.

Communication from merchant to DIBS

The MAC-parameter configuration consists of parameter data sent in from the merchant. A parameter is also referred to as a field. Its possible to choose which fields are sent and their
corresponding order in the actual calculation. The Secret key configuration can be found in the Manager under security.

The MAC-parameter configuration consist of the following two types of fields:

  1. Mandatory fields
  2. Optional fields

Mandatory fields are present in all mac configurations and can not be removed, neither can their order be changed. Mandatory fields must always be sent when using active mandatory mac check (see secret Key configuration in the previous section).

Optional fields are either Dibs fields like referenceNo etc. Or own custom parameters. The setup of optional parameters, meaning which fields and their respective order used for the actual calculation, can be edited in the Mac Configuration editor. The editor is described in detail later in this section.

Formula

The Mandatory default MAC is calculated by the merchant using the following formula:

SHA-1(data&currency&method&SecretKey&)

or

MD5(data&currency&method&SecretKey&)

Note how each parameter value is separated by ampersand (&).

Depending on what kind of key is active in DIBS Manager, use either SHA-1 or MD5. The actual parameters in the formula are described under input parameters

Calculation Example A

Let's assume that a secret key has been generated in Manager, the key type is SHA-1.

Secret key: 8CF47E1561ADAF8A07CFFF95099F823EDFADC18D

The other parameters used in the MAC base are the following mandatory fields:

data: 1:red bicycle:1:125000:

currency: SEK

method: cc.test

Using the formula SHA-1(data&currency&method&SecretKey&) the MAC base would be:

1:red bicycle:1:125000:&SEK&cc.test&8CF47E1561ADAF8A07CFFF95099F823EDFADC18D&

The resulting SHA-1 MAC would be: 2AE36D6C061772354DBDE5FD66531815B5913301

This MAC can then be sent to DIBS in a html form like this:

<input type=”hidden” name=”MAC” value=”2AE36D6C061772354DBDE5FD66531815B5913301”/>

Note that the MAC parameter name is case sensitive, but the mac value is not.

Communication from DIBS to merchant

Message Authentication Codes (MACs) can be used in all online communication from DIBS to the merchant; e-mail, http-reports and also in redirection URLs, see chapters 4.4 and 4.5 for more information regarding reports. In this way the merchant can verify that the information comes from DIBS and that it has not been tampered with in transit. The merchant's secret key will be used by DIBS to calculate a MAC much like in the above paragraph.

The formula used by DIBS to calculate the MAC is:

SHA-1(sum&currency&reply&id no&[referenceData&]SecretKey&)

or

MD5(sum&currency&reply&id no&[referenceData&]SecretKey&)

Note that the formula for return MACs is static and cannot be modified with custom parameters. Note also the referenceData placeholder in the formula. This is used if any of the following parameters are sent:

  1. referenceNo
  2. invoiceNo
  3. orderNo

ReferenceData should have the value of the most significant parameter in the list above. If for example both referenceNo and invoiceNo are used in the call, referenceData should be equal to referenceNo, and invoiceNo should not be included.

To use the return MAC in a report or page set use the DIBS tag [ver MAC]. This will be exchanged for ”MAC=X”, where X is the calculated MAC. The parameters used for the MAC base string can be retrieved using other DIBS tags, se http-report example:

http://YourURL/ReceivingPage?sum=[ver sum]&currency=[ver valueof="currency"]&reply=[ver reply]&verifyId=[ver id no]&referenceData=[ver valueof="referenceNo"]&[ver MAC]

This report contains all parameters needed to verify the MAC, and thereby ascertain whether the purchase was successful or not. Note how referenceData consists of referenceNo in this particular case above.

Calculation Example B

Continuing example A, the MAC base consists of the following data:

Sum: 1250,00

Currency: SEK

Reply: A

VerifyId: 13245678

ReferenceData: ABC123 (note information regarding this parameter above)

Secret key: 8CF47E1561ADAF8A07CFFF95099F823EDFADC18D

The MAC base would look like this:

1250,00&SEK&A&12345678&ABC123&8CF47E1561ADAF8A07CFFF95099F823EDFADC18D&

The resulting SHA-1 MAC is: 50C36481F1989EFC655A4C9AB7D8C1F80108B1E7

The http-report above would look like this:

http://YourURL/ReceivingPage?sum=1250,00&currency=SEK&reply=A&verifyId=12345678& referenceData=ABC123&MAC=50C36481F1989EFC655A4C9AB7D8C1F80108B1E7

The merchant can use the information from the report, in addition to the secret key, to calculate a MAC and compare it to the MAC sent from DIBS. If they are the same, no one has manipulated any of theparameters included in the MAC base. However, note that the calculated MAC is not case sensitive.

 

Do you have a question or need help?
Follow us
DIBS Payment Services
Stockholm +46 (0)8-527 525 00
Göteborg +46 031-600 800
København +45 7020 3077
Oslo +47 21 55 44 00