Difference between revisions of "CTP Configuration for Study Distribution"

From MircWiki
Jump to navigation Jump to search
 
(29 intermediate revisions by the same user not shown)
Line 2: Line 2:
 
   
 
   
 
==Requirements==
 
==Requirements==
Many hospitals distribute digital examinations to referring physicians by producing DICOM CDs. The cost and time to produce and distribute these CDs, along with the lack of standardization of the software viewers for them, has limited their acceptance by referring physicians, although most people acknowledge the need to make such information available quickly and conveniently.
+
Many hospitals distribute digital examinations to referring physicians by producing DICOM CDs. The cost and time to produce and distribute these CDs, along with the lack of standardization of the software viewers for them, has limited their acceptance by referring physicians.
  
 
This section describes a CTP configuration with these features:
 
This section describes a CTP configuration with these features:
 
*Studies are received from modalities or PACS via the DICOM protocol.
 
*Studies are received from modalities or PACS via the DICOM protocol.
*Studies are partially anonymized to remove unnecessary PHI (though not all PHI).
+
*Studies are stored, organized by patient ID.
*Studies are stored.
 
 
*A user account is automatically created, if necessary, for the patient when a study is received.
 
*A user account is automatically created, if necessary, for the patient when a study is received.
 
*Patients can view their studies at a web browser.
 
*Patients can view their studies at a web browser.
Line 21: Line 20:
  
 
   <Server port="1080" />
 
   <Server port="1080" />
 +
 +
  <Pipeline name="Pipeline">
 +
 +
        <DicomImportService
 +
            name="DICOM Import Service"
 +
            class="org.rsna.ctp.stdstages.DicomImportService"
 +
            root="roots/dicom-import"
 +
            port="104" />
 +
 +
        <FileStorageService
 +
            name="File Storage Service"
 +
            class="org.rsna.ctp.stdstages.FileStorageService"
 +
            root="storage"
 +
            timeDepth="90"
 +
            fsNameTag="00100020"
 +
            autoCreateUser="yes"
 +
            port="80"
 +
            requireAuthentication="yes"
 +
            quarantine="quarantines/storage" />
 +
 +
    </Pipeline>
 +
 +
</Configuration>
 +
</pre>
 +
 +
===Server===
 +
The configuration file places the CTP admin web server on port <b>1080</b>. This web server is used by administrators to monitor the status of the system. The choice of 1080 rather than the standard port 80 is made to preserve port 80 for the FileStorageService's web server.
 +
 +
===DicomImportService===
 +
The configuration file puts the DicomImportService on the standard well-known DICOM port, <b>104</b>. The DicomImportService accepts all Application Entity Titles, so when configuring the transmitting systems (modalities or PACS), any AE Title can be used.
 +
 +
===FileStorageService===
 +
The <b>root</b> attribute can point to any location where the FileStorageService can build its directory structure. It is shown in the configuration above as a relative path from the CTP directory (the directory in which the CTP application runs) to the <b>storage</b> directory. An absolute path may be specified instead, and that path can be on a shared drive on another computer if so desired.
 +
 +
The <b>fsNameTag</b> attribute is critical to the operation of this application. It is specified to point to the DICOM PatientID element. This causes the FileStorageService to create a separate tree of directories for each patient and to store all the patient's studies in that tree. Since access is restricted by such trees, this ensures that each patient can only see his own studies. For more information on the organization of directories, see the notes in [[CTP-The_RSNA_Clinical_Trial_Processor#FileStorageService |FileStorageService]].
 +
 +
The <b>timeDepth</b> attribute is included with its value set to <b>90</b>. Studies older than 90 days will then automatically be deleted. If permanent storage is desired, the attribute should be set to zero.
 +
 +
The FileStorageService web server is enabled in this configuration by specifying a <b>port</b> attribute. The value, <b>80</b>, assumes that this will be the most convenient port for users.
 +
 +
The <b>requireAuthentication</b> attribute is required to ensure that only authorized users can view studies. More information on access to studies is contained in [[The CTP FileStorageService Access Mechanism]].
 +
 +
The <b>autoCreateUser</b> attribute is included so that the system will create user accounts for users as their studies are received. This is only an administrative convenience. Administrators can use the <b>User Manager</b> servlet on the main admin web server to create and manage accounts at any time.
 +
 +
==Operation==
 +
The simplest way to use this application in practice is to install it on a computer in the institution's DMZ and open port 80 for access from the internet. This will allow modalities or the PACS to transmit studies from the protected network to CTP. It will also allow patients and their guests to access the studies while still protecting the secure network from the internet.
 +
 +
Two approaches can be taken for getting studies to CTP. One sends the studies automatically; the other requires manual selection and transmission.
 +
*The automatic case can be implemented by having the modalities automatically send studies to the DicomImportService when they transmit them to the PACS. Equivalently, it may be possible to configure a PACS to forward studies when they are received. If neither of those approaches is convenient, the RSNA MIRC project has a tool, DicomRouter, which receives studies and forwards them to multiple destinations.
 +
*The manual case requires someone to select the study at a PACS workstation and send it to the DicomImportService.
 +
 +
Once the studies are in the FileStorageService, they are automatically available for access.
 +
 +
Three approaches can be taken for providing referring physicians access to their patients' studies.
 +
*The simplest approach is to require the patient to give the referring physician his credentials (PatientID and password) on the FileStorageService's web server. In this case, when the physician logs in, the system thinks he is the patient, and he will have all the privileges of the patient, including the ability to delete cases.
 +
*A more complex approach is to create accounts for all referring physicians and require the patient to access the web server, click the <b>Manage Guest List</b> button, and add the referring physician to the guest list. In this case, when the physician logs in, the system knows who he is and provides access to all patients on whose guest list he appears. The guest privilege provides access to the studies for viewing but not for deletion.
 +
*In the case where a patient cannot access the web server, an administrative user with the <b>proxy</b> privilege can log in as himself, and add a referring physician to a patient's guest list on behalf of the patient.
 +
 +
All three approaches can be used concurrently since they are all equivalent as far as the system is concerned. Each has advantages and disadvantages. The first is simplest to operate and administer since it requires no manual intervention by hospital staff, but it grants referring physicians more control than some patients might want. The other approaches are more secure in that regard, but they require work by hospital staff.
 +
 +
==Security Issues==
 +
Two security issues merit special consideration. Both are addressed in the following enhanced configuration file. Comments on those components which differ from those in the previous configuration appear afterward.
 +
<pre>
 +
<Configuration>
 +
 +
  <Server
 +
        port="1080"
 +
        ssl="yes"
 +
        requireAuthentication="yes" />
  
 
   <Pipeline name="Pipeline">
 
   <Pipeline name="Pipeline">
Line 42: Line 110:
 
             root="storage"
 
             root="storage"
 
             timeDepth="90"
 
             timeDepth="90"
             fs-name-tag="00080020"
+
             fsNameTag="00100020"
             auto-create-user="yes"
+
             autoCreateUser="yes"
 
             port="80"
 
             port="80"
             require-authentication="yes"
+
             ssl="yes"
 +
            requireAuthentication="yes"
 
             quarantine="quarantines/storage" />
 
             quarantine="quarantines/storage" />
  
Line 52: Line 121:
 
</Configuration>
 
</Configuration>
 
</pre>
 
</pre>
 +
===Server===
 +
This configuration version enables Secure Sockets Layer (SSL) on the admin web server and also requires that a user be authenticated when accessing the admin web server. Neither of these provides much additional security, but they at least ensure that only users known to the system can access it, and they ensure that encryption keys, which can be part of an anonymizer script, are not transmitted in the clear when edited by an anonymizer configurator servlet.
 +
 +
===DicomAnonymizer===
 +
This stage is included in the pipeline to allow unnecessary PHI to be removed before storage. The idea is simply to minimize the PHI surface area of the objects as much as possible without compromising their utility. A simple example of what might be done is to replace the patient's name with his initials (using the <tt><b>@initials</b></tt> function). This would help to conceal the patient's identity but still give the user viewing the study some confidence that the object belongs to the subject patient.
  
====Server====
+
<em>It is critically important, however, that the PatientID element (0010,0020) not be modified because the FileStorageService uses it to separate the studies by patient.</em>
The configuration file places the CTP admin web server on port <b>1080</b>. This web server is used by administrators to monitor the status of the system. The choice of 1080 rather than the standard port 80 is made to preserve port 80 for the FileStorageService's web server.
+
 
 +
The DicomAnonymizer provides many functions. See [[The CTP DICOM Anonymizer]] for the excruciating details.
 +
 
 +
===FileStorageService===
 +
This configuration version enables SSL on the FileStorageService web server. Unlike the case of the admin web server, enabling SSL significantly improves security since the objects accessed on this web server do contain at least some PHI.
 +
 
 +
===Certificates for SSL===
 +
SSL requires a digital certificate to enable the handshake which precedes a secure transfer of information. The handshake accomplishes two things:
 +
*It authenticates the server to the client, assuring the client that the server is the one that it accessed.
 +
*It facilitates the negotiation of an encryption key for encrypting the data.
 +
CTP uses SSL in the web servers for admin and storage access and in the HttpImportService and HttpExportService.
 +
 
 +
In the HttpImportService and HttpExportService, the authentication aspect of the certificate is ignored since all that matters is the encryption. To simplify the setup of such transfers, CTP includes a certificate in a file called <b>keystore</b>.
 +
 
 +
In the case of the web servers, the client is always a web browser, and modern web browsers are very strict in their use of certificates, always requiring that they are valid (e.g., unexpired) and digitally signed by a Certificate Authority (CA) known to and trusted by the browser. It is not possible to provide a certificate for this purpose since each certificate applies to a specific application at a specific site. Thus, to use SSL for either of the CTP web servers requires obtaining a certificate from a commercial CA (and paying money for it). With the certificate in hand, it is necessary then to install it in the keystore. See [[Enabling SSL in the CTP Server]] for details.
 +
 
 +
==Research Applications==
 +
A similar application can occur in research, where studies may be acquired at modalities for individual researchers. The following configuration is very close to the first one presented in this article, but it has subtle and very important differences which are discussed afterward.
 +
<pre>
 +
<Configuration>
 +
 
 +
  <Server port="1080" />
 +
 
 +
  <Pipeline name="Pipeline">
 +
 
 +
        <DicomImportService
 +
            name="DICOM Import Service"
 +
            class="org.rsna.ctp.stdstages.DicomImportService"
 +
            root="roots/dicom-import"
 +
            port="104"
 +
            calledAETTag="00097770"
 +
            callingAETTag="00097772" />
  
====DicomImportService====
+
        <FileStorageService
The configuration file puts the DicomImportService on the standard well-known DICOM port, (<b>104</b>). The DicomImportService accepts all Application Entity Titles, so when configuring the transmitting systems (modalities or PACS), any AE Title can be used.
+
            name="File Storage Service"
 +
            class="org.rsna.ctp.stdstages.FileStorageService"
 +
            root="storage"
 +
            timeDepth="90"
 +
            fsNameTag="00097770"
 +
            autoCreateUser="yes"
 +
            port="80"
 +
            requireAuthentication="yes"
 +
            quarantine="quarantines/storage" />
  
====DicomAnonymizer====
+
    </Pipeline>
This stage is included in the pipeline to allow unnecessary PHI to be removed before storage. An example of what might be done is to replace the patient's name with his initials (using the <b>@initials</b> function. The DicomAnonymizer provides many functions. See [[The CTP DICOM Anonymizer]] for the excruciating details. If anonymization is not required, this stage can be removed from the configuration file.
 
  
====FileStorageService====
+
</Configuration>
The <b>root</b> attribute can point to any location where the FileStorageService can build its directory structure. It is shown in the configuration above as a relative path from the CTP directory (the directory in which the CTP application runs) to the <b>storage</b> directory. An absolute path may be specified instead, and that path can be on a shared drive on another computer if so desired.
+
</pre>
  
The <b>fs-name-tag</b> attribute is critical to the operation of this application. It is specified to point to the DICOM PatientID attribute. This causes the FileStorageService to create a separate tree of directories for each patient and to store all the patient's studies in that tree. Since access is restricted by such trees, this ensures that each patient can only see his own studies. For more information on the organization of directories, see the notes in [[CTP-The_RSNA_Clinical_Trial_Processor#FileStorageService |FileStorageService]].
+
===DicomImportService===
 +
This configuration stores the <b>called AE Title</b> and the <b>calling AE Title</b> from the DICOM association in two elements, (0009,7770) and (0009,7772). These are then available for the FileStorageService as described below.
  
The <b>timeDepth</b> attribute is included with its value set to <b>90</b>. Studies older than 90 days will then automatically be deleted. If permanent storage is desired, the attribute should be set to zero.
+
===FileStorageService===
 +
In this configuration, the <b>fsNameTag</b> attribute points to the element in which the called AE Title was stored by the DicomImportService. This causes the FileStorageService to create a separate tree of directories for each called AE Title and to store all the studies received for that AE Title in its tree.
  
The FileStorageService web server is enabled in this configuration by specifying a <b>port</b> attribute. The value, <b>80</b>, assumes that this will be the most convenient port for users.
+
The <b>autoCreateUser</b> attribute is set to <b>yes</b>. In this case, user accounts will automatically be created for each called AE Title as it is received. In operation, studies for a specific researcher (or clinical trial) would be sent to its AE Title, and researchers would be able to access the studies under that user account.
  
The <b>require-authentication</b> attribute is required to ensure that only authorized users can view studies. More information on access to studies is contained in [[The CTP FileStorageService Access Mechanism]].  
+
To make this approach work, modalities or PACS must be configured with destinations for each AE Title which is to be used to store objects.
  
The <b>auto-create-user</b> attribute is included so that the system will create user accounts for users as their studies are received. This is only an administrative convenience. Administrators can use the <b>User Manager</b> servlet on the main admin web server to create and manage accounts at any time.
+
==Coming Attriactions==
 +
Many features are planned for CTP. Two that are relevant to this application are:
 +
*A servlet allowing a user to change his password and to specify an email address.
 +
*An automatic email notification to a user when a study is stored to which the user is granted access.

Latest revision as of 01:42, 7 October 2014

This article describes how the CTP application can be configured to distribute patient studies to referring physicians and researchers. The intended audience for this article is system administrators. There are several articles on CTP on the RSNA MIRC wiki. All would be useful references when reading this article.

1 Requirements

Many hospitals distribute digital examinations to referring physicians by producing DICOM CDs. The cost and time to produce and distribute these CDs, along with the lack of standardization of the software viewers for them, has limited their acceptance by referring physicians.

This section describes a CTP configuration with these features:

  • Studies are received from modalities or PACS via the DICOM protocol.
  • Studies are stored, organized by patient ID.
  • A user account is automatically created, if necessary, for the patient when a study is received.
  • Patients can view their studies at a web browser.
  • Patients can download and/or delete their studies.
  • Patients can make their images available to their physicians, either by providing their credentials to their physicians or by granting their physicians guest access to their studies.
  • Administrators can grant physicians guest access to a patient's studies on behalf of the patient.
  • The system can automatically remove studies older than a specified age.

2 The Configuration File

The configuration of a CTP instance is specified by an XML file called config.xml located in the same directory as the program. See the main wiki article for details on how CTP processes data objects and all the standard pipeline stages that are available. This section describes only those standard stages which are necessary to implement this application, and only those attributes which are required to provide the necessary features.

<Configuration>

   <Server port="1080" />

   <Pipeline name="Pipeline">

        <DicomImportService 
            name="DICOM Import Service"
            class="org.rsna.ctp.stdstages.DicomImportService"
            root="roots/dicom-import" 
            port="104" />

        <FileStorageService
            name="File Storage Service"
            class="org.rsna.ctp.stdstages.FileStorageService"
            root="storage"
            timeDepth="90"
            fsNameTag="00100020"
            autoCreateUser="yes"
            port="80"
            requireAuthentication="yes"
            quarantine="quarantines/storage" />

    </Pipeline>

</Configuration>

2.1 Server

The configuration file places the CTP admin web server on port 1080. This web server is used by administrators to monitor the status of the system. The choice of 1080 rather than the standard port 80 is made to preserve port 80 for the FileStorageService's web server.

2.2 DicomImportService

The configuration file puts the DicomImportService on the standard well-known DICOM port, 104. The DicomImportService accepts all Application Entity Titles, so when configuring the transmitting systems (modalities or PACS), any AE Title can be used.

2.3 FileStorageService

The root attribute can point to any location where the FileStorageService can build its directory structure. It is shown in the configuration above as a relative path from the CTP directory (the directory in which the CTP application runs) to the storage directory. An absolute path may be specified instead, and that path can be on a shared drive on another computer if so desired.

The fsNameTag attribute is critical to the operation of this application. It is specified to point to the DICOM PatientID element. This causes the FileStorageService to create a separate tree of directories for each patient and to store all the patient's studies in that tree. Since access is restricted by such trees, this ensures that each patient can only see his own studies. For more information on the organization of directories, see the notes in FileStorageService.

The timeDepth attribute is included with its value set to 90. Studies older than 90 days will then automatically be deleted. If permanent storage is desired, the attribute should be set to zero.

The FileStorageService web server is enabled in this configuration by specifying a port attribute. The value, 80, assumes that this will be the most convenient port for users.

The requireAuthentication attribute is required to ensure that only authorized users can view studies. More information on access to studies is contained in The CTP FileStorageService Access Mechanism.

The autoCreateUser attribute is included so that the system will create user accounts for users as their studies are received. This is only an administrative convenience. Administrators can use the User Manager servlet on the main admin web server to create and manage accounts at any time.

3 Operation

The simplest way to use this application in practice is to install it on a computer in the institution's DMZ and open port 80 for access from the internet. This will allow modalities or the PACS to transmit studies from the protected network to CTP. It will also allow patients and their guests to access the studies while still protecting the secure network from the internet.

Two approaches can be taken for getting studies to CTP. One sends the studies automatically; the other requires manual selection and transmission.

  • The automatic case can be implemented by having the modalities automatically send studies to the DicomImportService when they transmit them to the PACS. Equivalently, it may be possible to configure a PACS to forward studies when they are received. If neither of those approaches is convenient, the RSNA MIRC project has a tool, DicomRouter, which receives studies and forwards them to multiple destinations.
  • The manual case requires someone to select the study at a PACS workstation and send it to the DicomImportService.

Once the studies are in the FileStorageService, they are automatically available for access.

Three approaches can be taken for providing referring physicians access to their patients' studies.

  • The simplest approach is to require the patient to give the referring physician his credentials (PatientID and password) on the FileStorageService's web server. In this case, when the physician logs in, the system thinks he is the patient, and he will have all the privileges of the patient, including the ability to delete cases.
  • A more complex approach is to create accounts for all referring physicians and require the patient to access the web server, click the Manage Guest List button, and add the referring physician to the guest list. In this case, when the physician logs in, the system knows who he is and provides access to all patients on whose guest list he appears. The guest privilege provides access to the studies for viewing but not for deletion.
  • In the case where a patient cannot access the web server, an administrative user with the proxy privilege can log in as himself, and add a referring physician to a patient's guest list on behalf of the patient.

All three approaches can be used concurrently since they are all equivalent as far as the system is concerned. Each has advantages and disadvantages. The first is simplest to operate and administer since it requires no manual intervention by hospital staff, but it grants referring physicians more control than some patients might want. The other approaches are more secure in that regard, but they require work by hospital staff.

4 Security Issues

Two security issues merit special consideration. Both are addressed in the following enhanced configuration file. Comments on those components which differ from those in the previous configuration appear afterward.

<Configuration>

   <Server 
        port="1080"
        ssl="yes"
        requireAuthentication="yes" />

   <Pipeline name="Pipeline">

        <DicomImportService 
            name="DICOM Import Service"
            class="org.rsna.ctp.stdstages.DicomImportService"
            root="roots/dicom-import" 
            port="104" />

        <DicomAnonymizer
            name="DICOM Anonymizer"
            class="org.rsna.ctp.stdstages.DicomAnonymizer"
            root="roots/anonymizer"
            script="roots/anonymizer/scripts/da.script"
            quarantine="quarantines/anonymizer" />

        <FileStorageService
            name="File Storage Service"
            class="org.rsna.ctp.stdstages.FileStorageService"
            root="storage"
            timeDepth="90"
            fsNameTag="00100020"
            autoCreateUser="yes"
            port="80"
            ssl="yes"
            requireAuthentication="yes"
            quarantine="quarantines/storage" />

    </Pipeline>

</Configuration>

4.1 Server

This configuration version enables Secure Sockets Layer (SSL) on the admin web server and also requires that a user be authenticated when accessing the admin web server. Neither of these provides much additional security, but they at least ensure that only users known to the system can access it, and they ensure that encryption keys, which can be part of an anonymizer script, are not transmitted in the clear when edited by an anonymizer configurator servlet.

4.2 DicomAnonymizer

This stage is included in the pipeline to allow unnecessary PHI to be removed before storage. The idea is simply to minimize the PHI surface area of the objects as much as possible without compromising their utility. A simple example of what might be done is to replace the patient's name with his initials (using the @initials function). This would help to conceal the patient's identity but still give the user viewing the study some confidence that the object belongs to the subject patient.

It is critically important, however, that the PatientID element (0010,0020) not be modified because the FileStorageService uses it to separate the studies by patient.

The DicomAnonymizer provides many functions. See The CTP DICOM Anonymizer for the excruciating details.

4.3 FileStorageService

This configuration version enables SSL on the FileStorageService web server. Unlike the case of the admin web server, enabling SSL significantly improves security since the objects accessed on this web server do contain at least some PHI.

4.4 Certificates for SSL

SSL requires a digital certificate to enable the handshake which precedes a secure transfer of information. The handshake accomplishes two things:

  • It authenticates the server to the client, assuring the client that the server is the one that it accessed.
  • It facilitates the negotiation of an encryption key for encrypting the data.

CTP uses SSL in the web servers for admin and storage access and in the HttpImportService and HttpExportService.

In the HttpImportService and HttpExportService, the authentication aspect of the certificate is ignored since all that matters is the encryption. To simplify the setup of such transfers, CTP includes a certificate in a file called keystore.

In the case of the web servers, the client is always a web browser, and modern web browsers are very strict in their use of certificates, always requiring that they are valid (e.g., unexpired) and digitally signed by a Certificate Authority (CA) known to and trusted by the browser. It is not possible to provide a certificate for this purpose since each certificate applies to a specific application at a specific site. Thus, to use SSL for either of the CTP web servers requires obtaining a certificate from a commercial CA (and paying money for it). With the certificate in hand, it is necessary then to install it in the keystore. See Enabling SSL in the CTP Server for details.

5 Research Applications

A similar application can occur in research, where studies may be acquired at modalities for individual researchers. The following configuration is very close to the first one presented in this article, but it has subtle and very important differences which are discussed afterward.

<Configuration>

   <Server port="1080" />

   <Pipeline name="Pipeline">

        <DicomImportService 
            name="DICOM Import Service"
            class="org.rsna.ctp.stdstages.DicomImportService"
            root="roots/dicom-import" 
            port="104"
            calledAETTag="00097770" 
            callingAETTag="00097772" />

        <FileStorageService
            name="File Storage Service"
            class="org.rsna.ctp.stdstages.FileStorageService"
            root="storage"
            timeDepth="90"
            fsNameTag="00097770"
            autoCreateUser="yes"
            port="80"
            requireAuthentication="yes"
            quarantine="quarantines/storage" />

    </Pipeline>

</Configuration>

5.1 DicomImportService

This configuration stores the called AE Title and the calling AE Title from the DICOM association in two elements, (0009,7770) and (0009,7772). These are then available for the FileStorageService as described below.

5.2 FileStorageService

In this configuration, the fsNameTag attribute points to the element in which the called AE Title was stored by the DicomImportService. This causes the FileStorageService to create a separate tree of directories for each called AE Title and to store all the studies received for that AE Title in its tree.

The autoCreateUser attribute is set to yes. In this case, user accounts will automatically be created for each called AE Title as it is received. In operation, studies for a specific researcher (or clinical trial) would be sent to its AE Title, and researchers would be able to access the studies under that user account.

To make this approach work, modalities or PACS must be configured with destinations for each AE Title which is to be used to store objects.

6 Coming Attriactions

Many features are planned for CTP. Two that are relevant to this application are:

  • A servlet allowing a user to change his password and to specify an email address.
  • An automatic email notification to a user when a study is stored to which the user is granted access.