Skip to Content
Technical Articles
Author's profile photo Jens Gleichmann

HANA secure network communication – part II

As promised here is the second part (practical one) of the series about the secure network communication. Please use part one for the knowledge basics.

  1. Scenarios [part I]
    1. Client & HANA Cockpit communication
    2. SolMan Communication
    3. AS ABAP
  2. JDBC/ODBC/SQLDBC [part I]
  3. Term clarification [part I]
  4. Create and sign certificate [part II]
  5. Import certificate to HANA Cockpit (for client communication) [part II]
  6. Import certificate to HANA resource(s) [part II]
  7. Configure clients (AS ABAP, ODBC, etc.) to use SSL [part II]
  8. Configure HDB parameters for high security [part II]
  9. Configure XSA with TLS and cipher for high security [part II]
  10. Import certificate to host agent [part II]
  11. Pros and Cons certification collections [part II]

4. Create and sign certificate

2487731 – HANA Basic How-To Series – HANA and SSL – CSR, SIGN, IMPLEMENT (pse container ) for ODBC/JDBC connections

Command:

sapgenpse get_pse -p <PSE_Name> -r <cert_req_file_name> -k <more options for SAN>
sapgenpse gen_pse -p cert.pse -r csr.txt -k GN-dNSName:<HOSTNAME incl. FQDN> "CN=<HOSTNAME incl. FQDN>, O=<organization>, C=<country>"

Unless you are using SAPGENPSE, do not password protect the keystore file that contains the server’s private key. If you use a PIN/passphrase keep in mind that you have to use sapgenpse seclogin option to create the cred_v2 file inside the SECUDIR:

sapgenpse seclogin -p <full path to pse> -x <passphrase> -O <sidadm> -v

It is possible to use multiple SANs:

-k <name>       Add Subject Alternative Names to the certification request.
                 Multiple -k <name> parameters are supported to create a list
                 of alternative names in the request.
                 If the type of the name is not derivable, the respective prefix
                 must be given:
                  'GN-rfc822Name:', 'GN-dNSName:', 'GN-uRI:',
                  'GN-iPAddress:', 'GN-directoryName:', 'GN-registeredID:'
                 Syntax to specify a name of type 'otherName':
                   GN-otherName:<oid>:<valueType>:<value>
                    oid      : 'UPN' or object identifier (1.2.840...)
                    valueType: Encoding type of value
                               'HEX': value is hex string of ASN.1 DERCode
                               'UTF8String': value will be encoded as UTF8String
                    value    : Name value (hex ASN.1 DERCode or string)
                 Examples:
                  -k GN-dNSName:www.sap.com
                  -k GN-iPAddress:127.0.0.1
                  -k GN-otherName:UPN:UTF8String:john.doe@sap.com
                  -k GN-otherName:1.3.6.1.4.1.694.2.2.2.444:HEX:0403020507

 

Sign the certificate signing request with a trusted Certificate Authority (CA) as pkcs7 which will include all CA certificates.

cp cert.pkcs7 cert.p7b
sapgenpse import_own_cert -p cert.pse -c cert.p7b

 

SAP recommendation:

“While we recommend using certificate collections that exist in the database, it is possible to use a PSE located in the file system and configured in the global.ini file.”

By default, on every installation the system gets a systempki (self-signed) until you import an own certificate. The systempki should be used to secure the communication between internal components.

global.ini: Set inside the section [communication] ssl from ‘off’ to ‘systempki’

[communication]
ssl = systempki

 

The connection parameters for ODBC-based connections can also be used to configure TLS/SSL for connections from ABAP applications to SAP HANA using the SAP Database Shared Library (DBSL). To pass the connection parameters to the DBSL, use the following profile parameter:

dbs/hdb/connect_property = param1, param2, …., paramN

Details:

https://help.sap.com/viewer/b3ee5778bc2e4a089d3299b82ec762a7/2.0.04/en-US/0ae2b75266df44499d8fed8035e024ad.html


5. HANA Cockpit

a) Export the keys in PKCS#12 transfer format:

sapgenpse export_p12 -p sapsrv.pse sapsrv.p12

b) Create a key file:

openssl pkcs12 -nodes -nocerts -in sapsrv.p12 -out sapsrv.key

c) Create a certificate file:

openssl pkcs12 -nodes -nokeys -in sapsrv.p12 -out sapsrv.pem

The HANA DB has to be online. The XSA can be offline, but will be restarted (thanks for the hint Dennis). I recommend this method, but you can also use the “online one” (xs set-sertificate) but here you have to follow more steps and at the end you have to restart the XSA. So, the easiest way is to use the XSA set-certificate command:

XSA set-certificate --cert /usr/sap/<SID>/HDB<instance-no>/<host>/sec/sapsrv.pem --key /usr/sap/<SID>/HDB<instance-no>/<host>/sec/sapsrv.key

Check it via:

xs login
xs domains

 

xs trusted-certificates
  • Won’t list the imported certificate

 

xs domains
  • Will show your certificate for your domain(s)

Afterwards check your system with the diagnose function

XSA diagnose

If you receive such an error, just renew the db trust:

XSA renew-db-trust

 

global.ini: Set inside the section [communication] ssl from ‘off’ to ‘systempki’ (default for XSA systems)

[communication]
ssl = systempki

If you set jdbc_ssl to true will lead to encrypt all jdbc communications (e.g. HANA database explorer) with all connected HANA resources! Only set this to true if you have configured all resources with SSL. By default, this enables security and forces all resources to use ssl.

alter system alter configuration ('xscontroller.ini','SYSTEM') set ('communication','jdbc_ssl') = 'true' with reconfigure;

You can use the same procedure for every other XSA installation. But keep in mind that jdbc_ssl parameter has no effect for Node.js applications! (more details in 8.)

 

Result: You have activated the SSL certificate for the HANA Cockpit. The clients can now connect via HTTPS to the HANA Cockpit.

 


6. HANA resource

  1. Shut down the system
  2. Check the certificate: sapgenpse get_my_name -p cert.pse
  3. Replace the sapsrv.pse, SAPSSLS.pse and SAPSSLC.pse with the created cert.pse
  4. Restart the system

Once again from part I which PSE is used for which service:

Source: SAP

SECUDIR=/usr/sap/<SID>/HDBxx/<hostname>/sec

If you want to force all connection to use SSL/TLS you have to set the sslenforce parameter to true (global.ini).

[communication]
sslEnforce = true

 

This means:

  • the application server connection via SQLDBC have to set up to be secure
  • HANA Cockpit connections have to set up to be secure
  • Local hdbsql connections have to be set up for encryption

It is also possible to create one certificate per tenant.

Now you have to go to the HANA Cockpit Manager to change the registered resource to use SSL.

Result: The database will trust all other certificates in the same domain which includes the HANA cockpit. All communications can now be established via SSL. The current status of encryption of the communication is optional not obligatory. All incoming communications can still be unencrypted! (more: Configure HDB for high security)

 


7. Configure clients (AS ABAP, hdbsql, ODBC, etc.) to use SSL

7.1 AS ABAP

There is already a blog about this configuration:

https://blogs.sap.com/2014/01/17/configure-abap-to-hana-ssl-connection/
1761693 – Additional CONNECT options for SAP HANA
2475246 – How to configure HANA DB connections using SSL from ABAP instance

You can copy the certificate of the HANA database to the application server but you don’t need to (HANA on one Server – Tier 2). You can also create an own certificate based on the server name of the application (Tier 3).

You just have to set the dbs/hdb/connect_property parameter to the correct value:

dbs/hdb/connect_property=ENCRYPT=TRUE,sslCryptoProvider=commoncrypto,sslKeyStore=/usr/sap/<SID>/HDBxx/<hostname>/sec/SAPSSLC.pse,sslTrustStore=/usr/sap/<SID>/HDBxx/<hostname>/sec/SAPSSLC.pse

 

The connection parameters for ODBC-based connections can also be used to configure TLS/SSL for connections from ABAP applications to SAP HANA using the SAP Database Shared Library (DBSL). To pass the connection parameters to the DBSL, use the following profile parameter:

dbs/hdb/connect_property = param1, param2, …., paramN

 

In some cases, you may receive an error if you force the use of TLS/SSL:

SQLERRTEXT : Connection failed (RTE: [300015] SSL certificate validation failed: host name ’10.xxx.xxx.xxx’ does not match names in certificate

severe db error -10709; work process is stopped

sql error -10709 performing CON

 

You have to set some tricky parameter due to the default gateway of the Linux server.

There are 3 different solutions:

  1. sslValidateCertificate = false => will not validate the certificate
  2. sslHostNameInCertificate = <vhostname> => will overwrite the calling hostname
  3. configure the hostname mapping inside the HANA

 

Solution 1

dbs/hdb/connect_property=ENCRYPT=TRUE,sslValidateCertificate=false,sslCryptoProvider=commoncrypto,sslKeyStore=/usr/sap/<SID>/HDBxx/<hostname>/sec/SAPSSLC.pse,sslTrustStore=/usr/sap/<SID>/HDBxx/<hostname>/sec/SAPSSLC.pse

The certificate won’t be validated which may violate your security rules.

Solution 2

dbs/hdb/connect_property=ENCRYPT=TRUE,sslHostNameInCertificate=<vhostname>,sslCryptoProvider=commoncrypto,sslKeyStore=/usr/sap/<SID>/HDBxx/<hostname>/sec/SAPSSLC.pse,sslTrustStore=/usr/sap/<SID>/HDBxx/<hostname>/sec/SAPSSLC.pse

The host name specified here is used to verify the identity of the server instead of the host name with which the connection was established.

Solution 3

global.ini

[public_hostname_resolution]
use_default_route=fqdn
map_<host_short_name>=<host_long_name>
map_<host_physical_short_name>=<host_long_name>

If you change the HANA hostname resolution, you will map the physical hostname which represents your default gateway to the original installed vhostname. For details how this is working, read this blog.

The cleanest way is the Golden middle – option 2. Please keep in mind to configure the correct default gateway with ‘is/local_addr’ for stateful firewall connections. (details see part I)

Result: Your ABAP application server now connects via TLS/SSL.

 


 

7.2 hdbsql

Here we talk about the client within the HANA client executable. Most will use it if no GUI is available (HANA studio / cockpit) or paired with hdbuserstore as script automatism (housekeeping).

Here it is pretty simple one option is to define manually some command line options:

  • hdbsql -e (forces using the encryption)
  • the other one to copy the sapsrv.pse to the sapcli.pse

cp /usr/sap/SID/HDB00/hostname/sec/sapsrv.pse /usr/sap/SID/HDB00/hostname/sec/sapcli.pse

connect string to skip hostname validation:

hdbsql -U <hdbuserstore key> -e -ssltrustcert

As always you can create an own certificate for the client and copy it to sapcli.pse instead of using the server sapsrv.pse.

But still some more options e.g. -ssltrustcert have to be added to the call.

Result: Your hdbsql connection will be now encrypted via SSL.

 

Details:

 


8. Configure HDB for high security

2300943 – Enabling SSL encryption for database connections for SAP HANA extended application services, advanced model

2487639 – HANA Basic How-To Series – HANA and SSL – MASTER KBA

# SSL for internal communication
ssl = on/systempki
# Enforce clients to connect only with valid certificate. 
sslEnforce=true
# XS advanced version < 1.0.82: This property tells SAP HANA XS advanced services and applications to open SSL encrypted connection to the SAP HANA database. 
# The default value is "false". 
jdbc_ssl=true
# Since XS advanced version 1.0.82, this property defaults to "true", if the database is configured to enforce SSL connections. Otherwise, the default is "false".  
hana_ssl = true
# XS advanced version < 1.0.82:  This property can be used to enable or disable validation of the certificate for SSL encrypted connection to the SAP HANA database. 
# This property takes only effect for SAP HANA XS advanced services and Java applications. 
# It has no effect for Node.js or XSJS applications. The default value is "false". 
jdbc_ssl_validate_certificate = true
# Since XS advanced version 1.0.82
hana_ssl_validate_certificate = true
# XS advanced version < 1.0.82: This property can be used to override the hostname, which is used during hostname validation of the SSL encrypted connection to the SAP HANA database. 
# This property takes only effect for SAP HANA XS advanced services and Java applications. 
# It has no effect for Node.js or XSJS applications.
jdbc_ssl_certificate_hostname = 
# Since XS advanced version 1.0.82
hana_ssl_certificate_hostname = 
# minimum available SSL protocol version: SSL30,TL10,TLS11,TLS12
sslMinProtocolVersion = TLS12
# maximum available SSL protocol version: TL10,TLS11,TLS12,MAX
sslMaxProtocolVersion = MAX
# values: commoncrypto (default), openssl, mscrypto
sslCryptoProvider = commoncrypto
# key store file used for external communication
sslKeyStore = sapsrv.pse
# trust Store file used for external communication
sslTrustStore = sapsrv.pse
# validate the cetificate of the communication partner during external communication (default: false) => set to true if possible
sslValidateCertificate = true
# For each porpuse in this list, the in-memory PSE store is omitted and the file-based PSE store is used
# Possible values are : JWT, SAML, SAP LOGON, SSL, X509, JWT
skip_in_memory_pse_store_for_purpose =
# SSL for internal communication over localhost
ssl_local = on
# Choose available ciphersuites (default: commoncrypto: PFS:HIGH::EC_HIGH:+EC_OPT openssl: ALL:!ADH:!LOW:!EXP:!NULL:@STRENGTH)
sslciphersuites = PFS:HIGH::EC_P256:EC_HIGH

Be careful with setting these parameters! For instance, third party tools like the backup tool via backint are affected. Check if your vendor supports SSL. Check all connecting interfaces for it.

Attention: With XSA 1.0.82 (begin of 2018), SAP introduced new parameters (Check note 2300943). However, newer XS advanced versions still can process these legacy properties. Check XSA runtime version with ‘xs login; xs version’

 

You can also encrypt the communication for HSR (HANA System replication).

Tip: Create a security configuration template (HANA Cockpit) for all your databases to apply changes pretty fast.

 

Result: You have forced all communication channels to use SSL. All incoming connections must use it or will be dropped.

 


9. Configure XSA with TLS and cipher for high security

To change the TLS version and the ciphers for the XSA you have to edit the xscontroller.ini

Details: official docucumentation

xscontroller.ini

[router]
#Default: 
Router.WebDispatcher.CipherSuites = 135:PFS:HIGH:TLS_FALLBACK_SCSV::EC_P256:EC_HIGH
#TLS only:
Router.WebDispatcher.CipherSuites = 544:PFS:HIGH::EC_P256:EC_HIGH

##544
#512 ("TLSv1.2") + 32 ("Strict protocol version configuration option")

##PFS
#Indicates that Perfect Forward Secrecy (PFS) cipher suites are to be used

##HIGH
#Indicates the security class of the cipher suite(s) to be used

##EC_*
#The configuration settings for “Elliptic Curve” (EC) cryptography, for example, the key length (EC_P256) and the security class (EC_HIGH)

 

Check with sapgenpse

# Default is "PFS:HIGH::EC_HIGH:+EC_OPT"
sapgenpse tlsinfo PFS:HIGH::EC_HIGH:+EC_OPT

 

# min. protocol TLS 1.2 without CBC
sapgenpse tlsinfo "550:PFS:HIGH:!eAES256_CBC:!eAES128_CBC::EC_HIGH:+EC_OPT"

Description: sapgenpse tlsinfo

 


10. SAP Host Agent

There is already a blog post in place covering this topic. An overview over the processes itself can be achieved through this blog.

Check also the official documentation.

  1. Create the certificate on base of the vhostname of the server
  2. Copy the *.pse as SAPSSLS.pse to /usr/sap/hostctrl/exe/sec/
  3. use sapgenpse seclogin option as root (with proper environment – means SECUDIR variable) when you have specified a PIN/passphrase
  4. set ssl/server_pse= <Path to Server PSE> inside the host_profile
  5. Restart the hostagent

Tip: use the integrated port reservation of the Host agent for all of your services

/usr/sap/hostctrl/exe/host_profile

reserved_port/product_list = HANA,XSA

Possible values are: HANA,HANAREP,XSA,ABAP,J2EE,SUITE,ETD,MDM,SYBASE,MAXDB,ORACLE,DB2,TREX,CONTENTSRV,BO,B1

Check SAP Note 401162 for details:

401162 – Linux: Avoiding TCP/IP port conflicts and start problems

 

Check also the saphostctrl functionality for the monitoring:

/usr/sap/hostctrl/exe/saphostctrl -function GetDatabaseSystemStatus -dbname SYSTEMDB@InstanceName -dbtype hdb

 

Details:

2621457 – hdbconnectivity failure after upgrade to 2.0

2629520 – Error : “hdbconnectivity (HDB Connectivity), Status: Error (SQLconnect not possible (no hdbuserstore entry found))” While SAP Host Agent is not working correctly – Solution Manager 7.2

Managed systems maintenance guide – preparing databases


11. Pros and Cons certification collections

There are two possibilities to store the certificates:

  • file based => PSE
  • inside the database => certificate collection

Due to the flexiblity there are some advantages (copy move of databases) in the newer solution (certificate collection), but if you have to update 100 HANA instances with new certificate every 2 years it can be easier to use the file based solution. Here you can reuse your current automatism for updating them.

 

Source: SAP

 


Summary

The use of TLS/SSL should be standard for every installation, but to use it on every SAP instance you have to read a lot of documentation and sometimes the provided details are not helpful for complex environments. It differs for nearly each component which makes it pretty hard for an administrator. Another thing is the maintainability of the certificates. Here your should consider a standard automatism. To set it up is one task, to maintain and operate it another.

I hope this little summary is helping you to understand the relations and avoid some errors and long researches.

 

Stay healthy,
-Jens (follow me on Twitter for more geeky news @JensGleichmann)

########
# Edit
# 2020/4/15 Inserted Vitaliys blog link + XSA diagnose details
# 2021/03/18 Inserted XSA high security – Kudos out to Patrick Heynen
# Inserted new parameters from 2300943
# 2021/04/06 Inserted possibility for multiple SAN in one request / certificate with sapgenpse
# 2021/04/26 added PIN/passphrase option for sapgenpse seclogin
# 2021/09/09 updated parameter info: is/local_addr thx @ Matthias Sander for the hint
########

Assigned Tags

      7 Comments
      You must be Logged on to comment or reply to a post.
      Author's profile photo Sumit Jaiswal
      Sumit Jaiswal

      Hi Jens,

      Wonderful information in a couple of blogs!!

      Though it's definitely not easy to go with so much secure setup for even an average complex landscape, hoping there will be a day when there would be a single instance for everything and  hits on this blog would go sky-high 🙂

      Author's profile photo Witalij Rudnicki
      Witalij Rudnicki

      I just published mine https://blogs.sap.com/2020/04/14/secure-connection-from-hdbsql-to-sap-hana-cloud/ and now seeing yours 🙂 But where you use -sslcertrust I dig deeper how to make sure HANA server authentication works from hdbsql 😀

      Author's profile photo Jens Gleichmann
      Jens Gleichmann
      Blog Post Author

      Great post Vitaliy! I haven't seen it yet, but I will link it in this post.The hdbsql connect in this blog was just a side effect which I have tested due to script automatism when forcing ssl 🙂

      If you copy your certificate to sapcli.pse inside your SECUDIR you won't have to add it to the hdbsql command. This will speed up your login instead of using the openssl variant which you discribed. It's a hidden feature which should be more visible for customers.

      Author's profile photo Anand Tigadikar
      Anand Tigadikar

      Thanks a lot for sharing this , it's a excellent blog 😉

      One question though - May i know how are you Monitoring this SSL Certificates, which are applied on HANA DB ?

      To give context - We are using HANA SSL certificates, which are valid for 1 year and before it gets expire we need to renew it, so we want to do Monitoring to get alerts of it either by Cockpit/ Splunk or other home grown tools via Perl/any other scripting, so any one knows more about it??

      Author's profile photo Jens Gleichmann
      Jens Gleichmann
      Blog Post Author

      You can use the SQL script collection from note 1969700 to do this.

      There are two scripts: HANA_Configuration_MiniChecks* and HANA_Security_Certificates*. You can also select directly the system view PSE_CERTIFICATES.

      More details => documentation

       

      Regards,

      Jens

      Author's profile photo Johannes Goerlich
      Johannes Goerlich

      Hello Jens,

      thank you for this very valuable blog series!

      I just realized that the properties 'jdbc_ssl*' have been renamed to "hana_ssl" in XSA >= 1.0.82. This is mentioned as a little note in SAP note 2300943 section 4. Not sure up to which revision the "legacy" properties will work.

      Best Regards

      Joe

      Author's profile photo Remi ASTIER
      Remi ASTIER

      Hello Jens,

      Comprehensive and complete, thanks a lot.

      In the step 5, it is possible to avoid exporting and converting the keys. 1 step instead of 4 🙂

      xs set-certificate <DOMAIN> --pse <PSE_FILE> --pse-pin <PSE_PIN>

      Maybe it's a new feature.