How-to sapgenpse

Published on 1. June 2020 | Updated on 18. March 2023

If you have to deal with certificates in the SAP environment, and this is always the case sooner or later ;-), you very quickly come into contact, directly or indirectly, with the command line tool sapgenpse. This article describes how and for what purpose you can use sapgenpse.

Introduction

At SAP, public-key certificates are stored in a Personal Security Environment (PSE).

It is an environment where both trusted public certificates and the owner’s private key are stored for a specific purpose. Therefore, only the owner of the information should have access to its PSE. A user’s or component’s PSE is usually located in a protected directory in the file system or on a smart card.

Earmarking consists, for example, of the SAP system acting both as a server and as a client. Therefore, SAP already provides for certain separations by default.

PSE Types

Firstly, there is SAPSSLS, which is used when the SAP application server acts as a web server and delivers the requests encrypted via HTTPS.

The SAP system itself, uses the SAPSYS PSE to create and verify digital signatures. However, this cannot be used to encrypt information.

For an encrypted network connection the SAPSNC is used, which can secure e.g. the SAP protocols RFC and DIAG. Single Sign-On (SSO) is also based on SNC.

The SAP system, when exchanging information, can also behave as a client when addressing another server. There are two PSEs for this:

The application server uses the anonymous client PSE (SAPSSLA) to connect to another web server when only server-side authentication is used. He does not use it for his own authentication.

In contrast, the standard SSL client PSE (SAPSSLC) is used to authenticate itself to other web servers.

Perhaps for better understanding, when you access this website, you are also using an anonymous connection. When you authenticate to the SAP Support Portal with a certificate, it corresponds to the standard SSL client PSE.

Maintain PSE with sapgenpse

You will normally maintain a PSE with an ABAP system using transaction STRUST. However, there are situations where the STRUST does not provide the desired function, but with the sapgenpse this is very possible. One example is the export of certificates with private key.

The basic functionality is provided by the CommonCryptoLib. It can be updated separately as part of the kernel. This may be necessary if you rarely update a stable kernel in your SAP environment to a higher version.

In this context, you should regularly read SAP Note 1848999.

Create PSE – sapgenpse gen_pse

As soon as one works on the command line with the tool sapgenpse, the variable SECUDIR must be maintained first. The following examples assume a *NIX type system, but the principle is the same for Windows.

ts1adm@/usr/sap/TS1/D00/sec $: export SECUDIR=$(pwd)
ts1adm@/usr/sap/TS1/D00/sec $: sapgenpse gen_pse -p SAPSSLS -a RSA:2048:SHA256 -k GN-dNSName:sapserver.example.com -k GN-dNSName:www.sapserver.example.com "CN=sapserver.example.com, OU=SAP-Basis, O=My Company, C=DE"

In the following the parameters are listed again individually.

-p SAPSSLS
-a RSA:2048:SHA256
-k GN-dNSName:sapserver.example.com 
-k GN-dNSName:www.sapserver.example.com 
"CN=sapserver.example.com, OU=SAP-Basis, O=My Company, C=DE"

The first parameter -p specifies the name of the PSE to be created. The parameter is mandatory.

The second parameter -a is optional. This allows you to select the key type to be used (RSA, DSA, or ECDSA), the key size that depends on the key type, and the hash algorithm for the signature (SHA1, SHA224, SHA256, SHA384, SHA512).

The -k GN-dNSName parameter is theoretically optional, but practically it should always be used. This parameter is used to specify a Subject Alternative Name (SAN). This is used so that the certificate can be verified against the hostname by the client. At the latest since google enforced the use by means of the web browser chrome in 2017 (heise: Chrome blocks certificates with common name), the parameter should be mandatory.

Finally, the Distinguished Name (DN) is specified in quotation marks. Theoretically, this could be specified empty if a Subject Alternative Name is specified at the same time. However, it is safe to assume that many implementations cannot cope with an empty DN. At least the Common Name (CN) should be specified.

The -x parameter was not specified in this example, but it is mandatory. It is used to specify the password that protects access to the PSE. Without a password, it may be possible for a third party to manipulate the PSE at the operating system level. If you still do not want to specify a password, then the query must be confirmed with ENTER blank.

In this example, the certificate request (—–BEGIN CERTIFICATE REQUEST—– … —–END CERTIFICATE REQUEST—–) was issued on the command line. One can “copy and paste” this Certificate Signing Request (CSR) to an internal Certification Authority (CA) (including the —- BEGIN and END —- lines) and forward it by mail to an appropriate person in charge.

Signing is almost mandatory if the server will be accessible for normal users. For example, if the SAP WebGui is accessed via it. However, the certificate of the internal root CA and, if applicable, other sub CAs must be installed on the user’s PC, for example via group policy in Windows. This then immediately helps with internal browsers like Edge or Internet Explorer. Additional measures must be taken when using Chrome or Firefox.

If you want to pass the CSR as a file, specify the parameter -r <filename>. As file extension csr has proven to be handy. However, this is not decisive.

ts1adm@/usr/sap/TS1/D00/sec $: sapgenpse gen_pse -p SAPSSLS -a RSA:4096:SHA256 -k GN-dNSName:sapserver.example.com -k GN-dNSName:www.sapserver.example.com -r request.csr  "CN=sapserver.example.com, OU=SAP-Basis, O=My Company, C=DE"
ts1adm@/usr/sap/TS1/D00/sec $: cat request.csr
-----BEGIN CERTIFICATE REQUEST-----
MIIE6TCCAtECAQAwVjELMAkGA1UEBhMCQVQxEzARBgNVBAoTCk15IENvbXBhbnkx
EjAQBgNVBAsTCVNBUC1CYXNpczEeMBwGA1UEAxMVc2Fwc2VydmVyLmV4YW1wbGUu
...
+4lJtsZDc2+9P4cSjK3UlLcwkatMZtBocZF9d4i8BnzYWbU2OO6zRxfsO1UUmKzy
zcqrsdHyTcXW9K/WWgCZ12nkAeBix2eWjf2rlIXRcjYwzsCFaPigEU/idRjGtI4g
N3tjrenMJqafYp0mhQ==
-----END CERTIFICATE REQUEST-----
ts1adm@/usr/sap/TS1/D00/sec $:

Self signed certificate

Basically, by creating the PSE above, you already have a self-signed certificate. This certificate will most likely cause browser warnings. This warning can be ignored or with the import, and thus a manual trust, this certificate can be deposited as trustworthy.

This can be useful if you are setting up a temporary test system and the signing request is not worth the effort.

In this case, you can create the PSE using the -noreq parameter. This will not output a CSR.

ts1adm@/usr/sap/TS1/D00/sec $: sapgenpse gen_pse -p SAPSSLS -k GN-dNSName:sapserver.example.com -k GN-dNSName:www.sapserver.example.com -noreq  "CN=sapserver.example.com, OU=SAP-Basis, O=My Company, C=DE"
Please enter PSE PIN/Passphrase:
Please reenter PSE PIN/Passphrase:

!!! WARNING: For security reasons it is recommended to use a PIN/passphrase
!!! WARNING: which is at least 8 characters long and contains characters in
!!! WARNING: upper and lower case, numbers and non-alphanumeric symbols.

ts1adm@/usr/sap/TS1/D00/sec $:

Renew certificate request

If a certificate is to be renewed, it is not necessary to create a new PSE. In many cases, you just want to renew the validity date and apply the existing settings.

ts1adm@/usr/sap/TS1/D00/sec $: sapgenpse gen_pse -p SAPSSLS  -j -onlyreq

-p SAPSSLS
-j 
-onlyreq

With the parameter -j the Subject Alternative Names (SAN) are taken over. The -onlyreq parameter is the actual call for certificate renewal. If this parameter is set, additional parameters such as the distinguished name or the algorithm are also ignored.

BUT, an“onlyreq” is not the recommendation, because with this also the “Private Key” remains the old one. Rebuilding the PSE always provides the opportunity to set new secure parameters (and also to replace compromised keys).

In the following screenshot, additional parameters were deliberately passed. With the parameter -v (verbose) it then also becomes apparent that the “Signed Part” includes the old distinguished name.

sapgenpse -onlyreq — sapgenpse certificate renewal

Tip: You can also extend the above command with the parameter -r <filename> and write the CSR to a file. Then, on a *NIX system where openssl is installed by default, you can also check this CSR afterwards using the command openssl req -in mycert.csr -noout -text. Alternatively, you can also display the CSR online, for example at https://www.sslshopper.com/csr-decoder.html.

Import certificate (certificate response) – sapgenspe import_own_cert

Once the CSR has been signed by a CA, the finished certificate must be imported. The complete certificate chain must be imported. It should also be noted that the certificate, the certificate response, must match the public key of the certificate signing request. So I can’t import any certificate just because the distinguished name matches ;-).

ts1adm@/usr/sap/TS1/D00/sec $: sapgenpse import_own_cert -p SAPSSLS -v -c /tmp/mycert.cer -r /tmp/SubCA.cer -r /tmp/RootCA.cer -x psepin

-p SAPSSLS 
-v 
-c /tmp/mycert.cer 
-r /tmp/SubCA.cer 
-r /tmp/RootCA.cer 
-x psepin

Specifying the PSE with the -p parameter is mandatory. With -v extended messages are output. The actual certificate is specified with the -c parameter. It also depends on the format in which the certificate is provided.

The PEM format can already be recognized in the certificate request. There the request begins with —–BEGIN CERTIFICATE REQUEST—–, the certificate begins with —–BEGIN CERTIFICATE —–. The ending can vary. Typical are .cer, .crt, .pem, .key. You can easily display it with a text editor.

These formats always contain only one certificate and not the certificate chain. Therefore, the certificate chain must be completed with the -r parameter.

With a P7B certificate, which usually also has this extension, you get a binary certificate that contains the entire certificate chain. With such a certificate, the certificate chain does not need to be manually extended with the -r parameter.

In the Related Links section there is a link that explains the different formats in more detail.

Password-free access to PSE – sapgenpse seclogin

To manage the PSE, you typically need a PIN. Access without PIN would allow full access to the private key as well, which is a security risk.

Nevertheless, sometimes there is a need to set up access without knowing the password. In SAP Hostagent, for example, the process runs under the user sapadm. However, the PSE setup is performed under a different user.

ts1adm@/usr/sap/TS1/D00/sec $: sapgenpse seclogin -p SAPSSLS -O sapadm -x psepin

-p SAPSSLS 
-O sapadm 
-x psepin

However, this only works if the credentials have not been protected with LPS. Then you cannot specify these credentials for another user.

These credentials are stored in the cred_v2 file. If the pin of a PSE is changed, the credentials must be stored again.

If you ever want to check which users have stored credentials, this is not so easy. Basically you can work with:

ts1adm@/usr/sap/TS1/D00/sec $: sapgenpse seclogin -l

, display the stored credentials. The only catch is that no user names are stored.

running seclogin with USER="ts1adm"

 0 (LPS:OFF): DNS=sapserver.example.com, CN=sapserver.example.com, OU=SAP-Basis, O=My Company, C=DE
         (LPS:OFF): /usr/sap/TS1/D00/sec/SAPSSLS.pse
      NOT readable for ts1adm

 1 (LPS:OFF): DNS=sapserver.example.com, CN=sapserver.example.com, OU=SAP-Basis, O=My Company, C=DE
         (LPS:OFF): /usr/sap/TS1/D00/sec/SAPSSLS.ps

You can see two entries here, starting with index 0, which is “NOT readable” for the querying user ts1adm. You can only “test” users here with the command sapgenpse seclogin -l -O sapadm:

sapgenpse seclogin -l -O sapadm
 running seclogin with USER="s4xadm"
 listing credentials for secondary user "sapadm" ...

 0 (LPS:OFF): DNS=sapserver.example.com, CN=sapserver.example.com, OU=SAP-Basis, O=My Company, C=DE
         (LPS:OFF): /usr/sap/TS1/D00/sec/SAPSSLS.pse

 0 (LPS:OFF): DNS=sapserver.example.com, CN=sapserver.example.com, OU=SAP-Basis, O=My Company, C=DE
         (LPS:OFF): /usr/sap/TS1/D00/sec/SAPSSLS.pse
      NOT readable for sapadm


 1 readable SSO-Credentials available (total 2)

Export private key – sapgenpse export_p8

Two formats are available for exporting the private key (incl. certificate): once PKCS 8 and PKCS 12, also known as file extension .p12 or .pfx.

With PKCS 8 a Base64 decoded file PEM file is generated. The content can then be viewed with cat, for example. When exporting, unlike my example, the -z parameter should be used to password protect the generated file.

ts1adm@/usr/sap/TS1/D00/sec $: sapgenpse export_p8 -p SAPSSLS -z "" server.pem

!!! WARNING: For security reasons it is recommended to use a PIN/passphrase
!!! WARNING: which is at least 8 characters long and contains characters in
!!! WARNING: upper and lower case, numbers and non-alphanumeric symbols.

ts1adm@/usr/sap/TS1/D00/sec $: cat server.pem
-----BEGIN PRIVATE KEY-----
MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQCeRkFg5nXMSvL4
...
6ArXXIkAMfBUp2dkA+hbwlFhYpgbZ+QZdeC47YGfhRnWGh9DFahvH26KTxHdoUOx
YGjG+ck0E3tHhmey+AXC/Fs=
-----END PRIVATE KEY-----
Certificate:
 Subject:                              DNS=sapserver.example.com, CN=sapserver.example.com, OU=SAP-Basis, O=My Company, C=DE
 Issuer:                               DNS=sapserver.example.com, CN=sapserver.example.com, OU=SAP-Basis, O=My Company, C=DE
 Serial Number:                        0A:20:22:08:17:07:48:01
-----BEGIN CERTIFICATE-----
MIIDkzCCAnsCCAogIggXB0gBMA0GCSqGSIb3DQEBCwUAMIGLMQswCQYDVQQGEwJE
...
NQglv0y8uKVR6gX1wUK7CaKZb3QvvoXi7GlxcMnSojlC0YICFKI0JukMQVO7Pq7g
lG13VaHAHA==
-----END CERTIFICATE-----

With PKCS 12 files you get a binary export, and an archive file that can store cryptographic objects in a single file. In contrast to PKCS 8, it can export and include all certificates of the “Chain of Trust”. Thus also the root certificate and all intermediate certificates.

Why should you export a PSE? Well, you get into this situation relatively quickly if you are running SAP Netweaver Java Server. Netweaver Java cannot generate a Subject Alternative Name during certificate creation. This does not generate valid certificates. An official way is to create a temporary PSE as described above and export it.

Addendum: As of Netweaver 7.50 SPS 25 it is now possible to generate Java SAN certificates with Netweaver. See “Related links”.

Definitions

PSE = the Personal Security Environmentis a secure repository for public and private keys.

SSF = SecureStore& Forward(SSF) mechanisms provide the ability to secure data and documents on the SAP NetWeaver Application Server (SAP NetWeaver AS) as independent data entities.

CCL = the CommonCryptoLibprovides the cryptographic functions (libraries and programs). The tool sapgenpse is a part of it. It is the successor of the SAPCryptoLib and part of the kernel.

SNC = Secure Network Communication, encrypted network connections in the SAP environment.

CA = a Certification Authorityis a certification authority that creates and manages certificates.

CSR = The Certificate Signing Requestis sent to a CA for signing. The response, the Certificate Response, is then the official certificate.