Expand +



Ensure the Confidentiality of Your SOAP Message Content — XML Encryption Using Web Services Security in SAP NetWeaver XI

by Peter McNulty | SAPinsider

January 1, 2007

by Peter McNulty, SAP Labs, LLC; Paul Medaille, SAP Labs, LLC; and Gerlinde Zibulski, SAP Labs, LLC SAPinsider - 2007 (Volume 8), January (Issue 1)

Web services and business-critical content often go hand in hand. Consider a business that uses Web services to conduct online credit card transactions. Such a company must take the utmost measures to ensure that credit card numbers and other key information does not end up in the wrong hands. It has been possible for some time to secure parts of Web services using XML signatures,1 which enable you to digitally sign a Web service message to ensure data integrity, authenticity, and non-repudiation. Until now, however, you could not encrypt the SOAP messages that two systems exchange when executing a Web service.

Full message-level security and Web service confidentiality — which prevents malicious packet sniffers from reading any message content — is only possible with XML encryption. Before, encryption was available only as part of a specific signature token — the user name/password XML signature — meaning that you could secure only the password with XML encryption, but not the full message content.

With the release of SAP NetWeaver 2004s and Support Package Stack (SPS) 15 of SAP NetWeaver 2004, XML encryption is available as part of SAP NetWeaver Exchange Infrastructure (see sidebar). Now, SAP customers can encrypt entire Web service message payloads during transport to ensure integrity, authenticity, non-repudiation, and confidentiality.

SAP NetWeaver XI Is the First SAP Solution to Enable XML Encryption

SAP NetWeaver Exchange Infrastructure (SAP NetWeaver XI) is the standards-based integration broker that functions as the prevailing integration gateway for mySAP applications. It allows customers to employ application-to-application (A2A) integration, a business-to-business (B2B) gateway that leverages open business standards and prebuilt content, and business process management (BPM) capabilities for service orchestration and process automation. By using SAP NetWeaver XI for XML encryption, companies can map to multiple interfaces, route to multiple partners, and add business process logic to services processing.

What's more, SAP NetWeaver XI is the service-enablement mechanism of all SAP systems and can Web-service-enable legacy SAP interfaces, such as remote-enabled function modules that are called via the Remote Function Call (RFC) protocol, BAPIs, or IDocs. By taking advantage of SAP NetWeaver XI's mapping and transformation capabilities and using them together with adapters, an SAP system can act as a Web services sender or receiver with non-Web-services-based interfaces.

XML Encryption Example: An Online Order

To employ XML encryption in your own organization, you must configure your SAP system to enable XML encryption and decryption according to the Web Services Security (WS-Security) standard.2 Let's look at an example of the XML encryption process before we get into the configuration details.

Consider an individual — we'll call him Business Partner A — who wants to securely consume a Web service that is offered by another business partner, Business Partner B. Business Partner A wants to consume the service on his SAP system (System A), but he does not have an interface for that service and does not want to develop one. Instead he can use SAP NetWeaver Exchange Infrastructure (SAP NetWeaver XI) to leverage an existing interface — for instance, an RFC-enabled function module — without having to code a Web service client.

Now Business Partner A can execute an RFC client call to the RFC destination, which is pointed to the SAP NetWeaver XI RFC adapter rather than to another application. As soon as he executes the call, the RFC adapter will transform the RFC message structure to XML and pass it to the integration server. The integration server will map the XML structure of the RFC message to the Web services interface document structure, and the SOAP adapter will in turn encrypt the message, leveraging the Web Services Security standard, which supports both SOAP and SAP NetWeaver XI protocols.3 To encrypt the message, the SOAP adapter (in System A) must use the public key in System B's certificate so that when Business Partner B receives the encrypted SOAP message, she can decrypt it with the private key certificate known only to her.

In this scenario, we use the SOAP adapter, which enables you to exchange SOAP messages, to simply explain how to use XML encryption for arbitrary Web service scenarios. In reality, you would have to use the SAP NetWeaver XI adapter, not the SOAP adapter, to communicate between SAP NetWeaver XI systems. Configuring the SAP NetWeaver XI adapter, which allows you to integrate SAP and non-SAP systems, is a very similar process to the one described here.

System A will then make the call to Business Partner B's system (System B) via SOAP messaging over HTTP.4 System B is also running SAP NetWeaver XI,5 so its SOAP adapter will decrypt the message, transform it back to the structure if necessary, and execute the service call against the backend system — which could be ABAP, Java, or non-SAP based. Figure 1 depicts this process.

Figure 1
Business partners can exchange Web services via SOAP messages by encrypting the message with a public key certificate and decrypting it with a private key certificate

For a full explanation of how to configure the SAP NetWeaver XI adapter, and for the Partner Connectivity Kit for Web Services Security, please see the guide "How To Configure Message Level Security in SAP XI 3.0," available at ? Exchange Infrastructure.

Ensure Confidential Content Exchange: Steps for Configuring XML Encryption

In order for System A to encrypt the SOAP message and for System B to decrypt it, both systems must first be configured to enable XML encryption of Web services. We'll now walk you through the steps for configuring XML encryption in the receiver system (System B), as well as creating its public key certificate. We'll also detail how to configure the sender system (System A) to conduct XML encryption, and we'll walk through the steps for importing the reciever's public key certificate. Note that for our configuration, we will use two ABAP stacks.6

As of SAP NetWeaver Exchange Infrastructure SPS 19, or SAP NetWeaver 2004s Process Integration SPS 10, the SAP system will support synchronous scenarios, so you can follow these directions to encrypt not only the response message, but also the request.

Step 1: Configure the Cryptographic Provider

To implement XML encryption according to the Web Services Security standard, you must meet two prerequisites, regardless of whether you are the sender or receiver. First, deploy the IAIK7 cryptographic library on the J2EE server of the adapter engine. You can download the IAIK library from the SAP Service Marketplace at

To test that the correct library is in place, log on to the SAP J2EE Visual Administrator and navigate to the server's SecurityProvider service. Click on the Cryptography Providers tab and select the provider "IAIK" (see Figure 2). The Provider Information field should show "IAIK Security Provider v3.12" and contain no reference to evaluation text; if there is any indication of evaluation text, you must re-install the library.

Figure 2
The IAIK library is properly installed if "IAIK Security Provider v3.12" is the only text appearing in the Provider Information field of the SAP J2EE Visual Administrator

Next, deploy the Java Cryptographic Extension (JCE) unrestricted policy to the corresponding Java Runtime Environment (JRE). When you download the JCE policy files from, be sure to get version 1.4.

To ensure you have the correct JCE policy files (for a Sun J2SE Development Kit), navigate within the file system to "\jre\lib\security" and look at the files "local_policy.jar" and "US_export_policy.jar." After installing the cryptographic library and the policy files, restart the entire J2EE cluster.

Each JCE policy file should be about 5KB; if the file is about 3KB, you have the wrong version. Download the correct version from the Java Web site, extract the policy files, and replace the existing ones.

Step 2: Create the Certificates for Encryption and Decryption

In order to encrypt or decrypt a message, the SOAP sender (System A in our example) must use the public key certificate of the SOAP receiver (System B) to encrypt the SOAP message before sending it. Then, Business Partner B can decrypt the message securely using his private key certificate. Let's first look at how this works from the receiver side.

To create a public key certificate, the receiver must use the SAP J2EE Visual Administration tool's Key Storage service. To access this service, start the J2EE Visual Administrator, select the correct server, and navigate to Services ? Key Storage (see the left side of Figure 3). Depending on your needs, you can use either a self-signed public key certificate, or generate and complete a certificate request to a certification authority;8 for the purposes of this article, we will show how to complete this step using a self-signed certificate.

Figure 3
Access the Key Storage service from within the SAP J2EE Visual Administrator

In the Key Storage service, navigate to the Runtime tab and select "WebServiceSecurity" from the Views pane. Under the Entry list, choose "Create." In the box that appears, fill out the Value fields in the Subject Properties area (see Figure 4 for sample entries) and provide an Entry Name (this is the same name that appears in the Keystore View). Next, check the Store Certificate checkbox, select a Key Length from the drop-down box (we recommend that you use "1024" for better security, as long as your partner application can work with 1024-bit keys), and choose "RSA" as the algorithm. Finally, click on the "Generate" button to complete the creation of your certificate.

Figure 4
Create a certificate in the SAP J2EE Visual Administrator tool's Key Storage service

If you create the certificate according to these instructions, two items will appear in the Entries pane in the Key Storage service, one with the Entry Name you specified, and one with "-cert" appended to that Entry Name (see the Entries pane in Figure 3). This is the certificate you will export to the client. To perform the export, select the "-cert" entry and click "Export." In the screen that appears, choose a file name and a location on the file system, and save the certificate file. This will create a file with a ".crt" extension. It contains the public key that the sender can import and use to encrypt the XML message.

To import this public key, the sender must have the ".crt" file that the receiver exported. After the security administrator at Business Partner A receives the ".crt" file from Business Partner B, he can load it into the Key Storage service of the J2EE Visual Administrator. Open the WebServiceSecurity Keystore View (or whichever Keystore View you want to use) as described above, and choose "Load." Then, navigate to the ".crt" file that the receiver sent to you on the consumer side.

Step 3: Configure the SOAP Adapter Communication Channel

Configuring XML message encryption or decryption in the SOAP adapter communication channel (as well as the corresponding sender or receiver agreement), is actually quite straightforward. Once again, let's begin with the receiver side.

As the receiver, you will be receiving an encrypted SOAP message, so you'll need to configure a sender SOAP adapter communication channel and a sender agreement. To do so, first create the SOAP communication channel under the corresponding Business System or Business Service (see the left side of Figure 5). To enable Web Service Security for this channel, check the Select Security Profile checkbox in the Security Parameters area and choose "Web Services Security" from the drop-down menu. If you are using digital signatures with the message, you can configure the Persist Duration to specify that the system should process signed messages only when they are delivered within a particular time interval.

Figure 5
Configure Security Parameters to enable Web Services Security for the SOAP adapter communication channel

On the corresponding sender agreement, you will need to configure the security parameters for the message exchange. The options for these settings only appear if you have configured the communication channel as above. In the Security Settings area of the sender agreement screen, select the Security Standard " oasis-200401-wss-wssecurity-secext-1.0.xsd" (see Figure 6).9 Select "Decrypt" as the Security Procedure to decrypt the message that the sender encrypts (remember that the message will be encrypted with the receiver's public key, therefore we need to be able to decrypt it with the receiver's private key). Choose "WebServiceSecurity" as your Keystore View and select the Entry Name that you'd used earlier as your Keystore Entry. Finish configuring the scenario (accounting for receiver determination, interface determination, etc.), then save and activate your changes.

Figure 6
On the sender agreement screen, the receiver must configure the sender agreement to decrypt the Web service

On the SOAP sender side, you must configure a receiver communication channel and a receiver agreement, a process very similar to that of the receiver side we just walked through. To start, check the Select Security Profile checkbox in the SOAP adapter communication channel and, from the drop-down menu, select "Web Services Security" (refer back to Figure 5). Again, fill in the Persist Duration fields if you are using digital signatures and want the message to be signed only when it is delivered within a particular time interval.

When you have saved the receiver communication channel, the receiver agreement screen will show the configuration options available for security settings. Again, choose the Security Standard "http://docs." and then select "Encrypt" as the Security Procedure.

Now, to be able to encrypt the message using the receiver's public key, you must specify the certificate that you imported from the receiver back in step 2. Type "WebServiceSecurity" as your Keystore View and then indicate the Keystore Entry based on the receiver certificate you imported earlier. Save your work, complete all other configuration steps (accounting for receiver determination, interface determination, etc.), then save and activate your changes.

You're done! Both the receiver and sender sides are now configured to perform XML encryption and decryption. At run time, SAP NetWeaver XI will encrypt the message content within the MIME document that is sent in the body of the HTTP message.

Remember, if you want to execute a synchronous Web service so that both the response and the request messages are encrypted, you must follow all steps from both the sender and receiver sides.


The adoption and use of Web services is growing rapidly; accordingly, SAP has increased its support for Web services security, enabling XML encryption via SAP NetWeaver Exchange Infrastructure. With this critical functionality, organizations can exchange messages that are confidential and that meet Web Services Security standards — and they can do so purely by configuration, without any custom coding. Furthermore, through its support for enterprise service-oriented architecture, SAP NetWeaver provides the ability to Web-service-enable legacy SAP interfaces, so even arbitrary SAP functionality can work with Web services. Look for future coverage of XML encryption and SAP's capabilities for implementing it programmatically and by configuration in both the ABAP and Java stacks.

The SAP Help Portal also contains step-by-step instructions for configuring the sender and receiver agreement security settings. To reference these instructions, go to helpdata/en/56/992d4142badb2be 10000000a1550b0/frameset.htm, then choose "Receiver Agreement" or "Sender Agreement," depending on your needs.

XML Encryption Beyond SAP NetWeaver XI

With the next major SAP NetWeaver release, SAP will expand its XML encryption capabilities to both the ABAP and Java stacks of SAP NetWeaver Application Server. Eventually security administration, including XML encryption capabilities, will be available via SAP NetWeaver Administrator, an application that runs in the portal and allows companies to centrally administer the entire system landscape from a portal application. The figure shows how you would configure Web services security via SAP NetWeaver Administrator so that it would then apply to any configured system in the system landscape directory, whether it is on ABAP or Java stacks.

1 For more on the use of XML signatures, and to see an example of publishing a Web service on an ABAP stack and consuming it on a Java stack, see the Security Strategies columns in the October-December 2005 and January-March 2006 issues of SAP Insider (

2 Web Services Security is a standard developed by the Organization for the Advancement of Structure Information Standards (OASIS).

3 In a B2B environment, both Business Partner A and Business Partner B would agree ahead of time to encrypt their messages using the Web Services Security standard.

4 Note that we will not discuss encrypting the data stream via HTTPS, as this article focuses only on message-level encryption. You'd want to use transport-level security, though, if you needed to encrypt the entire communication channel and not just the message. For more on when to use message-level and transport-level security, please see Jürgen Schneider's Security Strategies column in the January-March 2004 issue of SAP Insider (

5 XML encryption will also work in situations in which only one business partner is running SAP systems.

6 In an actual landscape, all systems would be separated from the Internet via firewalls, as shown in Figure 1. This is not relevant to our configuration directions, so we won't discuss it in detail. But keep in mind that you will have to open ports to allow messages to pass through.

7 The Institute for Applied Information Processing and Communications (IAIK) is part of the Graz University of Technology and is dedicated to information-security research.

8 To verify the authenticity of the certificate's public key through a trusted third party, you will want to send the certificate request to a certification authority. Otherwise, use a self-signed certificate.

9 See SAP note 769653 for an explanation of special cases in which you should use an alternative default value.

Additional Resources

SAP note 769653 — SAP XI: Message Security function released for SOAP-Adapter

SAP Insider articles by Peter McNulty and Gerlinde Zibulski (

  • "A Code-Free, Wizard-Driven Approach to Securing Your Web Services" (October-December 2005)

  • "Securely Consume Web Services — With No Coding" (January-March 2006)

Peter McNulty is an SAP NetWeaver Product Manager for SAP Labs, focused on development tools in ABAP and Java. He has been with SAP since November 1996, starting as an internal ABAP developer for SAP America and eventually managing the same development team prior to joining the Product Management organization. Peter holds a master's degree in computer information science from La Salle University. You can reach him at

Paul Medaille is a Product Manager for SAP NetWeaver Process Integration. He has worked for SAP since 1999 and has a background in systems and database administration, SAP system administration, and system integration. He has a degree in mathematics from the University of California at Davis and lives in Eugene, Oregon, with his wife and two retired racing greyhounds. You can reach him at

Gerlinde Zibulski is a Security Product Manager for SAP Labs, Palo Alto. She has been with SAP since January 1999. After more than two years in the International HR Consulting Department, Gerlinde moved into Technology Product Management and specialized in Security. As of January 2007, Gerlinde is Executive Assistant to Klaus Kreplin, Executive Vice President and Corporate Officer at SAP. Gerlinde holds a master's degree in economics from the Private University Witten/Herdecke. You can reach her at

An email has been sent to:

More from SAPinsider


Please log in to post a comment.

No comments have been submitted on this article. Be the first to comment!