Technical Articles
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.
- Scenarios [part I]
- Client & HANA Cockpit communication
- SolMan Communication
- AS ABAP
- JDBC/ODBC/SQLDBC [part I]
- Term clarification [part I]
- Create and sign certificate [part II]
- Import certificate to HANA Cockpit (for client communication) [part II]
- Import certificate to HANA resource(s) [part II]
- Configure clients (AS ABAP, ODBC, etc.) to use SSL [part II]
- Configure HDB parameters for high security [part II]
- Configure XSA with TLS and cipher for high security [part II]
- Import certificate to host agent [part II]
- Pros and Cons certification collections [part II]
4. Create and sign certificate
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:
5. HANA Cockpit
Determine which format your key file has with a look into it:
cat *.key | head -1
----- BEGIN ENCRYPTED PRIVATE KEY----- => PKCS#8
Format | PEM header |
PKCS#1 RSAPublicKey* | BEGIN RSA PUBLIC KEY |
X.509 SubjectPublicKeyInfo | BEGIN PUBLIC KEY |
PKCS#8 EncryptedPrivateKeyInfo | BEGIN ENCRYPTED PRIVATE KEY |
If it is a PKCS#12 format you have to follow this steps (there are several ways, just have a look at the openssl documentation):
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/options 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
- Shut down the system
- Check the certificate: sapgenpse get_my_name -p cert.pse
- Replace the sapsrv.pse, SAPSSLS.pse and SAPSSLC.pse with the created cert.pse
- 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:
- sslValidateCertificate = false => will not validate the certificate
- sslHostNameInCertificate = <vhostname> => will overwrite the calling hostname
- 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:
- Vitaliy Rudnytskiys blog: Secure connection from HDBSQL to SAP HANA Cloud
- Implement mutual authentication
8. Configure HDB for high security
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.
- Create the certificate on base of the vhostname of the server
- Copy the *.pse as SAPSSLS.pse to /usr/sap/hostctrl/exe/sec/
- use sapgenpse seclogin option as root (with proper environment – means SECUDIR variable) when you have specified a PIN/passphrase
- set ssl/server_pse= <Path to Server PSE> inside the host_profile
- 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: |
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
########
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 🙂
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 fromhdbsql
😀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.
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??
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
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
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.