formsg-python-sdk

This is the Python version of the Form Javascript SDK, which provides utility functions for verifying FormSG webhooks, as well as decrypting form submissions.

Note that this library is still in beta.

Requirements

Python 3.6+

Quickstart

pip install formsg-python-sdk

import formsg
# accepts STAGING or PRODUCTION, determines whether to use staging or production public signing keys
sdk = formsg.FormSdk("PRODUCTION")

# Your form's secret key downloaded from FormSG upon form creation
FORM_SECRET_KEY = "YOUR-SECRET-KEY"

# This is where your domain is hosted, and should match
# the URI supplied to FormSG in the form dashboard
YOUR_WEBHOOK_URI = "your-webhoook-uri"

# decryption without attachments
# if `verifiedContent` exists as a key in `encrypted_payload`, the return object will include a verified key
decrypted = sdk.crypto.decrypt(FORM_SECRET_KEY, encrypted_payload)

# webhook authentication
HEADER_RESP = "req.header.'x-formsg-signature'"
sdk.webhooks.authenticate(header=HEADER_RESP, uri=YOUR_WEBHOOK_URI)

# decryption with attachments
decrypted_with_attachments = sdk.crypto.decrypt_attachments(FORM_SECRET_KEY, encrypted_payload)

Refer to the example app if you're running a flask server.

End-to-end Encryption

Format of Submission Response

Format of Decrypted Submissions

crypto.decrypt(form_secret_key: str, decrypt_params: DecryptParams) takes in decrypt_params as the second argument, and returns an an object with the shape

{
  responses: FormField[]
  verified?: NotRequired[Mapping[str, Any]]
}

The decryptParams.encryptedContent field decrypts into a list of FormField objects, which will be assigned to the responses key of the returned object.

Furthermore, if decryptParams.verifiedContent exists, the function will decrypt and open the signed decrypted content with the package's own signingPublicKey in constants.py. The resulting decrypted verifiedContent will be assigned to the verified key of the returned object.

NOTE
If any errors occur, either from the failure to decrypt either encryptedContent or verifiedContent, or the failure to authenticate the decrypted signed message in verifiedContent, None will be returned.

Note that due to end-to-end encryption, FormSG servers are unable to verify the data format.

However, the decrypt function exposed by this library validates the decrypted content and will return None if the decrypted content does not fit the schema displayed below.

The full schema can be viewed in validate.ts.

If the decrypted content is the correct shape, then:

1. the decrypted content (from decryptParams.encryptedContent) will be set as the value of the responses key.
2. if decryptParams.verifiedContent exists, then an attempt to decrypted the verified content will be called, and the result set as the value of verified key. There is no shape validation for the decrypted verified content. If the verification fails, None is returned, even if decryptParams.encryptedContent was successfully decrypted.