iFormBuilder Data

What's covered:

• What is a Digital Signature?
• Why is Digital Signature important?
• How does a digital signature work?
• How do I verify data that has a digital signature?
• What should I do if the verification fails?
• How do I add a digital signature to my form data?
• Examples

What is a digital signature?

Digital Signature is a signing mechanism used on our HTTP Post Endpoints in iFormBuilder. When data is sent from our system to the endpoint the receiver can validate the data being processed is in fact from the correct source, and not an imposter.

Why is Digital Signature important?

• Ensures data integrity: Without a digital signature, data from an unauthorized source could be sent into the 3rd party system resulting in fraudulent information influencing decisions.
• Security: The use of digital signatures reduces risks of documents being altered while in transit.
• Accepted Globally: With digital signature being a global standard you can be sure our Data Delivery is compatible with any systems that follow this standard.
• Imposter prevention: No one can forge your digital signature or submit data falsely claiming it was signed by you.

How does a digital signature work?

When you configure a post endpoint you have the option to create a signature for each request. 

Each time a post request is sent to the webhook, the raw data and the selected algorithm will be used to create a hash of the data. The hashed data will be with the private key that has been supplied to generate the signature.

The signature is sent across as an extra header in the request call Hook-Signature and will look like the example below.

RHgSpGda+xvZy7ocBhE09ChQYNisCrB1pruV5dQ3DmP6VvOkJZZ2mWvLBBMxfycR+ORXzhLvjDZ0XgzQvy6WeGeSEjkpg46HmfenCqm2hoZhpOIqbL2Hw9AGVP6+sn2iQPrbcjGi9P8gfH4FMwbyRH2uCk7327ZBA9ZmYklkG4ZlgJ8dVINk1jISm2Q55Kyh5pTv01eqBYzsQGNZ1w14imHfYflUHWx207+FewTKlvrRtSe4sD9Q1WgvsQGD/dIyCD/XzOEiLQ4VnlYv1hV2nP+cP10v3gZR6z6VV+eDld/s9v+RaJfrF6l/fHAIVFLSYXgDuvDbnFNDDXICVzKkEg==

In addition to the signature, we send one additional header Hook-Algorithm that will carry one of the following values.

RSA signatures

• RS512
• RS384
• RS256
• RS224

Hash signatures

• HS512
• HS384
• HS256
• HS224

How do I verify the data? 

In order to verify the data, you must have the matching public key when using RSA signatures, or the same private key uploaded to the post data setting when using HS signatures. We highly recommend using RS512 if the receiver can support it.

RS

To verify a signature using the RS algorithm you will take the raw data that is sent over in the body of the post request and hash it using the (Hook-Algorithm) header. Pass the hashed data into a verification function that will leverage the signature, public key, and algorithm to verify the signature.

An example of how to do this in PHP can be found below.

// Verify the signature

openssl_verify($dataHash,$validatedSignature,$public_key_pem,$hashAlg);

HS

To verify a signature using the RS algorithm you will take the raw data that is sent over in the body of the post request and create a key and hash it using the (Hook-Algorithm) header.

An example of how to do this in PHP can be found below.

//Create a keyed hash of the data

$rawSignature = hash_hmac($hashAlg,$data,$private_key_pem,true);

Once you have created the signature, we need to base64 encode the result before comparing the generated signature to the one received in the header of the post request.

//Encode the signature just like the sender

$verifySignature = base64_encode($rawSignature);

After the signature has been encoded, you will do a string comparison to see if the signature that was generated matches the signature that was received in the request.

What should I do if the verification fails?

If verification of the signature fails, you should discard the data and throw an error back to the sender. Processing the data is risky as it may have been manipulated by a man in the middle attack, or could have come from an unknown source.

How do I add a digital signature to my form data?

To add a digital signature to your data, please follow the instructions below.

STEP 1. From the admin portal, hover over the Forms tab and select Form Builder. If you have the new mega menu, go to Forms and then select Form Builder.

STEP 2. There are two ways of accessing the new Post Data Endpoint interface.

Search for the form you want to add a post data endpoint to and click on the post data endpoint icon as seen below.

You can also get to the post data endpoint interface by going inside of a form and clicking the post data endpoint icon on the top right.

STEP 3. Create a new endpoint or edit an existing endpoint.

STEP 4. From the Secure Signature drop-down, select which type of signature you wish to use. 

STEP 5. Upload your private key.

A preview of the key will appear in the box below, like this:

STEP 6. Click Save when you are done.

Examples

If you're looking for some examples of Public Keys, Private Keys and Signature Validation code, our resident "Yoda", Tony Ruth, has put together some for you in this GitHub post. Have a look!