CommonCryptoLib: TLS protocol versions and cipher suites

[JoeGoerlich]

Many years ago SAP deprecated the SAPCRYPTOLIB and introduced the CommonCryptoLib (CCL) as its successor. The CCL is not only a replacement for its predecessor but also for OpenSSL, which was used for example by SAP HANA in its early days (and up to SAP HANA 2.0 SPS01 for LDAP).

In the meantime the CCL is available in its latest version 8.5.x and is used by many SAP components. Some examples are:

• SAP Host Agent,


• SAP Instance Agent,


• SAP NetWeaver AS ABAP,


• SAP NetWeaver AS Java,


• SAP HANA,


• SAP Web Dispatcher,


• various Kernel Tools (saphttp, sldreg, sapkprotp, sapcontrol, saphostcontrol, etc.)


• SAP Java Connector (SAP JCo)


• SAP Connector for Microsoft .NET 3.0 (SAP NCo)

All of these components have one thing in common: They make use of one or more communication protocols (e.g., HTTP, P4, IIOP, JDBC, LDAP) which nowadays should be secured using TLS (Transport Layer Security).

 

Please also read the other blogposts of this series:

CommonCryptoLib: TLS protocol versions and cipher suites
CommonCryptoLib: SNC protocol versions and cipher suites
CommonCryptoLib: Manage PSE files and SSO Credentials (cred_v2)
CommonCryptoLib: Certificate Revocation List validation

 

Updates:

2022-09-16: Added info about changes to TLS_FALLBACK_SCSV.
2022-03-21: Added info about changes to cipher suites and group assignment.
2022-02-25: Updated recommendation regarding "Allow blind sending of a client certificate".
2021-11-05: Linked other blogposts of this series. Added section on how to update the CCL.

---

Protocol versions

Since the main browser vendors decided to no longer support some TLS versions, every admin dealing with web applications had to learn at least in the recent months about the different TLS versions out there.
Some of the TLS versions are existing for more than 20 years and can be considered as weak. For example TLS 1.0 and TLS 1.1 have finally been flagged as deprecated by IETF (see rfc8996, which took them btw more than two and a half years (see https://datatracker.ietf.org/doc/rfc8996/history/).
And others are the new kids on the block like TLS 1.3 and ETS (formerly known as eTLS). They are so "fresh" that they aren't supported in all products, yet.

Please note: As of SAP notes 2765639 in AS ABAP, SAP note 2834475 in AS Java and SAP note 2939945 in SAP BusinessObjects BI Platform 4.x TLS 1.3 is currently not supported.

Today, the version which can be considered as widely supported is TLS 1.2.

Cipher suites

Cipher suites define a set of algorithms that usually contain a key exchange algorithm, a Signature, a bulk encryption algorithm, and a message authentication code (MAC) algorithm.

Not every cipher suites can be combined with every TLS protocol version.

And to cause even more confusion there are different notations on cipher suites: IANA naming vs. OpenSSL naming.

Please note: A comprehensive overview about all available cipher suites, TLS version support and a security classification can be found at https://ciphersuite.info/cs/.

 

Technical background on the CCL integration

SapSSL is the high-level protocol handler of the SAP Kernel and its components. Whenever cryptography for TLS is needed SapSSL addresses a cryptographic library.

The to-be-used library is configured by the profile parameter ssl/ssl_lib.

The CCL has a built-in default configuration which serves maximum compatibility but offers very weak security and therefore should no longer be used nowadays. To overwrite this default configuration most components read profile parameters and pass them through SapSSL to the CCL.
As some components do not read from profile parameters the CCL reads also from environment variables as a fallback. This allows a secure custom configuration to be used by these components.

SAP HANA (Database (incl. XS Classic) and XSA) integrate the CCL by other means. The CCLs' configuration is stored in the configuration .ini files.

Some components act only as clients (for example sapcontrol), some act only as server (for example sapstartsrv) and some act as both (for example the ICM of SAP NW AS ABAP).
Some components do not or at least partially not relay on the combination of SapSSL + CCL. Instead they use the Java IAIK-JCE or the JSSE, the Windows stack or any other products' own TLS stack. For example for the TLS handshake for incoming connections to the ICM of SAP NW AS Java the CCL is used, while SAP NW AS Java uses for outgoing connections the IAIK.
That means there are also other places where to configure TLS and cipher suites, besides the one described in this blogpost. SAP note 2384243 is a good read for that.

During the TLS handshake the server and the client are negotiating the to be used TLS protocol version and the to be used cipher suites. Each side typically support more than one cipher suite to offer higher compatibility. Each party asks for acknowledgement on the TLS version and the cipher suites in a given order until they come to an agreement. If no matching TLS version or cipher suite could be negotiated the handshake will fail.

How to update the CCL?

The CCL can be downloaded directly and the lib simply can be exchanged.

For SAP ABAP or Java systems it is also part of the SAP Kernel (Stack Kernel or DW_UTILS*.SAR).

For SAP HANA it comes with the Revision update. For SAP HANA an update of the CCL with a directly obtained library is not recommended nor supported.

SAP supports the current and one maintained version.

Please note: Please make sure you keep the CCL updated. Especially for non-SAP partner systems having interfaces based on SAP JCo or SAP NCo.

 

How to configure the protocols and cipher suites supported by the CCL?

As you may know there are the following profile parameters which allow to globally configure the available TLS protocol versions and cipher suites as well as the elliptic curves:

When acting as server: ssl/ciphersuites
When acting as client: ssl/client_ciphersuites

The corresponding environment variables, used by components which are not reading from profiles, are:

When acting as server: SAPSSL_CIPHERSUITES
When acting as client: SAPSSL_CLIENT_CIPHERSUITES

For all of them the value has to be in the following format:
<Protocol_Bit-mask>:<Cipher_config>::<Elliptic_Curves_config>.

 

Where to set these parameters?

To cover SAP Instance Agent, SAP NW AS ABAP, SAP NW AS Java and SAP Web Dispatcher we should add those profile parameters to the DEFAULT.PFL. This is also valid for SAP HANA, since it brings an Instance Agent with it which reads from the DEFAULT.PFL.

For the <sapsid>adm we also have to set those environment variables.
In addition to that we have to set the environment variable CCL_PROFILE to point to a profile file, e.g., the DEFAULT.PFL. This is because with this some command-line tools can be enabled to read the CommonCryptoLibs' configuration from a profile. This affects for example 'sapcontrol' or 'sapgenpse'.

Please note: The environment variables for <sapsid>adm must not be set via SAPStartSrv by adding SETENV_<xx>=<environment_variable>=<value> in the profiles. Since environment variables set by this method are only valid for child-processes of SAPStartSrv. <sapsid>adm is in most cases also used for some interactive operations using a shell.

In SAP HANA Database (incl. XS Classic) and SAP HANA XSA search for the properties sslMinProtocolVersion, sslCipherSuites, client_ciphersuites, and Router.WebDispatcher.CipherSuites. For the XSC WebDispatcher also the property ssl/ciphersuites can be set in the webdispatcher.ini overwriting the global values. The cipher suites follow the same format as below without the protocol bit-mask. I recommend the outstanding blog series from c9b9c8ea15574d29bfafe89e88ac94ec: HANA secure network communication.

To cover SAP Host Agent we should add those profile parameters to the host_profile.

Since the sapadm is typically a non-login user without a shell we have to set those environment variables through the host_profile by adding SETENV_<xx>=<environment_variable>=<value>.

For other components like SAP JCo or SAP NCo we have to set those environment variables.

What about legacy devices which still need support for outdated TLS versions and weak cipher suites?

In some environments we may need to connect Barcode scanners, HMIs and alike which do not yet support the latest crypto. This is not uncommon since vendors have to support these devices for a very long lifetime or simply did not pay attention to security when the device have been thrown onto the market years ago.

For this the ICM of SAP NW AS as well as the SAP Web Dispatcher allow to define a specific configuration for individual ports differing from the global configuration using the sub-parameter SSLCONFIG of the parameter icm/server_port_<xx> when acting as server.

To do so we may want to configure a separate port offering an outdated TLS version and weaker cipher suites. For sure we have to implement additional measures like implementing a local firewall or an ACL to restrict access to this port to the necessary devices only.

An additional approach could be to use the SAP Web Dispatcher as communication middle-ware and place it next to these legacy devices in the factory. On the SAP Web Dispatcher we can then use TLS re-encryption to use state of the art TLS protocol versions and strong cipher suites for the communication between the SAP Web Dispatcher and the backend.

Remember it is not that easy do identify all components and command-line tools on our SAP system which relay on the CCL, as you may have already noticed by reading the list of components in the intro. So using a specific per port configuration allows us to explicitly support legacy devices while not weaken the security of all our other connections. Keep in mind, the warnings given in SAP note 2384290 are not neglectable.

How to find the correct values?

During the last years various different recommendations have been made. Some of them with compatibility and others with a tradeoff of compatibility and security in mind. But still there is a lot of considerable confusion.

From my point of view this is often due to lack of knowledge about the configuration itself but also due to lack of knowledge about the whole topic. In many cases misleading or missing documentation plays also a role.

Now let's go into details about the protocols, cipher suites and elliptic curves to bring light into the dark, at least for the configuration part.

Protocol Bit-mask

Protocols and features supported by the CommonCryptoLib can be configured using a bit-mask (and keywords).

The bit-mask is described in SAP note 510007, chapter 7.

To enable explicitly TLS 1.2 the bit-mask would be: 544

(512 + 32 = TLS 1.2 + „Strict protocol version configuration“)

To enable TLS 1.2 and the highest protocol version which is going to be added in future (assuming TLS 1.3 would be rated higher then ETS formerly known as eTLS) a future proof (but some uncertainty adding) bit-mask would be: 546

(512 + 32 +2 = TLS 1.2 + „Strict protocol version configuration“ + Best )

Please note: Keep in mind that TLS 1.3 relays on different cipher suites than TLS 1.2. This has then to be considered by configuring a future proof list of supported cipher suites.

Other options like BC (no longer supported by TLS 1.2 and above) or "NO_GAP" (may lead to falsely enable protocol versions) should not be enabled by the bit-mask.

To add a protocol downgrade prevention mechanism on server side the keyword TLS_FALLBACK_SCSV may be added. Even if it is technically no longer needed for a server supporting TLS 1.2 and higher only, but it still may help to get - at least formally - a better security rating by test tools.

Please note: As of CCL 8.5.45 TLS_FALLBACK_SCSV is enabled by default when acting as server. To explicitly disable it the keyword "-TLS_FALLBACK_SCSV" has to be added to the configuration string.

With these considerations we end up with the sub-string 544:TLS_FALLBACK_SCSV

Cipher Suite Configuration

The CommonCryptoLib assigns sets of cipher suites to groups. The available groups can be displayed using sapgenpse by issuing the command
sapgenpse tlsinfo -H

The smallest group consists of a single bulk encryption algorithm and its mode + a certain key length (e.g., "eAES256_GCM"). The next larger consist of a single bulk encryption algorithm and its mode + all key lengths (e.g., "eAES256"). There are also groups combining a single algorithm and all its modes + all key lengths (e.g., "eAES").
Or groups that contain even more than one algorithms and key lengths which i call "classes".
These classes are defined by SAP. At time of writing the following classes exist:
"DEFAULT": Default cipher suites (HIGH:PFS:!aNULL:!eNULL)
"ALL": All supported cipher suites
"PFS": Perfect forward secrecy: key agreement with ephemeral keys
"HIGH": High security cipher suites (except PFS)
"MEDIUM": Medium security cipher suites
"LOW": (no longer used)

Please note: http/2 for example strictly requires cipher suites providing PFS (perfect forward secrecy) which is not given by a key exchange based on RSA and is not covered by the class "HIGH".

As these classes are defined by SAP they do not underlay a common understanding. From time to time SAP makes adjustments to these classes and communicate this via SAP note 2004653 (it is worth to subscribe to this note to keep track about changes). Almost all recommendations out there relay on these classes. Nevertheless, they do not provide control about the supported cipher suites to a full extent as it is desired in a high security area.
Furthermore, it also may be more complex to start with such a predefined class and strip it down to our needs than adding just the algorithms we want to support. Not knowing what happens after SAP made adjustments to the classes.

A good starting point could be to add cipher suites based on a well chosen bulk encryption algorithm and strip the resulting list down to the desired cipher suites by excluding certain key exchange algorithms or hash algorithms.

Please note: To have a full understanding some knowledge about cryptography would be an advantage, but also the security classification from https://ciphersuite.info/cs/ could be consulted to determine which cipher suites are safe to be supported.

EDIT: In CommonCryptoLib 8.5.42 the group assignment and supported cipher suites has changed. The cipher suites class MEDIUM is now *empty*, see SAP note 3128664.

Configuration example

In this example we may want to adjust the global cipher suites settings to support a list of cipher suites based on cryptography recommended also in the latest publications from NIST, ECRYPT and the BSI for future use.

Therefore we enable only cipher suites based on AES-GCM with a key length of 128-bits at minimum, but preferring 256-bit key length, and exclude all cipher suites based on RSA key exchange as well as exclude MACs using SHA with less than 256-bit.

To achieve this we use the sub-string eAES_GCM:+eAES128:!kRSA.

We can verify the resulting list of supported cipher suites using the following command:

sapgenpse tlsinfo -v 544:TLS_FALLBACK_SCSV:eAES_GCM:+eAES128:\!kRSA

Please note: On the command-line the "!" has to be escaped.

The output contains these ciphers:

Enabled cipher suites:
TLS_ECDHE_RSA_WITH_AES256_GCM_SHA384
TLS_ECDHE_ECDSA_WITH_AES256_GCM_SHA384
TLS_ECDHE_RSA_WITH_AES128_GCM_SHA256
TLS_ECDHE_ECDSA_WITH_AES128_GCM_SHA256

As the result list does already not contain any MACs using SHA1 the sub-string !mSHA1 can be omitted.
The result list also presents the list of cipher suites in the order offered used for negotiation during the handshake. With +eAES128 we move AES encryption algorithms using this key length to the end of the preferred order list.

Remark on undocumented syntax:
While "!" deletes matching items from the result list and deleted items can never reappear in the result,
"-" deletes matching items from the result list and deleted items can reappear in the result if added later again. This would make the order of arguments in the cipher configuration important!

Compatibility for legacy clients

After adjusting the global cipher suites we may need to determine the cipher suites needed for compatibility reasons.
For the ICM of SAP NetWeaver AS or SAP Web Dispatcher we add them only for the relevant port by adjusting the cipher suites for a dedicated, additional icm/server_port_<xx> for the relevant protocol using sub-parameter SSLCONFIG.
If a legacy configuration has to be done for other components relaying on the CCL and acting as a server which is very rare, it may be inevitable to adjust the global configuration effecting all communications.

To determine which cipher suites need to be supported we may collect TLS traces or take a look at the documentation of the client. Then we can extend the sub-string in order to offer matching cipher suites.

For example we may need to add the bulk encryption algorithm ARIA-GCM and allow RSA for key exchange resulting in the substring eAES_GCM:eARIA_GCM:+eAES128:+eARIA128.

Again we can verify the resulting list of supported cipher suites using the following command:

sapgenpse tlsinfo -v 544:TLS_FALLBACK_SCSV:eAES_GCM:+eAES128:eARIA_GCM:+eARIA128

The output now contains the these ciphers:

Enabled cipher suites:
TLS_RSA_WITH_AES256_GCM_SHA384
TLS_ECDHE_RSA_WITH_AES256_GCM_SHA384
TLS_ECDHE_ECDSA_WITH_AES256_GCM_SHA384
TLS_ECDHE_RSA_WITH_ARIA_256_GCM_SHA384
TLS_ECDHE_ECDSA_WITH_ARIA_256_GCM_SHA384
TLS_RSA_WITH_ARIA_256_GCM_SHA384
TLS_RSA_WITH_AES128_GCM_SHA256
TLS_ECDHE_RSA_WITH_AES128_GCM_SHA256
TLS_ECDHE_ECDSA_WITH_AES128_GCM_SHA256
TLS_ECDHE_RSA_WITH_ARIA_128_GCM_SHA256
TLS_ECDHE_ECDSA_WITH_ARIA_128_GCM_SHA256
TLS_RSA_WITH_ARIA_128_GCM_SHA256

Please note: As of SAP note 2384290 Solution Manager Diagnostic Agent is known to lack support for PFS cipher suites with ECDHE key exchange and therefore requires TLS cipher suites with static RSA key exchange for interoperability with CommonCryptoLib 8.

Elliptic Curves Configuration

Similar to cipher suites the CommonCryptoLib assigns sets of elliptic curves to "classes". These classes are defined by SAP.

At time of writing the following classes exist:
"EC_DEFAULT" (=EC_HIGH:EC_MEDIUM),
"EC_ALL" : All supported elliptic curves
"EC_HIGH" : High security elliptic curves
"EC_MEDIUM" : Medium security elliptic curves
"EC_LOW" : Low security elliptic curves
"EC_NIST" : NIST standardized elliptic curves, recommended in Suite B
"EC_IETF".

And again these classes are defined by SAP and do not underlay a common understanding (maybe except the EC_NIST one). From time to time SAP makes adjustments to these classes (see for example SAP Note 2415828). Almost all recommendations out there relay on these classes. Nevertheless, they do not provide control about the supported elliptic curves to a full extent as it may be desired.

Therefore we can also add elliptic curves providing strong security explicitly by listing them in the sub-string: EC_X25519:EC_P256:EC_P384:EC_P521

Please note: Defining the elliptic curves explicitly allows to specify their preferred order. If you are for example after high performance you may place Curve25519 on first place (since it is one of the fastest ECC curves), while placing other more computation time consuming ones later. You may want to keep a balance between computation time and provided security for the time being.

There is also a switch available which enables the performance optimization of elliptic curves. So we may want to add that as well: +EC_OPT

Please note: As of SAP note 2181733: EC_OPT leads to a higher CPU load during CommonCryptoLib initialization and can delay the startup of a TLS. This delay is indeed noticeable when testing the available ciphers using sapgenpse, but just in milliseconds.

This considerations will result in the sub-string EC_X25519:EC_P256:EC_P384:EC_P521:+EC_OPT

Server vs. client

So far we dealt mostly with the settings for the CCL configuration when acting as a server. The configuration when acting as client is slightly different.

When acting as HTTP client the option "Allow blind sending of a client certificate" should be enabled if a server sends an empty list of certificate authorities. If not enabled this would lead for the client to not being able to choose an acceptable client certificate.

Please note: The client certificate, which is to be sent to a server during the TLS handshake for mutual authentication (aka. authentication with client cert aka. X.509 authentication), is typically configured in the relevant HTTP destination as "SSL-Certificate" by choosing the relevant trust store for SSL client identities.
If "SSL Client (Anonmyous)" is selected, no client certificate will be sent at all. By default "SSL Client (Default" ist selected.

Another noticeable difference is the TLS_FALLBACK_SCSV which is only supported when acting as server. So if we want be precise we do not need to add this or other settings of the bit-mask targeting features for servers to the sub-string for the client side configuration.

Sapgenpse offers also the possibility to verify the CCLs' configuration when acting as client, by adding the switch "-c", for example:

sapgenpse tlsinfo -c -v 562:eAES_GCM:+eAES128:!kRSA

With this we may compare the supported TLS protocols and cipher suites offered by the server with the list of supported cipher suites according to our custom client-side configuration. The supported TLS protocols and cipher suites offered by the server can be determined for example using the command-line tool sslscan or OpenSSL or a trace from the handshake.

Please note: When acting as client, we have to swallow the bitter pill when it comes to compatibility: We can adjust the settings for supported cipher suites only for all outgoing connections at once.

 

Crafting the final parameter values

Having talked about all sub-strings and how to determine their values we now are able to craft the values for our global configuration parameters:

ssl/ciphersuites = 544:TLS_FALLBACK_SCSV:eAES_GCM:+eAES128:!kRSA::EC_X25519:EC_P256:EC_P384:EC_P521:+EC_OPT

ssl/client_ciphersuites = 562:eAES_GCM:+eAES128:!kRSA::EC_X25519:EC_P256:EC_P384:EC_P521:+EC_OPT

SAPSSL_CIPHERSUITES=544:TLS_FALLBACK_SCSV:eAES_GCM:+eAES128:!kRSA::EC_X25519:EC_P256:EC_P384:EC_P521:+EC_OPT

SAPSSL_CLIENT_CIPHERSUITES=544:eAES_GCM:+eAES128:!kRSA::EC_X25519:EC_P256:EC_P384:EC_P521:+EC_OPT

 

---

Next -->