formsg-sdk 0.1.4

Python SDK for FormSG

Please note that this is an SDK for webhooks integration, and not the FormSG system.

FormSG Python3 SDK

This SDK provides convenient utilities for verifying FormSG webhooks and decrypting submissions in JavaScript and Node.js.

Installation

Install the package with

pip install formsg-sdk

Usage

Quickstart usage with Flask:

import os
import formsg
from flask import Flask, request

#get your FormSG's secret key from environment
FORM_SECRET_KEY = os.getenv('FORM_SECRET_KEY')

@app.route('/formsgtest',methods=['POST'])
def formsgtest():
    data = formsg.decrypt_responses(request, FORM_SECRET_KEY,securehttp=True)
    print(data)
	#display the decrypted data received
	
	#do your processing here
	
    return data

if __name__ == '__main__':
    app.run(debug=True)

Webhook Authentication and Decrypting form responses

End-to-end Encryption

FormSG uses end-to-end encryption with elliptic curve cryptography to protect submission data and ensure only intended recipients are able to view form submissions. As such, FormSG servers are unable to access the data.

The underlying cryptosystem is x25519-xsalsa20-poly1305. This codebase is the python implementation of the NaCl library. Official webhook SDK by the FormSG team only supports javascript.

Format of Submission Response

Key	Type	Description
formId	string	Unique form identifier.
submissionId	string	Unique response identifier, displayed as 'Response ID' to form respondents
encryptedContent	string	The encrypted submission in base64.
created	string	Creation timestamp.
attachmentDownloadUrls	Record<string, string>	(Optional) Records containing field IDs and URLs where encrypted uploaded attachments can be downloaded.

Format of Decrypted Submissions

decrypt_responses(request, formSecretKey, securehttp=True) takes in a http request, formsecretkey (b64 encoded) and returns a dictionary with the following structure

{
'data': 
    {
    'formId': str
    'submissionId': str
    'version': str
    'created': str
    'attachmentDownloadUrls': dict
    'decryptedContent': [   
                        {
                        '_id': str
                        'question': str
                        'answer': str
                        'fieldtype': str
                            },
                            {
                        '_id': str
                        'question': str
                        'answer': str
                        'fieldtype': str
                        },
                            ...
                        ]
    }
}

Signature verification

Under the hood, signatures are verified upon decryption, using steps found here - Verifying Signatures Manually

TODO

Attachment decryption.