Cross Border Data Exchange IG
1.0.0 - CI Build International flag

Cross Border Data Exchange IG, published by IEHR-Workgroup. This guide is not an authorized publication; it is the continuous build for version 1.0.0 built by the FHIR (HL7® FHIR® Standard) CI Build. This version is based on the current content of https://github.com/InteropEHRate-project/cross-border-data-exchange/ and changes regularly. See the Directory of published versions

Signing Instructions

Contents:

Signing on transmission

When resources are requested from a server, the response to the request is transmitted as a bundle. If resources of the types listed above are part of the response, and they have no parents in the bundle, the server must create a Provenance for each of these resources. Those Provenances must be added to the bundle and transmitted to the client as well. This step is mandatory and the server is not allowed to send any of these resources without a Provenance, except if their parent is sent as well and a Provenance for the parent has been added to the bundle.

This applies to the following resources, which must be signed though the Provenance.signature before they are transmitted:

  • AllergyIntolerance
  • CarePlan
  • Composition
  • Condition
  • DiagnosticReport
  • DocumentReference
  • Encounter
  • Immunization
  • Media
  • MedicationRequest
  • MedicationStatement
  • Observation
  • Procedure

The following sections describe the process of adding a Provenance for a resource.

Instructions for the to-be-signed resource

The to-be-signed resource is extended with a ProvenanceExtension-IEHR that references the Provenance containing the signature for the resource (Provenance.signature). This Provenance must be part of the same bundle and must be referenced in this extension by its id (Provenance.id).

Instructions for the Provenance

The provenance is represented as a Provenance-IEHR. There should be one Provenance-IEHR in the bundle for each signed resource that is part of the bundle. The following attributes of the Provenance-IEHR resource are used to represent the required information:

  • The resource that is signed is referenced as the first entry in the target attribute (Provenance.target).
  • The instant of time at which the activity was recorded is stated at Provenance.recorded
  • The authors of the signed resources are represented as agents (Provenance.agents) where the type attributes contains the code 'author' and display 'Author' from the system http://terminology.hl7.org/CodeSystem/provenance-participant-type
  • The provider of the signed resources is represented as an agent (Provenance.agents) where the type attributes contains the code 'custodian' and display 'Custodian' from the system http://terminology.hl7.org/CodeSystem/provenance-participant-type
  • The signature is contained in the signature attribute (Provenance.signature)

Find all examples of Provenance-IEHR here.

Instructions for the Signature

The signature itself is represented as a Provenance-Signature-IEHR. The following attributes of the Provenance-Signature-IEHR resource are used to represent the required information:

  • Signature.when contains the information when the signature was created
  • Signature.who contains a reference to the party creating the signature. This must be the same party, that is the provider of the Provenance resource.
  • Signature.type is fixed to the code '1.2.840.10065.1.12.1.5' and display 'Verification Signature' from the codesystem 'urn:iso-astm:E1762-95:2013'
  • Signature.targetFormat contains the format of the signed resource, represented as a code from the TargetFormat ValueSet
  • Signature.sigFormat is fixed to the string 'application/jose', meaning the technical format of the signature is JSON Digital Signature
  • Signature.data contains the signature as a base64Binary

How to Sign a Resource

This section describes the procedure to sign a resource for transmission. The steps are repeated for each resource, that must be signed. It is assumed, that the resources are sent as a Bundle-IEHR and the Bundle is already set up, so that only the entries are missing.

  1. Set up a Provenance-IEHR
    • Create a new Provenance
    • Assign an id to the Provenance
    • Add the provider of the resource to the Provenance as Provenance.agent:Provider
    • Add the authors of the resource (can be multiple, but at least one) to the Provenance as Provenance.agent:authors
    • Set the Provenance.recorded attribute to the current time
    • Add a reference to the resource to the Provenance.target attribute
  2. Extend the resource with the ProvenanceExtension-IEHR and reference the Provenance in the extension
  3. Use the signing service to create the base64Binary signature for the resource
  4. Set up the Provenance-Signature-IEHR
    • Create a new Signature
    • Add the Signature to the Provenance in the Provenance.signature attribute
    • Set the Provenance.signature.data attribute to the base64Binary signature
    • Set the Provenance.signature.targetFormat to the format of the base64Binary signature (json or xml)
    • Set the Provenance.signature.when to the current date
    • Set the Provenance.signature.sigFormat attribute to 'application/jose'
    • Set the Provenance.signature.type attribute to the code '1.2.840.10065.1.12.1.5' and the display 'Verification Signature' in the system 'urn:iso-astm:E1762-95:2013'
  5. Add both the resource and the Provenance to the Bundle as Bundle.entry.resource's

Once all resources and their provenances were added to the bundle, it can be validated and sent.

How to Receive a Signed Resource

When the client receives a bundle as an answer to the request, it has to verify those resources. For each parent resource in the bundle, that is of a type from the list above, the client has to find the corresponding Provenance in the bundle. If it can not find the Provenance for a resource or is unable to verify the resource with the signature provided by its Provenance, the client has to refuse the resource and all its children.