How to configure SSL for HANA XS Engine using SAP Crypto libraries To secure communication between web-based clients and SAP HANA XS Engine

How to configure SSL for HANA XS Engine using SAP Crypto libraries To secure communication between web-based clients and SAP HANA XS Engine

www.sap.com TABLE OF CONTENTS OVERVIEW... 3 SYMPTOMS TO RESOLVE... 3 DOWNLOADING THE PRE-REQUISITES... 4 SAP Crypto Libraries... 4 SAPCAR Archiving/De-archiving Tool... 6 SSL Evaluation Certificate (SAPNetCA.cer)... 8 TRANSFERING THE PRE-REQUISITE FILES TO HANA... 9 De-Archiving the SAP Cryptographic Libraries... 9 CREATE THE SSL KEY PAIR AND CERTIFICATE REQUEST FILES... 10 Send the Certificate Request to a Certificate Authority to be signed... 10 Import the Signed Certificate using sapgenpse... 12 MODIFY THE SAP WEB DISPATCHER PROFILE... 13 Restart the HANA Web Dispatcher service... 13 CONFIRMING HTTPS AND SSL ARE WORKING... 14 Binding ports less than 1024 for use with SSL (optional)... 15 TROUBLESHOOTING... 15

OVERVIEW SAP HANA uses the Extended Application Services (XS) Engine as a lightweight web application. HANA leverages SAP s existing WebDispatcher to act as a proxy relaying communication between front-end http requests and HANA s back-end XS Engine. At the time this document was written the SAP HANA hardware vendors do not deliver the HANA appliance with SSL/HTTPs enabled for the XS Engine/WebDispatcher. This How To guide will walk through the steps to secure HTTP communication with XS Engine using SAPCrypto libraries and an SAP CA evaluation certificate for use in development or test environments. If you are interested in securing HANA communication with OpenSSL please see this document. This How To document is a supplement to section 4.3.3 in the HANA security guide as it provides missing information explaining how to download the SAPCrypto libraries from Service Market Place, as well as where to download the SSL Root evaluation certificate from SAP s web site. SYMPTOMS TO RESOLVE As seen in the following screenshots, http protocol is working for communication with SAP HANA s XS Engine. However, https protocol is not working: Also, the following errors can be seen in the SAP HANA web dispatcher trace file (red highlighting added for emphasis): /usr/sap/<sid>/hdb<instance_nr>/<hostname>/trace/dev_webdisp 3

Note: A file transfer program such as WinSCP is also required to copy these files to the HANA appliance [Thr 140625918502656] ================================================= [Thr 140625918502656] = SSL Initialization platform tag=(linuxx86_64_gcc43) [Thr 140625918502656] = (802_REL,Oct 6 2012,mt,ascii-uc,SAP_UC/size_t/void* = 16/64/64) [Thr 140625918502656] *** ERROR => DlLoadLib()==DLENOACCESS - dlopen("exe/libsapcrypto.so") FAILED "exe/libsapcrypto.so: cannot open shared object file: No such file or directory" [dlux.c 442] [Thr 140625918502656] *** ERROR => secudessl_loadlibrary(): Unable to load "exe/libsapcrypto.so" [ssslsecu.c 436 [Thr 140625918502656] *** ERROR => Loading of SSL library failed -- NO SSL available! [Thr 140625918502656] ================================================= [Thr 140625918502656] [Thr 140625918502656] <<- ERROR: SapSSLInit(read_profile=1)==SSSLERR_LIB_NOT_FOUND [Thr 140625918502656] *** ERROR => IcmServInitSSL: SapSSLInit (rc=-1): SSSLERR_LIB_NOT_FOUND [icxxserv.c 244] [Thr 140625918502656] *** WARNING => IcmAddService: Could not start service (rc=-14) PORT=4342,PROT=HTTPS,TIMEOUT= CTIMEOUT=600,VCLIENT=1 [icxxserv.c 616] DOWNLOADING THE PRE-REQUISITES From the SAP HANA Security Guide, section 4.3.3 requires the following files on the SAP HANA appliance. The following sections show where to download these files from Service Market Place. Also shown is where to get SAPCAR to de-archive SAP s.sar files. SAP Cryptographic libraries (libsapcrypto.so and sapgenpse) SAP Archive/de-archive tool (SAPCAR) SAP Root Authority Certificate for testing/evaluation (SAPNetCA.cer) SAP Crypto Libraries SAP Crypto libraries includes both sapgenpse and libsapcrypto.so Browse to http://service.sap.com/swdc, expand Support Packages and Patches and select Browse our Download Catalog, choose SAP Cryptographic Software, shown here: 4

Expand SAPCryptolib for Installation and choose SAPCRYPTOLIB 5.5.5 (or the latest version available), shown here: Choose the Linux on x86_64 64bit version, as shown: 5

SAPCAR Archiving/De-archiving Tool SAPCAR is SAP s archiving/de-archiving tool required to de-archive the SAPCryptoLib*.sar file. Browse to http://service.sap.com/swdc, expand Support Packages and Patches and select Browse our Download Catalog, choose Additional Components, shown here: 6

Choose SAPCAR, as shown here: Choose Linux on x58_64 64bit, and download the executable at the bottom of the page, as shown here: 7

SSL Evaluation Certificate (SAPNetCA.cer) Download SAPNetCA.cer from http://service.sap.com/trust as shown here: Save this file as SAPNetCA.cer, instead of the default filename getcert.cer. 8

TRANSFERING THE PRE-REQUISITE FILES TO HANA Use a file transfer tool, such as WinSCP to copy the SAPCrypto archive.sar file, the CA Root Certificate and the SAPCAR executable to the HANA Linux appliance. Place these files in the following locations, if these folders do not exist, create them (see below): sapcryptolib_36-10010845.sar sapcar_315-20010450.exe SAPNetCA.cer /usr/sap/<sid>/sys/global/security/lib/ /usr/sap/<sid>/sys/global/security/lib/ /usr/sap/<sid>/hdb<instance_nr>/<hostname>/sec/ De-Archiving the SAP Cryptographic Libraries Use SAPCAR to extract sapgenpse and libsapcrypto.so to /usr/sap/<sid>/sys/global/security/lib/, as shown below. Run the following command to de-archive sapcryptolib_36-10010845.sar: SAPCAR_0-10003690.exe -xvf SAPCRYPTOLIB_36-10010845.SAR Move libsapcrypto.so and sapgenpse files from: linux-x86_64-glibc2.3/ to /usr/sap/<sapsid>/sys/global/security/lib/ mv linux-x86_64-glibc2.3/*./* 9

CREATE THE SSL KEY PAIR AND CERTIFICATE REQUEST FILES Change to this directory: /usr/sap/<sid>/sys/global/security/lib cd /usr/sap/<sid>/sys/global/security/lib Add the directory containing the SAP Crypto libraries to your library path: export LD_LIBRARY_PATH=/usr/sap/<SAPSID>/SYS/global/security/lib Run sapgenpse, it will create two files, one in the sec/ directory and one in the current directory. The SAPSSL.req file is a certificate request file (an ASCII text file). The content of this file is to be sent to a certificate authority (CA). Other popular certificate authorities include VeriSign, DigiCert, GlobalSign, etc. The certificate authority signs the request and returns a file with the signed certificate. SAP also offers both free and fee-based CA services. Free testing/evaluation based for development or QA systems are available from https://service.sap.com/ssltest./sapgenpse get_pse -p SAPSSL.pse -x <PIN> -r SAPSSL.req "CN=<webdisp>, OU=<org_unit>, O=<company>, C=<country>" For the CN use the HANA System ID, as shown here:./sapgenpse get_pse -p SAPSSL.pse -x 1234 -r SAPSSL.req "CN=TST, OU=Support, O=SAP, C=CA" The contents of the SAPSSL.req file will look as follows (the body will be different): Copy this text as it will be needed in the next section. Send the Certificate Request to a Certificate Authority to be signed This guide will use a free evaluation certificate from SAP s website. Browse to http://service.sap.com/trust, and expand SAP Trust Center Services in Detail, and click SSL Test Server Certificates, and then click the Test it Now! button shown below: 10

Copy the text from SAPSSL.req file, and paste it into the Order SSL Server Test Certificate page shown here, choose the server type (other), and click the Continue button: SAP returns the signed certificate as text, copy this text and paste it into a file on the HANA db server: 11

/usr/sap/<sid>/hdb<instance_nr>/<hostname>/sec/sapssl.cer cd /usr/sap/<sid>/hdb<instance_nr>/<hostname>/sec vi SAPSSL.cer Paste in the text, save the SAPSSL.cer file. It is recommended to paste this text directly into a Linux text editor such as vi to avoid issues with differences in how MS Windows and Linux operating systems handled carriage returns and linefeeds. Import the Signed Certificate using sapgenpse Copy the sapgenpse file to /usr/sap/<sid>/hdb<instance_nr>/<hostname>/sec/ and import the certificate into the PSE. From the /usr/sap/<sid>/hdb<instance_nr>/<hostname>/sec/ run the following commands: 12

cp /usr/sap/<sid>/global/security/lib/sapgenpse../sapgenpse import_own_cert -c SAPSSL.cer -p SAPSSL.pse -x <PIN> -r SAPNetCA.cer MODIFY THE SAP WEB DISPATCHER PROFILE Add/modify the following parameters to the SAP Web Dispatcher profile (sapwebdisp.pfl), which can be found in the following location: /usr/sap/<sid>/hdb<instance_nr>/<hostname>/wdisp/ wdisp/shm_attach_mode = 6 wdisp/ssl_encrypt = 0 wdisp/add_client_protocol_header = 1 ssl/ssl_lib = /usr/sap/<sid>/sys/global/security/lib/libsapcrypto.so ssl/server_pse = /usr/sap/<sid>/hdb<instance_nr>/<hostname>/sec/sapssl.pse icm/https/verify_client = 0 icm/server_port_1 = PROT=HTTPS,PORT=$(_HTTPS_PORT),PROCTIMEOUT=600 Restart the HANA Web Dispatcher service Retrieve the process ID for the webdisp_hdb server: ps -ef grep <sid>adm Send a signal 2 to the service to restart it: sapcontrol -nr <instance_nr> -function SendSignal <process_id> 2 13

CONFIRMING HTTPS AND SSL ARE WORKING If everything is working as expected, then the SSL should be enabled. Confirm by looking to the dev_webdisp trace file for a success message (or error messages). [Thr 140442431035136] ================================================= [Thr 140442431035136] = SSL Initialization platform tag=(linuxx86_64_gcc43) [Thr 140442431035136] = (740_REL,May 13 2013,mt,ascii,SAP_UC/size_t/void* = 8/64/64) [Thr 140442431035136] DIR_INSTANCE="<hostname>" [Thr 140442431035136] DIR_LIBRARY="exe" [Thr 140442431035136] ssl/ssl_lib="/usr/sap/tst/sys/global/security/lib/libsapcrypto.so" [Thr 140442431035136] profile param "ssl/ssl_lib" = "/usr/sap/tst/sys/global/security/lib/libsapcrypto.so" [Thr 140442431035136] resulting Filename = "/usr/sap/tst/sys/global/security/lib/libsapcrypto.so" [Thr 140442431035136] = found SAPCRYPTOLIB 5.5.5C pl36 (Jul 3 2013) MT,AESNI,NB [Thr 140442431035136] = current UserID: "tstadm", env-var USER="tstadm" [Thr 140442431035136] = found SECUDIR environment variable [Thr 140442431035136] = using SECUDIR=/usr/sap/TST/HDB42/<hostname>/sec [Thr 140442431035136] ssl/server_pse="/usr/sap/tst/hdb42/<hostname>/sec/sapssl.pse" [Thr 140442431035136] profile param "ssl/server_pse" = "/usr/sap/tst/hdb42/<hostname>/sec/sapssl.pse" [Thr 140442431035136] resulting Filename = "/usr/sap/tst/hdb42/<hostname>/sec/sapssl.pse" [Thr 140442431035136] ssl/ciphersuites="193:high:medium:+e3des" [Thr 140442431035136] ssl/client_ciphersuites="192:high:medium:+e3des" [Thr 140442431035136] = secussl_create_ssl_ctx(): PSE "/usr/sap/tst/hdb42/<hostname>/sec/sapsslc.pse" not found, [Thr 140442431035136] = using PSE "/usr/sap/tst/hdb42/<hostname>/sec/sapssl.pse" as fallback [Thr 140442431035136] = secussl_create_ssl_ctx(): PSE "/usr/sap/tst/hdb42/<hostname>/sec/sapssla.pse" not found, [Thr 140442431035136] = using PSE "/usr/sap/tst/hdb42/<hostname>/sec/sapssl.pse" as fallback [Thr 140442431035136] ******** Warning ******** [Thr 140442431035136] *** No SSL-client PSE "SAPSSLC.pse" available [Thr 140442431035136] *** -- this might limit SSL-client side connectivity [Thr 140442431035136] ******** [Thr 140442431035136] = Success -- SapCryptoLib SSL ready! [Thr 140442431035136] ================================================= If the trace file shows success, then HTTPS is enabled, as shown: To avoid the certificate warning, client browsers can import the certificate by first clicking Continue to this website and then clicking the Certificate error and choosing to install the temporary certificate. 14

Binding ports less than 1024 for use with SSL (optional) If the port number for icm/server_port_1 is less than 1024 (e.g. 443 as shown above), it is required to include the EXTBND=1 and to follow the steps below to bind the server s listening port. Following the steps in this section is only required when binding SSL communication to a port less than 1024, as this requires superuser permissions and needs to be done by a super user such as root. Change the owner of the icmbnd command: chown root:sapsys icmbnd Change the permissions for the icmbnd command: chmod 4750 icmbnd Check the new permissions for the icmbnd command: ls al rwsr-x 1 root sapsys 1048044 Feb 13 16:19 icmbnd Bind the default SSL port to use. icmbnd -S <server port> -l <listen port> -p <protocol> TROUBLESHOOTING If you receive the error "Wrong or Missing PIN for PSE" upgrade to a later version of HANA (i.e. to SP6 or higher) to get a more recent version of HANA s web dispatcher. 15

www.sap.com 2015 SAP SE or an SAP affiliate company. 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 SE or an SAP affiliate company. SAP and other SAP products and services mentioned herein as well as their respective logos are trademarks or registered trademarks of SAP SE (or an SAP affiliate company) in Germany and other countries. Please see http://www.sap.com/corporate-en/legal/copyright/index.epx#trademark for additional trademark information and notices. Some software products marketed by SAP SE and its distributors contain proprietary software components of other software vendors. National product specifications may vary. These materials are provided by SAP SE or an SAP affiliate company for informational purposes only, without representation or warranty of any kind, and SAP SE or its affiliated companies shall not be liable for errors or omissions with respect to the materials. The only warranties for SAP SE or SAP affiliate company 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. In particular, SAP SE or its affiliated companies have no obligation to pursue any course of business outlined in this document or any related presentation, or to develop or release any functionality mentioned therein. This document, or any related presentation, and SAP SE s or its affiliated companies strategy and possible future developments, products, and/or platform directions and functionality are all subject to change and may be changed by SAP SE or its affiliated companies at any time for any reason without notice. The information in this document is not a commitment, promise, or legal obligation to deliver any material, code, or functionality. All forward-looking statements are subject to various risks and uncertainties that could cause actual results to differ materially from expectations. Readers are cautioned not to place undue reliance on these forward-looking statements, which speak only as of their dates, and they should not be relied upon in making purchasing decisions.