Version 9.8
 —  LoginModules Guide  —

Creating Internal User Repository Files

You can create and/or modify internal user repository files that contain user names and their respective encrypted passwords. Currently, there are two Software AG Security Infrastructure tools that you can use for this purpose: Internal User Repository Command Line Tool and the ssxtxtpasswd tool. Software AG recommends the usage of Internal User Repository Command Line Tool.

The information is organized under the following headings:


Internal User Repository Command Line Tool

The start scripts of the tool, internaluserrepo.bat and internaluserrepo.sh, are in the <SoftwareAG_directory>/common/bin directory. At a later stage, you can use the user repositories files with login modules that have a property for using such files (for now, these login modules are InternalLoginModule and SSXLoginModule).

Start of instruction setTo create and/or modify an internal user repository file

  1. Use the command prompt to open the <SoftwareAG_directory>/common/bin directory.

  2. Depending on the operating system, start the tool using one of the following commands:

    where

    Argument Description
    -h, -help Prints guidelines for using the tool.
    -f, -file Specifies the user repository file.
    -c, -create Creates a text repository file. You can specify the location and file name with the -f argument followed by the wanted URL (path and name of the file to be created). If only the -c option is specified, a file, named users.txt, is created in the execution directory of the tool. If you do not use the -c argument and the specified text file does not exist, an error is returned. If you specify -c and the file already exists, the new information is added at the end of the repository file.
    -p, -password Provides the specified password on the command line.

    Note:
    Passwords can contain only digits, Latin letters, and the following characters: ! ( ) - . ? [ ] _ ~. They cannot exceed 128 characters.

    -d, -delete Deletes the credentials for the specified user from the text repository file. If you do not specify a file and a users.txt file exists in the directory of the tool, the user is removed from this file.
    -e, -existing Checks whether the specified user exists in the text repository file. You should provide a URL to the file using the -f argument.
    <userId> Contains the user name for the text repository file operation. If you call the tool only with this option and a users.txt file exists in the directory of the tool, a new user with a user name <userId> is added in the file. Then, a prompt asks for the user password. If a user with this userId already exists in the repository file, the password is changed.

    Note:
    User names can contain only digits, Latin letters, and the following characters: ! ( ) - . ? [ ] _ ~. They cannot exceed 128 characters.

    Note:
    The only required parameter is userId.

Status Codes

Internal User Repository Command Line Tool returns exit codes that define the result of the execution. If the command is executed successfully, no exit status is returned.

You can see the descriptions of the exit codes in the following table:

Exit code Description
-1 The specific userId that is searched for (option -e) does not exist in the repository file.
1 The password is not set. Please specify a password.
2 The userId is too long. The maximal length for a userId is 128 characters.
3 The userId contains an invalid character.
4 The password contains an invalid character.
5 The password is too long. The maximal length for a password is 128 characters.
6 The repository file is inconsistent. Multiple version occur in the repository file.
7 The repository file is inconsistent. The version is invalid.
8 The repository file is inconsistent. The repository version is not specified.
9 The repository file cannot be opened or created.
10 The userId is missing.
11 The specified parameter is conflicting or invalid.

Top of page

ssxtxtpasswd Tool

Software AG Security Infrastructure provides also another tool (ssxtxtpasswd.exe, ssxtxtpasswd) with which you can create internal user repository files. At a later stage, you use these files with the SSXLoginModule. By default, the tool is available in the following directory on the file system: Software AG_directory\ common\runtime\security\bin. To start the ssxtxtpasswd tool, you use a command prompt. When you start the tool, you enter a user name and a password which are then encrypted (SHA512 and Base64) and provided in the result text file. The tool adds new or replaces existing user credentials in the text file.

Note:
When you enter a user name, you can use only digits, Latin letters, and the following characters: ! ( ) - . ? [ ] _ ~ . When you enter a password, you can use only digits, Latin letters, and the following characters: !"#$%&'()*+,-./:;<=>?[\]^_`{|}~.

Start of instruction setTo create and/or modify an internal user repository file

  1. Using the command prompt, open the following directory:

    Software AG_directory\ common\runtime\security\bin

    You cannot start the tool from a different location on the file system.

  2. Depending on the operating system, start the tool using one of the following commands:

    To customize the invocation of the tool in the means of invocation parameters, you can use a set of pre-defined optional arguments. The available arguments and the respective descriptions are as follows:

    Argument Description
    -f

    Provide a name for the result text file which contains the user credentials. If you do not use this argument the tool creates a default result file called ssx_user.

    -c

    Using this parameter, you create a text repository file with a specified name (-f parameter). If you do not use the -c parameter and the specified text file does not exist, an error is returned. If you specify -c and the file already exists, -c argument is ignored and the tool does not create a new file. When you execute the tool without specifying an argument for the result file name (-f argument), it still creates a text file with the corresponding internal user repository information. The file is created in the same folder in which you started the tool and has a predefined default name (ssx_user).

    -p

    Provide a password directly on the command line. Thus, the tool does not invoke a non-echo input of the password in the next steps.

    -d

    Remove credentials data for a particular user from the text repository file. When you use the -d parameter, the tool ignores the presence of the -c parameter.

    user ID

    Provide user name which you want to add or replace in the text file.

  3. Press Enter and then provide the password.

Example

The following examples provide information about more typical use cases of the tool:

ssxtxtpasswd.exe –c –f internalUser.txt –p pass myUser

ssxtxtpasswd.exe –c –f internalUser.txt –p newpass myUser

ssxtxtpasswd.exe –d –f internalUser.txt myUser

The tool creates a text file, which contains the encrypted internal user repository credentials, and stores it in the same directory in which you started it. As a next step, you can provide the file to the SSXLoginModule and search for INTERNAL users.

Top of page