Add cryptographic functions to SDK

README.md

@@ -2,7 +2,7 @@
 
 # FormSG Javascript SDK
 
-This SDK provides convenient utilities for verifying FormSG webhooks for applications written in JavaScript.
+This SDK provides convenient utilities for verifying FormSG webhooks and decrypting submissions in JavaScript and Node.js.
 
 ## Installation
 
@@ -12,11 +12,21 @@ Install the package with
 npm install @opengovsg/formsg-sdk --save
 ```
 
-## Usage
+## Configuration
+
+```javascript
+const formsg = require('@opengovsg/formsg')({
+  mode: 'production',
+})
+```
 
-### Webhook authentication
+| Option | Default      | Description                                                     |
+|--------|--------------|-----------------------------------------------------------------|
+| mode   | 'production' | Set to 'staging' if integrating against FormSG staging servers. |
 
-Protect your webhook endpoint with the FormSG SDK.
+## Usage
+
+### Webhook Authentication and Decrypting Submissions
 
 ```javascript
 // This example uses Express to receive webhooks
@@ -25,36 +35,68 @@ const app = require('express')()
 const formsg = require('@opengovsg/formsg')()
 
 // This is where your domain is hosted, and should match
-// the URI supplied in the FormSG form dashboard
+// the URI supplied to FormSGin the form dashboard
 const POST_URI = 'https://my-domain.com/submissions'
 
-app.post('/submissions', function(req, res, next) {
-  try {
-    formsg.webhooks.authenticate(req.headers['X-FormSG-Signature'], POST_URI)
-    // Continue processing the POST body
-    return next()
-  } catch (e) {
-    console.error(e)
-    return res.status(401).send({ message: 'Unauthorized' })
+// Your form's secret key downloaded from FormSG upon form creation
+const formSecretKey = process.env.FORM_SECRET_KEY
+
+app.post('/submissions',
+  // Endpoint authentication by verifying signatures
+  function (req, res, next) {
+    try {
+      formsg.webhooks.authenticate(req.headers['X-FormSG-Signature'], POST_URI)
+      // Continue processing the POST body
+      return next()
+    } catch (e) {
+      return res.status(401).send({ message: 'Unauthorized' })
+    }
+  },
+  // Decrypt the submission
+  function (req, res, next) {
+    const submission = formsg.crypto.decrypt(formSecretKey, req.body)
+    if (submission) {
+      // Continue processing the submission
+    } else {
+      // Could not decrypt the submission
+    }
   }
-})
+)
 
 app.listen(8080, () => console.log('Running on port 8080')
 ```
 
-## Configuration
+## End-to-end Encryption
 
-```javascript
-const formsg = require('@opengovsg/formsg')({
-  mode: 'staging',
-})
-```
+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.
 
-| Option | Default      | Description                                                     |
-|--------|--------------|-----------------------------------------------------------------|
-| mode   | 'production' | Set to 'staging' if integrating against FormSG staging servers. |
+The underlying cryptosystem is `x25519-xsalsa20-poly1305` which is implemented by the [tweetnacl-js](https://github.com/dchest/tweetnacl-js) library. Its source code has been [audited](https://cure53.de/tweetnacl.pdf)) by [Cure53](https://cure53.de/).
+
+### Format of Submission Response
+
+| Key              | Type   | Description                         |
+|------------------|--------|-------------------------------------|
+| formId           | string | Unique form identifier.             |
+| submissionId     | string | Unique submission identifier.       |
+| encryptedContent | string | The encrypted submission in base64. |
+| created          | string | Creation timestamp.                 |
+
+### Format of Decrypted Submissions
+
+The `encryptedContent` field decrypts into an array of objects, with each element representing a question-answer pair.
+
+Note that due to end-to-end encryption, FormSG servers are unable to verify the data format.
+
+Developers **must** program defensively to ensure that the fields are indeed accessible.
+
+| Key       | Type   | Description                                                                                                     |
+|-----------|--------|-----------------------------------------------------------------------------------------------------------------|
+| question  | string | The question listed on the form                                                                                 |
+| answer    | string | The submitter's answer to the question on form.                                                                 |
+| fieldType | string | The type of field for the question.                                                                             |
+| _id       | string | A unique identifier of the form field. WARNING: Changes when new fields are created/removed in the form.        |
 
-## Verifying signatures manually
+## Verifying Signatures Manually
 
 You can use the following information to create a custom solution, although we recommend using this SDK.
 
@@ -110,7 +152,7 @@ Verify that the `v1` signature is valid using a library of your choice (we use [
 If the signature is valid, compute the difference between the current timestamp and the received epoch,
 and decide if the difference is within your tolerance. We use a tolerance of 5 minutes.
 
-#### Additional checks that you may undertake
+#### Additional Checks
 
 - Check that request is for an expected form by verifying the form ID
 - Check that the submission ID is new, and that your system has not received it before

index.js

@@ -1,4 +1,5 @@
-const webhooks = require('./src/webhooks.js')
+const webhooks = require('./src/webhooks')
+const crypto = require('./src/crypto')
 
 /**
  * Entrypoint into the FormSG SDK
@@ -12,6 +13,7 @@ module.exports = function ({
   webhookSecretKey,
 } = {}) {
     return {
-      webhooks: webhooks({ mode, webhookSecretKey })
+      webhooks: webhooks({ mode, webhookSecretKey }),
+      crypto: crypto(),
     }
 }

package.json

@@ -18,6 +18,7 @@
     "tweetnacl-util": "^0.15.1"
   },
   "devDependencies": {
-    "jasmine": "^3.5.0"
+    "jasmine": "^3.5.0",
+    "lodash": "^4.17.15"
   }
 }

spec/crypto.spec.js

@@ -0,0 +1,53 @@
+const _ = require('lodash')
+
+const formsg = require('../index')()
+
+const {
+  plaintext,
+  ciphertext,
+  formSecretKey,
+  formPublicKey,
+} = require('./resources/crypto-data-20200322')
+
+describe('Crypto', function () {
+
+  it('should generate a keypair', () => {
+    const keypair = formsg.crypto.generate()
+    expect(Object.keys(keypair)).toContain('secretKey')
+    expect(Object.keys(keypair)).toContain('publicKey')
+  })
+
+  it('should generate a keypair that is valid', () => {
+    const { publicKey, secretKey } = formsg.crypto.generate()
+    expect(formsg.crypto.valid(publicKey, secretKey)).toBe(true)
+  })
+
+  it('should validate an existing keypair', () => {
+    expect(formsg.crypto.valid(formPublicKey, formSecretKey)).toBe(true)
+  })
+
+  it('should invalidate unassociated keypairs', () => {
+    const { secretKey } = formsg.crypto.generate()
+    const { publicKey } = formsg.crypto.generate()
+    expect(formsg.crypto.valid(
+      publicKey,
+      secretKey,
+    )).toBe(false)
+  })
+
+  it('should decrypt the submission ciphertext from 2020-03-22 successfully', () => {
+    const decryptedPlaintext = formsg.crypto.decrypt(formSecretKey, ciphertext)
+    expect(_.isEqual(decryptedPlaintext, plaintext)).toBe(true)
+  })
+
+  it('should return null on unsuccessful decryption', () => {
+    expect(formsg.crypto.decrypt('random', ciphertext)).toBe(null)
+  })
+
+  it('should be able to encrypt and decrypt submissions from 2020-03-22 end-to-end successfully', () => {
+    const { publicKey, secretKey } = formsg.crypto.generate()
+    const ciphertext = formsg.crypto.encrypt(publicKey, plaintext)
+    const decrypted = formsg.crypto.decrypt(secretKey, ciphertext)
+    expect(_.isEqual(decrypted, plaintext)).toBe(true)
+  })
+})

spec/resources/crypto-data-20200322.js

@@ -0,0 +1,97 @@
+/**
+ * DO NOT MODIFY THE DATA BELOW.
+ * 
+ * The below data represents a submission from 2020-03-22.
+ * It must remain unmodified to maintain strict backwards compatibility.
+ * 
+ * If changes are necessary, create new test data instead.
+ */
+
+const plaintext = [{
+  "_id": "5e7479c786eaf2002488a211",
+  "question": "Header",
+  "fieldType": "section",
+  "isHeader": true,
+  "answer": ""
+}, {
+  "_id": "5e7479a086eaf2002488a20e",
+  "question": "Email",
+  "fieldType": "email",
+  "answer": "[email protected]"
+}, {
+  "_id": "5e771c246b3c5100240368d8",
+  "question": "Mobile Number",
+  "fieldType": "mobile",
+  "answer": "+6598765432"
+}, {
+  "_id": "5e7479a386eaf2002488a20f",
+  "question": "Number",
+  "fieldType": "number",
+  "answer": "123"
+}, {
+  "_id": "5e771c346b3c5100240368da",
+  "question": "Decimal",
+  "fieldType": "decimal",
+  "answer": "0.123"
+}, {
+  "_id": "5e771c516b3c5100240368dc",
+  "question": "Short Text",
+  "fieldType": "textfield",
+  "answer": "Test"
+}, {
+  "_id": "5e771c596b3c5100240368dd",
+  "question": "Long Text",
+  "fieldType": "textarea",
+  "answer": "Long\nText"
+}, {
+  "_id": "5e771c626b3c5100240368de",
+  "question": "Dropdown",
+  "fieldType": "dropdown",
+  "answer": "Option 1"
+}, {
+  "_id": "5e771c666b3c5100240368df",
+  "question": "Yes/No",
+  "fieldType": "yes_no",
+  "answer": "Yes"
+}, {
+  "_id": "5e771c7a6b3c5100240368e0",
+  "question": "Checkbox",
+  "fieldType": "checkbox",
+  "answerArray": ["Option 2"]
+}, {
+  "_id": "5e771c8a6b3c5100240368e1",
+  "question": "Radio",
+  "fieldType": "radiobutton",
+  "answer": "Option 1"
+}, {
+  "_id": "5e771c8d6b3c5100240368e2",
+  "question": "Date",
+  "fieldType": "date",
+  "answer": "22 Mar 2020"
+}, {
+  "_id": "5e771c906b3c5100240368e3",
+  "question": "Rating",
+  "fieldType": "rating",
+  "answer": "5"
+}, {
+  "_id": "5e771c946b3c5100240368e4",
+  "question": "NRIC",
+  "fieldType": "nric",
+  "answer": "S9912345A"
+}]
+
+const ciphertext = 'RqOjwNXwiVJqvdTrQeD/NiktpI8vzo6CXlBBNihmmwI=;+0cGJwOA42F7DmQO7Kr6tNn9YH/7poDe:2jpehB9uW+63G1EimxOs1tsfR54xxSVZQbFMQaCa8ovVoF/6isBCEl5WLmrE1CRa2c5L2G5rAgCUnhsxQ7jVa//XEKr/m9kGNMbPnVqH62RslAxh30Mzz2he/ssbMazLDBzgQwd8I+pHnrBHQW5BsLqclj7QAMX3fa10Zon0ih4irWQ1o9eYitFllitD+vIcwbBzJyigGvD/t14+2/5imZmJdmJTJXd1ySxDo1X6KjBmph4rzvWtZSUgF7rRfMtAmbyOj87i6CkkNNIN4Dtl3zEuSeLuU2IDF7IHDdAwpmgWM9ejFpwrMFfr8PRovCubuRxCDQ1hV6GOyh60SlKA3oHQMhRQ2yia2vr9yxzHgO+wVUfgoiXQn8tvXFwZmzZd/eWENC1QI+XvP1jt50RIhQ0kMbyhBiaAG9nYlhGO3UHtmGGBoOdW4l4DZaWKRItnw1qgb2oxCvxOIkWNoafq1qJbYJsldOy6a/I2lbwAPL7MzVfgHJDj11dLOBgHGZHia6ZaROXYEiFpkVP8APOO/tgV902nOOlt+w63QNIieCIoGphn9LvOTo6Y6HD8qH6sekEyXCds6jP4RVw5XIN9LGeOWlEKx/VR2rf8b9qzFcYRPzfH5M8I9rpuZkk72ANiTeLRM8C8zWFnitzDlh1B2M+jnjrg+jEYm0ugro7tvHYSmU4tKcGR3mPlDrROjtFf3eBO8+pZKzuQfdA/7kN5YekAzyNjLcixioycrDmjR+BbBKxVrwNlm0hmHLLdU1g42GYpmfUUythDnqwALAOtaZcuj1ObX50h6kmhIl4fAEcXdLKKpoASzafbHnIH0iNX1CefnflLxymDPjjTFqcGSpY1vZf2pxDxUNZPXsd3vbV4KbrYq9v/R5NJ+mW3lxm839aN0pNsMbMetyZTyX8tXofWERxKEZDDXRCoYS0Ijml5h0X58juM13hNtc48iuPyx8oBIy4WophJ+M4CJfsq1wfBK0q+a8P2Tj8odJRQbbFdCoQRRRKbFhk0nT/R3V23cRjMB/Z1DCFmo8ywhUfSlMhrs8f6f3myhmJpzP5MXPJgzRIAytYtUF34j+9fspaYtyQHg4j4f8OBIYrNOCgt6++1bmy0+aI3Y0DoBJ1eLfe9iHUt64cvPbPqmAxX8Jkb1kY+OVwjx7DTxFc5dCzkL/3VA1FAZe7IqfP0v/3fTT6oK7nuy951GUSU9sBynV8Z6zJecYUWbgFZ1u/K8ag6btR2IeRFz7dG+Ffkb8nsGTcNm0l54Q/XbudtfIPN2GTGp1PlgFZ5JERszVrQ8MIrMnHtPvnbtIlqdVzZ0KwR1YQnqtjCoNnI/TzniRZnydE/qJCc5ZwAQDJhl0XRmVes5sp4obxhreSdgGjoyybeFN70rb6uMvsuBlTS5Z6xg7q4eW0e8Xx0PlKYJi8eUsFtzQlN3iJzgFTeLGOlguK2GWnI/Myy5/nan2Np5+eZ2GZhdn6s/NYmiJGLlcbmcXRLOj53O1Z9Oornc+Hq5rz+eZKg4uYNbyFCbvJ9d/wNbRaQva9kETeEfGVosZXotnA2dxYRF4A24Qwjo+yNeRlbyQBf0V0BWY+rfJ+F2JMP4LZ5FNVhd5JI16z7PEgqvlGqm7zkfPmwlTjCzDFXYz749fz9hrzqOCALguEhmMYEsun8mK7IptW77qbKyx2jTu/2OC6pqdWhHB3PliKZXD5EgedpqzHcWQg/s9TloSXy9pE9PEs0j+el+j4yXyQcfrAjODWHSrUXNWSJc1rOM1ochIYJWYHn4pf2Jxuop90+c4DFYp5eih3k8BGy4Etp6L0N7PJ+ugSqZV8L0QYT2sLBwG2cS8FNUGJPoUkUn6R2Bg7bTQ=='
+
+const formSecretKey = 'H7B0nKJ+E7+naSkQApxGayz1y/lZe4thta4iPp1B+Ns='
+const formPublicKey = 'NKHcx/SuUfBxhXe20yoVTCsDwQTSfrd5MMClCOrd/js='
+const submissionSecretKey = '9h1ys0ZpcPD9pBShwtE4YKXv8882ldjd9sF51YS3Fks='
+const submissionPublicKey = 'RqOjwNXwiVJqvdTrQeD/NiktpI8vzo6CXlBBNihmmwI='
+
+module.exports = {
+  plaintext,
+  ciphertext,
+  formSecretKey,
+  formPublicKey,
+  submissionSecretKey,
+  submissionPublicKey,
+}