It looks like you're in .
Like to go to the PicSafe site?
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!
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.
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.
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.
Please note this is just a guide. There are many more factors that might lead to a different method being suitable for your purpose.
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.
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.
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".
The following occurs. (Note: the numbers correspond to each number in the lines in the diagram above.)
metadata.json
), and a PDF document (report.pdf
).package.zip
).package.zip
file to create an encrypted file (package.encrypted
).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).package.json
file with the package.encrypted
file and creates a PicSafe File ({reportID}.picsafe
).{reportID}.picsafe
). This exposes the package.json
file and the package.encrypted
file.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.package.encrypted
file.package.encrypted
file and unzips it.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:
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.
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.
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!
The following occurs. (Note: the numbers correspond to each number in the lines in the diagram above.)
metadata.json
), and a PDF document (report.pdf
).package.zip
).package.zip
file to create an encrypted file (package.encrypted
).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).package.json
file with the package.encrypted
file and creates a PicSafe File ({reportID}.picsafe
).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}
{reportID}.picsafe
). This exposes the package.json
file and the package.encrypted
file.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.package.encrypted
file.package.encrypted
file and unzips it.{reportID}.picsafe
). This exposes the package.json
file and the package.encrypted
file.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.package.encrypted
file.package.encrypted
file and unzips it.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.
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:
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.
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.
There is only one requirement - ensure that WhatsApp is configured on your device.
The following occurs. (Note: the numbers correspond to each number in the lines in the diagram above.)
metadata.json
), and a PDF document (report.pdf
).package.zip
).package.zip
file to create an encrypted file (package.encrypted
).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).package.json
file with the package.encrypted
file and creates a PicSafe File ({reportID}.picsafe
).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}
{reportID}.picsafe
). This exposes the package.json
file and the package.encrypted
file.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.package.encrypted
file.package.encrypted
file and unzips it.{reportID}.picsafe
). This exposes the package.json
file and the package.encrypted
file.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.package.encrypted
file.package.encrypted
file and unzips it.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.
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.
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:
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.
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.
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:
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.
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.
Users simply have to select "My PicSafe" from the "Send to" page on the main form of the PicSafe app.
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.)
metadata.json
), and a PDF document (report.pdf
).package.zip
).package.zip
file to create an encrypted file (package.encrypted
).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).package.json
file with the package.encrypted
file and creates a PicSafe File ({reportID}.picsafe
).The following steps show how reports sent to My PicSafe can be retrieved in My PicSafe.
package.json
file and the package.encrypted
file.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.package.encrypted
file.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.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.
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.
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:
Users simply have to select "My PicSafe" from the "Send to" page on the main form of the PicSafe app.
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.)
metadata.json
), and a PDF document (report.pdf
).package.zip
).package.zip
file to create an encrypted file (package.encrypted
).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).package.json
file with the package.encrypted
file and creates a PicSafe File ({reportID}.picsafe
).The following is an example of how My PicSafe can be used. There are other ways it could also be used.
package.json
file and the package.encrypted
file.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.package.encrypted
file.package.encrypted
file and unzips the package.encrypted
file.Reports are stored on My PicSafe a with a 128-bit random string (22 character case sensitive alphanumeric string) pre-pended to the filename.
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:
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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).
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.
Users within your institution should be instructed to add a "Custom Integration" in their app. To do this, they have to do the following:
They are now able to send reports to your endpoint.
Now when a user submits a report the following occurs. (Note: the numbers correspond to the number in the diagram above.)
metadata.json
), and a PDF document (report.pdf)
.package.encrypted
).package.json
file.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). 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.
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.
To get PicSafe reports into the patient medical record via email a few things need to be set up first.
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:
They are now able to send reports to your institution.
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.)
metadata.json
), and a PDF document (report.pdf
).package.zip
).package.zip
file to create an encrypted file (package.encrypted
).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).package.json
file with the package.encrypted
file and creates a PicSafe File ({reportID}.picsafe
).package.json
file to find the Report ID and the location of the Key Server.package.encrypted
file.package.encrypted
file.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". Specifically, it includes:
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.
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.
To get PicSafe reports into the patient medical record via FHIR a few things need to be set up first.
PicSafe supports implementation with FHIR version STU3.
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. Currently, only two modes of authentication are supported. You choose and provide credentials during the account linking stage.
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.
POST /Patient
{
resourceType: "Patient",
id: 123,
active: "true",
name: {
family: "Patient",
given: [ "Joe" ]
},
birthDate: "1979-24-10"
}
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="
}
}
POST /Binary
{
resourceType: "Binary",
contentType: "application/pdf",
content: "aiytsdfcasdiu=="
}
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" } }
]
}
If you want to test the FHIR Integration, you can use a test by doing this.
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.
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:
They are now able to send reports via FHIR.
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.)
metadata.json
), and a PDF document (report.pdf
).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.
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.
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.
Users within your institution should be instructed to add an "Institution" in their app. To do this, they have to do the following:
They are now able to send reports to your institution.
Now when a user submits a report the following occurs. (Note: the numbers correspond to the number in the diagram above.)
metadata.json
), and a PDF document (report.pdf)
.package.encrypted
).package.json
file.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). 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.
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.
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.
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:
They are now able to send reports to your institution.
Now when a user submits a report the following occurs. (Note: the numbers correspond to the number in the diagram above.)
metadata.json
), and a PDF document (report.pdf
).package.zip
).package.zip
file to create an encrypted file (package.encrypted
).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).package.json
file with the package.encrypted
file and creates a PicSafe File ({reportID}.picsafe
).package.json
file and the package.encrypted
file.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.package.encrypted
file.package.encrypted
file and unzips the package.encrypted
file.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". Specifically, it includes:
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.
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).
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.
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:
They are now able to send reports to your institution.
Now when a user submits a report the following occurs. (Note: the numbers correspond to the number in the diagram above.)
metadata.json
), and a PDF document (report.pdf
).package.zip
).package.zip
file to create an encrypted file (package.encrypted
).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).package.json
file with the package.encrypted
file and creates a PicSafe File ({reportID}.picsafe
).package.json
file and the package.encrypted
file.package.encrypted
file and unzips the package.encrypted
file.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". Specifically, it includes:
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.
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.
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.
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).
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.
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)
decrypt.rb
(in the root directory) to another directory (e.g. your desktop). $ gem install ruby_rncryptor
$ ruby decrypt.rb input outputFor example:
$ ruby decrypt.rb 1234567890.picsafe 1234567890.zip
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 a user composes a "report" in the PicSafe app and presses the "Submit" button...
When a user composes a "report" in the app and presses the "Submit" button...
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.
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:
They are now able to send reports to your institution.
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:
$ docker login $ docker pull picsafe/keyserver
$ bin/docker-run secret-key [container-name [port [data-dir]]]To run the HTTPS version...
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)
/certs
directory. Name them privkey.pem
(private key), cert.pem
(cert), and fullchain.pem
(intermediate chain certs). -- 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 *@gmail.com fred@smith.com # whitelist mark@gmail.comThe above two files will forbid `fred@smith.com` and everyone from `@gmail.com` except for `mark@gmail.com` from accessing the key server.
$ git clone https://github.com/certbot/certbot $ cd certbotStop 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 -dFollow simple instructions of the installer, and you should get your certs saved to `/etc/letsencrypt/live/
$ mkdirThis will copy your certs into the data dir that is visible from inside the Docker image. Verify that the names of files are:/certs $ sudo cp -L /etc/letsencrypt/live/ /* /certs
* cert.pem * privkey.pem * fullchain.pemYou are ready to start the server.
$ ./certbot-auto renew $ sudo cp -L /etc/letsencrypt/live/Now you can restart the docker image./* /certs
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.
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...
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...
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.
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:
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.
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.
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.
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:
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.
To learn more about a license and which solution might best suit your needs, please contact us.
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.