SAP Note

1639578 - SSFS as password store for primary database connect

Version 16 Validity: 12.08.2015 - active Language English

Header Data
Released On 12.08.2015 12:19:55
Release Status Released for Customer
Component BC-DB-DBI DB Independent Database Interface
Other Components BC-DB-ORA-SYS Database Interface / DBMS for Oracle
BC-DB-SYB SAP Business Suite on Sybase ASE Database Platform
BC-SEC Security
Priority Correction with medium priority
Category Consulting

Symptom
This note describes the general steps that are required to use the "Secure Storage in File System
(AS ABAP)" (SSFS) for the storage of the password of the ABAP database user. In the following, the
"Secure Storage in File System (AS ABAP)" is also referred to as "secure storage". The note also
described the availability of the solution for the individual databases.

Currently, the procedure is supported by the following databases. Refer to the relevant notes for
details about availabilities and required database-specific configuration steps:

l Sybase ASE: SAP Note 1643080

l Oracle: SAP Note 1622837
l SAP HANA: SAP Note 2154997 (as of SAP Kernel 7.42, PL 101)

If you use Oracle as a database platform, take the following into account:

l All SAP products that can be used only with kernel version < 7.20, exclusively support the
standard OPS$ remote connect.

l All SAP products that are used with kernel version > 7.38, as well as all the Oracle databases >
Version 11.2, exclusively support the new connect procedure with SSFS that is described here.

The Oracle-specific SAP Note 1622837 describes how you best proceed for SAP or Oracle upgrade
projects that lead from one category to another.

Reason and Prerequisites

You are using an SAP product based on AS ABAP in combination with one of the aforementioned database
platforms and you are using the 7.20 kernel or higher. In addition, you fulfill the prerequisites
mentioned in the relevant platform notes, particularly if you are using the 7.20 kernel in the DCK
(downward-compatible kernel) mode.
In this case, you can decide to replace the platform-specific mechanism for storing the password of
the ABAP database user with a standardized procedure. To do this, you store user and password
information in an encrypted manner in the "Secure Storage in File System". After you make sure that
the SAP system and its tools can still connect to the database successfully after the changeover,
remove the old password storage. Optionally and to ensure greatest possible security, you can define
an external encryption key.

Solution
The steps required for the changeover are described below.

----------------------------------------------------------------------
1. Fulfilling the software prerequisites
----------------------------------------------------------------------
Make sure that your database platform is supported in the SAP Release and database release that you
require, and refer to the aforementioned platform notes for the minimum kernel patch level required
for this.
The following SAP Notes contain general prerequisites and corrections:

l SAP Note 1611877 (Support for ABAP SSFS during database connect)

l SAP Note 1678336 (RSecSSFs: UTF8 conversion failed with returncode 1)

The secure storage is supported by the ABAP programs RSECKEYGEN and RSECSSFX_ESCAPE. Note 1561615
describes the SAP Releases for which and the Support Package levels with which these are available.

----------------------------------------------------------------------
2. Preparing and securing the file system
----------------------------------------------------------------------
In general, we recommend storing the secure storage in the file system and the optional external
encryption key on SAPGLOBALHOST under $(DIR_GLOBAL)/security/rsecssfs/data or
$(DIR_GLOBAL)/security/rsecssfs/key, whereby these directories should be secured accordingly.

----------------------------------------------------------------------
2.1 Creating the directories
----------------------------------------------------------------------
Determine the value for DIR_GLOBAL (for example, from transaction AL11) on SAPGLOBALHOST. Replace
$(DIR_GLOBAL) in the following description with the determined value <dir_global>. Create the
required directories as described below if they do not already exist.

----------------------------------------------------------------------
SAPGLOBALHOST on UNIX or Linux
----------------------------------------------------------------------
Log on to SAPGLOBALHOST to the operating system as user <sid>adm and execute the following commands:

l mkdir <dir_global>/security

l mkdir <dir_global>/security/rsecssfs

l mkdir <dir_global>/security/rsecssfs/data

l mkdir <dir_global>/security/rsecssfs/key

----------------------------------------------------------------------
SAPGLOBALHOST on Windows
----------------------------------------------------------------------
Log on to SAPGLOBALHOST to the operating system as user <sid>adm and open a command box or a
powershell. Execute the following commands:

l mkdir <dir_global>\security

l mkdir <dir_global>\security\rsecssfs

l mkdir <dir_global>\security\rsecssfs\data

l mkdir <dir_global>\security\rsecssfs\key

Alternatively, you can also create the directory structure via the Windows file explorer.

----------------------------------------------------------------------
2.2 Securing the directories created
----------------------------------------------------------------------
In the following, make the directories that were created in step 2.1 available exclusively for the
users of the SAP system <sid>.
On Linux and UNIX, this is the user <sid>adm. On Windows, all relevant users are merged into the
groups SAP_<sid>_LocalAdmin and SAP_<sid>_GlobalAdmin.
In particular, cross-SAP system users and groups should not have any authorizations in these
directories.

The procedure depends on the operating system:

----------------------------------------------------------------------
SAPGLOBALHOST on UNIX or Linux
----------------------------------------------------------------------
If SAPGLOBALHOST runs on Unix or Linux, proceed as follows:

l Log on to SAPGLOBALHOST to the operating system as user <sid>adm and execute the following
commands:

l chmod 700 <dir_global>/security

l chmod 700 <dir_global>/security/rsecssfs

l chmod 700 <dir_global>/security/rsecssfs/data

l chmod 700 <dir_global>/security/rsecssfs/key

l Use "ls -al" to check the result. For example:

drwx------ <sid>adm sapsys data

drwx------ <sid>adm sapsys key

----------------------------------------------------------------------
SAPGLOBALHOST on Windows
----------------------------------------------------------------------
If SAPGLOBALHOST runs on Windows, <sid>-specific users and groups, operating system-specific users
and groups, and operating system administrators must have full access. In particular, this concerns
the following:

l SAP_<sid>_LocalAdmin (only in non-HA configurations)

l SAP_<sid>_GlobalAdmin
 l SYSTEM

l Administrators

All of the other users (in particular, <sid>-unspecific SAP users and groups such as SAP_LocalAdmin)
should not have any authorizations.

Proceed as follows:

l Log on to SAPGLOBALHOST as a user with administration authorizations.

l Open the explorer and right-click the folder <dir_global>/security/rsecssfs. Choose "Properties"
from the context menu.

l Go to the "Security" tab page and choose "Advanced", and choose "Change Permissions..." in the
window that is then displayed.

l First, deselect the option "Include inheritable permissions from this object's parent" and
choose "Add" in the warning message that is then displayed to transfer all of the existing
authorizations for this directory.

l Remove all of the entries from the "Permission entries" table, except the following:

¡ SAP_<sid>_LocalAdmin (only in non-HA installations)

¡ SAP_<sid>_GlobalAdmin

¡ SYSTEM

¡ Administrators

l If required, add missing groups.

l Edit the existing list entries so that there is an entry with the following values for each of
the aforementioned authorized groups:

¡ Type: "Allow"

¡ Permission: "Full control"

¡ Apply To: "This folder, subfolder and files"

l Finally, select the option "Replace all child object permissions with inheritable permissions
from object".

l Confirm all changes.

----------------------------------------------------------------------
2.3 Heterogeneous installations
----------------------------------------------------------------------
If you operate SAPGLOBALHOST on Linux or UNIX and application servers on Windows in addition to
this, you must ensure that, in addition to <sid>adm, all other users from the groups
SAP_<sid>_LocalAdmin or SAP_<sid>_GlobalAdmin also have access to the previously created directories
on SAPGLOBALHOST. Especially the SAPService<sid> user must have access (that was previously excluded
by chmod 700 on UNIX explicitly).

Therefore, check your Samba configuration. The configuration file smb.conf should contain an entry
for "username map", for example:
[global]
...
username map = /etc/username.map

The file username.map in turn should contain the following entry for local installations:
<sid>adm = <sid>adm SAPService<sid>

In the case of domain installations, the entry looks as follows:

<sid>adm = <domain>/<sid>adm <domain> /SAPService<sid>

This ensures that the SAPService<sid> user is handled in the same way as <sid>adm when accessing the
UNIX file systems that are made visible by Samba.

----------------------------------------------------------------------
3. Maintaining the SSFS profile parameters
----------------------------------------------------------------------
Set the following profile parameters that point to the previously created directories as the
location for the secure storage and the external key. We recommend that you add the parameters to
the default profile DEFAULT.PFL. Otherwise, you must maintain all of the instance profiles. Add the
following entries:
rsec/ssfs_datapath = $(DIR_GLOBAL)$(DIR_SEP)security$(DIR_SEP)rsecssfs$(DIR_SEP)data
rsec/ssfs_keypath = $(DIR_GLOBAL)$(DIR_SEP)security$(DIR_SEP)rsecssfs$(DIR_SEP)key

----------------------------------------------------------------------
4. Maintaining the SSFS environment variable
----------------------------------------------------------------------
The profile parameters rsec/ssfs_datapath and rsec/ssfs_keypath are interpreted only by the SAP
system. The do not apply to the SAP tools R3trans, R3load, and so on. For this, corresponding
environment variables must be set in .sapenv.sh, .sapenv.csh, .sapenv_<host name>.csh,
and .sapenv_<hostname>.sh on each application server, including the central instance. Depending on
the operating system, proceed as follows:

----------------------------------------------------------------------
Application server on UNIX and Linux
----------------------------------------------------------------------
For this, first determine the value <dir_global> for DIR_GLOBAL on the relevant application server
(for example, using transaction AL11). Then add the following lines to the logon script for <sid>adm
on this application server:

l For C shell scripts:

setenv RSEC_SSFS_DATAPATH <dir_global>/security/rsecssfs/data

setenv RSEC_SSFS_KEYPATH <dir_global>/security/rsecssfs/key

l For Korn shell scripts:

export RSEC_SSFS_DATAPATH=<dir_global>/security/rsecssfs/data
export RSEC_SSFS_KEYPATH=<dir_global>/security/rsecssfs/key

----------------------------------------------------------------------
Application server on Windows
----------------------------------------------------------------------
If your application server runs on Windows, proceed as follows:

l Determine the value <dir_global> for DIR_GLOBAL on the relevant application server (for example,
using transaction AL11).

Note that the specification for SAPGLOBALHOST occurs as a local path with disk drive letters,
whereas the specification for other application servers is a UNC path (for example,
\\$(SAPGLOBALHOST)\sapmnt\<sid>\SYS\global).

l If you have installed your SAP system in a domain, log on to the operating system as the
<domain>/<sid>adm user. Otherwise, log on with the local user <sid>adm.

l Open a command box and execute the following commands:

¡ setx RSEC_SSFS_DATAPATH <dir_global>\security\rsecssfs\data

¡ setx RSEC_SSFS_KEYPATH <dir_global>\security\rsecssfs\key

----------------------------------------------------------------------
5. Setting up the SSFS data storage and checking the access rights
----------------------------------------------------------------------

----------------------------------------------------------------------
5.1 Setting up the SSFS storage
----------------------------------------------------------------------
In the following, you must fill the secure storage in the file system with the required access
information for the ABAP database user. This information consists of at least the name of the ABAP
database user and the password of this user.
In the case of some database types, you must also make specifications about the target database. In
all other cases, this information is still derived from the SAP profile.

Note that storage differentiates between uppercase and lowercase characters.

l DB_CONNECT/DEFAULT_DB_USER
ABAP database connect user (usually "SAPSR3")
The storage in the secure storage should take place in an unencrypted manner for Support
reasons.

l DB_CONNECT/DEFAULT_DB_PASSWORD
Password of the ABAP database user
The storage in the secure storage takes place in an encrypted manner.

l DB_CONNECT/DEFAULT_DB_CON_ENV
Specifications about the ABAP target database
The storage in the secure storage takes place in an unencrypted manner. This parameter is
currently required for the SAP HANA database only.

Refer to the relevant platform note for the name of the database connect user, for the information
about whether the parameter DB_CONNECT/DEFAULT_DB_CON_ENV is required, and its exact format, if
required.
Proceed as follows:

l Log on to SAPGLOBALHOST as the <sid>adm user.

l Make sure that the environment variables RSEC_SSFS_DATAPATH and RSEC_SSFS_KEYPATH are set.

l Use the command line tool of the secure storage rsecssfx from the SAP kernel to add entries for
the user <name> and the password <pwd>, and to add any information about the target database as
follows:

rsecssfx put DB_CONNECT/DEFAULT_DB_USER <name> -plain

 rsecssfx put DB_CONNECT/DEFAULT_DB_PASSWORD <pwd>

If required, also use:

rsecssfx put DB_CONNECT/DEFAULT_DB_CON_ENV <con_env> -plain
Note the following: In non-Unicode systems, only characters from the 7-bit ASCII area
are permitted.
To avoid code page problems, we generally recommend that you adhere to this rule. If you
want to use other characters in Unicode systems, you must convert these using the ABAP report
RSECSSFX_ESCAPE into characters that can be used by rsecssfx.

l Check the content of the secure storage as follows:

rsecssfx list

Refer to the command line help for further commands for the administration of the secure
storage:

rsecssfx help

----------------------------------------------------------------------
5.2 Setting and checking the authorization of the SSFS data storage
----------------------------------------------------------------------
Due to the first call of "rsecssfx put", the system also creates the data storage of the secure
storage. The directory $(DIR_GLOBAL)/security/rsecssfs/data should now contain the file
SSFS_<sid>.DAT.

----------------------------------------------------------------------
SAPGLOBALHOST on Windows
----------------------------------------------------------------------
If your SAPGLOBALHOST runs on Windows, no action is required because the access rights are inherited
from the directory when the file is created.

----------------------------------------------------------------------
SAPGLOBALHOST on UNIX or Linux
----------------------------------------------------------------------
Otherwise, you must correct the access rights for the file, in the same way as for step 2.2, so that
only <sid>adm are authorized.

l chmod 600 <dir_global>/security/rsecssfs/data/SSFS_<sid>.DAT

For security reasons, also check the access rights here using "ls -al":
-rw------- <sid>adm sapsys SSFS_<sid>.DAT

----------------------------------------------------------------------
6. Optional: Creating an external encryption key
----------------------------------------------------------------------

----------------------------------------------------------------------
6.1 Creating the encryption key
----------------------------------------------------------------------
All of the encrypted entries in the secure storage are usually encrypted using a standard encryption
key. For additional security, however, you can define an individual external encryption key (24
bytes).

The ABAP report RSECKEYGEN can be used to generate keys from various phrases.

l Log on as <sid>adm.

l Due to the call of the command line tool, the new encryption key <ext_key> is set and the
content of the secure storage is encrypted again as a result. <ext_key> is specified in the
hexadecimal format (48 characters from the range '0-9' and 'A-F').

rsecssfx changekey <ext_key>

----------------------------------------------------------------------
6.2 Setting and checking the authorization of the SSFS key storage
----------------------------------------------------------------------
If SAPGLOBALHOST runs on Linux or UNIX, carry out step 5.2 for the file
<dir_global>/security/rsecssfs/data/SSFS_<sid>.KEY. You do not have to do anything for Windows.

----------------------------------------------------------------------
7. Changing to the new connection method
----------------------------------------------------------------------
----------------------------------------------------------------------
7.1 Setting the required parameters
----------------------------------------------------------------------
If you have executed all of the previous steps correctly, the SAP system should now be able to
retrieve the password information that is required for the connection to the primary ABAP database
from the secure storage in the file system. However, the conventional password storage is consulted
by default.

The changeover to the new method now takes place due to a further profile parameter or a further
environment variable. Proceed in the same way as described in step 3 and 4 to set the profile
parameter (on SAPGLOBALHOST) and the environment variable (for all of the application servers).

l Profile parameter: rsdb/ssfs_connect = 1

l Environment variable: rsdb_ssfs_connect 1

(To use the conventional storage, you must set the values of the profile parameter and environment
variable to the value '0'. This corresponds to the default.)

----------------------------------------------------------------------
7.2 Checking the successful changeover
----------------------------------------------------------------------
Restart the SAP system and check whether the connect was successful. If the changeover was
successful, the developer trace (SM50) should contain the following entry:
B read_con_info_ssfs(): DBSL supports extended connect protocol
B ==> connect info for default DB will be read from ssfs
Check this for all of the application servers.

In addition, make sure that the SAP tools are still able to connect to the database. To do this,
perform an R3trans test connect on the application servers as <sid>adm:
R3trans -d

If R3trans was able to connect to the database successfully, the message "R3trans finished (0000)."
should be displayed. You must now also check trans.log in the current directory for the following
entry:

B read_con_info_ssfs(): DBSL supports extended connect protocol

B ==> connect info for default DB will be read from ssfs

----------------------------------------------------------------------
8. Removing the user data from the platform-specific storage
----------------------------------------------------------------------
After you make sure that the SAP system and its tools are able to retrieve the password information
that is required for the initial connect to the ABAP database from the secure storage, you should
remove the old platform-specific password storage. Otherwise, you will not benefit from the
potential security-relevant improvements in comparison with the old method.

To do this, follow the instructions in the relevant platform notes.

Validity
Software Component From Rel. To Rel. And Subsequent
KRNL32NUC 7.20 7.20
7.20EXT 7.20EXT
KRNL32UC 7.20 7.20
7.20EXT 7.20EXT
KRNL64NUC 7.20 7.20
7.20EXT 7.20EXT
KRNL64UC 7.20 7.20
7.20EXT 7.20EXT
8.02 8.02
KERNEL 7.20 7.20
8.02 8.02

Causes - Side Effects

Notes / Patches corrected with this note

Note Reason From Version To Version Note Solution Version Support Package
The table does not contain any entries

The following SAP Notes correct this Note / Patch

Note Reason From Version To Version Note Solution Version Support Package
1639578 0 0 1678336 1

References
This document refers to:
SAP Notes
1868094 Overview: Oracle Security SAP Notes
1764043 Support for secure storage in BR*Tools
1745266 RSecSSFs: Restriction of configuration options in kernel
1678336 RSecSSFs: UTF8 conversion failed with returncode 1
1643080 SYB: Database connect information for Sybase ASE
1622837 Secure connection of AS ABAP to Oracle via SSFS
1611877 Support for ABAP SSFS during database connect
This document is referenced by:
SAP Notes (8)
1764043 Support for secure storage in BR*Tools
2154997 Migration of hdbuserstore entries to ABAP SSFS
1643080 SYB: Database connect information for Sybase ASE
1868094 Overview: Oracle Security SAP Notes
1622837 Secure connection of AS ABAP to Oracle via SSFS
1745266 RSecSSFs: Restriction of configuration options in kernel
1678336 RSecSSFs: UTF8 conversion failed with returncode 1
1611877 Support for ABAP SSFS during database connect