In this blog post, I will explain how authentication with X.509 certificates and private keys works in the ODBC driver for ABAP. I will cover both formats: PEM certificates and an SAP PSE file. Simply choose whichever format is more convenient in your setup; both can be converted to one another.
Configuring certificate authentication on the backend system is a general user configuration topic and is out of scope for this post.

X.509 certificate-based authentication allows clients to authenticate using a certificate and private key instead of a username and password. To activate X.509 authentication, set the connection parameter AuthenticationType=X509. The Uid parameter is not needed for X.509 authentication.

PEM Certificates

The driver offers two connection string parameters related to PEM certificates: TrustedCertificates (certificates used to verify the server’s identity) and UserCertificates (the client certificate and PKCS#8-formatted private key used for mutual TLS). Both parameters accept the same format and are treated as one combined set, so the split is purely a matter of convenience. If the combined input across both parameters contains multiple private keys, only the first private key (encrypted or not) is used. TrustedCertificates and UserCertificates are not part of the Windows UI and must be added to Additional Attributes field.

Inline PEM Certificates

Before patch level (PL) 33, the only way to pass PEM certificates and private keys to the driver was by embedding them directly in the connection string. This can make the connection string very long and is incompatible with some tools. For example, the unixODBC driver manager reads config files incorrectly if the values contain line breaks, which is the case for PEM-encoded data.

PEM Certificate Files

Starting with PL 33, it is possible to set the parameters TrustedCertificates and UserCertificates to point to a file path instead of inline data. Each file must contain only certificate data, private keys, or both – in the same format used when passing them inline to the parameters.

For example, a PEM file containing a certificate and a private key looks like this:
—–BEGIN CERTIFICATE—–
<base64 encoded certificate>
—–END CERTIFICATE—–
—–BEGIN PRIVATE KEY—–
<base64 encoded private key>
—–END PRIVATE KEY—–

Encrypted Private Keys

PL 33 also added support for encrypted private keys. Encrypted private keys are supported for both inline values and file paths. The password for the private key is provided in the Pwd parameter. Note that this is the same Pwd connection parameter used for login credentials; however, when AuthenticationType=X509 is set, it is only used to decrypt the private key and is not sent to the server.

An incorrect password for the private key produces this error:
RfcCreateInMemoryPSE: failed to generate in memory PSE. Importing private key failed (RESULT: PSE credentials not available or wrong PIN!).

PSE File

SAP systems commonly use PSE (Personal Security Environment) files to store certificates and private keys. Unlike PEM files, PSE files are managed through SAP’s own cryptographic library, sapcryptolib, and its associated tool sapgenpse. sapgenpse is included in the sapcryptolib package, which is a general prerequisite for using the driver. If your certificate infrastructure already uses PSE files, you can pass them directly to the driver without converting to PEM.

To use the PSE file (containing certificates and a private key), add PseFile=<path_to_pse_file> to the connection string. The parameter is also part of the Windows UI. The PSE file is decrypted by sapcryptolib itself (not by the driver), using credentials stored in a cred_v2 file. The Pwd connection parameter is not used.

To create the cred_v2 file, do the following:

1. Set SECUDIR

Decide where to store the cred_v2 file and set the SECUDIR environment variable to that path.

On Linux and macOS, this is done by the following command:

export SECUDIR=<path_to_secure_directory>

On Windows, you can use this command:

set SECUDIR=<path_to_secure_directory>

2. Create the cred_v2 file with sapgenpse

From a shell where the SECUDIR environment variable is visible, execute the following command:

sapgenpse seclogin -p <path_to_pse_file> -x <password_for_pse_file>

With the cred_v2 file in place, the SECUDIR environment variable must be set in the environment of the process running the ODBC driver.

If the driver cannot find or read the cred_v2 file, the connection will fail with the following error:
SSSLERR_PSE_MISSING_PIN: Could not create credential from <path_to_pse_file> for client role.

Examples

⚠️For readability, line breaks have been added after each connection string attribute. To use the example connection strings in the driver, these line breaks have to be removed! ⚠️

Connection String with Inlined PEM Certificates

Driver=<path_to_driver>;
Host=<host_address>;
Port=<port>;
ServicePath=/sap/bc/sql/sql1/sap/S_PRIVILEGED;
Typemap=semantic;
AuthenticationType=X509;
CryptoLibrary=<path_to_cryptolib>;
TrustedCertificates={
—–BEGIN CERTIFICATE—–
<base64 encoded certificate>
—–END CERTIFICATE—–
};
UserCertificates={
—–BEGIN CERTIFICATE—–
<base64 encoded certificate>
—–END CERTIFICATE—–
—–BEGIN CERTIFICATE—–
<base64 encoded certificate>
—–END CERTIFICATE—–
—–BEGIN CERTIFICATE—–
<base64 encoded certificate>
—–END CERTIFICATE—–
—–BEGIN PRIVATE KEY—–
<base64 encoded private key>
—–END PRIVATE KEY—–
}

Connection String with PEM Certificate Files and Password

Driver=<path_to_driver>;
Host=<host_address>;
Port=<port>;
ServicePath=/sap/bc/sql/sql1/sap/S_PRIVILEGED;
Typemap=semantic;
AuthenticationType=X509;
CryptoLibrary=<path_to_cryptolib>;
TrustedCertificates=<path_to_trusted_certificates_pem_file>;
UserCertificates=<path_to_user_certificates_pem_file>;
Pwd=<password_for_pem_private_key>

Connection String with PSE Certificate File

Driver=<path_to_driver>;
Host=<host_address>;
Port=<port>;
ServicePath=/sap/bc/sql/sql1/sap/S_PRIVILEGED;
Typemap=semantic;
AuthenticationType=X509;
CryptoLibrary=<path_to_cryptolib>;
PseFile=<path_to_pse_file>

 In this blog post, I will explain how authentication with X.509 certificates and private keys works in the ODBC driver for ABAP. I will cover both formats: PEM certificates and an SAP PSE file. Simply choose whichever format is more convenient in your setup; both can be converted to one another.Configuring certificate authentication on the backend system is a general user configuration topic and is out of scope for this post.X.509 certificate-based authentication allows clients to authenticate using a certificate and private key instead of a username and password. To activate X.509 authentication, set the connection parameter AuthenticationType=X509. The Uid parameter is not needed for X.509 authentication.PEM CertificatesThe driver offers two connection string parameters related to PEM certificates: TrustedCertificates (certificates used to verify the server’s identity) and UserCertificates (the client certificate and PKCS#8-formatted private key used for mutual TLS). Both parameters accept the same format and are treated as one combined set, so the split is purely a matter of convenience. If the combined input across both parameters contains multiple private keys, only the first private key (encrypted or not) is used. TrustedCertificates and UserCertificates are not part of the Windows UI and must be added to Additional Attributes field.Inline PEM CertificatesBefore patch level (PL) 33, the only way to pass PEM certificates and private keys to the driver was by embedding them directly in the connection string. This can make the connection string very long and is incompatible with some tools. For example, the unixODBC driver manager reads config files incorrectly if the values contain line breaks, which is the case for PEM-encoded data.PEM Certificate FilesStarting with PL 33, it is possible to set the parameters TrustedCertificates and UserCertificates to point to a file path instead of inline data. Each file must contain only certificate data, private keys, or both – in the same format used when passing them inline to the parameters.For example, a PEM file containing a certificate and a private key looks like this:—–BEGIN CERTIFICATE—–<base64 encoded certificate>—–END CERTIFICATE———-BEGIN PRIVATE KEY—–<base64 encoded private key>—–END PRIVATE KEY—–Encrypted Private KeysPL 33 also added support for encrypted private keys. Encrypted private keys are supported for both inline values and file paths. The password for the private key is provided in the Pwd parameter. Note that this is the same Pwd connection parameter used for login credentials; however, when AuthenticationType=X509 is set, it is only used to decrypt the private key and is not sent to the server.An incorrect password for the private key produces this error:RfcCreateInMemoryPSE: failed to generate in memory PSE. Importing private key failed (RESULT: PSE credentials not available or wrong PIN!).PSE FileSAP systems commonly use PSE (Personal Security Environment) files to store certificates and private keys. Unlike PEM files, PSE files are managed through SAP’s own cryptographic library, sapcryptolib, and its associated tool sapgenpse. sapgenpse is included in the sapcryptolib package, which is a general prerequisite for using the driver. If your certificate infrastructure already uses PSE files, you can pass them directly to the driver without converting to PEM.To use the PSE file (containing certificates and a private key), add PseFile=<path_to_pse_file> to the connection string. The parameter is also part of the Windows UI. The PSE file is decrypted by sapcryptolib itself (not by the driver), using credentials stored in a cred_v2 file. The Pwd connection parameter is not used.To create the cred_v2 file, do the following:1. Set SECUDIRDecide where to store the cred_v2 file and set the SECUDIR environment variable to that path.On Linux and macOS, this is done by the following command:export SECUDIR=<path_to_secure_directory>On Windows, you can use this command:set SECUDIR=<path_to_secure_directory>2. Create the cred_v2 file with sapgenpseFrom a shell where the SECUDIR environment variable is visible, execute the following command:sapgenpse seclogin -p <path_to_pse_file> -x <password_for_pse_file>With the cred_v2 file in place, the SECUDIR environment variable must be set in the environment of the process running the ODBC driver.If the driver cannot find or read the cred_v2 file, the connection will fail with the following error:SSSLERR_PSE_MISSING_PIN: Could not create credential from <path_to_pse_file> for client role.Examples⚠️For readability, line breaks have been added after each connection string attribute. To use the example connection strings in the driver, these line breaks have to be removed! ⚠️Connection String with Inlined PEM CertificatesDriver=<path_to_driver>;Host=<host_address>;Port=<port>;ServicePath=/sap/bc/sql/sql1/sap/S_PRIVILEGED;Typemap=semantic;AuthenticationType=X509;CryptoLibrary=<path_to_cryptolib>;TrustedCertificates={—–BEGIN CERTIFICATE—–<base64 encoded certificate>—–END CERTIFICATE—–};UserCertificates={—–BEGIN CERTIFICATE—–<base64 encoded certificate>—–END CERTIFICATE———-BEGIN CERTIFICATE—–<base64 encoded certificate>—–END CERTIFICATE———-BEGIN CERTIFICATE—–<base64 encoded certificate>—–END CERTIFICATE———-BEGIN PRIVATE KEY—–<base64 encoded private key>—–END PRIVATE KEY—–}Connection String with PEM Certificate Files and PasswordDriver=<path_to_driver>;Host=<host_address>;Port=<port>;ServicePath=/sap/bc/sql/sql1/sap/S_PRIVILEGED;Typemap=semantic;AuthenticationType=X509;CryptoLibrary=<path_to_cryptolib>;TrustedCertificates=<path_to_trusted_certificates_pem_file>;UserCertificates=<path_to_user_certificates_pem_file>;Pwd=<password_for_pem_private_key>Connection String with PSE Certificate FileDriver=<path_to_driver>;Host=<host_address>;Port=<port>;ServicePath=/sap/bc/sql/sql1/sap/S_PRIVILEGED;Typemap=semantic;AuthenticationType=X509;CryptoLibrary=<path_to_cryptolib>;PseFile=<path_to_pse_file> Read More Technology Blog Posts by SAP articles 

#SAPCHANNEL