Developing Adapter User-Module to Encrypt XML Elements in Process Integration 7.1

Transcription

1 Developing Adapter User-Module to Encrypt XML Elements in Process Integration 7.1 Applies to: SAP NetWeaver Process Integration 7.1. For more information, visit the Service Bus-based Integration homepage. Summary By using the Process Integration monitoring tools in ABAP and java, we can see all the elements in the XML payload. However, there are situations which we may not want certain XML elements values in the message payload to be displayed. The reason may be due to privacy reasons or security concerns. Examples might be SSN or credit card numbers. In order to hide the values of those elements, we can encrypt them by using the adapter user-modules. In this article, we will provide a step-by-step development guide required to encrypt and decrypt values of XML elements using an adapter user-module. Author: William Li Company: SAP Labs LLC Created on: 12 January 2010 Author Bio William Li is a member of the SAP NetWeaver Integration Team in SAP NetWeaver RIG Americas focusing on Process Integration. He has been with SAP since originally as a SAP America consultant then as a developer at SAPLabs. He joined SAP Intelligence Platform and NetWeaver RIG Americas in January of SAP AG 1

2 Table of Contents Introduction... 3 Overview... 3 Restrictions... 3 Encryption/Decryption... 4 Step-By-Step Direction... 4 Obtain the library (or jar) files necessary for development... 4 Include the jar files in the library classpath of SAP NetWeaver Developer Studio... 5 Create EJB and EAR projects for the User-Module... 7 Create an Enterprise Bean in the EJB project Examine and verify the content of the ejb-jar.xml file Enter the JNDI name in the ejb-j2ee-engine.xml file Include external libraries in the EJB project so the java class can be compiled Enter the code for XMLElementEncryptionBean Delete the package containing the Local and Remote interfaces from the build Configure the EAR Project Enter target server information Deploy the EAR file on the server Testing Example 1: Sender Communication Channel Configuration Example 1: Receiver Communication Channel Configuration Example 1: Test Results Example 2: Sender Communication Channel Configuration Example 2: Receiver Communication Channel Configuration Example 2: Test Results Appendix PI 7.10 Adapter User-Module Source Program to Encrypt/Decrypt XML Element Values Related Content Copyright SAP AG 2

3 Introduction Overview The Process Integration s monitoring tool in ABAP (aka SXMB_MONI) and java (aka RWB) are indispensible in debugging, error alerting and tracking of messages. The monitoring tools also provide us ability to examine the message payload. Within the payload, we can see all the elements and their values, including those that might be considered private or pose security risks. In order to avoid these problems, we can encrypt the values of those elements so that they are no longer readable. When the values are encrypted, we must make sure that they cannot be read in either the ABAP monitor or the java monitor. The adapter user-module is ideally suited for this purpose. It can be used to encrypt data at the sender adapter and decrypt data at the receiver adapter. Furthermore, it can also be used for both request and response messages, in case of synchronous scenarios. The user-module will use 2 parameters: action and elementname Examples: action: encrypt or decrypt elementname: the element(s) whose values will be encrypted or decrypted (multiple elements can be specified, separated by commas,, ). The element s XML path can also be specified; the user-module will act on those elements meeting the path specification, e.g. if the path is ssn, then all ssn s value will be encrypted or decrypted, and if the path is personal/ssn, then only those ssn s with a parent node of personal will be acted upon.) For the following XML: <CreditCardAuthorizationRequest> <personal> <CC_Number> </CC_Number> </personal> <company> <CC_Number> </CC_Number> </company> </CreditCardAuthorizationRequest> Example 1: action: encrypt elementname: CC_Number result: both CC_Number will be encrypted Example 2: action: encrypt elementname: personal/cc_number result: only the value of CC_Number with parent personal will be encrypted Note: This guide can also serve as a template for development of any adapter user-module. Restrictions Adapter user-module is only available with java adapters. Consequently, HTTP and IDoc adapters, and ABAP proxies cannot be used SAP AG 3

4 Encryption/Decryption The adapter user-module will be using the standard java symmetric ciphering, where the same secret key is used for encryption and decryption. The key is included in the user-module; therefore, no other key(s) will be needed during runtime. If asymmetric ciphering is required, you can change the routines to use the public and private keys during encryption and decryption. Step-By-Step Direction SAP NetWeaver Developer Studio 7.1 SP8 will be used during our development. Lower SP levels may have a different user-interface or menu navigation path. Obtain the library (or jar) files necessary for development In order to develop the user-module locally on the NW Developer Studio on your laptop, some PI libraries will be required. These libraries must be included in the java classpath during development. The libraries, or jar files, have to be taken from an existing SAP PI installation. Find the library files in following folders: com.sap.aii.af.cpa.svc.api.jar: <bin>/services/com.sap.aii.af.cpa.svc/lib com.sap.aii.af.lib.mod.jar: <bin>/ext/com.sap.aii.af.lib\lib com.sap.aii.af.ms.ifc_api.jar: <bin>/interfaces/com.sap.aii.af.ms.ifc/lib com.sap.aii.af.svc_api.jar: <bin>/services/com.sap.aii.af.svc/lib sap.com~tc~logging~java~impl.jar: <bin>/system jce.jar: from <bin> = /usr/sap/<sid>/dvebmgsnn/j2ee/cluster/bin on a SAP PCK 7.1 installation 2010 SAP AG 4

5 Include the jar files in the library classpath of SAP NetWeaver Developer Studio Create the local directory c:\jars\usermodulelib_710 and copy those jar files into this newly created local directory. Open up NW Developer Studio and follow the following steps: a. Navigate to Windows Preference b. In the Preference window (as shown below), expand Java, and select User Libraries and click New : c. Enter UserModule_Lib_710 as the library name and click OK SAP AG 5

6 d. Click Add JARs : e. Navigate to c:\jars\usermodulelib_710 and highlight all the jar files. Click Open SAP AG 6

7 f. Click OK to finish. Create EJB and EAR projects for the User-Module In SAP NetWeaver Developer Studio, follow the steps below: Create a new project by using the menu: File New Project a. Select: EJB EJB Project Click Next 2010 SAP AG 7

8 b. Enter project name: XMLEncryption Configuration: in the dropdown, select SAP EJB J2EE 1.4 Project. Check Add project to an EAR. The EAR Project Name will automatically be filled. Click Next. c. Click Next SAP AG 8

9 d. Uncheck Create an EJB Client. Click Finish. The following projects should be created: 2010 SAP AG 9

10 Create an Enterprise Bean in the EJB project a. Right-click on the projct XMLEncryption New EnterpriseBean: b. Create the package and class for the EJB project. a. EJB Name: XMLElementEncryption b. Bean Type: Select the dropdown Stateless Session Bean c. Default EJBPackage: com.adapter.usermodule d. Uncheck option: generate default interfaces Check option: add optional interfaces e. Click Next 2010 SAP AG 10

11 c. Assign user-module interfaces. Use the following values to assign to the parameters in the screen below: Remote interface: com.sap.aii.af.lib.mp.module.moduleremote Home interface: com.sap.aii.af.lib.mp.module.modulehome Local interface: com.sap.aii.af.lib.mp.module.modulelocal LocalHome interface: com.sap.aii.af.lib.mp.module.modulelocalhome Uncheck option: Service End point Click Finish SAP AG 11

12 Examine and verify the content of the ejb-jar.xml file With the above step, the contents of the ejb-jar.xml file are generated. Examine and verify the content of the ejb-jar.xml file. a. On the left panel, navigate: XMLEncryption project ejbmodule META-INF. Double-click on the ejb-jar.xml. b. When the ejb-jar.xml is displayed on the right panel, select the Enterprise Bean tab on the bottom. Expand Session beans and select XMLElementEncryption SAP AG 12

13 All the local and remote interfaces should be displayed. The Service endpoint should be empty. (If Service endpoint is not empty, you can go to the Source tab and edit the XML document.) Enter the JNDI name in the ejb-j2ee-engine.xml file a. On the left panel, double-click on the ejb-j2ee-engine.xml. ejb-j2ee-engine.xml will be displayed on the right panel. b. Expand Session beans and click on XMLElementEncryption. Enter for JNDI Name: XMLElementEncryption (The JNDI name is used in the communication channel configuration. It is the Module Name in the Module tab of configuration. For more details, please reference the testing section of this article.) Save the file SAP AG 13

14 Include external libraries in the EJB project so the java class can be compiled a. Right-click on the XMLEncryption project Build Path Configure Build Path b. In the Properties dialogue box, under the Libraries tab, click Add Library SAP AG 14

15 c. In the dialogue box, select User Library and click Next : d. Select the user libraries create in a previous step and click Finish SAP AG 15

16 e. The library should appear in the build path. Click OK to complete. Enter the code for XMLElementEncryptionBean a. Double-click on XMLElementEncryptionBean.java. The java program will be displayed on the right-panel SAP AG 16

17 b. Replace the java program by using copy-n-paste of the java source program from the Appendix. Save the file SAP AG 17

18 c. If you are using this guide as a template to develop your own user-module, below are sections of importance: 1. Note the lines which you can use to read your own user-module parameters and set default parameter values: 2010 SAP AG 18

19 2. Process the inbound payload and outputs the modified payload: It is advisable to call a method to modify or process the payload. This can simplify the development process and allows the re-use of the template for future user-module development. 3. Examine the remaining code and other methods used to process the message and to insure that logging and tracing of message processing have proper identifications SAP AG 19

20 Delete the package containing the Local and Remote interfaces from the build When we created the Enterprise Beans, we entered the Local and Remote interfaces. These interfaces already exist in the adapter framework, therefore, we must exclude the ones created by NWDS from the build. a. Expand the build folder in the EJB Project. b. Delete the com/sap/ classes, by right-click on sap and select Delete. Confirm the delete when requested. (If you do not see the com/sap/ folder, this means that the project has not been built. You can build the project by right-click on the EJP project, e.g. XMLEncryption, and select Build. The Project Build Automatically on the top menu will need to be turned off in order to see the Build in XMLEncryption.) 2010 SAP AG 20

21 Configure the EAR Project The EAR file contains the JAR file created from the EJB project. Also, it contains configuration information of the libraries, services and interfaces that will be used by the user-module in the EJB. In addition, it also contains the SAP manifest file, which has unique identifiers for each specific EAR. The manifest information is generated uniquely each time it is modified. a. Expand the EAR project. Double-click on the application-j2ee-engine.xml file. b. In the right panel, click on Reference, and then the SAP AG 21

22 c. Click: Create New in the dialog box. d. Enter the following information in the screen: Reference target: engine.security.facade Reference type: hard Reference target type: service Provider name: sap.com 2010 SAP AG 22

23 e. Repeat the same process (click on Reference and + ) for each of the following: Reference target Reference type Reference target type Provider name engine.j2ee14.facade hard library sap.com com.sap.aii.af.svc.facade hard service sap.com com.sap.aii.af.ifc.facade hard interface sap.com com.sap.aii.af.lib.facade hard library sap.com com.sap.base.technology.facade hard library sap.com Upon completion, you should have the following: Check the option: Failover mode Save the file. Now we are ready to deploy the EAR file SAP AG 23

24 Enter target server information Server information can be obtained from System Information in /nwa of the server, e.g. In this example: SAP AG 24

25 a. In NWDS, Navigate to Windows Preference In the Preference window (as shown below), select SAP AS Java. Enter the following information for the server: Instance host: nspah227 Instance number: 27 Click: Register SAP Instance 2010 SAP AG 25

26 The following will result : Click OK to exit. Deploy the EAR file on the server a. Right-click the EAR project. Select: Run As Run on Server 2010 SAP AG 26

27 b. Click Next. c. Click Next SAP AG 27

28 d. Select Web browser and click Next. When prompted for user/password, enter a valid an user with Administrator role. e. Click OK to complete deployment SAP AG 28

29 Testing Example 1: Sender Communication Channel Configuration Module Name (JNDI name): XMLElementEncryption Type: LocalEnterpriseBean Parameter Name: action: encrypt elementname: CC_Number 2010 SAP AG 29

30 Example 1: Receiver Communication Channel Configuration Module Name (JNDI name): XMLElementEncryption Type: LocalEnterpriseBean Parameter Name: action: decrypt elementname: CC_Number Example 1: Test Results 2010 SAP AG 30

31 Example 2: Sender Communication Channel Configuration Module Name (JNDI name): XMLElementEncryption Type: LocalEnterpriseBean Parameter Name: action: encrypt elementname: personal/cc_number 2010 SAP AG 31

32 Example 2: Receiver Communication Channel Configuration Module Name (JNDI name): XMLElementEncryption Type: LocalEnterpriseBean Parameter Name: action: decrypt elementname: personal/cc_number Example 2: Test Results 2010 SAP AG 32

33 Appendix PI 7.10 Adapter User-Module Source Program to Encrypt/Decrypt XML Element Values Below is the listing of the java program: /** * */ package com.adapter.usermodule; //Classes for EJB import javax.ejb.createexception; import javax.ejb.sessionbean; import javax.ejb.sessioncontext; // Classes for Module development & Trace import com.sap.aii.af.lib.mp.module.*; import com.sap.engine.interfaces.messaging.api.*; import com.sap.engine.interfaces.messaging.api.auditlog.*; import com.sap.tc.logging.*; // XML parsing and transformation classes import org.w3c.dom.document; import org.w3c.dom.node; import org.w3c.dom.nodelist; import org.w3c.dom.element; import java.io.inputstream; import java.io.stringwriter; import javax.xml.transform.dom.domsource; import javax.xml.transform.stream.streamresult; import javax.xml.parsers.documentbuilderfactory; import javax.xml.transform.transformer; import javax.xml.transform.transformerfactory; // //java ciphering import javax.crypto.cipher; import javax.crypto.secretkey; import javax.crypto.spec.secretkeyspec; import sun.misc.base64encoder; import sun.misc.base64decoder; public class XMLElementEncryptionBean implements SessionBean, Module { public static final String VERSION_ID = "$Id://tc/aii/30_REL/src/_adapters/_module/java/user/module/XMLElementEncrypt.java#1 $"; static final long serialversionuid = L; private String xform = "DES/ECB/PKCS5Padding"; private byte[] secretkey = {16,-128,98,-36,62,-33,26,87; private SessionContext mycontext; public void ejbremove() { public void ejbactivate() { public void ejbpassivate() { public void setsessioncontext(sessioncontext context) { mycontext = context; public void ejbcreate() throws CreateException { 2010 SAP AG 33

34 public ModuleData process(modulecontext modulecontext, ModuleData inputmoduledata) throws ModuleException { String SIGNATURE = "process(modulecontext modulecontext, ModuleData inputmoduledata)"; Location location = null; AuditAccess audit = null; // Create the location always new to avoid serialization/transient of location try { location = Location.getLocation(this.getClass().getName()); catch (Exception t) { t.printstacktrace(); ModuleException me = new ModuleException("Unable to create trace location", t); throw me; Object obj = null; Message msg = null; MessageKey key = null; try { obj = inputmoduledata.getprincipaldata(); msg = (Message) obj; if (msg.getmessagedirection().equals(messagedirection.outbound)) key = new MessageKey(msg.getMessageId(), MessageDirection.OUTBOUND); else key = new MessageKey(msg.getMessageId(), MessageDirection.INBOUND); audit = PublicAPIAccessFactory.getPublicAPIAccess().getAuditAccess(); Module called"); audit.addauditlogentry(key, AuditLogStatus.SUCCESS, catch (Exception e) { ModuleException me = new ModuleException(e); throw me; // Read the channel ID, channel and the module configuration String action = null; String elementname = null; "XMLElementEncrypt: try { // CS_GETMODDAT START action = (String) modulecontext.getcontextdata("action"); elementname = (String) modulecontext.getcontextdata("elementname"); // CS_GETMODDAT END if (action == null) { location.debugt(signature, "action parameter is not set. Default used: encrypt."); audit.addauditlogentry(key, AuditLogStatus.WARNING, "action parameter is not set. Default used: encrypt."); action = "encrypt"; location.debugt(signature, "action is set to {0", new Object[] {action); audit.addauditlogentry(key, AuditLogStatus.SUCCESS, "action is set to {0", new Object[] {action); if (elementname == null) { location.debugt(signature, "elementname parameter is not set."); audit.addauditlogentry(key, AuditLogStatus.WARNING, "elementname parameter is not set."); action = "encrypt"; location.debugt(signature, "elementname is set to {0", new Object[] {elementname); audit.addauditlogentry(key, AuditLogStatus.WARNING, "elementname is set to {0", new Object[] {elementname); catch (Exception e) { 2010 SAP AG 34

35 location.catching(signature, e); location.errort(signature, "Cannot read the module context and configuration data"); audit.addauditlogentry(key, AuditLogStatus.ERROR, "Cannot read the module context and configuration data"); ModuleException me = new ModuleException(e); location.throwing(signature, me); throw me; try { XMLPayload xmlpayload = msg.getdocument(); InputStream isxml = (InputStream)xmlpayload.getInputStream(); String sxml = encryptdecrypt(action, isxml, elementname); byte[] doccontent = sxml.getbytes(); if(doccontent!= null) { xmlpayload.setcontent(doccontent); inputmoduledata.setprincipaldata(msg); catch (Exception e) { ModuleException me = new ModuleException(e); throw me; return inputmoduledata; public String encryptdecrypt(string action, InputStream is, String elementnames) { String svalue = null; StringWriter out = new StringWriter(); Document doc = null; String[] names = elementnames.split(","); try { doc = DocumentBuilderFactory.newInstance().newDocumentBuilder().parse(is); for (int n = 0; n<names.length; n++) { String[] nodenames = names[n].trim().split("/"); String nodename = nodenames[nodenames.length-1]; NodeList list = doc.getelementsbytagname(nodename); for(int i = 0; i < list.getlength(); i++) { Element e = (Element)list.item(i); Node nodetoencryptdecrypt = e.getchildnodes().item(0); // check parent nodes, if valid if (nodevalid(nodetoencryptdecrypt, nodenames)) { String nodevalue = nodetoencryptdecrypt.getnodevalue(); if (action.equalsignorecase("encrypt")) { byte[] bvalue = nodevalue.getbytes(); byte[] bencrypted = encrypt(bvalue); BASE64Encoder encode64 = new BASE64Encoder(); svalue = encode64.encode(bencrypted); else { BASE64Decoder decode64 = new BASE64Decoder(); byte[] bdecrypted = decrypt(decode64.decodebuffer(nodevalue)); svalue = new String(bDecrypted); nodetoencryptdecrypt.setnodevalue(svalue); 2010 SAP AG 35

36 TransformerFactory tfac = TransformerFactory.newInstance(); Transformer trans = tfac.newtransformer(); trans.setoutputproperty("omit-xml-declaration", "no"); trans.transform(new DOMSource(doc.getDocumentElement()), new StreamResult(out)); catch (Exception e) { e.printstacktrace(); return out.tostring(); private boolean nodevalid(node node, String[] names) { if (names.length == 1) return true; boolean valid = true; String[] elementnames = new String[names.length]; int j = 0; for (int i=names.length-1; i>=0; i--) { elementnames[j++] = names[i]; Node[] parents = new Node[names.length]; parents[0] = node.getparentnode(); for (int i=1; i<names.length; i++) { parents[i] = parents[i-1].getparentnode(); for (int i=0; i<names.length; i++) { if (!parents[i].getnodename().equalsignorecase(elementnames[i])) { valid = false; break; return valid; private SecretKey getsecretekey() { SecretKey secretkey = new SecretKeySpec(secretKey, "DES"); return secretkey; private byte[] encrypt(byte[] inpbytes) throws Exception { SecretKey key = getsecretekey(); Cipher cipher = Cipher.getInstance(xform); cipher.init(cipher.encrypt_mode, key); return cipher.dofinal(inpbytes); private byte[] decrypt(byte[] inpbytes) throws Exception { SecretKey key = getsecretekey(); Cipher cipher = Cipher.getInstance(xform); cipher.init(cipher.decrypt_mode, key); return cipher.dofinal(inpbytes); 2010 SAP AG 36

37 Related Content Modules in Message Exchange Example Adapter and Example Module Adapter Configuration in the Integration Builder For more information, visit the Service Bus-based Integration homepage SAP AG 37

38 Copyright Copyright 2010 SAP AG. All rights reserved. No part of this publication may be reproduced or transmitted in any form or for any purpose without the express permission of SAP AG. The information contained herein may be changed without prior notice. Some software products marketed by SAP AG and its distributors contain proprietary software components of other software vendors. Microsoft, Windows, Excel, Outlook, and PowerPoint are registered trademarks of Microsoft Corporation. IBM, DB2, DB2 Universal Database, System i, System i5, System p, System p5, System x, System z, System z10, System z9, z10, z9, iseries, pseries, xseries, zseries, eserver, z/vm, z/os, i5/os, S/390, OS/390, OS/400, AS/400, S/390 Parallel Enterprise Server, PowerVM, Power Architecture, POWER6+, POWER6, POWER5+, POWER5, POWER, OpenPower, PowerPC, BatchPipes, BladeCenter, System Storage, GPFS, HACMP, RETAIN, DB2 Connect, RACF, Redbooks, OS/2, Parallel Sysplex, MVS/ESA, AIX, Intelligent Miner, WebSphere, Netfinity, Tivoli and Informix are trademarks or registered trademarks of IBM Corporation. Linux is the registered trademark of Linus Torvalds in the U.S. and other countries. Adobe, the Adobe logo, Acrobat, PostScript, and Reader are either trademarks or registered trademarks of Adobe Systems Incorporated in the United States and/or other countries. Oracle is a registered trademark of Oracle Corporation. UNIX, X/Open, OSF/1, and Motif are registered trademarks of the Open Group. Citrix, ICA, Program Neighborhood, MetaFrame, WinFrame, VideoFrame, and MultiWin are trademarks or registered trademarks of Citrix Systems, Inc. HTML, XML, XHTML and W3C are trademarks or registered trademarks of W3C, World Wide Web Consortium, Massachusetts Institute of Technology. Java is a registered trademark of Sun Microsystems, Inc. JavaScript is a registered trademark of Sun Microsystems, Inc., used under license for technology invented and implemented by Netscape. SAP, R/3, SAP NetWeaver, Duet, PartnerEdge, ByDesign, SAP Business ByDesign, and other SAP products and services mentioned herein as well as their respective logos are trademarks or registered trademarks of SAP AG in Germany and other countries. Business Objects and the Business Objects logo, BusinessObjects, Crystal Reports, Crystal Decisions, Web Intelligence, Xcelsius, and other Business Objects products and services mentioned herein as well as their respective logos are trademarks or registered trademarks of Business Objects S.A. in the United States and in other countries. Business Objects is an SAP company. All other product and service names mentioned are the trademarks of their respective companies. Data contained in this document serves informational purposes only. National product specifications may vary. These materials are subject to change without notice. These materials are provided by SAP AG and its affiliated companies ("SAP Group") for informational purposes only, without representation or warranty of any kind, and SAP Group shall not be liable for errors or omissions with respect to the materials. The only warranties for SAP Group products and services are those that are set forth in the express warranty statements accompanying such products and services, if any. Nothing herein should be construed as constituting an additional warranty SAP AG 38