Tivoli Header

Tivoli Storage Manager Using the Application Program Interface

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.This sign-on process requires the use of a password. When the password is coupled with the node name of the client, it insures proper authorization when it connects 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 will update the password before the session can be established successfully. The example in Figure 4 demonstrates the procedure to change a password by using dsmChangePW. The login owner must be root or TSM-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 will be 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.

For UNIX: Only the root user or the TSM-authorized user can change the password when using passwordaccess prompt. Only the root user or the TSM-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:

Note:
Options users and groups are not recognized.

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

Figure 2. 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 3. 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("%s\n",msgBuf);                                                    |
|      free(msgBuf) ;                                                            |
|      return;                                                                   |
|}                                                                               |
+--------------------------------------------------------------------------------+

Figure 4. 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 = %i\n",rc);                         |
|}                                                                               |
|else                                                                            |
|{                                                                               |
|   printf("*** Your new password has been accepted and updated.\n");            |
|}                                                                               |
|return 0;                                                                       |
+--------------------------------------------------------------------------------+
Note:
Nodes in a cluster share a single password.


[ Top of Page | Previous Page | Next Page | Table of Contents | Index ]