Central Note for CommonCryptoLib 8 (SAPCRYPTOLIB)

Central Note for CommonCryptoLib 8 (SAPCRYPTOLIB)

Symptom

The current ABAP Kernels come with CommonCryptoLib (SAPCRYPTOLIB) Version 8.5.

This is the central note for CommonCryptoLib.

Other Terms

CommonCryptoLib, SAPCRYPTOLIB, NetWeaver, ABAP, JAVA, Kernel, HANA, DW_UTILS, SAPEXE, FIPS 140-2, SSO, SSL, TLS, SNC, SSF

Reason and Prerequisites

The CommonCryptoLib (SAPCRYPTOLIB) Version 8.5 is fully compatible with previous versions of CommonCryptoLib or SAPCRYPTOLIB beginning with AS ABAP Kernel 7.20 PL88.

If your system or Kernel uses CommonCryptoLib 8.4, or with the deprecated SAPCRYPTOLIB version 5.5, it is recommended to update to the latest CommonCryptoLib version 8.5.

Important

You must not use CommonCryptoLib if you are running Kernel releases prior to 7.20 PL88, as CommonCryptoLib is not fully compatible with such old releases. Use SAPCRYPTOLIB 5.5 PL38 in such cases.

Prerequisites

Beginning with Kernel 7.20 PL88, no specific Kernel patch is required to use CommonCryptoLib. The library is fully compatible with SAPCRYPTOLIB and SAPSECULIB.
CommonCryptoLib is also shipped with current Kernel packages, so that a new Kernel updates from any old SAP cryptographic library.

For CommonCryptoLib 8.5 and higher, AS ABAP requires a patch that fixes the error “SAPCRYPTOLIB too old” displayed by SAP GUI. See SAP Note 2304831.

Licensing

No extra licenses are required for:

  • Server-to-server communication
  • Kerberos or X.509 server authentication based encrypted only client-to-server communication (SNC Client Encryption)
  • Default system internal security
  • SNC and SSF certificate revocation list checking (CRL)

Licenses for the product SAP Single Sign-On are required if one or more of the following features are used:

  • User based SSO with X.509 or Kerberos, like SNC for SAP GUI or RFC clients
  • User based SSO with Kerberos/SPNego for Web browsers
  • Digital signatures (SSF) with hardware security modules (HSM)

For CommonCryptoLib versions before 8.5, download and install the component NWSSO FOR COMMONCRYPTOLIB 2.0 from SAP Marketplace to activate your SAP SAP Single Sign-On license.

For CommonCryptoLib 8.5 and higher, this component is not required anymore.

Further Installation Hints

Also read SAP Note 510007, section “Manual First-Time Installation or Configuration of SAPCRYPTOLIB on an SAP NetWeaver 6xx, 70X, 71X, 72x, or 73x System” and SAP Note 2125088.

Solution

Availability

Use kernel patch according to levels maintained in this note, tab “SP Patch Level”. The library is part of the DW_UTILS*.SAR package. The note 19466 decribes the patch procedure.

New Features in CommonCryptoLib (SAPCRYPTOLIB) Version 8.4.30 or higher

  • SNC Library for SAP ABAP Application Server or RFC
    Full SNC compatibility with SAPCRYPTOLIB (X.509), plus Kerberos based authentication for SAP GUI clients.
  • X.509 and Kerberos end-user authentication in parallel
    Allow to configure server identities from PKI and Windows Domain in mixed mode to provide two user authentication protocols in parallel.
  • SPNego for SAP ABAP Application Server
    Windows Kerberos authentication using Web Interface in SAP ABAP Application Server.
  • FIPS 140-2 Certification for Crypto Kernel
    CommonCryptoLib 8.4.33 or higher is shipped with an optional certified crypto kernel library. See SAP Note 2117112 for important details.
  • INTEL AES Native Interface Support
    Crypto Kernel makes use of INTEL AES-NI on Microsoft Windows and Linux platforms.
  • IBM VCIPHER AES Support
    Crypto Kernel makes use of VIPHER AES on IBM platforms with POWER8 CPUs (CommonCryptoLib 8.4.47 or higher).

New Features in CommonCryptoLib (SAPCRYPTOLIB) Version 8.5.2 or higher

  • SNC protocol enhancements for SAP Single Sign-On 3.0
    X.509 based Encryption Only mode and Perfect Forward Secrecy are now supported. A new Server Session Key mode replaces previously offered SSO modes.
  • Configuration Parameters in Profile
    Instead of local XML files, the runtime configuration parameters can be placed in a profile now.
  • New SAPGENPSE Commands
    GET_CRL and SNCINFO have been added to the standard tool set. The CRL download tool is now part of the standard CommonCryptoLib.
  • New FIPS 140-2 Crypto Kernel with Elliptic Curves Cryptography
    Since May 05, 2017 the new crypto kernel version 8.4.47 is certified by NIST. See http://csrc.nist.gov/groups/STM/cmvp/documents/140-1/1401val2017.htm#2900.

How to verify the FIPS 140-2 Compliance Status
In a command shell, go to folder /usr/sap/<SID>/exe, and run the utility “sapgenpse cryptinfo”, which prints out several properties of the locally installed CommonCryptoLib. The default behavior of CommonCryptoLib is to use the internal crypto kernel, which is not certified but comes with latest fixes and enhancements. See SAP Note 2117112 for implementation details.

Properties of SAP CommonCryptoLib Crypto Kernel

1. with default crypto kernel, here on Windows with INTEL processor:

FIPS 140-2 = NO
API-VERSION = 2
VERSION = 8.5.2
FILE-VERSION = 8.5.2.0
SELFTEST = OK (run in init call)
BINARY =
CPU-FEATURES-SUPPORTED = AES-NI,CLMUL,SSE3,SSSE3
CPU-FEATURES-ACTIVE = AES-NI,CLMUL,SSE3,SSSE3
HASH-ALGORITHMS = MD5,SHA1,SHA224,SHA256,SHA384,SHA512,RIPEMD128,RIPEMD160
CHECKSUM-ALGORITHMS = MD2,MD4,CRC32
ENCRYPTION-ALGORITHMS = RSA,ELGAMAL,AES128,AES192,AES256,DES,TDES2KEY,TDES3KEY,IDEA,RC2,RC4,RC5_32
ENCRYPTION-MODES = ECB,CBC,CFB*8,OFB*8,CTR,CTSECB,CTSCBC,GCM
PADDING-MODES = PKCS1BT01,PKCS1BT02,PKCS1PSS,PKCS1OAEP,X.923,PEM,B1,XML,SSL
KEYEDHASH-ALGORITHMS = HMAC
SIG-ALGORITHMS = RSA,DSA,ECDSA
KEYEXCHANGE-ALGORITHMS = DH,ECDH
ELLIPTIC-CURVES = P-192,P-224,P-256,P-384,P-521
RANDOM-ALGORITHMS = CTR_DRBG

2. with optional FIPS crypto kernel module enabled:

FIPS 140-2 = YES
API-VERSION = 2
VERSION = 8.4.47
FILE-VERSION = 8.4.47.0
SELFTEST = OK (run in library initialization)
BINARY = D:\usr\sap\NW1\DVEBMGS01\exe\sapcrypto.dll
CPU-FEATURES-SUPPORTED = AES-NI,CLMUL,SSE3,SSSE3
CPU-FEATURES-ACTIVE = AES-NI,CLMUL,SSE3,SSSE3
HASH-ALGORITHMS = MD5,SHA1,SHA224,SHA256,SHA384,SHA512,RIPEMD128,RIPEMD160
CHECKSUM-ALGORITHMS = MD2,MD4,CRC32
ENCRYPTION-ALGORITHMS = RSA,ELGAMAL,AES128,AES192,AES256,DES,TDES2KEY,TDES3KEY,IDEA,RC2,RC4,RC5_32
ENCRYPTION-MODES = ECB,CBC,CFB*8,OFB*8,CTR,CTSECB,CTSCBC,GCM
PADDING-MODES = PKCS1BT01,PKCS1BT02,PKCS1PSS,PKCS1OAEP,X.923,PEM,B1,XML,SSL
KEYEDHASH-ALGORITHMS = HMAC
SIG-ALGORITHMS = RSA,DSA,ECDSA
KEYEXCHANGE-ALGORITHMS = DH,ECDH
ELLIPTIC-CURVES = P-192,P-224,P-256,P-384,P-521
RANDOM-ALGORITHMS = CTR_DRBG

 

Trouble Shooting CommonCryptoLib

In CommonCryptoLib 8.5.3 a new method for trace configuration was introduced. The configuration is described in note 2338952. If CommonCryptoLib is configured this way the following trace configuration is not possible.

To turn on trace file generation for CommonCryptoLib, go to the program folder where the library is loaded from (like /usr/sap/<SID>/<INST>/exe), and create a new text file named “sectrace.ini” with the following content:

LEVEL=4
DIRECTORY=<new-or-empty-subfolder>

The value of DIRECTORY must a valid folder name for the respective platform, and it must be the subfolder of an existing one, and should be placed in a local drive. If DIRECTORY does not exist, it will be created.

Example for Windows: DIRECTORY=D:\usr\sap\<SID>\<INST>\sectrace

Example for Linux: DIRECTORY=/usr/sap/<SID>/<INST>/sectrace

where <SID> and <INST> are the concrete SID and instance names.

The number and size of generated trace files in DIRECTORY may grow very quickly, so there should be sufficient disk space.

It is recommended to remove or rename “sectrace.ini” once the trouble shooting activities are completed, which will turn off further tracing immediately. All trace files should be removed manually once they are not needed for problem analysis anymore.

The full syntax of sectrace.ini is as follows:

;; Trace configuration for CommonCryptoLib

;; Directory where trace files are written
;;     You can use environment variables (%VARNAME%) in the specified path.
;;     %.BINDIR.% will be replaced by the directory of the CommonCryptoLib installation
;;     There will be one trace file for each process.
;; Directory          = <path-to-trace-folder>
;; Linux/UNIX platforms:
; Directory          = /usr/sap/<SID><INST>/sectrace
;; Windows platforms:
; Directory          = D:\usr\sap\<SID>\<INST>\sectrace
Directory          = %.BINDIR.%/../sectrace

;; Trace level
;;    0: Deactivated
;;    1: Errors
;;    2: + Warnings
;;    3: + Infos
;;    4: + Developer traces
;; Level              = <level-number>
;; Developer traces:
Level               = 4

;; Log Rotation

;;  Specify a file size (in bytes). If the trace file sec-*.trc becomes much bigger than this size, 
;;   its content is moved to a backup file named sec-*.<number>.trc and <number> is incremented.
;;   The value 0 (default) turns log rotation off.
;; RotateFileSize     = <size-in-bytes>
;; Rotate files if larger than 10MB:
RotateFileSize     = 10000000

;;   Number of trace backup files 
;;   If this configured number of backup files has been reached then <number> is set to 0 again 
;;   so the oldest backup file will be overwritten.
;; RotateFileNumber   = <number-of-backup-files>
;; Rotate with 10 backup files:
RotateFileNumber   = 10

 

Maintenance Strategy

There is one current and maintained version of CommonCryptoLib, which represents the latest fixes and feature enhancements. Previous versions are not changed anymore, i.e. there are no hotfixes for old versions. Even in case of a security relevant corrections, only the latest version will be patched.

Patches are provided on a non-regular base, i.e. when a security issue needs to be fixed or other corrections are required, or when new features and improvements shall be offered.

Usually, the latest version also triggers a NetWeaver Kernel patch. This allows two methods of implementation: Either install the latest Kernel patch, or keep the Kernel and install the latest CommonCryptoLib only.

The following Version History of CommonCryptoLib shall be used to decide on the minimum compatible version for a system. In general, it is recommended to update to the latest version.

 

Version History of CommonCryptoLib

Version SAP Note Fixes and Features
8.4.9 1902750 Fixes for SNC and SPNego with Apple iOS.
8.4.10 1931634 Fixes some stability issues.
8.4.11 1931778 Fixes for SSF and ABAP APIs.
8.4.12 1932471 Fixes for sapgenpse, SSL, SNC, and SSF.
8.4.13 1963136 Fixes for SSL PSEs in STRUST.
8.4.14 1971668 Fixes for STRUST, ABAP server, and HP-UX.
8.4.15 1978222 Fixes for STRUST and RSA-PSS.
8.4.16 1993863 Fixes for SNC credentials for ABAP on Windows, certificate import in STRUST, and ABAP WAS certreq/certreq2 in Google Chrome.
8.4.17 2001527 Fixes for SAP Content Server 6.50 and SAP Web Dispatcher.
8.4.18 n/a n/a
8.4.19 2015923 Fixes for SNC with wrong peer name scheme, certificates with some GeneralizedTime formats, SNC credentials confusion, and LPS decryption.
8.4.20 2029258 Fixes for SNC names with x500UniqueIdentifier, Kerberos keyTab confusion in SNC and SPNego, and SSF with HSM RSA keys larger than 2048 bit.
8.4.21 2040818 Fixes for compatibility with SAPCRYPTOLIB 5.5.5 PSE credentials.
8.4.22 2044737 Fixes for compatibility with SAPCRYPTOLIB 5.5.5 SSL PSEs and SAP Content Server 6.50.
8.4.23 2054332 Fixes for STRUST certificate export and SAP Content Server 6.50 on Windows.
8.4.24 2058745 Fixes for for compatibility with SAPCRYPTOLIB 5.5.5 PSE private keys.
8.4.25 2062967 Fixes for memory leaks in ABAP work processes on UNIX.
8.4.26 n/a n/a
8.4.27 n/a n/a
8.4.28 n/a n/a
8.4.29 n/a n/a
8.4.30 2071200 Fixed a functional error
8.4.31 2065806 Fixes for memory leaks in ABAP work processes on UNIX, out-of-memory situations, PSE and PKCS#12 file permission security on Linux/UNIX, RSA keys using a public exponent different from 65537, missing RIPDEMD128 in SSF, ABAP report RPUSVKD0 (and probably others) to create the PSE credentials, display of key usages dataEncipherment and cRLSign during import of PKCS#12 files, SAP Web Dispatcher SSL using certificates with too many RDN components, compatibility with SAPCRYPTOLIB 5.5.5 PSEs with long lists of trusted certificates.

Featuring TLS 1.2 support, performance improvements in RSA and AES, and RSA-PSS for HSM keys used by SAP SSO Secure Login Server.

8.4.32 2095346 Fixes for HANA DB encryption performance using specialized AES API.
8.4.33 2111574 Fixes for PKCS#12 file import, and SSF signature compatibilty with 3rd party applications.

Featuring a FIPS 140-2 certified cryptographic kernel module.

8.4.34 2120780 Fixes for certificates with special date formats, TLS with RSA key size 4096 bit on client side, SNC names with leading “#”, Kerberos names with doubled domain, SNC names with non-ASCII-characters, TLS in non-blocking mode.
8.4.35 2134460 Fixes for PSE generation with Distinguished Names containing escaped Unicode characters and for PSE file permissions on Windows.
8.4.36 2146549 Fixes for SSL/TLS ephemeral RSA keys with non-export cipher suites, SSL/TLS RSA key size minimum for client and server certificates, SSL/TLS cipher suite default list, new cipher suite name suffix TLS_, SNC with high performance for large CRLs, sapgenpse get_my_name with (extended) key usage output.
8.4.37 2164991 Fixes for empty certificate name parts, unknown algorithms identifiers, and trace output of verification results on PowerPC and SPARC platforms.
8.4.38 2181733 Fix for SNC cache of PSE files.

Featuring performance improvements for most cryptographic algorithms, TLS with Perfect Forward Secrecy (PFS) with ECDHE and GCM, new command line sapgenpse tlsinfo to analyze and design TLS ciphersuite profile parameters, and support for more certificate details in STRUST. Weak algorithms MD2 and MD4 disabled for secure hashing purposes.
Some new features are not available in the current FIPS 140-2 certified external crypto kernel.

8.4.39 2192597 Fix for TLS 1.1 and 1.2 record protocol.
8.4.40 2196546 Fixes for command sapgenpse maintain_pk, certificate import in STRUST, memory leak in TLS and SNI, crashes on HP-UX and AIX during library initialization, PSE paths in Content Server.
8.4.41 2202512 Fix for crash in AES functions on PowerPC.
8.4.42 2209439 Fixes for forked SSL/TLS clients, SNI TLS extensions, failed LIKEY initialisation in ABAP work processes.

Featuring sapgenpse command line options to support multiple Subject Alternative Names in certificate signing requests, an option to support PKCS#8 private key export from PSEs, and a new shipment format for the FIPS 140-2 certificated cryptographic kernel module.

8.4.43 2223635 Fixes for SNC errors on SAProuter, for rare crashes in SSL/TLS on HANA DB, failed LIKEY initialisation in ABAP work processes, and PSE creation in STRUST where SHA-1 was still the default.
8.4.44 n/a This version was replaced by 8.4.45.
8.4.45 2241096 Fix for rare crashes in SSL/TLS on HANA DB.

Featuring VCIPHER support for Linux with POWER8 CPUs to accellerate AES.

8.4.46 2243018 Removed VCIPHER support for POWER8 CPUs again.
8.4.47 2243550 Added VCIPHER support for POWER8 CPUs again.
8.4.48 2253695 Fixes for small memory leak in SPNEGO, ECDH with P-244 and P-256, TLS with FIPS crypto kernel.

Featuring a new TLS ciphersuite flag for strict protocol version configuration.

8.4.49 2275390 Fixes for sapgenpse commands concerning PKCS#12 passwords, Kerberos keytabs, subjectAlternativeNames in PKCS#12 or PKCS#7 files, SHA-2 in PKCS#10 generation, and a fix for SNC names with German Umlauts. SSLv3 and MEDIUM cipher suites have been removed from the default configurations.
8.5.0 n/a This version was not released.
8.5.1 2296831 New minor version of CommonCryptoLib, only shipped with initial download image for SAP Single Sign-On 3.0. It is recommended to use version 8.5.2 or higher.
8.5.2 2339102 Fixes for sapgenpse command seclogin, minor and small memory allocation corrections, and elimination of weak TLS cipher suites.

Featuring new SNC modes for SAP Single Sign-On 3.0, configuration by profile parameters, new sapgenpse commands, support for TLS_FALLBACK_SCSV, and a new FIPS 140-2 crypto kernel (which is not certified yet).

8.5.3 2338757 Fixes CommonCryptoLib configuration profile issues.

Featuring CommonCryptoLib trace configuration using profile parameters.

8.5.4 2288631 Fixes a wrong error code in TLS re-negotiation, a weakness in TLS cipher suites (Sweet32/3DES), and a self-test failure on AIX/POWER8.

Featuring a sapgenpse command line option to turn off implicit trust to a PSE´s identity certificate and root CA.

8.5.5 2365041 Fixes undesired SNC/Kerberos mode in server-to-server communication and a wrong default for Certificate Policy verification in SNC and TLS.

Featuring profile parameter based configuration for mail address derived SNC names, new command options for sapgenpse get_crl, and a new command sapgenpse hsminfo to create and test HSM token identifiers.

8.5.6 2376742 Fixes potential crash in TLS handshake.

Featuring CRL checking during TLS handshakes, improved Kerberos traces, and trace file names with process names.

8.5.7 2390726 Fixes in configuration of SNC with X.509 or Kerberos and other “profile” parameters, TLS configuration´s handshake parameter flag collisions, TLS cipher suite default placement of P-256 reverted to EC_HIGH, and a rare dead lock situation in multi-threading situations.

Featuring general checking of CRLs also outside SNC/SSF/TLS, and support for STRUST crypto algorithm selection (only 7.50 and higher).

8.5.8 2417508 Fixes in TLS to avoid crash when no server certificate was received, and in sapgenpse tlsinfo -H help text.

Featuring SPARC CPU crypto acceleration (T4 and higher) of AES, MD5, SHA-1, SHA-2, RSA and ECC arithmetic, and a new profile parameter to disable any CPU based crypto (INTEL, POWER8, SPARC).

8.5.9 2423394 Fixes in TLS to prevent crashes in end points like ICM, SAPSTARTSRV or SAP HANA DB Index Server.
8.5.10 2427966 Fixes in compiler settings for Linux to make use of RELRO memory corruption mitigation technique, and in SSFW_KRN_VERIFY to verify the trust of the provided certificate in raw signatures.
8.5.11 2434211 Fixes in library initialization, SNC with ECDHE and SHA-512, SNC configuration, and trace file names on AIX.

Featuring new SNC modes for upcoming SNC Client Encryption 2.0.

8.5.12 2453677 Fixes in PSE file write operation and certificate signing request with doubled Subject Alternative Names.

Featuring support for time_t output in certificate parsing function.

8.5.13 2459506 Fixes in X.509 certificate chain constructions from lists with same subject names, failures in verifications caused by such situations, memory leaks in signature verification, and improvements of certificate print-outs in traces.
8.5.14 2481365 Fix in certificate print-outs to correct a regression with SAP HR digital signature generation.
8.5.15 2510863 Fixes in Kerberos (memory leaks), certificate generation with seriaNumber RDN, TLS flags for “Allow blind sending of a client certificate” and “BC” on client side, command sapgenpse hsminfo, and OpenLDAP / TLS interrupt handling.

Featuring new configuration properties for credentials file encryption algorithms and user ID generation, and PSE file encryption algorithms.

Software Components
Software Component From To And Subsequent
KRNL32NUC 7.20 7.20
KRNL32NUC 7.20EXT 7.20EXT
KRNL32NUC 7.21 7.21
KRNL32NUC 7.21EXT 7.21EXT
KRNL32UC 7.20 7.20
KRNL32UC 7.20EXT 7.20EXT
KRNL32UC 7.21 7.21
KRNL32UC 7.21EXT 7.21EXT
KRNL64NUC 7.20 7.20
KRNL64NUC 7.20EXT 7.20EXT
KRNL64NUC 7.21 7.21
KRNL64NUC 7.21EXT 7.21EXT
KRNL64NUC 7.38 7.38
KRNL64NUC 7.40 7.40
KRNL64NUC 7.41 7.41
KRNL64UC 7.20 7.20
KRNL64UC 7.20EXT 7.20EXT
KRNL64UC 7.21 7.21
KRNL64UC 7.21EXT 7.21EXT
KRNL64UC 7.38 7.38
Support Package Patches
Software Component Support Package Patch Level Download
SAP KERNEL 7.20 32-BIT SP513 513
SAP KERNEL 7.20 32-BIT UNICODE SP513 513
SAP KERNEL 7.20 64-BIT SP000 513
SAP KERNEL 7.20 64-BIT SP513 513
SAP KERNEL 7.20 64-BIT UNICODE SP000 513
SAP KERNEL 7.20 64-BIT UNICODE SP513 513
SAP KERNEL 7.21 32-BIT SP136 136
SAP KERNEL 7.21 32-BIT UNICODE SP136 136
SAP KERNEL 7.21 64-BIT SP136 136
SAP KERNEL 7.21 64-BIT UNICODE SP136 136
SAP KERNEL 7.21 EXT 32-BIT SP136 136
SAP KERNEL 7.21 EXT 32-BIT UC SP136 136
SAP KERNEL 7.21 EXT 64-BIT SP136 136
SAP KERNEL 7.21 EXT 64-BIT UC SP136 136
SAP KERNEL 7.38 64-BIT SP039 39
SAP KERNEL 7.38 64-BIT UNICODE SP039 39
SAP KERNEL 7.40 64-BIT SP026 26
SAP KERNEL 7.40 64-BIT UNICODE SP026 26
References
This document is causing side effects
Attributes
Name Value
Other Components BC-IAM-SSO-SL Secure Login
Other Components BC-SEC Security

You may also like...

Leave a Reply

Your email address will not be published. Required fields are marked *