SAP Note

Header Data

Symptom

You need to use the SAP Cryptographic Library for encrypting data in the SAP system (using SSF).

Other Terms

encryption, SAPSECULIB, SAPCRYPTOLIB, security, ELSTER, SSF, RSA

Reason and Prerequisites

The system is delivered with the SAP Security Library (SAPSECULIB). This library can be used for digital signatures created by the SAP system, but not for encrypting data. To have the system encrypt data, you must replace the SAPSECULIB with the SAP Cryptographic Library (SAPCRYPTOLIB). Important: you require a newer version of the SAPCRYPTOLIB - at least patchlevel 15 (or higher), see note 690999. The SAPCRYPTOLIB underlies German export regulations and therefore, its delivery is controlled. It is available to authorized customers on the SAP Service Marketplace at http://service.sap.com/download.

Solution

Replace the SAPSECULIB with the SAPCRYPTOLIB on the system's application server(s) and set up the system for using encryption. Follow the steps below. Important: If you are installing the SAPCRYPTOLIB for use with a specific application, then refer to the application's documentation. Certain applications do not require that the server's certificate is signed by a Certification Authority (for example, the HCM application ELSTER). The application may also specify certain information, for example, the algorithm to use or the naming convention for the Distinguished Name. Note: For the AS/400 platform, see Note 758667 for instructions on installing the SAPCryptolib and using the configuration program sapgenpse.

Installing the SAPCryptolib

1. Download the SAPCryptolib from the SAP Service Marketplace. See note 397175. You will receive a package containing the library, a license ticket "ticket" and the configuration program "sapgenpse".

2. Copy the library and the "sapgenpse" program to the $DIR_EXECUTABLE directory. Copy the "ticket" file to the $DIR_INSTANCE/sec directory on every application server.

3. For each application server, set the environment variable SECUDIR to the $DIR_INSTANCE/sec directory for the application server's user. (For UNIX, set it in the application server's startup scripts, For Windows, set it in <SID>adm's environment.)

4. Also make sure that the environment variable USER is set to the user that runs the application server. For Windows, this user is typically SAPService<SID>. For UNIX, it is typically <sid>adm. For AS/400, it is typically <SID>(<instance>). For more information, see Note 800240.

5. To replace the SAPSECUILIB library with the SAPCRYPTOLIB library, set the following profile parameters and restart the server(s).

¡     ssf/name    = SAPSECULIB

¡     ssf/ssfapi_lib  = <Path and file name of SAPCRYPTOLIB>

¡     sec/libsapsecu  = <Path and file name of SAPCRYPTOLIB>

           Set these profile parameters in the instance profile and not in the default profile.                     Note: There are additional parameters that you may need to set for specific applications. For example, the parameter ssf/ssf_symencr_alg specifies the algorithm to use for encryption. Possible values are DES-CBC (default), TRIPLE-DES, and IDEA. For information about which

    662340 - SSF Encryption Using the SAPCryptolib  

Version   18     Validity: 25.02.2009 - active   Language   English

Released On 25.02.2009 09:21:29

Release Status Released for Customer

Component BC-SEC-SSF Secure Store and Forward

Priority Recommendations / Additional Info

Category Consulting

additional parameters are necessary for the application and their corresponding values, see the application's documentation.                     

Configuring Application-Specific Settings

1. If necessary, define a new SSF application in the SSFAPPLIC table. Call the table maintenance SE16 and create a new entry in the namespace (Y,Z):

           APPLIC = 'ZMYAPP'            B_TOOLKIT, B_FORMAT, B_PAB, B_PROFID, B_PROFILE, B_ENCRALG = 'X'            B_HASHALG, B_INCCERTS, B_DETACHED, B_ASKPWD = ' '            DESCRIPT = <Description of the SSF application>            (This step is not necessary if a definition for the application already exists in SSFAPPLIC.)

2. Before you can use the PSE file in the application, you must make the following Customizing settings in transaction SSFA. (Some of the following input fields may be preselected with standard values and may therefore not be displayed.)

           Security product     = SAPSECULIB            SSF format       = PKCS7            Private address book   = < filename of the PSE file>            SSF profile name     = < filename of the PSE file>            SSF-Profile-ID     = < Distinguished Name>            Hash algorithm     = <empty>            Encryption alg.      = < symmetric encryption algorithm>            Certificates for data    = X            Only dig. Signature      = < empty>            Password dialog box      = < empty>            

Maintaining the Server's Personal Security Environment

Before creating a PSE for your application, check your application's documentation for the algorithm type that is required for the PSE to be used (DSA or RSA). The procedure to use depends on the release:

l As of Release NW 2004s, you can use the transaction STRUST to maintain the PSE to use for the application. When creating the PSE, you can choose the algorithm and key length to use.

l In Release 6.10-6.40, follow SAP Note 836367. After implementing this note, you can use the report SSF_CREATE_PSE to create the PSE to use.

l In Release 4.5B until 4.6C, you have to use the command line tool sapgenpse for the PSE maintenance. Follow the steps below:

1. The server must possess a public and private key pair to use for encrypting and decrypting the data. This key pair is stored in a file in the file system, called a Personal Security Environment (PSE). To create the key pair and PSE for the application, use the "sapgenpse" tool provided with the SAPCRYPTOLIB package.

           You can work in any local directory to perform the sapgenpse steps:

a) Copy the SAPCRYPTOLIB and the sapgenpse program into the file directory in which you want to create the PSE (or a %PATH% directory).

b) Set the SECUDIR environment variable to your selected directory. You can now create and edit the PSE files in this directory.

c) To create a PSE, execute the following command (if you do not want to use a PIN, confirm the two PIN queries with Return)

                     sapgenpse get_pse -p <file name>.pse -r <file name>.p10 "<Distinguished Name>"                     For example:                      sapgenpse get_pse -p APPLIC<XYZ>.pse -r APPLIC<XYZ>.p10 "CN=APPLIC, O=MyCompany, C=<Country_Code>"                     Note: The SSF applications are client-specific, therefore we recommend including the SAP system client in the filename. (Notation <XYZ> in the example above.)                     Also: The <Country_Code> is a 2-letter country description. For example, use US for the United States, use DE for Germany.

2. If the correponding public-key certificate is to be signed by a CA, then make sure the CA issues the certificate in the format PKCS#7 with complete upward path. To obtain a certificate signed by a CA:

a) Transfer the contents of the p10 file to the CA and save the resulting certificate request response from the CA in a p7 file.

b) Import the resulting certificate request response into the PSE using the following command:

                     sapgenpse import_own_cert -c <file name>.p7 -p <file name>.pse

c) If you want to include trusted certificates in the PSE file so that you can verify other users' (or systems') digital signatures, execute the following command:

                     sapgenpse maintain_pk -a <input file>.cer -p <file name>.pse

d) If you need to export the server's public-key certificate, for example, to be able to be checked by another server or system, use the following command:

                     sapgenpse export_own_cert -o <output file>.cer -p <file name>.pse -x [<PIN>]            For more information on sapgenpse, call one of the following statements.            sapgenpse -h            sapgenpse <command> -h            For example: sapgenpse import_own_cert -h

3. Copy the PSE to the $DIR_INSTANCE/sec directory on each application server. Also store a backup copy of the PSE in a separate location.

4. If you provided a PIN to protect the PSE, create credentials so the application server can access the PSE at run-time. Perform the following:

a) Log on to the application server as <sid>adm (or <SID>(<instance>) for AS/400).

b) Set the environment variable SECUDIR to the $DIR_INSTANCE/sec directory

c) Navigate to the $(DIR_EXECUTABLE)/sec directory.

d) Execute the following command:

                    For Windows:                      sapgenpse seclogin -p <path and file name>.pse -x [PIN] -O [<Windows_Domain>\]SAPService<SID>                     For UNIX:                      sapgenpse seclogin -p <path and file name>.pse -x [PIN] -O <sid>adm                     Note: The parameter -O is case-sensitive.                     For AS/400, see Note 758667.

Validity

References

This document refers to:

SAP Notes

This document is referenced by:

SAP Notes (22)

Software Component From Rel. To Rel. And Subsequent

SAP_APPL 45B 45B  

46B 46B  

46C 46C  

470 470  

SAP_BASIS 46B 46D  

610 640  

1034482   FAQ: Credit card encryption in CRM

1053296   Credit card encryption in the POS Data Management

1105524   Security when displaying credit card numbers

1375378   Select the right version of an SAP security toolkit

1452833   Prerequisites for analyzing support messages on STRUST

1502999   IOS-WDABAP: MsProject Integration and Whitelist

1524196   Import certificates in ABAP and Java

354819   Collective note SAPSECULIB

397175   SAP Cryptographic Software - Export control

510007   Setting up SSL on Web Application Server ABAP

578377   Digital signatures with SAPCRYPTOLIB

633462   Encrypting credit card data

690999   SAPCRYPTOLIB 555pl15: several important bug fixes

700659   Security Guide: mySAP Supply Chain Management

758667   iSeries: Installing sapcrypto library for R/3

766703   FAQ: Credit card encryption in R/3 systems

800240   FAQ: SAP Cryptographic Library error analysis (App. Server)

836367   SSF PSEs: Setting algorithm and key length

86927   Using the digital signature in the R/3 System

894022   NAE: Credit Card Masking

836367   SSF PSEs: Setting algorithm and key length

510007   Setting up SSL on Web Application Server ABAP

1034482   FAQ: Credit card encryption in CRM

1053296   Credit card encryption in the POS Data Management

1502999   IOS-WDABAP: MsProject Integration and Whitelist

633462   Encrypting credit card data

1375378   Select the right version of an SAP security toolkit

1105524   Security when displaying credit card numbers

1422864   CGsprint 1.x: Installation or upgrade

800240   FAQ: SAP Cryptographic Library error analysis (App. Server)

578377   Digital signatures with SAPCRYPTOLIB

397175   SAP Cryptographic Software - Export control

86927   Using the digital signature in the R/3 System

354819   Collective note SAPSECULIB

700659   Security Guide: mySAP Supply Chain Management

1452833   Prerequisites for analyzing support messages on STRUST

758667   iSeries: Installing sapcrypto library for R/3

1844549   CGsprint 2.x: Installation/Upgrade

690999   SAPCRYPTOLIB 555pl15: several important bug fixes

766703   FAQ: Credit card encryption in R/3 systems

1524196   Import certificates in ABAP and Java

894022   NAE: Credit Card Masking