To analyze the SAPCryptolib installation and configuration, execute the test report ZSSF_TEST_PSE, which is attached to this note. Follow the instructions that apply to any error messages accordingly. See the description for the report below.
In addition to describing this report, this note provides answers to the following questions:
- 1. Where do I get the SAPCryptolib? What do I do if I cannot access it?
- 2. Since installing the SAPCryptolib, SSF messages appear in the system log (transaction SM21). What do these mean? Do I have to do anything to correct this situation?
- 3. The settings in the SSF profile parameters do not seem to be taking effect. What should I do?
- 4. I receive a warning when setting the SSF parameters ssf/name or sec/libsapsecu. The warning indicates that the parameters are not known. What should I do?
- 5. I am using German HR functions (Elster or electronic communication with a health insurance provider) and the test report provided by the application (RPUTX8D0 or RPUSVID0, respectively) returns an error. What should I do?
- 6. How can I create a separate certificate request with sapgenpse?
- 7. What are credentials?
- 8. How can I check what credentials exist using sapgenpse?
- 9. Can I delete unnecessary credentials?
- 10. Under what user does the application server run?
- 11. Most of the documentation about SAPCryptolib applies to Windows or UNIX environments. What about AS/400?
See the sections below for answers to these questions.
Note:The instructions provided in this note apply when using the sapgenpse command line tool for maintaining the Personal Security Environments (PSEs). As of Release 6.10, you can alternatively use the trust manager (transaction STRUST) to perform the operations.
##################################################################
Instructions for test report ZSSF_TEST_PSE
With this report, you can check the use and configuration of the SAPCryptolib for a particular PSE.
Importing the report
To create the report, create an empty report using transaction SE80 and import the source code according to the correction instructions provided.
In releases 6.20 - 7.00, you also have to apply the correction instructions provided with Note 912405.
Prerequisites for executing the report
You know the filename of the PSE for which you want to check the configuration. If the application that uses the PSE is specified as an SSF application in transaction SSFA, then you can check this table to determine the filename. Otherwise, either check the $(DIR_INSTANCE)/sec directory on the application server, or check your application's documentation.
Executing the report
Use transaction SE38 to run the report. Enter the filename (and PIN) of the PSE to check, and indicate whether a signature, encryption, or both should be tested.
If the PSE is protected with a PIN, then be sure to enter the PIN in the entry field. Otherwise, the report cannot perform all possible tests.
After execution, the report shows the following information:
- System information
- Profile parameter settings
- Environment variable values for SECUDIR and USER
- SAPSeculib or SAPCryptolib versions
- Certificates stored in the PSE
- Contents of the SSF applications table (SSFA) for this PSE
- Results of signature or encryption test(s)
##################################################################
Errors and Warnings Detected by the Test Report Error: Profile parameters sec/libsapsecu and ssf/ssfapi_lib are different
Note: This error can only be determined if the profile parameter ssf/name is set to SAPSECULIB.
Solution: Make sure the following parameters are set accordingly:
- ssf/name = SAPSECULIB
- sec/libsapsecu =
- ssf/ssfapi_lib =
Set these profile parameters in the instance profile and not in the default profile.
******************************************************************
Error: Environment variable SECUDIR not set or has wrong value.
Solution: Set the environment variable SECUDIR to $(DIR_INSTANCE)/sec for the user running the application server. This is the directory where the PSEs are located.
For the application server: If multiple application server instances for the same are on the same host, then set this variable in the startup script for the application server instance. Otherwise, set it in the environment for the user who runs the application server.
For the command tool sapgenpse: Make sure you set SECUDIR in the environment for the user running the tool. To be sure, you can set it in the shell where you are executing the tool.
Note: Also make sure that the environment variable USER is set to the user who runs the application server.
******************************************************************
Error: SSF_KRN_VERSION failed, SY-SUBRC = or Could not determine version, CRC =
Solution:Check the version of the SAPCryptolib. If the test report was not able to determine the version, then check the WHICH.TXT file that is provided with the SAPCryptolib archive to determine which version applies to your operating system and SAP kernel version.
Check the installation of the SAPCryptolib:
- Make sure the SAPCryptolib is located in the $(DIR_EXECUTABLE) directory.
- Make sure the ticket file (ticket) is located in $(DIR_INSTANCE)/sec.
If the installation appears to be correct, then check the trace file (transaction ST11) for more details about the error.
******************************************************************
Error: Error opening PSE file
Solution: Use transaction AL11 to check the filename and location of the PSE file in the $(DIR_INSTANCE)/sec directory. Also check for the credentials file cred_v2. If this file is missing, then create credentials for the PSE. See question number 8 in this note for information about how to create credentials.
******************************************************************
Error: Certificate is expired.
Solution: Obtain a new certificate by creating a new certificate request, sending it to a CA to be signed and importing the signed certificate into the PSE.
See question 6 in this note for information about how to create a certificate request using sapgenpse.
******************************************************************
Error: Table entry contains wrong ID
Solution: Set the correct SSF profile ID using the transaction SSFA.
******************************************************************
Error: Certificate does not allow encryption.
Note: This message applies only to encryption test.
Solution: The key pair used must have been generated using an algorithm that supports encryption (for example, RSA). Therefore, either create a new PSE and key pair using the RSA algorithm, or specify a different PSE where the RSA algorithm is used.
******************************************************************
Warning: Profile parameter sec/libsapsecu not set
Solution: Set this parameter to the path and filename of the SAPCryptolib (or SAPSeculib).
******************************************************************
Warning: No credentials available for this PSE/user
Solution: Create credentials for this PSE and for the correct user (see question 8 in this note).
##################################################################
The following sections provide answers to the questions listed at the beginning of the note.
##################################################################
Question 1. Where do I get the SAPCryptolib? What do I do if I cannot access it?
You can download the SAPCryptolib from the SAP Service Marketplace at http://service.sap.com/download -> SAP Cryptographic Software.
Choose the SAPCryptolib package that applies to your operating system. See the document WHICH.TXT, which is included in the SAPCryptolib archive, to make sure you have the correct version.
Note that this software package underlies German export regulations and is therefore not available to all customers. Authorized customers need to have an appropriate attribute maintained in the customer profile to be able to access this page. Therefore, if you receive an access error, create a message under the component XX-SER-GEN-CONTR to find out if you are authorized, and if authorized, have your customer profile maintained.
See also Note 397175.
##################################################################
Question 2: Since installing the SAPCryptolib, SSF messages appear in the system log (transaction SM21). What should I do about these?Examples of such messages include:
- SSF_ALERT_CERTEXPIRE
- SSF_KRN_SIGN_BY_AS
Answer: One case that produces SSF messages is when certificates are close to expiring or have expired (for example, SSF_ALERT_CERTEXPIRE). For such cases, see Notes 572035 and 588297.
Another case that produces SSF messages is if an signing or verification operation is attempted, but the corresponding PSE is missing. In this case, if the PSE in question (for example, the system PSE) has not yet been created on the application server, then create it using transaction STRUST or (in release 4.6) transaction PSEMAINT.
#################################################################
Question 3: The settings in the SSF profile parameters do not take effect. What should I do?
The relevant profile parameters include:
- ssf/name = SAPSECULIB
- sec/libsapsecu =
- ssf/ssfapi_lib =
as well as any other ssf* profile parameters.
Answer: Make sure you set these profile parameters in the instance profile and not in the default profile. Also pay close attention to the syntax. ssf/name must be SAPSECULIB (not SAPCRYPTOLIB).
##################################################################
Question 4: I receive a warning when setting certain SSF parameters that the parameters are not known. What should I do?
The relevant profile parameters are:
- ssf/name
- sec/libsapsecu
Answer: You can ignore this warning. Also, make sure that you set the values of these profile parameters correctly.
##################################################################
Question 5: I am using German HR functions (Elster or electronic communication with a health insurance provider) and the test report provided by the application (RPUTX8D0 or RPUSVID0, respectively) returns an error. What should I do?
There are three possible causes for this error:
- The credentials are not set correctly meaning the server cannot access its PSE.
- The profile parameters are not set correctly.
- One (or both of) the environment variables SECUDIR and USER are not set correctly.
Solution:
Check if the report runs with or without providing a PIN. Depending on the results, apply the following:
- If the report runs successfully when providing a PIN, but returns an error when no PIN is provided, then the application server does not have access to credentials, and therefore, also does not have access to its PSE. In this case, make sure you provide the user that runs the application server (either adm or SAPService) in the -O option for the sapgenpse call when creating the credentials.
See question 8 in this note.
- If the report returns an error for both cases (with and without a PIN), then check for the existence of the credentials file, the profile parameter settings and the environment variable values.
To determine which settings are not correct, see the instructions for the ZSSF_TEST_PSE report in this note.
##################################################################
Question 6: How can I create a separate certificate request using sapgenpse?
Answer: You may have to create a separate certificate request, for example, to renew a certificate or the original certificate request is no longer available or was not generated when the PSE was created.
To create a separate certificate request, use the following command:
sapgenpse gen_pse -p -r < certificate request file name> -onlyreq
##################################################################
Question 7: What are credentials?
Answer: A dialog user uses a PIN to access his or her PSE at run-time, however because the application server cannot actively provide a PIN at run-time, it uses credentials that are stored in the file system. These credentials are stored in a file named cred_v2 in the SECUDIR directory on the application server. If multiple PSEs for various purposes are used, then all of the corresponding credentials are stored in the same file.
Access to the credentials is checked for the active user.
##################################################################
Question 8: How can I check/create credentials using sapgenpse?
Answer: Use the following command to view the existing credentials:
sapgenpse seclogin -l
This command shows a list of the available credentials for the current user. If no credentials appear, then either no credentials exist, or they exist for a different user.
If the credentials exist but you still have problems with them, check the credential entries carefully for misspellings or typing errors. The credentials are identified according to the Distinguished Name, therefore, make sure this name is correct. Also make sure that the path provided to the PSE is correct. If the credentials are not correct, then delete them and create them again.
If you use the sapgenpse tool to create credentials, make sure you provide the correct user in the -O option to create them for the user that runs the application server.
Use the following sapgenpse command line to create credentials:
sapgenpse seclogin -p . pse -x [PIN] -O
Note: The parameter -O is case-sensitive.
Example (Windows):
sapgenpse seclogin -p .pse -x [PIN] -O []SAPService
To find out the user for which the SAPCryptolib needs credentials, see question number 10 in this note.
##################################################################
Question 9: How can I delete credentials?
Answer: First, list the credentials as shown in question 8.
To delete a specific credential, use the following command:
sapgenpse seclogin -d -p
where is the number of the credential shown in the credential list.
##################################################################
Question 10: Under what user does the application server run?
Answer: Under Windows, the application server user is typically SAPService. For UNIX, it is typically adm. For AS/400, it is typically ().
However, some installations run under a different user. Therefore, make sure you know under which user the server runs. For example, under Windows, to find out which user runs the application server, check the user that runs the Windows service SAPService.
You can also use the report RSBDCOS0 and sapgenpse to check the user under which the application server runs. Start the report RSBDCOS0 and execute the command:
sapgenpse seclogin -l 2>&1
For AS/400, use the command:
call sapgenpse parm('seclogin''-l')
This is the user for which you need to create credentials.
Note: Under Windows, you can use the following Windows command to look up the Windows domain.
net config workstation
##################################################################
Question 11: Most of the information in the documentation about SAPCryptolib applies to Windows or UNIX environments. What about AS/400?Answer: See Note 758667