Encrypting Forms

Last updated: 3 May 2024

This procedure is quite technical and is intended for users who are comfortable with advanced technical instructions and requires strict attention to detail.

Encrypted forms work by encrypting the data on the phone the moment it is saved. Data sent to KoboToolbox is encrypted and completely inaccessible to anyone not possessing the private key. In this case, KoboToolbox serves simply as a storage locker for your encrypted files - a place to upload and then download for later for local decryption (using ODK Briefcase). Since the form submissions are encrypted, it means, however, anything that requires access to the data like the map view or data export won’t work within KoboToolbox. The extra level of security makes using KoboToolbox in a way to collect sensitive data while meeting certain data protection protocols possible.

How it Works

KoboCollect supports the ability to encrypt the content of a form the moment it is marked as completed and ready for submission on the phone. To take advantage of this requires the use of a public encryption key which you include in the XLSForm and a private key (which you never share) that is used by ODK Briefcase to decrypt the data locally after you’ve downloaded it from KoboToolbox. The public key is used to encrypt data while the private key decrypts it. Only a person who has the private key, can decrypt the data encrypted with the public key. To understand more about public and private key infrastructure see here.

How to encrypt XLS forms

  1. Create your form in KoboToolbox as always. Download the form from the drafts list as an XLS file.

  2. In the downloaded file go to the ‘settings’ sheet.

  3. Add a column submission_url and type https://kc.kobotoolbox.org/submission or https://kc-eu.kobotoolbox.org/submission (depending upon the server you are using).

  4. Add another column public_key (i.e. base64RsaPublicKey). Paste your compatible public key.

    (Please see image below for reference)

    image

  5. Upload the XLS file back to KoboToolbox. You can either import it back to the Form Drafts list and then deploy it as a new survey project, or import it directly to your deployed Projects list. Once deployed you should see a label with the text “encrypted” next to your form name.

Please note that the URL for an authenticated user no longer includes **yourusername** per recent updates.

How to decrypt forms

ODK Briefcase is used to download the encrypted files from KoboToolbox and decrypt them locally on your computer using a private key ensuring single access to the data. For decryption to be successful with ODK Briefcase make sure you download and install the Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files 6 from the Java download site. This is required for decryption to be successful.

To install the JCE:

  1. Unzip the downloaded zip archive

  2. Navigate into the extracted directory tree and copy the local_policy.jar and US_export_policy.jarfiles to the lib\security directory

  3. Paste these files inside the installation directory of the Java Runtime Enviornment (JRE) of your computer, replacing earlier versions of these files.

    • On Windows, the JRE is usually installed here: C:\Program Files\Java\jre7\lib\security

    • On OSX the location is /Library/Internet Plug-Ins/JavaAppletPlugin.plugin/Contents/Home/lib/security

To decrypt your forms:

  1. Download and open ODK Briefcase.

  2. Specify a Storage Location under the Settings tab.

  3. Open the Pull tab and click Configure.
    image

  4. Then enter the following:

    • https://kc.kobotoolbox.org OR https://kc-eu.kobotoolbox.org(depending on which server you use)

    • Your username

    • Your password

    • Press Connect when done
      image

Please note that the server URLs above no longer need to include **yourusername** per recent updates.

  1. A list of projects is displayed. Select a project that you wish to pull and press Pull. You will receive a message Success under the Pull Status.

  2. Now go to Export tab.

  3. Press the Edit Default Configuration to ensure that you have the PEM private key at the PEM file location.
    image
    If it’s not there, select the PEM private key from the folder you had secured safely. (Note: You will also see all the projects here that has been successfully pulled.)

  4. Now check the project that you would wish to export and press Export.

  5. Data is exported as a CSV file, you can now view the unencrypted data.

Generating RSA Encryption Keys

To generate the RSA public-private key pairs you can use the OpenSSL software package, which is pre-installed on OSX and Linux. On Windows you have to download and install the OpenSSL software package from this site. (Note: install the Win64 OpenSSL v1.1.1c in C: rather than the default location C:\Program Files)

How to generate RSA key for use with encrypted forms on KoboToolbox

Note: We strongly recommend using OpenSSL as documented below for creating your public/private key pair as other methods may not be supported by the software.

  1. Open a Windows ‘cmd’ window.

  2. Type the following command: cd C:\OpenSSL-Win32\bin to change to the /bin directory in the OpenSSL directory.

    image

  3. Create a 2048-bit private key and write it to the MyPrivateKey.pem file by typing the following command, then press Enter: openssl genpkey -out MyPrivateKey.pem -outform PEM -algorithm RSA -pkeyopt rsa_keygen_bits:2048

    image

  4. Then, extract the public key for the above private key. Type the following command then press Enter: openssl rsa -in MyPrivateKey.pem -inform PEM -out MyPublicKey.pem -outform PEM -pubout

    image

  5. You have now generated two files that is:

    • MyPrivateKey.pem - your private key that you need to move to a secure location.

    • MyPublicKey.pem - your public key, that you can share with anyone you want to share information securely

  6. Open the MyPublicKey.pem with Notepad or another text edit, your public key is the uninterrupted very long string of characters,

e.g.:Tjhfur1K9+BRQ2USezIPbtyahbfuNqviI5Suhm8maA3JoELRHj9psjf/oNWoG87aFtKNbLrRaCEDP oFMDC9NEzWlv5L49BygeieMu/wg/rtMT0M0kgDbKxw5weJJgyb9P41aMsrqAAAAB3NzaC1yc2EAAAADAQAB AAABAQDfNoFX7bh3bfdW6lGfDht1Ea8PUBLKYjugbHN5jS7j5fHV6dexM+kzvITVgoyjhhKPXeCbaT62vD/ saTqJFXJzlysnZ24fqxNkjreO5K5EQ9c3ggwqML06+AKrFUSP5jpnyJJH8btNwKl6D5pG4ZseHwDUKzZtae xtPTNQz67kdYIKdtCkCsQHVsy4xvy/A0jzfK3xyOkG6j+L

This string is what you will need to paste under the public_key field in your settings sheet on your XLS file.

IMPORTANT: make sure that you paste only the public key string and no blank spaces or line breaks!

MyPrivateKey.pem is the file you will use when exporting the submissions using ODK Briefcase.

Note: When trying to edit a form that has been encrypted, you receive a message “This form cannot be edited once it has been marked as finalized. It may by encrypted”.