Technology Blogs by SAP
Learn how to extend and personalize SAP applications. Follow the SAP technology blog for insights into SAP BTP, ABAP, SAP Analytics Cloud, SAP HANA, and more.
cancel
Turn on suggestions
Auto-suggest helps you quickly narrow down your search results by suggesting possible matches as you type.
Showing results for 
Search instead for 
Did you mean: 

Outbound httpS with HANA XS (part 1) - set up your HANA box to use SSL/TLS

kai-christoph_mueller
Participant
‎11-01-2013 11:31 PM

Intro

Hi everyone, welcome to my first blog!

It's the first one in a series, accompanying you on your journey with HANA. Starting with the basic setup of your HANA box to use in- and outbound HTTP calls via Secure Sockets Layer (SSL) / Transport Layer Security (TLS), the blogs will help you advance step by step until you end up designing and implementing a complete XS application that calls an external HTTPS service.

This is a rather advanced topic in the area of SAP HANA XS. Along the way, some of you may discover things you have not heard of before, such as .xsjs, .xshttpdest and trust stores. I will try to keep things as simple as possible and and will also keep trying to stimulate the appetites of XS newbies.  If you're hungry and looking for a good point to start from, you can try walking the Road to HANA for Software Developers, until you reach the REST for your Models on the SAP HANA XS vista point.

So let's get started with the encryption thing by first setting up your HANA box.

Prerequisites

Depending on your individual setup, you may need to get a larger or smaller number of files.  The basic requirement is to be able to download the SAP cryptographic library. For a more complex scenario involving a certification authority, you will also need the relevant root certificates.  In my example, I am simply leveraging the SAP infrastructure for this.

Files

I would have liked to provide all the necessary files in this blog.  Due to legal constraints, however, I'm unfortunately not allowed to do so. Nevertheless, it's fairly easy to get them at:

OS access

You need to be able to copy files to and access the HANA box as <sid>adm.

So, who is going to sign for this?

If you want to use https, you will usually need to deal with certification authorities and public key infrastructures (if you are completely new to this topic, please refer to other resources to get started).  Another (easier and often cheaper) way is to sign the certificates on your own.  While the external signing ensures real security (and that nice green status color in your browser without the need to resort to any hacks), the self-signing may be what you are looking for if you want to get your development environment up and running as quickly as possible.

I am going to provide shortcuts for setting it up either way. Nevertheless, here is the official documentation in case you're interested:

The easy way - self signing

You just want to set up your development box, but you don't have certificates of a CA (Certification Authority) or your very own CA?  Or maybe you just want to get it done on the fast track?  If so, this is the right place for you!

The following script (also attached), will do all the work for you. Just set some parameters at the beginning, copy the above mentioned files (in section 'Prerequisites') to the working folder on your HANA host and relax after starting the script.

So here is what you need to do:

  • Create a working folder containing the following files
    • setUpSapCryptoSelfSigned.sh (main execution script, see below or attachment)
    • sapgenpse
    • libsapcrypto.so

             

  • Edit the script and adapt the following parameters according to your needs
    • INSTANCE='<YOUR_HANA_SID>'
    • INSTNO='<YOUR_HANA_INST_NO>'
    • HOST='<YOUR_HANA_NETWORK_HOST_WITHOUT_DOMAIN>'
  • copy the folder to the HANA server, make the files readable and the script executable for <sid>adm
  • run the script as <sid>adm

This is what needs to be executed:

setUpSapCryptoSelfSigned.sh



#!/bin/bash

read -p 'You NEED to run this script as <sid>adm

&& you need to set the variables in the script

If this is not the case abort here (Ctrl+C)'

INSTANCE='<YOUR_HANA_SID>'

INSTNO='<YOUR_HANA_INST_NO>'

HOST='<YOUR_HANA_NETWORK_HOST_WITHOUT_DOMAIN>'

#example

#INSTANCE='TES'

#INSTNO='40'

#HOST='pall00539444a'

# bash does not provide DIR_SECURITY_LIB inside this subshell

DIR_SECURITY_LIB="/usr/sap/$INSTANCE/SYS/global/security/lib"

cp libsapcrypto.so $DIR_SECURITY_LIB

cp sapgenpse $DIR_SECURITY_LIB

mkdir $SECUDIR

# Create the trust store files

$DIR_SECURITY_LIB/sapgenpse gen_pse -p $SECUDIR/sapsrv.pse -x '' "CN=${HOST}"

$DIR_SECURITY_LIB/sapgenpse gen_pse -p $SECUDIR/sapcli.pse -x '' "CN=${HOST}"

$DIR_SECURITY_LIB/sapgenpse gen_pse -p $SECUDIR/SAPSSL.pse -x '' "CN=${HOST}"

echo "Please note that all of these PSE files are self signed. In a productive scenario you would have to sign them by a CA."

echo "Going to update Web dispatcher profile and restarting that process"

echo "

wdisp/ssl_encrypt = 0

ssl/ssl_lib = /usr/sap/$INSTANCE/SYS/global/security/lib/libsapcrypto.so

ssl/server_pse = SAPSSL.pse

icm/HTTPS/verify_client = 0

icm/HTTPS/forward_ccert_as_header = true

" >>  /usr/sap/$INSTANCE/HDB$INSTNO/$HOST/wdisp/sapwebdisp.pfl

kill -9 `pidof sapwebdisp_hdb`

kill -9 `pidof hdbxsengine`

echo "Now you may proceed with setting up your XS applications as described at

http://help.sap.com/hana/SAP_HANA_Developer_Guide_en.pdf

(Chapter 3.6 - maintaining application security)'

"

echo "You can check whether the https setup was successfull via

https://$HOST:43$INSTNO/sap/hana/xs/admin/

- you may need to wait a little bit for a restart of some processes

- you need the according roles

check: Go to the trust manager. If there is no error message on the bottom of the screen you are all setup."

# DEBUGGING

#

# Reset the system (pls adapt the wdisp.pfl on your own (not a must))

# rm -f $DIR_SECURITY_LIB/*; rm -f $SECUDIR/*; kill -9 `pidof sapwebdisp_hdb`; kill -9 `pidof hdbxsengine`

#

#  Troubleshooting SSL for HANA/XS

#

    # check the traces (dev_wdisp and xsengine) for errors (either via HANA Studio > Administration perspective > Diagnosis Files or in /usr/sap/<SID>/HDB<instno>/<host>/trace).

    # increase the trace-level for the HDB Web Dispatcher by adding icm/log_level = <level> (e.g. 2) to sapwebdisp.pfl in /usr/sap/<SID>/HDB<instno>/<host>/wdisp.

    # increase the trace level: In HANA Studio, Administration perspective > Trace Configuration, Edit Configuration for "Database Trace" and change XSENGINE to e.g. INFO.

#Troubleshooting SSL for HANA/XS

# In HANA Studio, open the Administration perspective for the HANA system and set the following configuration parameters in indexserver.ini, section communication:

# sslcryptoprivder = sapcrypto

# sslkeystore = /usr/sap/<SID>/HDB<instno>/<host>/sec/SAPSSL.pse

# ssltruststore = /usr/sap/<SID>/HDB<instno>/<host>/sec/SAPSSL.pse

# sslvalidatecertificate = false

# sslvalidatecertificate should be set to false, as most of the internal systems won't resolve the hostnames properly.

That's it.

As the script already told you, you can check if https is working by opening the following URL in your browser (please mind the s in https and the changed port😞

https://<yourHostName>:43<InstanceNumber>

You should now see something like:

using Firefox

using Chrome

After adding a security exception (via 'I understand the risks' or 'Proceed anyway' - depending on your browser) you most likely will discover the XS engine welcome screen:

Don't be surprised if your browser does not trust that    connection - you did sign the certificates yourself. If you don't like this, just go on with the next (optional) sub-chapter.

In any case, inbound https should be up and running now.  :smile:

Would you like to watch this whole process in a video?  Here you go:

Hacking that red status (optional)

If that red status annoys you, I can show you how to get rid of it.  But it is a hack of sorts, so just don't tell anyone about it.  It does have some security drawbacks and it most likely has to be done for every user.

In a nutshell:

    Export the certificate via your browser and import it as a trusted root certificate.

Using Chrome, this can be done via:

Export

  • click the red symbol
  • tab: connection
  • 'certificate information'
  • tab: Details
  • button: copy to file

  Import

Depending on your cache settings, you should be able to just restart Chrome and see the green icon.

The delegated way - ask the CA to sign it

Ok, so you already have a connection to a CA, are not too happy about the red symbols in your browser and dislike the hack above due to its security drawbacks? Furthermore, you're familiar with the whole security thing, or at least know someone who is and who owes you a favor?  Fine, so let's go ahead and use that CA infrastructure to become more secure and make sure you're really communicating with whom you think you should be!

The following script is an enhanced version of the script above. At least, it's enhanced with regards to some setup aspects and the interactive signing question.

You will be asked to have your created certificates be signed by a CA while the script is running.  If you need to have an external CA sign them, then I recommend running the script steps manually. In general, this may be the safer option. I have only been looking at the SAP internal frontend, and I'm sure most frontends will look different and the certificate names might also be different. Anyway. I hope the basic steps can help you get the installation up and running.

Regarding the configuration described above, you will additionally have to perform the following steps:

  • have to copy the SAPNetCA.cer root certificate (or the root certificate, you plan to use) into your working folder

         

  • configure additional parameters at the beginning of the script:
    • INSTANCE='<YOUR_HANA_SID>'
    • SIDADM='<YOUR_HANA_SIDADM>'
    • INSTNO='<YOUR_HANA_INST_NO>'
    • HOST='<YOUR_HANA_NETWORK_HOST>'
    • DOMAIN='<YOUR_HANA_NETWORK_DOMAIN>'
    • ORG='<YOUR_CERTIFICATE_ORGNANIZATION>'
    • COUNTRY='<YOUR_CERTIFICATE_COUNTRY>'
  • leave the PIN unset (see the next sub chapter for details)
    • PIN=''

NOTE: if you are using root certificate other than SAPNetCA.cer, then you will need to adapt the script accordingly.

Once you're done with all these steps, you can then go ahead and execute the ..CA.. script.

setUpSapCryptoCAsigned.sh



#!/bin/bash

read -p 'You NEED to run this script as <sid>adm

&& you need to set the variables in the script

If this is not the case abort here (Ctrl+C)'

#INSTANCE='<YOUR_HANA_SID>'

#SIDADM='<YOUR_HANA_SIDADM>'

#INSTNO='<YOUR_HANA_INST_NO>'

#HOST='<YOUR_HANA_NETWORK_HOST>'

#DOMAIN='<YOUR_HANA_NETWORK_DOMAIN>'

#ORG='<YOUR_CERTIFICATE_ORGNANIZATION>'

#COUNTRY='<YOUR_CERTIFICATE_COUNTRY>'

#example

#INSTANCE='TES'

#SIDADM='tesadm'

#INSTNO='40'

#HOST='pall00539444a'

#DOMAIN='pal.sap.corp'

#ORG='SAP'

#COUNTRY='DE'

# PIN does not increase security significantly and it's not possible to load the certificate into memory with one being set

PIN=''

# bash does not provide DIR_SECURITY_LIB inside this subshell

DIR_SECURITY_LIB="/usr/sap/$INSTANCE/SYS/global/security/lib"

cp libsapcrypto.so $DIR_SECURITY_LIB

cp sapgenpse $DIR_SECURITY_LIB

cp SAPNetCA.cer $DIR_SECURITY_LIB

mkdir $SECUDIR

##########################################

# sapssl

##########################################

# Create the SSL key pair and the certificate request in $SECUDIR

# This creates the Personal Security Environment (SAPSSL.pse) and the corresponding certificate request (SAPSSL.req).

$DIR_SECURITY_LIB/sapgenpse get_pse -p $SECUDIR/SAPSSL.pse -x $PIN -r $SECUDIR/SAPSSL.req "CN=${HOST}.${DOMAIN}, OU=${INSTANCE}, O=$ORG, C=$COUNTRY"

cat $SECUDIR/SAPSSL.req

read -p "

Now go to your signing CA (SAP also offers CA services where you can have test certificates signed instantly at

        http://service.sap.com/Trust

        https://websmp106.sap-ag.de/SSLTest

) and sign the certificate.

In the SAP in house case it works like this:

    - Go to https://secsrvtest.wdf.sap.corp/TCS/cgi-bin/secuWPCA.pl

    - paste the content from SAPSSL.req (printed above) to the text area

    - leave SAPNetCA as CA

    - select 'certify the cert. req.' as command

    - submit

    - Copy the resulting certificate from the output (everything including -----BEGIN CERTIFICATE----- and -----END CERTIFICATE-----)

      to a new text file (here: SAPSSL.cert) and save it to '$SECUDIR'

      ( here: $SECUDIR/SAPSSL.cert ) .

    -> Hit <ENTER> when finished

"

#Import the certificate into the PSE:

$DIR_SECURITY_LIB/sapgenpse import_own_cert -c $SECUDIR/SAPSSL.cert -p $SECUDIR/SAPSSL.pse -x $PIN -r $DIR_SECURITY_LIB/SAPNetCA.cer

#Create a Credential File to enable access for HDB (which runs as <sid>adm) to the PSE: Use

$DIR_SECURITY_LIB/sapgenpse seclogin -p $SECUDIR/SAPSSL.pse -x $PIN -O $SIDADM

# and make the credentials file read only for <sid>adm

chmod 600 $SECUDIR/cred_v2

##########################################

# sapsrv

##########################################

$DIR_SECURITY_LIB/sapgenpse get_pse -p $SECUDIR/sapsrv.pse -x '' -r $SECUDIR/sapsrv.req "CN=${HOST}.${DOMAIN}, OU=${INSTANCE}, O=$ORG, C=$COUNTRY"

cat $SECUDIR/sapsrv.req

read -p "

Now go to your signing CA (SAP also offers CA services where you can have test certificates signed instantly at

        http://service.sap.com/Trust

        https://websmp106.sap-ag.de/SSLTest

) and sign the certificate.

In the SAP in house case it works like this:

    - Go to https://secsrvtest.wdf.sap.corp/TCS/cgi-bin/secuWPCA.pl

    - paste the content from sapsrv.req (printed above) to the text area

    - leave SAPNetCA as CA

    - select 'certify the cert. req.' as command

    - submit

    - Copy the resulting certificate from the output (everything including -----BEGIN CERTIFICATE----- and -----END CERTIFICATE-----)

      to a new text file (sapsrv.cert) and save it to '$SECUDIR'

      ( $SECUDIR/sapsrv.cert ) .

    -> Hit <ENTER> when finished

"

#Import the certificate into the PSE:

$DIR_SECURITY_LIB/sapgenpse import_own_cert -c $SECUDIR/sapsrv.cert -p $SECUDIR/sapsrv.pse -r $DIR_SECURITY_LIB/SAPNetCA.cer

#Create a Credential File to enable access for HDB (which runs as <sid>adm) to the PSE: Use

$DIR_SECURITY_LIB/sapgenpse seclogin -p $SECUDIR/sapsrv.pse -x $PIN -O $SIDADM

##########################################

# sapcli.pse

##########################################

$DIR_SECURITY_LIB/sapgenpse gen_pse -p $SECUDIR/sapcli.pse -x '' "CN=${HOST}.${DOMAIN}, OU=${INSTANCE}, O=$ORG, C=$COUNTRY"

##########################################

# Configure the HDB Web Dispatcher for SSL

##########################################

echo "

wdisp/ssl_encrypt = 0

ssl/ssl_lib = /usr/sap/$INSTANCE/SYS/global/security/lib/libsapcrypto.so

ssl/server_pse = SAPSSL.pse

icm/HTTPS/verify_client = 0

icm/HTTPS/forward_ccert_as_header = true

" >>  /usr/sap/$INSTANCE/HDB$INSTNO/$HOST/wdisp/sapwebdisp.pfl

kill -9 `pidof sapwebdisp_hdb`

kill -9 `pidof hdbxsengine`

echo "Now you may proceed with setting up your XS applications as described at

http://help.sap.com/hana/SAP_HANA_Developer_Guide_en.pdf

(Chapter 3.6 - maintaining application security)'

"

echo "You can check whether the https setup was successfull via

https://$HOST$DOMAIN:43$INSTNO/sap/hana/xs/admin/

- you may need to wait a little bit for a restart of some processes

- you need the according roles

check: Go to the trust manager. If there is no error message on the bottom of the screen you are all setup."

# DEBUGGING

#

# Reset the system (pls adapt the wdisp.pfl on your own (not a must))

# rm -f $DIR_SECURITY_LIB/*; rm -f $SECUDIR/*; kill -9 `pidof sapwebdisp_hdb`; kill -9 `pidof hdbxsengine`

#

#  Troubleshooting SSL for HANA/XS

#

    # check the traces (dev_wdisp and xsengine) for errors (either via HANA Studio > Administration perspective > Diagnosis Files or in /usr/sap/<SID>/HDB<instno>/<host>/trace).

    # increase the trace-level for the HDB Web Dispatcher by adding icm/log_level = <level> (e.g. 2) to sapwebdisp.pfl in /usr/sap/<SID>/HDB<instno>/<host>/wdisp.

    # increase the trace level: In HANA Studio, Administration perspective > Trace Configuration, Edit Configuration for "Database Trace" and change XSENGINE to e.g. INFO.

#Troubleshooting SSL for HANA/XS

# In HANA Studio, open the Administration perspective for the HANA system and set the following configuration parameters in indexserver.ini, section communication:

# sslcryptoprivder = sapcrypto

# sslkeystore = /usr/sap/<SID>/HDB<instno>/<host>/sec/SAPSSL.pse

# ssltruststore = /usr/sap/<SID>/HDB<instno>/<host>/sec/SAPSSL.pse

# sslvalidatecertificate = false

# sslvalidatecertificate should be set to false, as most of the internal systems won't resolve the hostnames properly.

After following the interactive part of the script and making sure the whole process has executed successfully, you should see a green status on your https connection (assuming you have also installed the relevant root CA into your browser):

Do you prefer to see these steps in a video?  Here you go:

Using a PIN for the Trust Stores

Using a PIN for the Trust Stores is not a good idea. This is because the PIN mechanism works on file system level and once the Trust Store gets loaded into memory it is not possible to unlock a Trust Store anymore. As there furthermore is no great benefit in enhanced security I highly recommend not to set one at all.

Check the installation

To finally verify that you have not only successfully installed SSL but also maintained the trust store relations in the correct way, you should do the following:

If you do not see this:

Then everything is fine :smile:

Debugging

If you have issues running the script, you can find more information on how to wipe the stuff you just did at the end of each script. You'll also find some hints on how to set trace levels for analyzing more hard-to-find issues.  Then, of course, there's also the official documentation....

Last words

So that was easy, wasn't it? :wink:

Honestly, I really hope things worked out for you as smoothly as they did for me. The CA signing setup is not an easy thing to do and remote support might be very hard (are you happy providing me with your <sid>adm user?).  Nevertheless, I'm happy to help in any way that I can.

Ready to use this setup?

Check out the followup blog available at:

Outbound httpS with HANA XS (part 2) - set up the trust relation

DISCLAIMER:

Please be aware that several processes will be restarted during the script execution (the hard way).  This might disturb others also working on the same box.

These scripts have run smoothly wherever they were tested. Nevertheless, you should be aware of what you are doing and are fully responsible for any side effects to your own system. Good luck! :wink:

34 Comments
Labels in this area
Popular Blog Posts