PicSafe^® Documentation

Details on how to integrate PicSafe^® into your workflow, and how to use PicSafe's a Software Development Kit (SDK) and various API's to help hospitals and institutions efficiently integrate PicSafe into their workflow.

PicSafe has been built to enable easy integration with a variety of workflows. PicSafe can stand alone or integrate with various third party storage services and individual hospital and institution medical record systems.

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

1. Overview

The rather complex diagram below outlines how the various workflows work within PicSafe. The row with the coloured items corresponds to the different workflows listed in the menu. Don't worry if the diagram does not make much sense. Upon reading the sections below, each aspect is explained.

View Fullscreen

The primary aim of PicSafe is to allow doctors and health professionals to comply with privacy regulations when sending and storing clinical photos, video and audio clips. Integration into medical record (EMR/EHR) systems is an added bonus and can obviously be very useful. We want to emphasize that PicSafe is still tremendously valuable without EMR/EHR integration.

2. Workflows

Workflow. An orchestrated and repeatable pattern of business activity enabled by the systematic organization of resources into processes that transform materials, provide services, or process information.

In simple terms, and in the context of clinical photography, a workflow is the process you use to capture and send a clinical photo. We have gone to great lengths to provide many options to make integrating PicSafe into your daily activities as smooth, painless, quick and easy as possible.

Below we discuss each of the methods to help you determine which is right for you or your clinic or hospital.

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.

2.1 Send to Recipient

Merely putting clinical images (and video and audio) in the medical record can be valuable but much of the value of taking clinical photos on a mobile phone stems from the ease of sharing and conferring with colleagues. Unfortunately, not safe to transmit patient data via email, text message, WhatsApp, or any other non-medical-grade messaging system. It also does not comply with privacy regulations. Further, systems that allow you to upload a photo to an electronic medical record system generally limit access to within a hospital. Anecdotally, doctors often work across multiple institutions, and often want to confer with colleagues outside of their current institution (e.g. someone they went to medical school with that is now an expert in a particular area). This is why PicSafe built the ability to securely send a receive "reports" via email (without the need for a dedicated encrypted email service), text message and WhatsApp.

2.1.1 Send to Recipient - Email

Anecdotally, taking clinical photos using the default camera and sending them via email is common practice. It is, however, not safe to transmit patient data via email.

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.)

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.
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.
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 Report ID and 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.
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.
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.
- From the package.json file, the app extracts the report ID and 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". 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 hospitals and 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.

2.1.2 Send to Recipient - Text Message

Anecdotally, taking clinical photos using the default camera and sending them via text message is rife. It is, however, not safe to transmit patient data via text message. Here we will describe how PicSafe can be used to make sharing clinical photos, video and audio safe while utilizing the convenience of sending via text message.

Please note, we use the term "Text Message" Short Messaging Service (SMS) interchangeably.

On iOS devices, when sending a text message to someone who is also on an iOS device, will be sent via iMessage. It is also not safe to transmit patient data via iMessage. PicSafe also secures patient data send via iMessage.

Setup

There is only one requirement - ensure that text messaging is configured on your device. It is almost impossible not to have it set on a phone these days!

Sending

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

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.
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 the Key Server run by PicSafe. It is not possible to use a private key server when sending via Text Message.
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 Report ID and 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 file to the "My PicSafe", a temporary storage server.
  - The file is stored there for 7 days.
  - There are PicSafe Servers in Australia, Canada, Germany, Ireland, the UK, and the USA. If you are in one of these countries, it will use a server in that country. If you are in New Zealand, it will use the server in Australia. If you are in an EU country other than the UK or Ireland, it will use the server in Germany. Anywhere else, it will use the server in the USA.
- The app generates a link (URL) where the report can be downloaded.
- The app opens the device's messages app to compose a new message. The message is pre-populated with the link and instructions as to how to view it.
```
Please tap the link below (valid for 7 days) to view ta PicSafe report containing {list or files - e.g. 1 photo}.


https://my.picsafe.com/app/report/{country}/{random string}-{Report ID}
```
- The user can pick a recipient out of their devices built-in address book and send.
The recipient receives a text message with the link in it (see the screenshots below).
- If the recipient has the PicSafe app and they tap on the link:
  - The PicSafe app will open.
  - The app will download the report.
  - The will check that the recipient is still logged in to PicSafe.
  - The app unzips the PicSafe file ({reportID}.picsafe). This exposes the package.json file and the package.encrypted file.
  - From the package.json file, the app extracts the report ID and 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 app displays the report.
  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, and an access log.
- If the recipient does not have the PicSafe app and they tap on the link:
  - A webpage on my.picsafe.com will open.
  - The page prompts the user to either:
    - View on their phone. After following these steps, the process above applies.
      1. Download the free PicSafe® app.
      2. Open the app.
      3. Create an account and sign in.
      4. Re-open this page on your phone.
      They are instructed to download the app from the App Store or Google Play.
    - View on their computer. If they are not signed in to my.picsafe.com, they will be prompted to sign in or create a (free) PicSafe account first. They, simply, tap on the thumbnail image.
      - The web page/browser will download the report (into memory).
      - The web page/browser opens up and unzips the PicSafe file ({reportID}.picsafe). This exposes the package.json file and the package.encrypted file.
      - From the package.json file, the web page/browser extracts the report ID and the URL of the Key Server that was used to produce the Key used to encrypt the package.encrypted file.
      - The web page/browser 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 web page/browser decrypts the package.encrypted file and unzips it.
      - The web page/browser displays the report.
      This is all done in the browser. No files are downloaded to the filesystem at this stage.

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 via text message. If someone were sniffing traffic (i.e. they intercepted the text message), 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.

If we take the analogy of a doctor sending a confidential "paper" report through the post to another doctor, there is an implicit duty-of-care that a doctor should exhibit in sending the report to the intended recipient. Writing the incorrect postal address, or placing the report into the wrong pigeonhole can result in a report ending up in the wrong hands, just as it would if a doctor were to send a report to the wrong phone number. PicSafe relies on the same implicit duty-of-care when allowing doctors to send reports via text message.

Using the same analogy, if a doctor is sending a confidential "paper" report through the post to another doctor, there is also 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.

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

2.1.3 Send to Recipient - WhatApp

Anecdotally, taking clinical photos using the default camera and sending them via WhatsApp is common practice. It is, however, not safe to transmit patient data via WhatsApp. Here we will describe how PicSafe can be used to make sharing clinical photos, video and audio safe while utilizing the convenience of sending via WhatsApp.

Setup

There is only one requirement - ensure that WhatsApp is configured on your device.

Sending

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

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.
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 the Key Server run by PicSafe. It is not possible to use a private key server when sending via WhatsApp.
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 Report ID and 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 file to the "My PicSafe", a temporary storage server.
  - The file is stored there for 7 days.
  - There are PicSafe Servers in Australia, Canada, Germany, Ireland, the UK, and the USA. If you are in one of these countries, it will use a server in that country. If you are in New Zealand, it will use the server in Australia. If you are in an EU country other than the UK or Ireland, it will use the server in Germany. Anywhere else, it will use the server in the USA.
- The app generates a link (URL) where the report can be downloaded.
- The app opens the device's messages app to compose a new message. The message is pre-populated with the link and instructions as to how to view it.
```
Please tap the link below (valid for 7 days) to view ta PicSafe report containing {list or files - e.g. 1 photo}.


https://my.picsafe.com/app/report/{country}/{random string}-{Report ID}
```
- The user can pick a recipient out of their devices built-in address book and send.
The recipient receives a WhatsApp message with the link in it.
- If the recipient has the PicSafe app and they tap on the link:
  - The PicSafe app will open.
  - The app will download the report.
  - The will check that the recipient is still logged in to PicSafe.
  - The app unzips the PicSafe file ({reportID}.picsafe). This exposes the package.json file and the package.encrypted file.
  - From the package.json file, the app extracts the report ID and 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 app displays the report.
  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, and an access log.
- If the recipient does not have the PicSafe app and they tap on the link:
  - A webpage on my.picsafe.com will open.
  - The page prompts the user to either:
    - View on their phone. After following these steps, the process above applies.
      1. Download the free PicSafe® app.
      2. Open the app.
      3. Create an account and sign in.
      4. Re-open this page on your phone.
      They are instructed to download the app from the App Store or Google Play.
    - View on their computer. If they are not signed in to my.picsafe.com, they will be prompted to sign in or create a (free) PicSafe account first. They, simply, tap on the thumbnail image.
      - The web page/browser will download the report (into memory).
      - The web page/browser opens up and unzips the PicSafe file ({reportID}.picsafe). This exposes the package.json file and the package.encrypted file.
      - From the package.json file, the page/browser extracts the report ID and the URL of the Key Server that was used to produce the Key used to encrypt the package.encrypted file.
      - The web page/browser 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 web page/browser decrypts the package.encrypted file and unzips it.
      - The web page/browser displays the report.
      This is all done in the browser. No files are downloaded to the filesystem at this stage.

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 via WhatsApp. If someone were sniffing traffic (i.e. they intercepted the WhatsApp message), 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.

If we take the analogy of a doctor sending a confidential "paper" report through the post to another doctor, there is an implicit duty-of-care that a doctor should exhibit in sending the report to the intended recipient. Writing the incorrect postal address, or placing the report into the wrong pigeonhole can result in a report ending up in the wrong hands, just as it would if a doctor were to send a report to the wrong recipient. PicSafe relies on the same implicit duty-of-care when allowing doctors to send reports via WhatsApp.

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

2.2 Send to Storage

Storing patient photos, videos and audio is often required by law, and it is often a particularly useful medical for tool where it is appropriate to store and track pictorial changes over time. Using PicSafe, you can keep an archive of patient media.

Patient photos form part of the patient's medical record. As with any document that forms part of the patient's medical record, you must store photos securely. Most countries have laws stipulation a period in which photos must be stored. Further, keeping a record of photos may help in case of future disputed.

2.2.1 Send to Storage (My PicSafe)

PicSafe enables you to capture photos, video and audio and upload reports to "My PicSafe". My PicSafe is, essentially, a temporary storage server. It serves as a place where encrypted PicSafe reports can be temporarily stored while waiting for other systems to "get" them.

For instance:

An individual user can send a report to My PicSafe they can access it later through My PicSafe.
A clinic, hospital or other institution with an Enterprise account can set up a script to that polls the PicSafe User server to see if there are any new reports. This is useful where an EHR, EMR, or Data Warehouse cannot have a direct connection to an endpoint.
A third-party tool (like an EHR, EMR, or Data Warehouse) can suggest users send reports to My PicSafe and within the third-party tool there can be an option to periodically request new reports and store them in a patients medical record.

Although this section has been placed under the "Send to Storage" heading, it could equally have been listed under "Send to EMR/EHR" heading. It can be used for both.

PicSafe encrypted reports and stored for seven days.

Cloud map

There are PicSafe Clouds in Australia, Canada, Germany, Ireland, the UK, and the USA. Amazon Web Services host all PicSafe Clouds. The users country will dictate which server is used.

If the user is in a country that has a PicSafe Cloud, the PicSafe Cloud for in that country will be used.
If you are in New Zealand, it will use the PicSafe Cloud in Australia.
If you are in an EU country other than the UK or Ireland, it will use the PicSafe Cloud in Germany.
Anywhere else, it will use the server in the USA.

2.2.1.1 Accessing Via "My PicSafe"

User Setup

Users simply have to select "My PicSafe" from the "Send to" page on the main form of the PicSafe app.

Sending

When sending to My PicSafe for the purpose of retrieving in My PicSafe or for integrating into an EMS/EMR or data warehouse, the first four steps are the same. When a user submits a report, the following occurs. (Note: the numbers correspond to the number in the diagram above.)

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.
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 the Key Server run by PicSafe. It is not possible to use a private key server when sending via Text Message.
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 Report ID and 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 My PicSafe.
The app then sends a request to the User Server where a log of uploaded reports is stored.

Retrieving in My PicSafe

The following steps show how reports sent to My PicSafe can be retrieved in My PicSafe.

The user signs into My PicSafe and the webpage queries the user server and displays a list of reports recently uploaded.
The user clicks on one and the browser downloads it.
The browser then does the following:
- The browser opens up and unzips the PicSafe file (in memory). This exposes the package.json file and the package.encrypted file.
- From the package.json file, the browser extracts the report ID and the URL of the Key Server that was used to produce the Key used to encrypt the package.encrypted file.
- The browser 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 browser decrypts the package.encrypted file and unzips the package.encrypted file. The decryption is done purely in the browser, so no unencrypted patient data travels over the Internet.
- The browser then displays the report.
From there the user can choose to save the encrypted report or save the unencrypted files as they see fit.

Viewing a Saved Encrypted PicSafe Report

If you save a PicSafe Report (.picsafe file), or you have been sent one, you can view it either in the PicSafe app, or by going to My PicSafe. Simply drag the .picsafe file onto the box and the browser will decrypt and display the report.

Decrypt in browser

2.2.1.2 Accessing Via a Script

Institution Setup

In order to operate a script that fetches reports from My PicSafe, you must have an API key. In order to have an API key, you must be the administrator of a PicSafe Enterprise account.

In very simple terms, the PicSafe app allows reports to be uploaded to My PicSafe. It is up to your server or computer to fetch the files, decrypt them and move them as you see fit.

You will need to write your own script that fetches and then decrypts the encrypted PicSafe files from My PicSafe. See the Sample Ruby PicSafe Cloud Sync repository. It is a Ruby script that can be run on any server or computer. Details of how to run this script are in the README.md file in the repository.

Pre-requisites

In order to do this, you need to be an administrator of a PicSafe Enterprise account. Sign in to My PicSafe and in the "Enterprise Account Information" section you will find the following:

API Key - This is used to identify your Enterprise when making calls to my.picsafe.com from the command line script. This is how we know reports of which users you are interested in.
Key Server Token - This is the token that contains all information about your Enterprise and identifies it to the Key Server. Key Server holds the keys for decryption of any report in the system and keeps the log of everyone requesting them for each report. This is how we know who and when requested the key for each particular report decryption.

User Setup

Users simply have to select "My PicSafe" from the "Send to" page on the main form of the PicSafe app.

Sending

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.
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 the Key Server run by PicSafe. It is not possible to use a private key server when sending via Text Message.
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 Report ID and 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 My PicSafe.
The app then sends a request to the User Server where a log of uploaded reports is stored.

Integration into an EMR/EHR or Data Warehouse

The following is an example of how My PicSafe can be used. There are other ways it could also be used.

The script that runs on a server or computer that you operate sends a request to the PicSafe User Server to see if there are any new reports. If there are, the user server returns a URL where they can be downloaded.
The script downloads the reports from My PicSafe to the local filesystem.
The script then does the following:
- The script opens up and unzips the PicSafe file (in memory). This exposes the package.json file and the package.encrypted file.
- From the package.json file, the script extracts the report ID and the URL of the Key Server that was used to produce the Key used to encrypt the package.encrypted file.
- The script 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 script decrypts the package.encrypted file and unzips the package.encrypted file.
The script places the decrypted files in a specified location on the system that is running it, which may be used to place it a medical record system.

Security

Reports are stored on My PicSafe a with a 128-bit random string (22 character case sensitive alphanumeric string) pre-pended to the filename.

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

2.2.2 Send to 3rd Party Storage Services

PicSafe PRO and PicSafe Enterprise enable you to capture photos, video and audio and upload reports to various third party storage services. PicSafe currently supports both Box and Dropbox.

2.2.2.1 Box

PicSafe PRO and PicSafe Enterprise enable you to capture photos, video and audio and upload reports to Box meaning 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.

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.

2.2.2.2 Dropbox

PicSafe PRO and PicSafe Enterprise enable you to capture photos, video and audio and upload reports to Dropbox meaning 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.

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.

2.2.3 Send to Storage (Upload to Custom Data Warehouse)

PicSafe PRO and PicSafe Enterprise enable you to capture photos, video and audio and upload reports to a custom "Data Warehouse". PicSafe does not provide a data warehouse, rather it enables you to integrate with existing data warehouses.

In very simple terms, the PicSafe app allows reports to be uploaded via HTTPS to an endpoint that you host. It is up to your endpoint to move the files into a data warehouse. Reports are uploaded 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.

Please note, the instructions here are the same as the instructions for sending to an EMR/EHR via HTTPS (below).

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 a "Custom Integration" in their app. To do this, they have to do the following:

Open the PicSafe app and tap on "Settings".
Tap on "Custom Integration" row under the "Medical Record Integrations" heading.
Tap the "Add" button in the top right.
In "Send type" select "HTTP(S) 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 the "Medical Record" heading. Tap on that.

They are now able to send reports to your endpoint.

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.)

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.
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.
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.

2.3 Send to 3rd Party Electronic Medical Record (Electronic Health Record) System

2.3.1 Send to EMR/EHR - Email

Hospitals and 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.

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. picsafe@myhospital.com). 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 "Custom Integration" row under the "Medical Record Integrations" heading.
Tap 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 the "Medical Record" heading. 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.)

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.
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.
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 Report ID and 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.
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 Report ID and the location of the Key Server.
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.
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.

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

2.3.2 Send to EMR/EHR - FHIR

Fast Healthcare Interoperability Resources (FHIR) is a new and emerging technology aimed at improving the ability to share medical data. Many of the top EMR/EHR vendors have committed to providing interfaces that support FHIR connectivity. PicSafe can interface with FHIR-based systems which means you can get PicSafe up and running super quickly.

This documentation is designed for those that wish to set up or configure a FHIR server to integrate with PicSafe. It is assumed that you have at least an intermediate knowledge of FHIR.

Institution Setup

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

FHIR Version

PicSafe supports implementation with FHIR version STU3.

API Calls

As stated above, this documentation covers API calls from PicSafe to a FHIR server. The calls that PicSafe makes only use a limited subset of the FHIR API's. Your FHIR server will need you to support the following.

GET /Practitioner - Used during linking to find and list all practitioner records and let the user pick them. This record will be referenced in uploaded media and binary data (PDF).
GET /Patient?given=&family=&birthdate= - Initial query used to find a patient for automatic referencing. If no results returned, the next call is used.
GET /Patient?family=&birthdate= - Used to get a less-restricted list of patient matches. If several records are returned, a picker is displayed.
POST /Patient - Used to create a patient record.
POST /Media - Used for uploading of media (audio/video/photo) items of the report.
POST /Binary - Used for uploading of report PDF.
POST /DocumentManifest - Used for creating a document manifest that acts as the collection for the uploaded media and binary and provides the description of the report.

Authentication

Currently, only two modes of authentication are supported. You choose and provide credentials during the account linking stage.

No authentication (nor testing only)
Basic authentication

If you would like the user to authenticate with OAuth and your FHIR server acts as an OAuth Service Provider, please contact us, and we can add your server as a service provider.

Sample Requests

Creating patient

POST /Patient
{
  resourceType: "Patient",
  id: 123,
  active: "true",
  name: {
    family: "Patient",
    given: [ "Joe" ]
  },
  birthDate: "1979-24-10"
}

Uploading media (photo, video, audio)

POST /Media
{
  resourceType: "Media",
  type: "photo",
  subject: {
    reference: "Patient/patient-ref",
    display: "Joe Patient"
  },
  operator: {
    reference: "Practitioner/practitioner-ref",
    display: "Dr Feelgood"
  },
  content: {
    contentType: "image/jpeg",
    data: "kajsdflkajhdflicuyvcvejharcbiuawyrvcburawt="
  }
}

Uploading report PDF

POST /Binary
{
  resourceType: "Binary",
  contentType: "application/pdf",
  content: "aiytsdfcasdiu=="
}

Creating document manifest

POST /DocumentManifest
{
  resourceType: "DocumentManifest",
  status: "current",
  subject: {
    reference: "Patient/patient-ref",
    display: "Joe Patient"
  },
  author: {
    reference: "Practitioner/practitioner-ref",
    display: "Dr Feelgood"
  },
  description: "PicSafe Report",
  content: [
    { pReference: { reference: "Media/photo-ref" } },
    { pReference: { reference: "Media/video-ref" } },
    { pReference: { reference: "Media/audio-ref" } },
    { pReference: { reference: "Binary/pdf-ref" } }
  ]
}

Creating Sample Data (for testing without your FHIR server)

If you want to test the FHIR Integration, you can use a test by doing this.

Make sure you have PicSafe version 2.7.0 or higher. You can check by scrolling to the bottom of the "Settings" page.
Sign in to a PicSafe PRO or Enterprise account in the PicSafe App.
Tap on the "FHIR Integration" row on the "Settings" page.
Enter in the FHIR URL of `http://vonk.fire.ly` (important that there are no trailing slashes).
Select "None" for the authentication method.
Tap the "Connect" button (top right).
Select the "Practitioner" (this is a list of practitioners provided by the FHIR server).
Go back to the main form.
Take a photo, enter patient details and capture consent as you would normally on PicSafe.
Tap the "Send to" row and select "FHIR".
Press the "Send" button. If there is no patient match on the FHIR server, it will prompt you to select a patient or create one before sending.

Notes: For this example, we are using the http://vonk.fire.ly server for sample data. You can freely create data on the sample server and use it in the app.

User Setup

Users within your institution should be instructed to link to your FHIR Server 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 "FHIR Integration" row under the "Medical Record Integrations" heading.
Select the "Authentication" type. This will most likely be "Basic".
Enter the "FHIR URL".
Tap the "Connect" button in the top right.
You will be presented with a list of "Practitioners" that comes from the FHIR server. Select your name.

They are now able to send reports via FHIR.

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.)

When a user signs up or in, they will be capable of "connecting" to their "Practitioner" account on the FHIR server.
A bit happens here!
- The user creates a "report" (e.g. a clinical photo).
- The app generates a Metadata File (metadata.json), and a PDF document (report.pdf).
- The PicSafe app will send a request to the FHIR server with the patient's details.
  - If there is a direct match with the name, and date-of-birth, or with patient ID the report will be linked to that patient.
  - If there are multiple matches for the last name and date-of-birth, the user is prompted to select a patient.
  - If there a patient ID is entered and there is a conflict between the name and date-of-birth entered and the name and date-of-birth that came from the FHIR server, a warning prompt will be shown.
  - If there are no patients that match, the user can choose to create a new patient on the FHIR server.
  - When you choose to create a patient on the FHIR server, and you enter a patient ID, most FHIR servers will generate their own GUID and ignore the inputted patient ID.
- - The app creates a `DocumentManifest` record to group media and binary uploads.
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

All reports should be uploaded over HTTPS (i.e. the FHIR Server URL should use 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 FHIR server will be set up securely. Do not test sending real patient data to the vonk.fire.ly test FHIR server.

2.3.3 Send to EMR/EHR - HTTPS

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.

Institution Setup

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 "Custom Integration" row under the "Medical Record Integrations" heading.
Tap 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 the "Medical Record" heading. 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.)

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.
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.
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

2.3.4 Send to EMR/EHR - HTTP (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.

Institution Setup

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 "Custom Integration" row under the "Medical Record Integrations" heading.
Tap 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 the "Medical Record" heading. 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.)

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.
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.
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 Report ID and 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.
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.
- From the package.json file, the Endpoint Server extracts the report ID and 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.
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.

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

2.3.5 Send to EMR/EHR - HTTP (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).

Institution Setup

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 "Custom Integration" row under the "Medical Record Integrations" heading.
Tap 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 the "Medical Record" heading. 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.)

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.
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 Report ID and 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.
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.

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

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.

3. 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:

{
  "id": "##report_id##",
  "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

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)

Copy decrypt.rb (in the root directory) to another directory (e.g. your desktop).
Navigate to that directory and run:
```
$ gem install ruby_rncryptor
```
Run the decrypt file in this format:
```
$ ruby decrypt.rb input output
```
For example: $ ruby decrypt.rb 1234567890.picsafe 1234567890.zip

4. Limiting Access - 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 organization, 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.

When sending via email

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

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.
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.
When the recipient receives the email, they will be prompted to open the .picsafe file in the PicSafe app.
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...

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.
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).
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.
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 "Custom Integration" row under the "Medical Record Integrations" heading.
Tap 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 the "Medical Record" heading. 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 hospitals and 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:

Register your Key Server You will have to register your Key Server with PicSafe to get a Key Server Token. Please contact us 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.
Install Docker. To install Docker follow Instruction here: https://docs.docker.com/engine/installation/

Pull the Docker image

$ docker login
$ docker pull picsafe/keyserver

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)

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`

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
*@gmail.com
fred@smith.com

# whitelist
mark@gmail.com
```
The above two files will forbid `fred@smith.com` and everyone from `@gmail.com` except for `mark@gmail.com` from accessing the key server.
NOTE: for changes to these files to take effect, the application (Docker container) has to be restarted.
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.
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.

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. Endpoint SDK - 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...

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.
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).
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.
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...

The app packages up the media, the data, and a PDF into a Report. The app sends the report to endpoint (URL).
The endpoint receives the Report (zipped file that contains the media, data and PDF).
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.

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

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 "Custom Integration" row under the "Medical Record Integrations" heading.
Tap 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 the "Medical Record" heading. 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.

6. Licensing

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 license. As has been discussed above, this includes the following methods of sending/submitting reports:

Email to Medical Record
Upload to Medical Record
Upload to Medical Record (with Dynamic Key Encryption)
Upload to Medical Record (with Static Key Encryption)

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

Get a License

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

7. User Management

Assigning which users are part of the enterprise license 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.

PicSafe® Documentation

1. Overview

2. Workflows

Which method is best for me?

2.1 Send to Recipient

2.1.1 Send to Recipient - Email

Setup

Sending

Security

2.1.2 Send to Recipient - Text Message

Setup

Sending

Security

2.1.3 Send to Recipient - WhatApp

Setup

Sending

Security

2.2 Send to Storage

2.2.1 Send to Storage (My PicSafe)

2.2.1.1 Accessing Via "My PicSafe"

User Setup

Sending

Retrieving in My PicSafe

Viewing a Saved Encrypted PicSafe Report

2.2.1.2 Accessing Via a Script

Institution Setup

Pre-requisites

User Setup

Sending

Integration into an EMR/EHR or Data Warehouse

Security

2.2.2 Send to 3rd Party Storage Services

2.2.2.1 Box

Setup

Sending

Security

2.2.2.2 Dropbox

Setup

Sending

Security

2.2.3 Send to Storage (Upload to Custom Data Warehouse)

Institution Setup

User Setup

Sending

Security

2.3 Send to 3rd Party Electronic Medical Record (Electronic Health Record) System

2.3.1 Send to EMR/EHR - Email

Institution Setup

User Setup

Sending

Security

2.3.2 Send to EMR/EHR - FHIR

Institution Setup

FHIR Version

API Calls

Authentication

Sample Requests

Creating Sample Data (for testing without your FHIR server)

User Setup

Sending

Security

2.3.3 Send to EMR/EHR - HTTPS

Institution Setup

User Setup

Sending

Security

2.3.4 Send to EMR/EHR - HTTP (with Dynamic Key Encryption)

Institution Setup

User Setup

Sending

Security

2.3.5 Send to EMR/EHR - HTTP (with Static Key Encryption)

Institution Setup

User Setup

Sending

Security

3. Contents of a Report

File Structure

package.json

metadata.json

PicSafe^® Documentation