IBM Tivoli Storage Manager, Version 7.1

Session security

Tivoli Storage Manager, a session-based system, has security components that permit applications to start sessions in a secure manner. These security measures prohibit unauthorized access to the server and help to insure system integrity.

Every session that is started with the server must complete a sign-on process, requires a password. When the password is coupled with the node name of the client, it insures proper authorization when connecting to the server. The application client provides this password to the API to start the session.

Two methods of password processing are available: passwordaccess=prompt or passwordaccess=generate. If you use the passwordaccess=prompt option, you must include the password value on each dsmInitEx call. Or, you can supply the node name and owner name on the dsmInitEx call.

Passwords have expiration times associated with them. If a dsmInitEx call fails with a password-expired return code (DSM_RC_REJECT_VERIFIER_EXPIRED), the application client must enter the dsmChangePW call using the handle that is returned by dsmInitEx. This updates the password before the session can be established successfully. The example in Figure 3 demonstrates the procedure to change a password by using dsmChangePW. The login owner must be root or Tivoli Storage Manager-Authorized to change the password.

The second method, passwordaccess=generate, encrypts and stores the password value in a file. The node name and owner name cannot be supplied on the dsmInitEx call, and the system default values are used. This protects the security of the password file. When the password expires, the generate parameter creates a new one and updates the password file automatically.

Note:

If two different physical machines have the same Tivoli Storage Manager node name or multiple paths are defined on one node using several server stanzas, passwordaccess=generate might only work for the stanza which is used first after password expiration. During the first client-server contact, the user is prompted for the same password for each server stanza separately, and for each stanza, a copy of the password is stored separately. When the password expires, a new password is generated for the stanza which connects the first client-server contact. All subsequent attempts to connect via other server stanzas fail, because there is no logical link between their respective copies of the old password, and the updated copy generated by the stanza used first after password expiration. In this case, you must update the passwords prior to expiration or after expiration as a recovery from the situation, as follows:
1. Run dsmadmc and update the password on the server.
2. Run dsmc -servername=stanza1 and use the new password to generate a proper entry.
3. Run dsmc -servername=stanza2 and use the new password to generate a proper entry.
For UNIX or Linux: Only the root user or the Tivoli Storage Manager-Authorized user can change the password when using passwordaccess=prompt. Only the root user or the Tivoli Storage Manager-Authorized user can start the password file when using passwordaccess=generate. You can use the Trusted Communication Agent (TCA) child process for password processing. The application should be aware of this because a child process and the SIGCLD signal are used. The TCA is not used in these situations:
- The passwordaccess option is set to prompt.
- The login user is root.
- The caller of the function must be a Tivoli Storage Manager-Authorized user.
Note: The options users and groups are not recognized.

An application can restrict user access by other means, such as setting access filters.

Applications that use multiple IP connections to a single Tivoli Storage Manager server should use the same nodename and Tivoli Storage Manager client password for each session. Follow these steps to enable this support:

Define one Tivoli Storage Manager server stanza in the dsm.sys file.
For the connections not using the default IP address, specify the option values for TCPserver address and TCPport on the dsmInitEx call.

These values override the IP connection information, but the session still uses the same dsm.sys stanza node and password information.

Note: Nodes in a cluster share a single password.

Figure 1. An example of starting and ending a session

dsmApiVersionEx * apiApplVer;
char           *node;
char           *owner;
char           *pw;
char           *confFile = NULL;
char           *options = NULL;
dsInt16_t      rc = 0;
dsUint32_t     dsmHandle;
dsmInitExIn_t  initIn;
dsmInitExOut_t initOut;
char           *userName;
char           *userNamePswd;
 
memset(&initIn, 0x00, sizeof(dsmInitExIn_t));
memset(&initOut, 0x00, sizeof(dsmInitExOut_t));
memset(&apiApplVer,0x00,sizeof(dsmapiVersionEx));
apiApplVer.version = DSM_API_VERSION; /* Set the applications compile */
apiApplVer.release = DSM_API_RELEASE;  /* time version.         */
apiApplVer.level   = DSM_API_LEVEL;
apiApplVer.subLevel= DSM_API_SUBLEVEL;
 
printf("Doing signon for node %s, owner %s, with password %s\n", node,owner,pw);
 
initIn.stVersion = dsmInitExInVersion;
initIn.dsmApiVersionP = &apiApplVer
initIn.clientNodeNameP = node;
initIn.clientOwnerNameP = owner ;
initIn.clientPasswordP = pw;
initIn.applicationTypeP = "Sample-API AIX";
initIn.configfile = confFile;
initIn.options = options;
initIn.userNameP = userName;   
initIn.userPasswordP = userNamePswd;
rc = dsmInitEx(&dsmHandle, &initIn, &initOut);
 
if (rc == DSM_RC_REJECT_VERIFIER_EXPIRED)
{
   printf("*** Password expired. Select Change Password.\n");
   return(rc);
}
else if (rc)
{
   printf("*** Init failed: ");
   rcApiOut(dsmHandle, rc);   /* Call function to print error message */
   dsmTerminate(dsmHandle);    /* clean up memory blocks */
   return(rc);
}

Figure 2. Details of rcApiOut

void rcApiOut (dsUint32_t handle, dsInt16_t rc)
{
     char *msgBuf ;
 
     if ((msgBuf = (char *)malloc(DSM_MAX_RC_MSG_LENGTH+1)) == NULL)
     {
          printf("Abort:  Not enough memory.\n") ;
          exit(1) ;
      }
 
      dsmRCMsg(handle, rc, msgBuf);
      printf("
      free(msgBuf) ;
      return;
}

Figure 3. An example of changing a password

printf("Enter your current password:");
gets(current_pw);
printf("Enter your new password:");
gets(new_pw1);
printf("Enter your new password again:");
gets(new_pw2);
/* If new password entries don't match, try again or exit. */
/* If they do match, call dsmChangePW.                          */
 
rc = dsmChangePW(dsmHandle,current_pw,new_pw1);
if (rc)
{
   printf("*** Password change failed.  Rc = 
}
else
{
   printf("*** Your new password has been accepted and updated.\n");
}
return 0;

Feedback