Global

We've detected that you're in . Would you like to go to the PicSafe site?

Integrations

PicSafe provides a Software Development Kit (SDK) and various API's to help institutions efficiently integrate PicSafe into their workflow.


PicSafe has been built to enable easy integration with various third party storage services and individual institutions' medical record systems.

Please be warned. This section has been designed for those with a solid understanding of technology. It's going to get technical!

1. Methods of Sending/Submitting Reports

The intimidating and confusing (at first look) diagram below shows that there are seven types of integrations. Each will be discussed further below. This might not make sense now, but hopefully, this page clears up any questions you have!

  1. Upload to Box (teal lines)
  2. Upload to Dropbox (royal blue lines)
  3. Email to Recipient (grey and pink lines)
  4. Email to Medical Record (grey and light blue lines)
  5. Upload to Medical Record (green lines)
  6. Upload to Medical Record (with Dynamic Key Encryption) (grey and yellow lines)
  7. Upload to Medical Record (with Static Key Encryption) (grey and purple lines)

Please note, the numbers next to the "methods" above do not correspond to the numbers in the diagram below. Use the colours above and match them to the diagram below (the grey lines are used by multiple sending methods).

Send options

Which method is best for me?

Please note this is just a guide. There are many more factors that might lead to a different method being suitable for your purpose.

1.1 Upload to Box

PicSafe PRO enables you to capture photos, video and audio and upload reports to Box. This means that you can use this PicSafe to keep an archive of patient media. This is particularly useful for areas of medicine where it is appropriate to store and track pictorial changes over time.

Upload to Box

Setup

To setup sending to Box, tap on the "Settings" button (on the primary form), then tap the "Box" row under the "Integrations" heading. Then tap on the "Log in to Box" button. You will be guided through the process to log in to Box.

Setup Box

Sending

To send to Box, on the primary form just above the "Submit" button is a "send to" field. Tap on that and select "Box". Upon submitting, the app will upload the report to your Box account (follow the teal line in the diagram at the top of the page).

Note, a "PicSafe" directory will be created in your Box account, and all reports will be uploaded here.

Security

Box, in conjunction with PicSafe, can be used to help you comply with HIPAA and HITECH.

All reports are uploaded over HTTPS. We do not encrypt reports using the key server when submitting to Box as it is assumed that Box stores all reports securely. Please see the Box HIPAA And HITECH Overview And FAQs for more information.

1.2. Upload to Dropbox

PicSafe PRO enables you to capture photos, video and audio and upload reports to Dropbox. This means that you can use this PicSafe to keep an archive of patient media. This is particularly useful for areas of medicine where it is appropriate to store and track pictorial changes over time.

Upload to Dropbox

Setup

To setup sending to Dropbox, tap on the "Settings" button (on the primary form), then tap the "Dropbox" row under the "Integrations" heading. Then tap on the "Log in to Dropbox" button. You will be guided through logging in to Dropbox.

Setup Dropbox

Sending

To send to Dropbox, on the primary form just above the "Submit" button is a "send to" field. Tap on that and select "Dropbox". Upon submitting the app will upload the report to your Dropbox account (follow the royal blue line in the diagram at the top of the page).

Note, an "Apps/PicSafe" directory will be created in your Dropbox account, and all reports will be uploaded here.

Security

Dropbox, in conjunction with PicSafe, can be used to help you comply with HIPAA and HITECH.

All reports are uploaded over HTTPS. We do not encrypt reports using the key server when submitting to Dropbox as it is assumed that Dropbox stores all reports securely. Please see Dropbox's Help Center article for more information.

1.3 Email to Recipient

Technically this not really an "integration" as sending reports via email is part of the core functionality of PicSafe. To be comprehensive, we have, nonetheless, included discussion here.

Email to Recipient

Setup

There is only one requirement - ensure that email is configured on your device. The vast majority of people will set this up when they first setup their device. If you don't have email setup, you will be notified when trying to send.

In iOS email can be setup in "Settings" > "Main, Contacts, Calendars".

On Android, open your device's email application, tap "Menu", and tap "Accounts".

Sending

The following occurs. (Note: the numbers correspond to each number in the lines in the diagram above.)

  1. When a users signs in/up, the User Server will return a User Token. The User Token is a hashed and signed version of the user data. It is used later for verifying user requests.
  2. The app sends a request with the user's details in the User Token and a Report ID to the Key Server. The Key Server will verify that the user details are valid (this ensures that request has come from a trusted source). The Key Server responds with a Key that is used by the app for the report encryption later in the process. By default, the app will use a Key Server run by PicSafe. Should you want your institution to restrict recipients to be only staff members of their institution, this can be achieved by running a private key server.
  3. A bit happens here!
    • The app generates a Metadata File (metadata.json), and a PDF document (report.pdf).
    • The app then packages these two files along with the media and relevant thumbnails into a zipped file (package.zip).
    • Using the Key (fetched from the Key Server above), the app then encrypts the package.zip file to create an encrypted file (package.encrypted).
    • The app then generates a package file (package.json) which contains the URL of the Key Server (so when it comes time to decrypt the report the app will know where to get the key from).
    • The app then zips the package.json file with the package.encrypted file and creates a PicSafe File ({reportID}.picsafe).
    • The app opens the device's default email client to compose a new email and attaches the PicSafe File. The email is pre-populated with instructions as to how to open the PicSafe File.
    The user can pick a recipient out of their devices built in address book and send.
  4. The recipient receives an email with a PicSafe file attached to it. It includes instructions as to how to open it. Assuming the recipient has never used PicSafe before...
    • They are instructed to download the app from the App Store or Google Play.
    • The user signs up for a PicSafe account (free).
    • Their email address is validated, and their details are stored in the User Server.
    • The User Server will return a User Token.
    Now the recipient has the app installed, if they tap on the PicSafe File in the email, they will be prompted to open the file in the PicSafe app.
  5. For the app to display the report the following occurs:
    • The app opens up and unzips the PicSafe file ({reportID}.picsafe). This exposes the package.json file and the package.encrypted file.
    • The app extracts the URL of the Key Server that was used to produce the Key used to encrypt the package.encrypted file.
    • The app sends a request off to the Key Server with the recipient’s User Token and asks for the Key.
    • The Key Server logs the request and thereby produces an audit trail of who has accessed the report.
    • The Key Server responds with the Key used to decrypt the package.encrypted file.
    • The app decrypts the package.encrypted file and unzips it.
    The recipient can now see the report deals and media in the app. They can also view (and if necessary, print out) a PDF report.

Security

Here we have securely captured patient data and media, recorded consent and transmitted it securely to a recipient. Because all patient and user data is strongly encrypted (in the attached PicSafe file), we can share this file through email. If someone were sniffing traffic (i.e. they intercepted the email), the file will be meaningless gobbledygook! The only way they could do anything with it is by creating a PicSafe account and thereby leaving an audit trail as to who they are. Should you want your institution to restrict recipients to be only staff members of their institution, this can be achieved by running a private key server.

If we take the analogy of a doctor sending a confidential "paper" report through the post to another doctor, there is an implicit understanding and ethical obligation that the recipient will not in turn act inappropriately with that data (e.g. share it on Facebook). PicSafe relies on the same implicit understanding and ethical obligation when giving the recipient the ability to view and print out a PDF report.

PicSafe uses RNCryptor for encrypting reports. RNCryptor is a cross-language AES Encrypter/Decrypter data format. The data format includes all the metadata required to securely implement AES encryption, as described in "Properly encrypting with AES with CommonCrypto," and iOS 6 Programming Pushing the Limits, Chapter 15. Specifically, it includes:

  • AES-256 encryption
  • CBC mode
  • Password stretching with PBKDF2
  • Password salting
  • Random IV
  • Encrypt-then-hash HMAC

This format was used because it is widely supported. This makes it easier for institutions to integrate PicSafe into their medical record systems. There are implementations of RNCryptor in Swift, Objective-C, C, C++, C#, Erlang, Go, Haskell, Java, PHP, Python, Javascript, and Ruby.

1.4 Email to Medical Record

Health institutions often have very restrictive firewalls and data passing in and out of the network is often blocked (understandably so). This often means IT departments are reluctant to open the firewall up to allow third party services such as PicSafe through. Email, however, is an almost universal protocol that is allowed through all firewalls given its ubiquitous nature. Hence, we provide the option of sending email reports directly from a users device to an institution assigned email account.

Email to Medical Record

Institution Setup

To get PicSafe reports into the patient medical record via email a few things need to be set up first.

  • You should set up an email address for the express purpose of receiving PicSafe reports (e.g. [email protected]). This is where all emailed reports will be sent initially.
  • You will have to build an Endpoint Server. This is essentially some middleware that reads the mailbox for new email, extracts the attached reports, decrypts them, parses the data and inserts into the medical record system. More detail on this is provided in the Running a private Endpoint server section below.

User Setup

Users within your institution should be instructed to set up an "Institution" within the PicSafe app on their device(s). To do this, they have to do the following:

  • Open the PicSafe app and tap on "Settings".
  • Tap on "Institutions Medical Record" and then the "Add" button in the top right.
  • In "Send type" select "Email", enter the name of your institution (e.g. "My Hospital"), enter the specified email address in the "Endpoint" field, and in the "Key Server" field enter the URL of your Key Server if you have one (otherwise leave it blank).
  • Tap the "Save" button in the top right and go back to the primary form.
  • Now in the primary form, in the "Send to" options there will be a "My Hospital" listing under "Institutions". Tap on that.

They are now able to send reports to your institution.

Setup Institution Email

Sending

Now when a user submits a report the following occurs. (Note: the numbers correspond to the number in the diagram at the top of the page.)

  1. When a users signs in/up, the User Server will return a User Token. The User Token is a hashed and signed version of the user data. It is used later for verifying user requests.
  2. The app sends a request with the user's details in the User Token and a Report ID to the Key Server. The Key Server will verify that the user details are valid (this ensures that request has come from a trusted source). The Key Server responds with a Key that is used by the app for the report encryption later in the process. By default, the app will use a Key Server run by PicSafe. Should you want your institution to restrict recipients to be only staff members of their institution, this can be achieved by running a private key server.
  3. A bit happens here!
    • The app generates a Metadata File (metadata.json), and a PDF document (report.pdf).
    • The app then packages these two files along with the media and relevant thumbnails into a zipped file (package.zip).
    • Using the Key (fetched from the Key Server above), the app then encrypts the package.zip file to create an encrypted file (package.encrypted).
    • The app then generates a package file (package.json) which contains the URL of the Key Server (so when it comes time to decrypt the report the app will know where to get the key from).
    • The app then zips the package.json file with the package.encrypted file and creates a PicSafe File ({reportID}.picsafe).
    • The app opens the device's default email client and attaches the PicSafe File to an email.
    • The email is pre-populated with the specified email address in the "To" field.
    The user then sends the email.
  4. The End Point Server should be configured to routinely check the specified email account for new emails. When there is one, it should...
    • Download the email and extract the attached PicSafe File.
    • Unzip the PicSafe File.
    • Read the contents of the package.json file to find the location of the Key Server.
  5. The Endpoint then has to send a request to the Key Server to get Key to decrypt the file. Upon getting the response, it will...
    • Decrypt the package.encrypted file.
    • Unzip the package.encrypted file.
    • Parse the Metadata File to get the details of the report.
  6. The report can then be transferred to the medical record system using whatever method is available (varies between systems). See the Contents of a Report section below for what data you might want to put in the medical record. It may be you just want the PDF, or you can insert the media items individually.

Security

Here we have securely captured patient data and media, recorded consent and transmitted it securely through the institution's firewall and into a patient record. Because all patient and user data is strongly encrypted (in the attached PicSafe file), we can share this file through email. If someone were sniffing traffic (i.e. they intercepted the email), the file will be meaningless gobbledygook! The only way they could do anything with it is by creating a PicSafe account and thereby leaving an audit trail as to who they are. Should you want your institution to restrict recipients to be only staff members of their institution, this can be achieved by Running a private Key Server.

PicSafe uses RNCryptor for encrypting reports. RNCryptor is a cross-language AES Encrypter/Decrypter data format. The data format includes all the metadata required to securely implement AES encryption, as described in "Properly encrypting with AES with CommonCrypto," and iOS 6 Programming Pushing the Limits, Chapter 15. Specifically, it includes:

  • AES-256 encryption
  • CBC mode
  • Password stretching with PBKDF2
  • Password salting
  • Random IV
  • Encrypt-then-hash HMAC

This format was used because it is widely supported. This makes it easier for institutions to integrate PicSafe into their medical record systems. There are implementations of RNCryptor in Swift, Objective-C, C, C++, C#, Erlang, Go, Haskell, Java, PHP, Python, Javascript, and Ruby.

1.5 Upload to Medical Record

It is possible to upload reports directly to an endpoint hosted by your institution much like how the app uploads to Box and Dropbox. The report will not be encrypted before being sent, but it will be sent over HTTPS and therefore can be deemed as being sent securely. When uploading direct to an Endpoint Server, the app will upload a zip file containing all the media files, a metadata.json file and a PDF report.

Upload to Medical Record

Institution Setup

You will need to set up a private Endpoint Server. As part of this, you will need to write middleware to take reports uploaded to the endpoint and move them into your medical record system (PicSafe does not perform this integration).

See the Sample Ruby on Rails Endpoint Server repository. Although written in Rails, the code should reasonably easy to follow even if you are not familiar with Rails. You can see the result at http://endpoint.picsafe.com.

For more information, please see the Running a private Endpoint Server section below.

User Setup

Users within your institution should be instructed to add an "Institution" in their app. To do this, they have to do the following:

  • Open the PicSafe app and tap on "Settings".
  • Tap on "Institutions Medical Record" and then the "Add" button in the top right.
  • In "Send type" select "Post", enter the name of your institution (e.g. "My Hospital"), enter the "Endpoint" URL (e.g. http://endpoint.picsafe.com), and leave the "Key Server" field blank.
  • Tap the "Save" button in the top right and go back to the primary form.
  • Now in the primary form, in the "Send to" options there will be a "My Hospital" listing under "Institutions". Tap on that.

They are now able to send reports to your institution.

Setup Institution Upload

Sending

Now when a user submits a report the following occurs. (Note: the numbers correspond to the number in the diagram above.)

  1. When a users signs in/up, the User Server will return a User Token. The User Token is a hashed and signed version of the user data. It is used later for verifying user requests.
  2. The app does the following:
    • Generates a Metadata File (metadata.json), and a PDF document (report.pdf).
    • Packages these two files along with the media and relevant thumbnails into a zipped file (package.encrypted).
    • Uploads the report to your Endpoint Server.
  3. The Endpoint Server will...
    • Download the email and extract the attached PicSafe File.
    • Unzip the PicSafe File.
    • Read the contents of the package.json file.
    The report can then be transferred to the medical record system using whatever method is available (varies between systems). See the Contents of a Report section below for what data you might want to put in the medical record. It may be you just want the PDF, or you can insert the media items individually.

The app will submit the file to Endpoint Server with the following file path:

POST https://{endpoint url}/api/report picsafe_file

The POST accepts the form with two fields:

  • token This is the User Token generated from the User Server. It will be decoded so you can verify that the user sending the report is an authentic PicSafe user, and they are who they say they are.
  • picsafe_file This is the binary zip file (as discussed above).

Security

All reports should be uploaded over HTTPS. Using this technique, we do not encrypt reports before submitting. Therefore, we rely on data been sent securely via HTTPS. It is assumed that the endpoint will store all reports securely. The endpoint server that you set up can be tested using HTTP but should only ever be used in production using HTTPS.

1.6 Upload to Medical Record (with Dynamic Key Encryption)

It is possible to upload encrypted reports directly to an endpoint hosted by your institution. Much like how reports are encrypted before being emailed, here reports are being encrypted before being uploaded to an endpoint.

Upload to Medical Record (with Dynamic Key Encryption)

Institution Setup

You will need to set up a private Endpoint Server. As part of this, you will need to write middleware to take reports uploaded to the endpoint and move them into your medical record system (PicSafe does not perform this integration).

See the Sample Ruby on Rails Endpoint Server repository. Although written in Rails, the code should reasonably easy to follow even if you are not familiar with Rails. You can see the result at http://endpoint.picsafe.com.

For more information, please see the Running a private Endpoint Server section below.

Once the server has been setup, you can send reports.

User Setup

Users within your institution should be instructed to set up an "Institution" within the PicSafe app on their device(s). To do this, they have to do the following:

  • Open the PicSafe app and tap on "Settings".
  • Tap on "Institutions Medical Record" and then the "Add" button in the top right.
  • In "Send type" select "Post (Dynamic Key)", enter the name of your institution (e.g. "My Hospital"), enter the "Endpoint" URL (e.g. http://endpoint.picsafe.com), and leave the "Key Server" field blank.
  • Tap the "Save" button in the top right and go back to the primary form.
  • Now in the primary form, in the "Send to" options there will be a "My Hospital" listing under "Institutions". Tap on that.

They are now able to send reports to your institution.

Setup Institution Upload with Dynamic Key Encryption

Sending

Now when a user submits a report the following occurs. (Note: the numbers correspond to the number in the diagram above.)

  1. When a users signs in/up, the User Server will return a User Token. The User Token is a hashed and signed version of the user data. It is used later for verifying user requests.
  2. The app sends a request with the user's details in the User Token and a Report ID to the Key Server. The Key Server will verify that the user details are valid (this ensures that request has come from a trusted source). The Key Server responds with a Key that is used by the app for the report encryption later in the process. By default, the app will use a Key Server run by PicSafe. Should you want your institution to restrict recipients to be only staff members of their institution, this can be achieved by running a private key server.
  3. A bit happens here!
    • The app generates a Metadata File (metadata.json), and a PDF document (report.pdf).
    • The app then packages these two files along with the media and relevant thumbnails into a zipped file (package.zip).
    • Using the Key (fetched from the Key Server above), the app then encrypts the package.zip file to create an encrypted file (package.encrypted).
    • The app then generates a package file (package.json) which contains the URL of the Key Server (so when it comes time to decrypt the report the app will know where to get the key from).
    • The app then zips the package.json file with the package.encrypted file and creates a PicSafe File ({reportID}.picsafe).
    • The app then uploads the report to your Endpoint Server.
  4. Before the report can be transferred to the patient medical record system, the following occurs:
    • The Endpoint Server opens up and unzips the PicSafe file. This exposes the package.json file and the package.encrypted file.
    • The Endpoint Server extracts the URL of the Key Server that was used to produce the Key used to encrypt the package.encrypted file.
    • The Endpoint Server sends a request off to the Key Server with the recipient’s User Token and asks for the Key.
    • The Key Server logs the request and thereby produces an audit trail of who has accessed the report.
    • The Key Server responds with the Key used to decrypt the package.encrypted file.
    • The Endpoint Server decrypts the package.encrypted file and unzips the package.encrypted file.
  5. The report can then be transferred to the medical record system using whatever method is available (varies between systems). See the Contents of a Report section below for what data you might want to put in the medical record. It may be you just want the PDF, or you can insert the media items individually.

Security

Using this technique, reports will be encrypted in PicSafe before they are sent. This means that the endpoint does not necessarily need to be transmitted over HTTPS for it to remain secure.

PicSafe uses RNCryptor for encrypting reports. RNCryptor is a cross-language AES Encrypter/Decrypter data format. The data format includes all the metadata required to securely implement AES encryption, as described in "Properly encrypting with AES with CommonCrypto," and iOS 6 Programming Pushing the Limits, Chapter 15. Specifically, it includes:

  • AES-256 encryption
  • CBC mode
  • Password stretching with PBKDF2
  • Password salting
  • Random IV
  • Encrypt-then-hash HMAC

This format was used because it is widely supported. This makes it easier for institutions to integrate PicSafe into their medical record systems. There are implementations of RNCryptor in Swift, Objective-C, C, C++, C#, Erlang, Go, Haskell, Java, PHP, Python, Javascript, and Ruby.

1.7 Upload to Medical Record (with Static Key Encryption)

It is possible to upload encrypted ly to an endpoint hosted by your institution but rather than using a dynamic key (as described in the section above) you use a "static" key. Here we use Public-key cryptography (key pair). The public key is distributed to users (used to encrypt reports), and the private key is stored on the Endpoint Server (to decrypt reports).

Upload to Medical Record (with Static Key Encryption)

Institution Setup

You will need to set up a private Endpoint Server. As part of this, you will need to write middleware to take reports uploaded to the endpoint and move them into your medical record system (PicSafe does not perform this integration).

See the Sample Ruby on Rails Endpoint Server repository. Although written in Rails, the code should reasonably easy to follow even if you are not familiar with Rails. You can see the result at http://endpoint.picsafe.com.

For more information, please see the Running a private Endpoint Server section below.

You will have to generate a key-pair. The private key is stored on the Endpoint Server while the public key is distributed to users.

Once the server has been setup, you can send reports.

User Setup

Users within your institution should be instructed to set up an "Institution" within the PicSafe app on their device(s). To do this, they have to do the following:

  • Open the PicSafe app and tap on "Settings".
  • Tap on "Institutions Medical Record" and then the "Add" button in the top right.
  • In "Send type" select "Post (Static Key)", enter the name of your institution (e.g. "My Hospital"), enter the "Endpoint" URL (e.g. http://endpoint.picsafe.com), and in the the "Key" field enter the provided key.
  • Tap the "Save" button in the top right and go back to the primary form.
  • Now in the primary form, in the "Send to" options there will be a "My Hospital" listing under "Institutions". Tap on that.

They are now able to send reports to your institution.

Setup Institution Upload with Static Key Encryption

Sending

Now when a user submits a report the following occurs. (Note: the numbers correspond to the number in the diagram above.)

  1. When a users signs in/up, the User Server will return a User Token. The User Token is a hashed and signed version of the user data. It is used later for verifying user requests.
  2. A bit happens here!
    • The app generates a Metadata File (metadata.json), and a PDF document (report.pdf).
    • The app then packages these two files along with the media and relevant thumbnails into a zipped file (package.zip).
    • Using the Key (fetched from the Key Server above), the app then encrypts the package.zip file to create an encrypted file (package.encrypted).
    • The app then generates a package file (package.json) which contains the URL of the Key Server (so when it comes time to decrypt the report the app will know where to get the key from).
    • The app then zips the package.json file with the package.encrypted file and creates a PicSafe File ({reportID}.picsafe).
    • The app then uploads the report to your Endpoint Server.
  3. Before the report can be transferred to the patient medical record system, the following occurs:
    • The Endpoint Server opens up and unzips the PicSafe File. This exposes the package.json file and the package.encrypted file.
    • Using the private key, the Endpoint Server decrypts the package.encrypted file and unzips the package.encrypted file.
    • The report can then be transferred to the medical record system using whatever method is available (varies between systems). See the Contents of a Report section below for what data you might want to put in the medical record. It may be you just want the PDF, or you can insert the media items individually.

Security

Using this technique, reports will be encrypted in PicSafe before they are sent. This means that reports sent to the endpoint do not necessarily need to be transmitted over HTTPS for it to remain secure.

PicSafe uses RNCryptor for encrypting reports. RNCryptor is a cross-language AES Encrypter/Decrypter data format. The data format includes all the metadata required to securely implement AES encryption, as described in "Properly encrypting with AES with CommonCrypto," and iOS 6 Programming Pushing the Limits, Chapter 15. Specifically, it includes:

  • AES-256 encryption
  • CBC mode
  • Password stretching with PBKDF2
  • Password salting
  • Random IV
  • Encrypt-then-hash HMAC

This format was used because it is widely supported. This makes it easier for institutions to integrate PicSafe into their medical record systems. There are implementations of RNCryptor in Swift, Objective-C, C, C++, C#, Erlang, Go, Haskell, Java, PHP, Python, Javascript, and Ruby.

This method relies on you generating a private and public key pair. The public key is what the users enter in the app as the "Static Key". The private key is stored on the endpoint and is used to decrypt reports.


2. Contents of a Report

File Structure

A Report is sent/uploaded as a .picsafe file. See the structure below.

  • {ReportID}.picsafe
    • package.json
    • package.encrypted
      • metadata.json
      • report.pdf
      • consent.jpg (if consent is signed)
      • consent.m4a (if consent is verbal)
      • {ItemID}-thumbnail.jpg
      • {ItemID}.jpg (if media is a photo)
      • {ItemID}.m4v (if media is a video)
      • {ItemID}.m4a (if media is a audio)

Multiple media items can be included in a report and therefore there can be multiple {ItemID}-thumbnail.jpg and {ItemID}-thumbnail.jpg|m4v|m4a files.

To extract the package.json file out of the .picsafe file you should unzip the .picsafe file.

package.json

The package.json file contains the following:

{
  "keyserver_url": "##keyserver_url##"
}

Obviously ##keyserver_url## would be replaced with the URL of the Key Server used to encrypt the report (e.g. https://key.picsafe.com).

metadata.json

The metadata.json file contains the following:

{
  "report": {
    "patient": {
      "firstname": "##patientfirstname##",
      "lastname": "##patientlastname##",
      "day": "##birthday##",
      "month": "##birthmonth##",
      "year": "##birthyear##",
      "patientid": "##patientid##",
      "translator": "##translator##",
      "guardian": "##guardian##"
    },
    "user": {
      "userid": "##userid##",
      "title": "##title##",
      "firstname": "##userfirstname##",
      "lastname": "##userlastname##",
      "email": "##email##",
      "country": "##country##"
    },
    "details": {
      "notes": "##notes##",
      "datetime": "##datetime##",
      "reportid": "##reportid##",
      "sendtype": "##sendtype##",
      "sendto": "##sendto##",
      "reportendpoint": "##reportendpoint##",
      "ip": "##ip##",
      "location": {
        "latitude": "##latitude##",
        "longitude": "##longitude##",
        "address": "##address##"
      },
      "platform": "##platform##",
      "architecture": "##architecture##",
      "manufacturer": "##manufacturer##",
      "model": "##model##",
      "os": "##os##",
      "uuid": "##uuid##",
      "version": "##version##",
      "pro": "##pro##"
    },
    "consent": {
      "type": "##consenttype##",
      "treatment": "##treatment##",
      "education": "##education##",
      "publication": "##publication##",
      "consentlevels": "##consentlevels##"
    },
    "media": [
      {
        "mediaid": "##mediaItems[i].id##",
        "type": "##mediaItems[i].type##",
        "levels": "##mediaItems[i].levels##"
      }
    ]
  }
}

Obviously, all values surrounded by hashes would be replaced with appropriate values. The data in the media element can contain multiple values.

It is recommended that you test decrypting reports locally to see all the variations/values that are possible.

Decrypting .picsafe files from command line

  1. Create a file called decrypt.rb and place the following in it:
    require 'ruby_rncryptor'
    
    # encryption key
    key = '##key##'
    
    input  = ARGV[0]
    output = ARGV[1]
    
    if input.to_s =~ /^$/ or output.to_s =~ /^$/
      puts "Usage: decrypt.rb input output"
      exit 1
    end
    
    encrypted = File.open(input, 'rb').read
    decrypted = RubyRNCryptor.decrypt(encrypted, key)
    File.open(output, 'wb').write(decrypted)
  2. Copy decrypt.rb (in the root directory) to another directory (e.g. your desktop).
  3. Navigate to that directory and run:
    $ gem install ruby_rncryptor
  4. Run the decrypt file in this format:
    $ ruby decrypt.rb input output
    For example: $ ruby decrypt.rb 1234567890.picsafe 1234567890.zip

3. Running a private Key Server

A Key Server is used to dish out keys which are used to encrypt reports in the PicSafe app before sending. See the Methods of Sending/Submitting Reports section above for details on which methods use the Key Server.

If you want to limit who can send and/or receive PicSafe reports from within your organizations, or you want to access the audit trail of who has accessed reports, then you will need to set up a private Key Server. If you don't need this functionality, then you can use the default Key Server provided by PicSafe.

Before explaining how to setup a private Key Server, a brief recap on how the PicSafe sending process works will help.

Process when sending via email

When sending via email

When a user composes a "report" in the PicSafe app and presses the "Submit" button...

  1. The app fetches a Key from a Key Server. By default, the app uses a Key Server run by PicSafe (https://key.picsafe.com). All that Key Server does is dishes out keys and logs who access those keys when a report is opened.
  2. The app packages up the media, the data, and a PDF into a Report. This Report is then encrypted using the Key. The report is then packaged along with the location of the key server into ".picsafe" file. The app opens the default email program on the device and attaches the encrypted report. The user then picks to whom they want to send the report just like composing a normal email.
  3. When the recipient receives the email, they will be prompted to open the .picsafe file in the PicSafe app.
  4. When they do, the app will open the .picsafe file and get the location of the key server. It will then send a request to the key server asking for the key to decrypt the report. Along with this request, it sends the users information thereby giving us an "audit trail" of who has accessed the report. Once the key is received the app will decrypt the report, and the recipient can see its contents.
When uploading to a medical record.

When a user composes a "report" in the app and presses the "Submit" button...

  1. The app fetches a Key from a Key Server. By default, the app uses a Key Server run by PicSafe. All that Key Server does is dishes out keys and logs who access those keys when a report is opened.
  2. The app packages up the media, the data, and a PDF into a Report. This Report is then encrypted using the Key. The report is then packaged along with the location of the key server into ".picsafe" file. The app sends the report to endpoint (URL).
  3. The endpoint receives the .picsafe file and sends a request to the Key Server to get the key to decrypt the report. It then decrypts the report and in turn sends it on.
  4. The endpoint can then be configured to send to report another location (e.g. a patients medical record).
Run a private Key Server

To set up a private Key Server, PicSafe provides a turnkey Docker image. It allows you to very simply set up and host a private Key Server and it can be easily configured to whitelist or blacklist certain email addresses. For example, you could add a rule that says only PicSafe users that have an email address that ends in "@myhospital.com" can access the key to unlock reports.

Instruct users to use your Key Server

Users within your institution should be instructed to set up an "Institution" within the PicSafe app on their device(s). To do this, they have to do the following:

  • Open the PicSafe app and tap on "Settings".
  • Tap on "Institutions Medical Record" and then the "Add" button in the top right.
  • In "Send type" select "Email", enter the name of your institution (e.g. "My Hospital"), leave the "Endpoint" field blank, and in the "Key Server" field enter the URL of your Key Server (e.g. https://key.picsafe.com)
  • Tap the "Save" button in the top right and go back to the primary form.
  • Now in the primary form, in the "Send to" options there will be a "My Hospital" listing under "Institutions". Tap on that.

They are now able to send reports to your institution.

Setting up a Key Server

The Key Server server is built using Elixr and Phoenix. For ease of deployment and distribution, we use Docker. It is designed to be installed in multiple locations. PicSafe hosts a version on Digital Ocean (key.picsafe.com), but institutions can run a private version within their network or on their web hosting. You will not need to install Elixr as that is included in the Docker image we provide.

Please follow these instructions:

  1. Register your Key Server You will have to register your Key Server with PicSafe to get a Key Server Token. During the send process, requests that come through to the Key Server will contain a User Token. The Key Server Token on the Key Server needs to be compatible to verify the user's details. All requests to get a Key to either encrypt or decrypt reports are logged by Key Servers, and we need to verify that all requests are legitimate to maintain an accurate log/audit trail.
  2. Install Docker. To install Docker follow Instruction here: https://docs.docker.com/engine/installation/
  3. Pull the Docker image
    $ docker login
    $ docker pull picsafe/keyserver
  4. Run docker image. You can run the Image in either HTTP or HTTPS. It is recommended that you use HTTPS, but HTTP is provided for testing.
    To run the HTTP-only version...
    $ bin/docker-run secret-key [container-name [port [data-dir]]]
    
    secret-key      -- the same key you defined in `key_server_secret` of `config/secrets.yml`
    container-name  -- (default: keyserver) set different names for different environments.
    port            -- (default: 80) port number to listen for connections
    data-dir        -- (default: /home/deploy/data) path to directory holding data for this server (database and blacklist / whitelist)
    
    To run the HTTPS version...
    • You need to generate SSL certs and put them into your /certs directory. Name them privkey.pem (private key), cert.pem (cert), and fullchain.pem (intermediate chain certs).
    • Next, you need to run the Docker image as above (just use a different script -- bin/docker-run-ssl):
      $ bin/docker-run-ssl secret-key [container-name [port [data-dir [pk-file cert-file fullchain-file]]]
      
      pk-file -- (default: /certs/privkey.pem) path to the private key relative to `data-dir`
      cert-file -- (default: /certs/cert.pem) path to the cert file relative to `data-dir`
      fullchain-file -- (default: /certs/fullchain.pem) path to the intermediate certs chain file relative to `data-dir`
      
  5. Blacklist and whitelist email addresses (optional). Decryption key can be requested by users with allowed email addresses only. By default, everyone is welcome, but you can specify match patterns in `/blacklist` and `/whitelist` files -- a pattern per line (empty lines ignored). Patterns support wildcards. For example:
    # blacklist
    [email protected]
    [email protected]
    
    # whitelist
    [email protected]
    The above two files will forbid [email protected]` and everyone from [email protected]` except for [email protected]` from accessing the key server.
    NOTE: for changes to these files to take effect, the application (Docker container) has to be restarted.
  6. Generate SSL certificates. We recommend using free SSL certificates from LetsEncrypt. Here's what you do:
    $ git clone https://github.com/certbot/certbot
    $ cd certbot
    Stop any web service or app running on port 80 here. You should not be running them, but anyway. It's important the port is unused.
    $ ./certbot-auto certonly --standalone -d 
    Follow simple instructions of the installer, and you should get your certs saved to `/etc/letsencrypt/live/`.
    $ mkdir /certs
    $ sudo cp -L /etc/letsencrypt/live//* /certs
    This will copy your certs into the data dir that is visible from inside the Docker image. Verify that the names of files are:
    * cert.pem
    * privkey.pem
    * fullchain.pem
    You are ready to start the server.
  7. Renew SSL certificates (when required). In three months your certs will expire, and you will need to renew them. LetsEncrypt has a simple script for this, but you must stop the service/app running on port 80 first, and then:
    $ ./certbot-auto renew
    $ sudo cp -L /etc/letsencrypt/live//* /certs
    Now you can restart the docker image.

4. Running a private Endpoint Server

An Endpoint Server is a server that you host that can accept uploaded PicSafe reports. Even though it is not technically correct, we also refer to the "Middleware" server that is used in the Email to Medical Record as an Endpoint Server.

The Endpoint Server will host middleware that your IT department will need to create. It simply takes reports uploaded to the endpoint and moves them into your medical record system. PicSafe does not perform this integration. PicSafe provides a Sample Ruby on Rails Endpoint Server that does this. It should be a reasonably easy task to write something similar in another language.

Before explaining how to setup a private Endpoint Server, a brief recap on how the PicSafe sending process works will help.

Encrypt the report in the app before sending (using a Dynamic Key)

In the diagram at the top of the page see the yellow lines. When a user composes a "report" in the app and presses the "Submit" button...

  1. The app fetches a Key from a Key Server. All that Key Server does is dishes out keys and logs who access those keys when a report is opened. You can use the Key Server run by PicSafe, or you can run a private Key Server.
  2. The app packages up the media, the data, and a PDF into a Report. This Report is then encrypted using the Key. The report is then packaged along with the location of the key server into ".picsafe" file. The app sends the report to endpoint (URL).
  3. The endpoint receives the .picsafe file and sends a request to the Key Server to get the key to decrypt the report. It then decrypts the report and in turn sends it on.
  4. The endpoint can then be configured to send to report another location (e.g. a patients medical record).
Don't encrypt the report in the app before sending.

In the diagram at the top of the page see the green lines. When a user composes a "report" in the app and presses the "Submit" button...

  1. The app packages up the media, the data, and a PDF into a Report. The app sends the report to endpoint (URL).
  2. The endpoint receives the Report (zipped file that contains the media, data and PDF).
  3. The endpoint can then be configured to send to report another location (e.g. a patients medical record).

HTTP or HTTPS

It is possible to send reports to an endpoint via HTTP or HTTPS. It is also possible to specify if the reports should be encrypted in the app before being sent. Obviously, it is possible to send reports that are encrypted in the app as well as sending via HTTPS also. This is recommended. If using HTTP, you should make sure that reports are always encrypted in the app before being sent. This is a huge security vulnerability if not!

Whether a report is sent via HTTP or HTTPS is merely a matter of which protocol is specified when an institution is added. "http://endpoint.picsafe.com" would send it via HTTP and "https://endpoint.picsafe.com" would send it via HTTPS.

Encryption options

Below we will discuss the different processes relating to whether the report is encrypted in the app before sending or not.

Process when sending to an endpoint

The Test an Endpoint Server

To trial this system, you do not need to set up a private endpoint yet. We have a test endpoint but, please note, all reports are visible to the public. DO NOT USE IT FOR LIVE PATIENT DATA.

Test users within your institution should be instructed to set up an "Institution" within the PicSafe app on their device(s). To do this, they have to do the following:

  • Open the PicSafe app and tap on "Settings".
  • Tap on "Institutions Medical Record" and then the "Add" button in the top right.
  • In "Send type" select "Post (Dynamic Key)", enter the name of your institution (e.g. "My Hospital"), in the "Endpoint" field enter "http://endpoint.picsafe.com", and leave the "Key Server" field blank.
  • Tap the "Save" button in the top right and go back to the primary form.
  • Now in the primary form, in the "Send to" options there will be a "My Hospital" listing under "Institutions". Tap on that.

They are now able to send reports to your institution. When test users "Submit" a report they will be uploaded to the demo endpoint. Once finished uploading, if you go to http://endpoint.picsafe.com/, you will see the reports uploaded. Obviously, under normal circumstances, a page like this would not be visible to the public.

Setup a private Endpoint Server

As stated above, you will need to set up a private Endpoint Server. As part of this, you will need to write middleware to take reports uploaded to the endpoint and move them into your medical record system (PicSafe does not perform this integration).

For details on how to handle the various tasks an Endpoint Server needs to perform, please see the Sample Ruby on Rails Endpoint Server. Although written in Rails, the code should reasonably easy to follow even if you are not familiar with Rails. You can see the result at http://endpoint.picsafe.com.


5. Getting Reports Into the Medical Record

Please see the section above, Running a private Endpoint Server.


6. Licensing and User Management

Benefits of a License?

As well as allowing users within an institution to submit reports to a patients medical record, all users within an institution will have access to PicSafe PRO features.

Who needs a License?

An institution that wants to allow their users to generate PicSafe reports and have then inserted into the patient's medical record will need a licence. As has been discussed above, this includes the following methods of sending/submitting reports:

If your institution uses Box or Dropbox for storage you will find it easier purchasing an enterprise licence rather than each user having to purchase access to PicSafe PRO through the App Store or Google Play.

User Management

Assigning which users are part of the enterprise licence can be done by using the domain name in the email address of users (e.g. all users with an email address ending in "@myhospital.com") or by providing a comma separated list of email addresses.

Get a License

To learn more about a licence and which solution might best suit your needs, please contact us.

Contact Us About a License