Creating internal user repository files

You can create and/or modify internal user repository files that contain user names and their respective encrypted passwords.

SSX provides a tool that you can use to create internal user repository files:

  • ssxtxtpasswd.exe on Windows
  • ssxtxtpasswd on UNIX

At a later stage, you can use the internal user repository file to authenticate users independently from your system. With a default installation, the tool is available in the following directory:

  • Windows:

    C:\SoftwareAG\common\security\ssx\bin

    Note:

    The tool may also be available in the ssx_32 directory (instead of ssx). This is only for backwards compatibility.

  • UNIX:

    /opt/softwareag/common/security/ssx/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 hashed (SHA512 and Base64) and provided in the result text file. The tool adds new or replaces existing user credentials in the text file.

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:

! " # $ % & ' ( ) * + , - . / : ; < = > ? [ \ ] ^ _ ` { | } ~

The user-defined repository files must comply with the following format: 

*
* Default test repository for INTERNAL or TEXT based authentication
*
version:3.0
*
*
user:user_id:hashed_password
*

To create and/or modify an internal user repository file

  1. Set up the environment as described in Preparing the environment.
  2. Start the tool using the following command: 
    ssxtxtpasswd [-f result_file_name] [-c] [-p password] 
  [-d | -e] user_ID

    To customize the parameters for invoking this tool, you can use a set of predefined optional arguments. The available arguments and their 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 argument). 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 -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. Providing a password as a command line argument is considered insecure.
    -d Remove credentials data for a particular user from the text repository file. When you use the -d argument, the tool ignores the presence of the -c argument.
    -e Just check if a particular user exists in the text repository file.
    user_ID Provide a user name which you want to add, delete, check or replace in the text file.
  3. Press ENTER.
    If -p is not provided, the tool will interactively ask you to provide the password.

Examples

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

ssxtxtpasswd.exe -c -f internalUser.txt -p pass myUser
ssxtxtpasswd.exe -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 configuration option internalRepository (see the corresponding product documentation for more information).