INTERNAL

How to Configure TLS/SSL in SAP HANA

Applicable Releases:

• SAP HANA 2, all SPS

Topic Area:

• Configuration, Security

Required capability of the operator:

• SAP HANA Database, TLS

Version 2.0.0 - January 2022

1
DOCUMENT HISTORY

Document version Description

1.0 First official release of this guide
2.0.0 Update and extension

2
TABLE OF CONTENTS
DOCUMENT HISTORY ..................................................................................................................................... 2
BEFORE YOU START ...................................................................................................................................... 5
Organizational Requirements ......................................................................................................................... 5
Trust stores ...................................................................................................................................................... 5
Certificates ....................................................................................................................................................... 6
Crypto Library .................................................................................................................................................. 6
Tools to create server certificates ................................................................................................................. 6
sapgenpse ........................................................................................................................................................ 7
SAP HANA Web Dispatcher Admin tool ........................................................................................................ 8
CREATE THE PERSONAL SECURE STORE (PSE) FILE .............................................................................. 9
CLIENT CONFIGURATION ............................................................................................................................ 11
Database clients that connect via SQL interface to the SAP HANA system ........................................... 11
SAP HANA clients like JDBC, ODBC, SQLDBC .......................................................................................... 11
NetWeaver ABAP connection to SAP HANA database .............................................................................. 11
SAP HANA ODBC client connections to SAP HANA database................................................................. 12
SAP HANA studio connections to SAP HANA database ........................................................................... 12
SAP HANA XS Classic Web Application (XSC) .......................................................................................... 12
SAP HANA Cockpit ........................................................................................................................................ 13
SAP HANA database Lifecycle Manager (LCM) via SAP Host Agent ....................................................... 13
SAP HANA XS Advanced Web Applications (XSA) .................................................................................... 14
SAP start service (sapstartsrv) .................................................................................................................... 14
APPENDIX ...................................................................................................................................................... 16
Allow TLS v1.2 only for client connections ................................................................................................ 16
For SAP HANA database............................................................................................................................... 16
For SAP HANA XS Advanced (XSA) ............................................................................................................ 16
Additional information .................................................................................................................................. 16

3
Typographic Conventions

Type Style Description

Example Text Words or characters quoted
from the screen. These
include field names, screen
titles, pushbuttons labels,
menu names, menu paths,
and menu options.
Cross-references to other
documentation
Example text Emphasized words or
phrases in body text, graphic
titles, and table titles
Example text File and directory names and
their paths, messages,
names of variables and
parameters, source text, and
names of installation,
upgrade and database tools.
Example text User entry texts. These are
words or characters that you
enter in the system exactly as
they appear in the
documentation.
<Example Variable user entry. Angle
text> brackets indicate that you
replace these words and
characters with appropriate
entries to make entries in the
system.
EXAMPLE TEXT Keys on the keyboard, for
example, F2 or ENTER.

Icons

Icon Description
Caution

Important

Note

Recommendation or Tip

Example

4
SAP HANA supports encrypted communication for all external (client-server) communication and internal
communication.

SAP recommends using encrypted communication channels where possible.

The aim of this document is to describe one way of configuring secure communication (TLS/SSL) in typical
installation scenarios. The initial scenario described is an SAP HANA system installed on a single host with
incoming connections from HANA SQLDBC and HTTP clients for database and administrative access.

BEFORE YOU START

Organizational Requirements

Important
You need profound knowledge of encryption (TLS), certificate management and SAP HANA databases.

Make yourself familiar with the configuration on the SAP HANA side by reading the relevant documentation:

• SAP Note 2487639 - HANA Basic How-To Series - HANA and SSL - MASTER KBA
• SAP HANA Security Guide for SAP HANA Platform > SAP HANA Network and Communication Security
• SAP HANA Security Guide for SAP HANA Platform > Certificate Management in the Database
• SAP HANA Security Guide for SAP HANA Platform > Certificate Management in the File System
• SAP Note 2338952 - CommonCryptoLib 8.5: Configuration Profile Parameters
• SAP Note 3127404 - sapsrv.pse no longer contains a self-signed certificate as of SAP HANA database
2.0 SPS 06

Trust stores

The X.509 client certificates used for securing external communication channels and several user
authentication mechanisms can – or in some case must – be stored and managed in the SAP HANA
database.

For more information, see: SAP HANA Security Guide for SAP HANA Platform > Certificate Management in
the Database

Certificates stored in the SAP HANA database view SYS.CERTIFICATES are used for trust validation. They
are the public-key certificates of trusted communication partners or root certificates from trusted Certification
Authorities. In other words, they contain the public part of a user's or component's public and private key
pair.
Not all certificates can be stored in the database, in particular the certificates required to secure internal
communication channels using the system Public Key Infrastructure (system PKI), and HTTP client access
(SAP HANA XS, classic model) using SAP Web Dispatcher. These certificates are contained in Personal
Security Environment (PSE) files located in the file system.

5
Example: Personal Security Environment files used on the SAP HANA server

Server PSE file Used for communication to the SAP HANA database from
SAPSSLS.pse SAP HANA XS-Classic clients and the SAP HANA internal Web dispatcher

sapsrv.pse SAP HANA JDBC, ODBC client

SAP Host Agent, SAP HANA Studio

Additional information:
• 2009878 - Purpose of the PSE Files in PSE Management of SAP Web Dispatcher
• SAP HANA Security Guide for SAP HANA Platform > Certificate Management in the File System

Certificates
The SAP HANA database owns a public and private key pair as well as a public-key certificate.
All databases (system database and tenant databases) can have their own key pair and public key
certificate. In distributed SAP HANA systems, every host must have its own key pair and public key
certificate.

The SAP HANA database uses its private/own certificate to validate public keys provided by clients.
By default, the HANA server does not validate the client certificates. You can enable validation of the client's
identity on the server by changing the parameter [communication] sslValidateCertificate in the
global.ini file to true.

For further information see: SAP HANA Security Guide for SAP HANA Platform
> Server-Side TLS/SSL Configuration Properties for External Communication (JDBC/ODBC)
> TLS/SSL Configuration on the SAP HANA Server

Crypto Library
SAP HANA uses the CommonCryptoLib installed with the database.

Note
OpenSSL is deprecated. If you are still using OpenSSL, please migrate to CommonCryptoLib (SAP Note
2093286).

Tools to create server certificates

You can use the tools provided with OpenSSL to create server certificates.

If you are using CommonCryptoLib, you can also use the SAP Webdispatcher administration tool or the
SAPGENPSE tool, both of which are delivered with SAP HANA.

6
sapgenpse

Use the sapgenpse tool in combination with the CommonCryptoLib. Both are delivered with your SAP
HANA installation (default location: /usr/sap/<sid>/HDB<instance>/exe)

For more information, see: SAP HANA Security Guide for SAP HANA Platform > TLS/SSL Configuration on
the SAP HANA Server

sapgenpse shows its version, the version of CommonCryptoLib, as well as the environment variable
$SECUDIR.

Log on to the SAP HANA host as <sid>adm and execute

> sapgenpse
...
Loaded CommonCryptoLib from sapgenpse folder
"/usr/sap/AUS/HDB09/exe/libsapcrypto.so"
Platform: linux-gcc-4.3-x86-64 (linux-gcc-4.3-x86-64)
Versions: SAPGENPSE 8.5.40 (Aug 26 2021)
CommonCryptoLib 8.5.40 (Aug 26 2021) [AES-NI,CLMUL,SSE3,SSSE3]
Build change list: 244259
USER="<sid>adm"
Environment variable $SECUDIR is defined:
"/usr/sap/<SID>/HDB<INSTANCE>/<hostname>/sec"

The parameter tlsinfo shows information about the properties of the cipher suites.
> sapgenpse tlsinfo <configured TLS Cipher Suites>

Example:
> sapgenpse tlsinfo PFS:HIGH::EC_HIGH:+EC_OPT
Running in server mode
Configured protocol versions:
TLSv1.0, TLSv1.1, TLSv1.2
Enabled cipher suites:
TLS_ECDHE_RSA_WITH_AES128_GCM_SHA256
TLS_ECDHE_RSA_WITH_AES256_GCM_SHA384
TLS_ECDHE_RSA_WITH_AES128_CBC_SHA
TLS_ECDHE_RSA_WITH_AES256_CBC_SHA384
TLS_ECDHE_RSA_WITH_AES256_CBC_SHA
...

By default, the SAP HANA system uses the cipher suites defined in:
global.ini
[communication]
sslciphersuites=PFS:HIGH::EC_HIGH:+EC_OPT

7
 Important
Always use TLSv1.2 or higher, since TLSv1.0 and TLSv1.1 are insecure.

SAP HANA Web Dispatcher Admin tool

The SAP HANA Web Dispatcher Administration tool based on XS Classic provides a simple way to configure
TLS. It is available on the SAP HANA XS Web server at the following URL:

http://<WebServerHost>:80<SAPHANAinstance>/sap/hana/xs/wdisp/admin/

For more information about the SAP Web Dispatcher administration tool, see:
• SAP HANA Administration Guide for SAP HANA Platform > Configure HTTPS (SSL) for Client
Application Access
• SAP Note 2009483 - PSE Management in Web Administration Interface of SAP Web Dispatcher
• SAP Note 2502174 - HANA Basic How-To Series - Securing HANA XS classic via SSL / HTTPS -
using Web Dispatcher Administration and pse container (Microsoft CA edition) - SYSTEMDB

8
CREATE THE PERSONAL SECURE STORE (PSE) FILE

Create the server's public and private key pair in addition to the public-key certificate.

Refer to the comprehensive documentation in:

• SAP HANA Security Guide for SAP HANA Platform > TLS/SSL Configuration on the SAP HANA Server

This step is required for file-based and in-database certificate store configuration.

1. Log on to the SAP HANA host as <sid>adm.

2. Always use Fully Qualified Domain Names (FQDN) for the host.

3. Create a new PSE file and a public and private key pair, as well as the public-key certificate and a
certification request file.

> sapgenpse gen_pse -v -s 2048 -p cert.pse -r cert.csr -k GN-

dNSName:<hostname with FQDN> "CN=<hostname with FQDN>, O=<your
organization>, C=<your country>"

-v verbose output
-s <size> key size in Bits (default=alg-specific, rsa=DEFAULT_RSA_KEYSIZE,
dsa=DEFAULT_DSA_KEYSIZE).
-p <pse-file> path and name for (new) PSE file
-r <req-file> path and name for PKCS#10 certificate signing request file
-k <name> Add Subject Alternative Names to the certification request. Repeat the -k option for
every FQDN of the host.

Important
Unless you are using SAPGENPSE, do not password protect the keystore file cert.pse that
contains the server's private key. When using the SAP Web Dispatcher administration tool to
create a personal security environment (PSE) for the server, do not specify a PIN.

As a result, you will get two files:

• The public certificate of the host in the Personal Secure Stores file cert.pse
• The certificate signing request in file cert.csr

4. Sign the certificate signing request in file cert.csr with a trusted Certificate Authority (CA).

If available, choose PKCS #7 as the output format (as this will include all CA certificates).

5. Copy the content to a new file on the server, e.g., signed_cert.p7b.

9
6. Import the signed certificate in file signed_cert.p7b into the server PSE file by executing:

> sapgenpse import_own_cert -p cert.pse -c signed_cert.p7b

7. As a result, you now have a file containing the signed certificates in the PSE store named
cert.pse which is your template for various clients.

Note
If the signed certificate file signed_cert.p7b does not contain the CA certificates you need to import
them from a separate file using option -r of sapgenpse:

> sapgenpse import_own_cert -p cert.pse -c signed_cert.p7b -r <additional

file containing RootCA certificate(s)>

10
CLIENT CONFIGURATION

Depending on the scenario of the SAP HANA client usage, the newly created PSEs have to be properly
named and placed.

For more information, see: SAP HANA Developer's Information Atlas > SAP HANA Custom Application-
Development Scenarios

Database clients that connect via SQL interface to the SAP HANA system

These clients are:

• SAP HANA JDBC client, e.g., NetWeaver JAVA, SAP HANA Studio
• SAP HANA SQLDBC client, e.g., NetWeaver ABAP and its derivates ODBC, ADO.NET, MDX,
Python API

SAP HANA clients like JDBC, ODBC, SQLDBC

These connections use the sapsrv.pse trust store on the SAP HANA system.

1. Log on to the SAP HANA host as <sid>adm.

2. Copy the PSE file cert.pse, which you created in the previous chapter, to folder:
$SECUDIR (default = /usr/sap/<SID>/HDB<instance-no>/<host>/sec)
3. Rename the existing sapsrv.pse file to .old:
> mv $SECUDIR/sapsrv.pse $SECUDIR/sapsrv.pse.old
4. Make the new cert.pse the trust store by renaming it:
> mv $SECUDIR/cert.pse $SECUDIR/sapsrv.pse
5. Restart the SAP HANA system.

NetWeaver ABAP connection to SAP HANA database

Please refer to the NetWeaver documentation and corresponding SAP notes about where to place the trust
store file cert.pse which you created in the previous chapter.

Refer to the comprehensive documentation in:

• Transport Layer Security on the AS ABAP > Configuring SAP NetWeaver AS for ABAP to Support
TLS
• 2475246 - How to configure HANA DB connections using SSL from ABAP instance

Useful SAP Notes:

• 1761693 - Additional CONNECT options for SAP HANA
• 2843930 - Appl.Server can't connect to HANA Database using encryption using $(SECUDIR)
• 2846403 - ERROR Connection failed ... Cannot create SSL context: ... The PSE file does not exist
• 2919754 - In-Database SSL/TLS Certificate Management for Specific Host Names Still Requires the
Default PSE Store in File sapsrv.pse

11
SAP HANA ODBC client connections to SAP HANA database

Add the public-key certificate of the SAP HANA server or the root certificate to the trust store which is used
by the HANA ODBC client.

Set the relevant connection properties for secure communication to the server:

• SAP HANA Security Guide for SAP HANA Platform > Client-Side TLS/SSL Connection Properties
(ODBC)
• SAP HANA Client Interface Programming Reference > Connect to SAP HANA via ODBC

SAP HANA studio connections to SAP HANA database

Refer to the comprehensive documentation in:

• SAP HANA Administration with SAP HANA Studio > Configure TLS/SSL for SAP HANA Studio
Connections
• 2487698 - HANA Basic How-To Series - HANA and SSL - establishing a secured JDBC connection
using HANA Studio

SAP HANA XS Classic Web Application (XSC)

Port 43xx (HTTPS)

Refer to the comprehensive documentation in:

• SAP HANA Administration Guide for SAP HANA Platform
> Configure HTTPS (SSL) for Client Application Access
> Configure HTTP(S) Access to Tenant Databases via SAP HANA XS Classic

• SAP Note 2502174 - HANA Basic How-To Series - Securing HANA XS classic via SSL / HTTPS -
using Web Dispatcher Administration and pse container (Microsoft CA edition) - SYSTEMDB

SAP HANA XS-Classic applications and SAP HANA internal Web Dispatcher use the SAPSSLS.pse trust
store on the SAP HANA host:

1. Log on to the SAP HANA host as <sid>adm.

2. Copy the PSE file cert.pse, which you created in the previous chapter, to folder:
$SECUDIR (default = /usr/sap/<SID>/HDB<instance-no>/<host>/sec)
3. Rename the existing SAPSSLS.pse file to .old:
> mv $SECUDIR/SAPSSLS.pse $SECUDIR/SAPSSLS.pse.old
4. Make the new cert.pse the trust store by renaming it:
> mv $SECUDIR/cert.pse $SECUDIR/SAPSSLS.pse
5. Restart the SAP HANA internal Web Dispatcher or the HANA system

12
 SAP HANA Cockpit

Refer to the comprehensive documentation in:

• SAP HANA Administration with SAP HANA Cockpit > Security Considerations for SAP HANA
Cockpit
• 2631903 - HANA Basic How-To Series - Securing HANA 2.0 Cockpit (or WebIDE) running on XSA
via SSL / HTTPS (EXAMPLE: Microsoft CA edition)

SAP HANA database Lifecycle Manager (LCM) via SAP Host Agent

Port 1129

Refer to the comprehensive documentation in:

• SAP Host Agent > SSL Configuration for the SAP Host Agent

Use the trust store SAPSSLS.pse of the SAP Host Agent.

Do not password protect the SAPSSLS.pse file.

1. Log on to the host where the SAP Host Agent is installed as user root.
2. Copy the PSE file cert.pse, which you created in the previous chapter, to folder:
$SECUDIR (default = /usr/sap/hostctrl/exe/sec)
3. Rename the existing SAPSSLSv.pse file to .old:
> mv $SECUDIR/SAPSSLS.pse $SECUDIR/SAPSSLS.pse.old
4. Make the new cert.pse the trust store by renaming it:
> mv $SECUDIR/cert.pse $SECUDIR/SAPSSLS.pse
5. Delete an existing file cred_v2.

6. Restart the SAP Host Agent:

> /usr/sap/hostctrl/exe/hostexecstart -restart

Further source of information:

• Blog: SSL Configuration of the SAP Host Agent

13
SAP HANA XS Advanced Web Applications (XSA)

These connections use the certificates deployed to the default domain (default entry point to all applications
and services via the Platform Router).

Note
The ports used depend on XSA routing mode as described in:

• SAP HANA Administration Guide for SAP HANA Platform > Maintaining Application Routes in XS
Advanced
• 2245631 - Routing Mode and Default Domain configuration for SAP HANA extended application
services, advanced model

XSA requires the certificate in PEM format. Therefore, you must convert your certificate:

1. Log on to the SAP HANA host as <sid>adm.

2. Convert the cert.pse, which you created in the previous chapter, into to PEM format:
a) Export the keys in PKCS#12 transfer format:
sapgenpse export_p12 -p sapsrv.pse sapsrv.p12
b) Create a certificate file:
openssl pkcs12 -nodes -nokeys -in sapsrv.p12 -out sapsrv.pem

3. Install the PEM file in XSA as described in:

SAP HANA Administration Guide for SAP HANA Platform > Maintaining Trust Certificates in XS
Advanced

Additional information:
• Blog: Upgrading HANA XSA & WebIDE + SSL Configuration

SAP start service (sapstartsrv)

port 5xx14
These connections can be configured to use the SAPSSLS.pse trust store of the SAP HANA host.

1. Log on to the host as <sid>adm.

2. Edit the sapstartsrv instance profile file:
/hana/shared/<SID>/profile/<SID>_HDB<instance-no>_<host>
3. Search for line starting with SECUDIR:
SECUDIR = $(SAP_RETRIEVAL_PATH)/sec
4. Add underneath the SECUDIR line:
ssl/server_pse=$(SAP_RETRIEVAL_PATH)/sec/SAPSSLS.pse
This is required as by default sapstartsrv searches for SAPSSLS.pse in path:
/usr/sap/<SID>/<Instance>/sec

5. Restart the sapstartsrv service:

14
 > sapcontrol -nr <instance-no> -function RestartService

Additional information:
• Blog: SAP HANA Under The Hood – SAPInit and SAPStartSrv

15
APPENDIX

Allow TLS v1.2 only for client connections

You want to prohibit the usage of all TLS versions below TLS v1.2 for connections to the SAP HANA system.

For SAP HANA database

• JDBC/ODBC connections to the HANA DB as described in SAP HANA Security Guide for SAP
HANA Platform > Server-Side TLS/SSL Configuration Properties for External Communication
(JDBC/ODBC)
• XS-Classic: It is not possible to directly restrict the TLS version accepted from XS-Classic. This must
be done via the Web Dispatcher.
• Web Dispatcher: The parameter mentioned in SAP Note 2829919 also applies to the internal SAP
HANA Web Dispatcher:
global.ini [communication] sslminprotocolversion = TLS12
• 2829919 - How to enable TLS 1.2 for all Hana ports

For SAP HANA XS Advanced (XSA)

• 2852432 - How to disable TLS 1.0 and 1.1 on HANA XSA?

• 510007 - Additional considerations for setting up SSL on Application Server ABAP

Additional information

Blogs:

• HANA secure network communication – part I

• HANA secure network communication – part II

16
www.sap.com/contactsap

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

The information contained herein may be changed without prior notice. 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 or its affiliated companies shall not be liable
for errors or omissions with respect to the materials. The only warranties for SAP 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, and they should not be relied upon in making purchasing decisions.

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. All other product and service names mentioned are the trademarks of their respective companies. See www.sap.com/trademark for additional trademark information and notices.