Introduction
This article describes one particular scenario in which documents can be encrypted by applying a Digital Rights Management (DRM) solution. Documents that are protected by DRM can only be decrypted by their intended audience. For this purpose, the document contains information about which users may access it with which rights, such as read, write, print, etc. Other users are not able to access the document. This makes it safe to distribute the document even via e-mail.
A general introduction to the topic of “Digital Rights Management in SAP Systems” is available on SCN here.
Disclaimer
This article does not describe a general solution, but demonstrates one approach on how to integrate DRM into an existing SAP NetWeaver AS ABAP system. For this purpose, one product was selected to perform the DRM related tasks. There are other products on the market. These can be used in a similar fashion, as long as the general procedure to encrypt documents is comparable.
SAP is currently not planning to develop its own DRM product, and SAP also is currently not planning to integrate any specific DRM products into the SAP standard. Customers who want to set up DRM protection have to use non-SAP products.
Proof of Concept Implementation Overview
This section describes the specific scenario used in our showcase. First, we describe the use case and general setup, and we list the different protagonists within this scenario and their interaction. The next section shows the detailed configuration of the ABAP system, mainly the required customizing settings and the calling and implementation of the DRM logic. To complete this scenario, the implementation of a Business Add-In (BAdI) is required. The general program logic flow used in this implementation is explained.
This showcase explains one example on how to call the DRM logic. This call needs to be performed at a central place. All documents passing this place will be encrypted. If any other channel for document creation and up- or download is used, the DRM encryption will not take place. Hence, to reach a complete protection in an overall solution, an analysis of the document flow is required: Which channels are used for documents? Only with a consistent concept covering all these channels all relevant documents can be protected.
Use Case
The general scenario in which Digital Rights Management protection on data usually is applied looks as follows: In an ABAP system, either a human user or an automatic process access data and make it available for user download. While the human user might instantaneously get access to the downloaded data, the automatic process will usually save the document data for later download. In both cases, the DRM protection shall be applied to the document prior to the download, and even before saving the document in a place where it may be accessed later.
Examples for direct user interaction are reports with information on sales, taxes, or other transactional or master data. Such information can be downloaded for example into spreadsheets for further analysis, or be sent to other persons. Also individual records such as an invoice, a fact sheet about a potential customer, or a material with a component list or construction drawing might be the subject of such downloads. In the most cases, the users start a transaction, select the information they are interested in, and then trigger the download of the information into an MS office, PDF, or any other document format.
Automatic processes could be involved in case mass data is gathered and aggregated into a report. One example could be a legal report in which tax information needs to be listed for auditors in a specific format defined by the tax authorities. Especially in case of time consuming calculations, it makes sense to run a program in the background and provide the result in an appropriate format (such as MS office formats, PDF, or any integrated application-specific format) for download. The access to the download file can be provided by a transaction, or by receiving an e-mail containing a download link.
General Setup
Figure 1: Overview of DRM in ABAP provides an overview of the scenario. A human actor or an automatic job access the application logic. In this transaction, data is collected that can be displayed and downloaded. During this download, the DRM protection shall be applied.
The figure shows one block for the existing logic for the document creation. Two additional boxes are shown (highlighted in grey) that are introduced for the DRM scenario. Within the ABAP system, a new block for the DRM logic is introduced. A call to this DRM logic needs to be included into the general logic.
Figure 1: Overview of DRM in ABAP
When a document is created, it is passed from within the application logic to the new ABAP block with the DRM logic. From here, the connection to the DRM tool is established. The document is sent to the DRM tool outside the ABAP system where it is encrypted. The user is not able to prevent this call to the DRM logic.
Usage of the Virus Scan Interface
This section provides information on the solution that was opted for in the showcase scenario. As explained in the former section, the document shall be encrypted at a point of time when the data is available, but before handing it to the user (or saving it for later download).
The ABAP system contains a functionality that is able to support this usage: The Virus Scan Interface (VSI). By using the VSI, documents can be sent to virus scan applications that examine the document and return the information whether or not it contains a virus. A description of the VSI is available in the SAP Online help, see here and here.
For the DRM scenario shown in this article, we made use of the VSI. The VSI allows calling own coding, in case a virus scan product is in use that requires specific handling. For this purpose, a Business Add-In (BAdI) is available. Hence, our DRM showcase consists of a configuration part that leads to the calling of a BAdI during the document creation on the one hand and the implementation part on the other hand. The implementation consists of two parts: First, calling the BAdI at the central place of the document flow. Second, implementing the BAdI.
Proof of Concept Implementation
Using the Virus Scan Interface (VSI) requires some configuration. The following sections describe this in detail.
In addition, the call to the DRM tool needs to be implemented. This is achieved by introducing the call and by implementing the BAdI that allows specific handling of the VSI. For the former, example coding is shown. For the latter, an example program flow is described that might be used to send a document for encryption and return the encrypted document.
Virus Scan Interface Configuration
All configuration tasks for the VSI are performed in customizing. Start transaction SPRO and choose “SAP Reference IMG”. In the customizing tree, the path to the VSI is: SAP Customizing Implementation Guide → SAP NetWeaver → Application Server → System Administration → Virus Scan Interface. All activities mentioned below belong to this node.
Figure 2: Customizing activities for VSI
First, a Scanner Group is needed. For this purpose, execute the activity “Define Scanner Groups”, choose “New Entries (F5)” and enter a new group – it is important to activate the checkbox “Business Add-In”:
Figure 3: Example for the attributes of a new Virus Scan Group
The second activity “Define Virus Scan Servers” is not needed in this context.
The call to the BAdI later on requires the definition of a virus scan profile. This profile is passed as parameter when instantiating the virus scan functionality. For this purpose, define a new profile in the activity “Define Virus Scan Profile” as in the following example (use a “Z” as prefix in the customer namespace) and activate is by using the respective checkbox:
Figure 4: Define new virus scan profile
To integrate your own virus scan group as a step into a given profile, you need to enter it in the configuration. Mark the entry in question and double-click on “Steps” in the tree on the left. In the detail display, choose “New entries (F5)” (by the respective pushbutton or in the menu via Edit → New entries). Include your new virus scan group by choosing the type “Group” and entering the virus scan group name defined in the respective activity. Save the changes (Ctrl+S or in the menu: Table View → Save).
Figure 5: Add new step for a virus scan profile
Creating the Business Add-In (BAdI) for VSI
Finally, you need the BAdI for the new virus scanner group. Execute the activity “Implement BAdI for Virus Scanners” and choose “Create (F5)” in the popup.
Figure 6: Create BAdI implementation for virus scanner group
Enter a filter value containing the name of the virus scanner group, then save and activate:
Figure 7: Enter filter value for BAdI implementation
For the implementation, switch to the tab “Interface” and double-click on the method name GET_INSTANCE:
Figure 8: Starting point for BAdI implementation
The method implementation of GET_INSTANCE is quite short and might look like this:
method IF_EX_VSCAN_INSTANCE~GET_INSTANCE.
data: lo_instance type ref to Z_VSI_NEW_GROUP. " example class name
create object lo_instance.
eo_instance ?= lo_instance.
endmethod.
The coding refers to the own class, in this example: Z_VSI_NEW_GROUP. This class implements the interface IF_VSCAN_INSTANCE. The relevant method is SCAN_BYTES – it is called by using the information returned by the BAdI.
Calling the BAdI for VSI
The following code extract shows how the BAdI for the VSI might be called. This code example is not complete. The comments contain information about required actions, such as filling the profile name into the appropriate field and proceeding with the encrypted document after it was returned by the BAdI call.
data: lf_profile type vscan_profile
,lo_instance type ref to cl_vsi
,lf_filename type string
,lf_job_id type vscan_job_id
,lf_data type xstring
,lf_data_encrypted type xstring
,lf_scanrc type i
.
" Get profile name into lf_profile (must be filled):
" lf_profile =
" Get VSI instance for given profile
call method cl_vsi=>get_instance
exporting
if_profile = lf_profile
importing
eo_instance = lo_instance
exceptions
configuration_error = 1
profile_not_active = 2
profile_not_found = 3
internal_error = 4
others = 5.
if sy-subrc <> 0.
" Implement appropriate error handling
" Error information is available in the system fields
" See e.g. below:
" message id sy-msgid type sy-msgty number sy-msgno
" with sy-msgv1 sy-msgv2 sy-msgv3 sy-msgv4.
endif.
" Optional step for VSI: Use file name as Job ID
" If used: Fill lf_filename with file name
call method cl_vsi=>calc_job_id
exporting
if_filename = lf_filename
if_only_filename = abap_true " optional - without path
" default: file path is kept
receiving
ef_job_id = lf_job_id.
" In method get_instance, the settings were evaluated
" --> the following method will cause the calling of desired BAdI
call method lo_instance->if_vscan_instance~scan_bytes
exporting
if_job_id = lf_job_id " optional - default: profile name
if_data = lf_data
if_do_clean = abap_true " ! Must be set
" -> to get encrypted data back
importing
ef_scanrc = lf_scanrc
ef_data = lf_data_encrypted
" Use following parameter to evaluate errors from BAdI:
" et_bapiret =
exceptions
not_available = 1
configuration_error = 2
internal_error = 3
others = 4
.
if sy-subrc <> 0.
" See above: Implement appropriate error handling
endif.
if lf_scanrc = if_vscan_instance=>con_scanrc_clean_ok. " = -1
" encrypted file is now available in lf_data_encrypted
" Insert own logic to return encrypted file here
endif.
Possible Program Flow for BAdI Implementation
This article shows a possible program flow in Figure 9: Sequence diagram for encryption program flow: During an application, a document is created and encrypted by applying DRM protection. By configuring the VSI as described above, the newly defined BAdI implementation is called.
Figure 9: Sequence diagram for encryption program flow
Supposing that the DRM tool can be called via a command line tool, the steps for the document encryption look as follows: The document, along with information about the metadata, is passed to the tool. The metadata contains information about the users and the specific rights assigned to the users, as well as the key used for the encryption. The collection of this metadata information is called “template” within this article.
In order to pass the document to the tool, it is first saved to a file system that can be accessed from both the application server and the DRM tool. Use the transaction FILE to define a logical path name for saving this file. By calling the function module FILE_GET_NAME, this path can safely be retrieved by its logical name. The original file name is contained in the importing parameter IF_JOB_ID of the method SCAN_BYTES.
To call the tool from an ABAP system, define an operating system command in transaction SM49. It makes sense to offer the option to pass the file and template name and any further desired options as parameters.
To trigger the execution of an external command from a program, use the function module SXPG_COMMAND_EXECUTE. Note that different application servers might run on different operating systems. In case not all of them fit to the operating system on which the DRM tool is running, a wrapper may be used: By wrapping the call to the external command in an RFC enabled function module, the appropriate application server may be addressed explicitly.
After the encryption was performed by the external command, the document in its location on the file system is encrypted. From here, it needs to be retrieved and then can be passed back to the calling program. We recommend deleting the encrypted file from the file system afterwards.
Refer to the Class Builder (transaction SE24) for the method SCAN_BYTES of interface IF_VSCAN_INSTANCE. The interface documentation contains the link to the method documentation of SCAN_BYTES. All relevant parameters are explained here.
Some detail information on these parameters: The encrypted data is returned in the exporting parameter EF_DATA of method SCAN_BYTES. As the data was modified by the encryption, the exporting parameter EF_SCANRC should be set to -1. This return code indicates to the caller that the data of EF_DATA should be taken over.
Usage of Microsoft Active Directory Rights Management Services
Up to now, this article provided a general description without specifying a certain DRM product. When working on this showcase, we used the product “Microsoft Active Directory Rights Management Services” (Microsoft RMS) as an example. This last section of the article describes how this specific product was used.
The description in this article starts at a point where a Microsoft RMS installation is already present. Hence, the server performing the document decryption at the first access of the document by a user is up and running in the system landscape. Templates have already been uploaded (in this article you can find a description on how to define and upload these templates). These templates contain information on the users who are allowed to access the document, the rights they should have (read, write, print, etc.), as well as the encryption key. The latter was acquired during the system setup.
The direct call of the encryption by the command prompt and the result of the successful encryption could look as follows, with the document c:\usr\sap\hallo.docx and the template c:\usr\sap\RMS_templates\dusers.xml:
Figure 10: Example for direct call and output of the RMS bulk tool via command prompt
Microsoft RMS only supports certain document formats. The tool performs checks for the file ending. For instance, the format “.docx” is allowed, plus additional office formats. The Active Directory Rights Management Services Bulk Protection Tool acts as DRM tool here. The documentation contains a list of supported formats. This tool is available here.
For running this RMS bulk tool, you need operating system commands. From at least one application server, it should be possible to call the RMS bulk tool directly. If this was not possible for all application servers, an RFC enabled function module should be used. The RFC destination for the respective call should then point to an application server that is able to call the RMS bulk tool.
