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

How to configure SSL for HANA XS Engine using SAP Crypto libraries

3

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

How to configure SSL for HANA XS Engine using SAP Crypto libraries

4

[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:

Note: A file transfer program such as WinSCP is also required to copy these files to the HANA appliance

How to configure SSL for HANA XS Engine using SAP Crypto libraries

5

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:

How to configure SSL for HANA XS Engine using SAP Crypto libraries

6

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:

How to configure SSL for HANA XS Engine using SAP Crypto libraries

7

Choose SAPCAR, as shown here:

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

How to configure SSL for HANA XS Engine using SAP Crypto libraries

8

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.

How to configure SSL for HANA XS Engine using SAP Crypto libraries

9

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 /usr/sap/<SID>/SYS/global/security/lib/

sapcar_315-20010450.exe /usr/sap/<SID>/SYS/global/security/lib/

SAPNetCA.cer /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/* ./*

How to configure SSL for HANA XS Engine using SAP Crypto libraries

10

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:

How to configure SSL for HANA XS Engine using SAP Crypto libraries

11

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:

How to configure SSL for HANA XS Engine using SAP Crypto libraries

12

/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:

How to configure SSL for HANA XS Engine using SAP Crypto libraries

13

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

How to configure SSL for HANA XS Engine using SAP Crypto libraries

14

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.

How to configure SSL for HANA XS Engine using SAP Crypto libraries

15

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.

© 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.

www.sap.com