TAA Tools
CHGUSRPWD       CHANGE USER PASSWORD                   TAASECI

     *********************************************************
     *                                                       *
     *  The CHGUSRPWD tool has been created, but             *
     *    requires changes on your part. A test program      *
     *    is also created for demonstration purposes.        *
     *    See the implementation section.                    *
     *                                                       *
     *********************************************************

The Change  User Password  command is  intended for those  environments
where a change  to a user password should be  replicated on one or more
other systems.

See the CHG128PWD tool for changing 128 byte passwords.

Instead  of using  the normal CHGUSRPRF  command to  change a password,
the change would  be made  using CHGUSRPWD.   This allows the  password
and document password  to be captured, masked, sent  to another system,
unmasked  and applied  on the other  system with  the companion command
CHGUSRPWD2.

     *********************************************************
     *                                                       *
     *  You must have the TAA Productivity Tools product     *
     *    on each system that will either originate          *
     *    a password change or be the remote system to       *
     *    be changed.                                        *
     *                                                       *
     *********************************************************

The normal  method  of sending  the  command would  be  by the  use  of
SBMRMTCMD which  is part of DDM  support.  Other alternatives  are also
possible such as journaling.

A typical command on the originating system would be:

      CHGUSRPWD   USRPRF(xxxx) PASSWORD(yyyy) DOCPWD(zzz) PWDEXP(*SAME)

The  change  can  also be  made  using  the CHGPWD  command.    See the
special instructions for this.

The passwords are not shown in the job log.

The CL programs  must be  modified to  provide unique  secret codes  to
assist  in   masking  the   passwords.     Once  you   have  made   the
modifications  and created  your version  of  the programs,  the source
and  the programs should  be kept in  a secure library.   See the later
discussion on modifications and security considerations.

CHGUSRPWD command                                     *CMD
-----------------

The CHGUSRPWD  command should  be  entered on  the originating  system.
It  will change  the  password(s) and  use  a technique  to submit  the
CHGUSRPWD2  command to a remote system.   The normal method would be to
use the DDM command SBMRMTCMD.

   USRPRF        The user profile to be modified.

   PASSWORD      The password to  be assigned.   The default is  *SAME.
                 A password can be up to 10 characters in length.

   DOCPWD        The document  password to  be assigned.   The  default
                 is  *SAME.    A  document  password  can  be up  to  8
                 characters in length.

   PWDEXP        Whether the password  should be set  to expired.   The
                 default is *SAME.  A *YES or *NO may be specified.

   CHGUSRPRF     Whether  the CHGUSRPRF  command should  be  run.   The
                 default is  *YES.  The intent of  this parameter is to
                 avoid  changing the  profile when  it will  be changed
                 by the CHGPWD command.

CHGUSRPWD2 command                                    *CMD
------------------

The  CHGUSRPWD2  command is  to  be  run  on  a  remote  system.    The
CHGUSRPWD  command  must send  the  CHGUSRPWD2  command  to the  remote
system.   CHGUSRPWD2 should not  be used directly  as it expects masked
input for the password parameters.

   USRPRF        The user profile to be modified.

   MSKPWD        The password to  be assigned.   A  masked password  of
                 20 bytes must be input.

   MSKDOCPWD     The  document  password  to  be assigned.    A  masked
                 password of 20 bytes must be input.

   PWDEXP        Whether  the password should  be set to  expired.  The
                 default is *SAME.  A *YES or *NO may be specified.

Restrictions
-------------

Capturing the password to be sent  to another system requires that  you
do not use  the system supplied  CHGUSRPRF command.  Passwords  must be
changed  by  the CHGUSRPWD  command.   See  also  the instructions  for
allowing the user to change the passwords via the CHGPWD command.

A  program can  only be  named for the  QPWDVLDPGM system  value if the
QPWDLVL is 0 or 1 (allows for a maximum of 10 byte passwords).

Prerequisites
-------------

The following TAA Tools must be on your system:

     CVTFRMHEX    Convert from hex
     CVTHEX       Convert to hex
     FREE         Free an RPG program
     OR           Or bytes together
     SCRAMBLE     Scramble bytes
     SNDCOMPMSG   Send completion message
     SNDDIAGMSG   Send diagnostic message
     SNDESCMSG    Send escape message
     UNADOPT      Unadopt

Implementation
--------------

The tool  is created  so that  you  can test  the concept  on a  single
system.   You must  make changes  and re-create the  tool to  cause the
function  to  work  on a  remote  system.   See  the  later  section on
modifying the CL programs.

You  must also  consider  DDM  security.    See  the  section  on  'DDM
Considerations.'

Demonstration and Testing
-------------------------

To demonstrate the function  and test it on a  single system, a special
program  is provided  to work  with the  code  as is  shipped.   Do the
following to test the tool before making any modifications:

  1.   Signon  as  the  Security  Officer   or  a  user  with   *ALLOBJ
       authority.

  2.   Use a test  profile and change  the password using the  TAA Tool
       CHGUSRPWD command:

           CHGUSRPWD   USRPRF(xxxx) PASSWORD(yyyy)

  3.   The  code  as  shipped  for  CHGUSRPWD  executes  the  CHGUSRPRF
       command  to  change the  specified parameters.   It  also builds
       the CHGUSRPWD2  command  and places  it  in the  TSTCHGPWD  data
       area in  TAASECURE.  The CHGUSRPWD2 command  includes the masked
       passwords  as hex data.   You may display  the command which has
       been created by:

           DSPDTAARA   DTAARA(TAASECURE/TSTCHGPWD)

  4.   Using the system command CHGUSRPRF,  change the password of  the
       same profile to some other value:

           CHGUSRPRF   USRPRF(xxxx) PASSWORD(yyyy)

  5.   Call the test program in TAASECURE:

           CALL        PGM(TAASECURE/TAASECIC8)

       This  program should  respond  with messages  that describe  the
       previous  steps   and  a  completion  message  that  states  the
       password has been  changed by the  TAA Tool CHGUSRPWD2  command.

  6.   Signon to  the profile with  the password  that you assigned  in
       Step  2.   This  should prove  that  the the  password  is being
       properly unmasked to make the change.

If  you are  using the technique  via the QPWDVLDPGM  system value, you
should signon to  the test profile  and make a  password change.   Then
as the Security Officer, repeat steps 4-6.

You may  want to  use the  same approach to  test the  modifications to
the  CL programs for your  'secret code' described in  the next section
before you attempt  to send the CHGUSRPWD2  command to another  system.
This  will  ensure  that  the  same  'secret  code'  is  used  in  both
programs.   After this step  is working, you could  modify the TAASECIC
program to send the  CHGUSRPWD2 command to a  remote system and  remove
the  special  test  code  that  updates  the  TSTCHGPWD  data  area  in
TAASECURE.  See the next section.

Modifying the CL programs
-------------------------

The  TAASECIC  and  TAASECIC2   programs  must  be  modified.    Before
modifying  the  programs,  use  the the  CRTTAASRCF  command  to create
QATTxxx source files in a library such as:

       CRTTAASRCF   LIB(xxxx)

Then use the CPYTAA2  command to copy the  source for the tool to  your
library.

       CPYTAA2    TOOL(CHGUSRPWD) TOLIB(xxx)

Both the  CL programs (TAASECIC and  TAASECIC2) need to  be modified to
supply  your own  unique version of  the secret  codes.   Two codes are
provided for  each  program.   The  first  is  the code  used  for  the
password  value  and the  second  is  used  for the  document  password
value.

Use SEU to modify the source:

        STRSEU      SRCFILE(xxx/QATTCL) SRCMBR(TAASECIC)

The  code variables are declared  at the beginning of  each program and
the VALUE parameter should be changed  to some unique value known  only
to  you.   After  you  have changed  the  variables,  end SEU  (do  not
attempt to create anything at this time).

Use SEU to modify the source for the second program:

        STRSEU      SRCFILE(xxx/QATTCL) SRCMBR(TAASECIC2)

Since  both  programs  must  agree  on  the  values  you  use,  a  good
technique  would be to  use the SEU  split screen to  copy the two DCLs
from TAASECIC to the second  program.  After you have made  the change,
end SEU.

At  this point  it  is recommended  that  you create  the two  programs
without  making  any further  modifications and  try  the demonstration
program as described in  the previous section.   This will ensure  that
the programs are both using the same 'secret code'.

You can create the tool from the source you modified by specifying:

           CRTTAATOOL    TOOL(CHGUSRPWD)  SRCLIB(xxx)

Now try  the demonstration test as  described in the  previous section.

After  this test is complete,  you must modify the  TAASECIC program to
send the  CHGUSRPWD2  command to  one  or  more remote  systems.    The
typical  solution would  be  to  use  DDM via  the  SBMRMTCMD  command.
TAASECIC  program must also  be modified to  specify the DDM  file name
to  be  used  for the  SBMRMTCMD.    Use SEU  as  described  earlier to
TAASECIC in TAASECURE.   See the discussion  at about statement 180  of
the TAASECIC program.

After you  have modified the source,  you should re-create  the tool as
follows:

           CRTTAATOOL    TOOL(CHGUSRPWD)  SRCLIB(xxx)

It  is important that you  protect your secret codes.   See the section
on Security considerations.

There is  no reason  for  you to  write  down your  secret code  in  an
offline place.   If you  have to recreate the  programs, you can  use a
different  value  as  there  is nothing  kept  on  any  of the  systems
involved that  will  use the  old  value (assuming  that  the  password
changes were successfully applied).

Good practice would be  to save your secure library,  secure the media,
and  then delete the  secure library.   This  will provide a  backup if
the objects are damaged.

You  must have the TAA Productivity  Tools product on the systems where
the change may originate from or be applied.

Use with CHGPWD command
-----------------------

The CHGPWD command can be used  in a user program to allow an  end user
to change  his own password.   The system also supports  the capability
to force  the CHGPWD prompt after N days  of usage of the same password
with  the   QPWDEXPITV  system   value  or   by  specifying   CHGUSRPRF
PWDEXP(*YES).

When CHGPWD  is used, the system  supports an optional exit  program to
ensure that  the password meets a specific  installation's rules.  This
exit program can  also be used to  capture the password  to send it  to
another system.

A  program  (TAASECIC3) is  provided  to  do  this.   As  the  Security
Officer, you  must change the  system value QPWDVLDPGM  to specify this
program.

           CHGSYSVAL     SYSVAL(QPWDVLDPGM) VALUE('TAASECIC3 TAATOOL')

The  program TAASECIC3 exists  in TAATOOL and is  owned by the Security
Officer and adopts  his profile.  This  allows access to the  TAASECURE
library.

When the next  user changes his password with  CHGPWD, the exit program
TAASECIC3  will  be called.    It invokes  the CPP  (TAASECIC)  for the
CHGUSRPWD command.  This will  cause the same function as if  CHGUSRPWD
was invoked  directly except  that the CHGUSRPRF  function is  not done
(it has already been done by the system).

DDM considerations
------------------

The  DDM  Users Guide  describes  how the  SECURELOC  parameter  in the
remote systems  configuration controls  who the  user profile  is  that
will be used  on the remote  system.  If SECURELOC(*YES)  is specified,
the  command will  be run  by  the same  user profile  and  no security
considerations should exist.

If  SECURELOC(*NO) is  specified, the command  must be run  by the user
specified for the DDM  job.  To allow  a single user profile  to change
the passwords  for any user  will probably cause a  security violation.
A  program written to adopt  the security officers profile  can be used
to accept  a string  and  execute it.   To  prevent this  program  from
being  used   in  an  non-secure   manner,  you  should   provide  some
technique.

A  solution would be  to use a  CALL command instead  of the CHGUSRPWD2
with SBMRMTCMD.   Pass the same  list of  values.  The  program on  the
remote system would accept  the parameters and pass the  same list plus
a secure  code to a  second program which adopts  the security officers
profile.   The  second program  would verify  that the secure  code was
correct and then perform the CHGUSRPWD2 command.

Security considerations
-----------------------

The  code  is  written  to  attempt  to  minimize  security  exposures.
However, because  the programs  and the submitted  command are  the key
to determining what the passwords are, there is always an exposure.

For  example,  there is  nothing  to  prevent an  authorized  user from
saving the TAASECURE library and  taking it to another system where  he
can analyze  the information as the  Security Officer.  While  it would
not  be  easy  to  determine  what  is  being  done,  it would  not  be
impossible.

Unless you are willing to  assume a risk of  this type, you should  not
implement CHGUSRPWD.

You  can reduce  this  risk  somewhat by  saving  the source  files  to
secure media and deleting them from the system.

The  sensitive  objects  (the  CL  programs which  contain  the  secret
codes)  are  placed  in the  private  library TAASECURE.    The Product
Library for  the  CHGUSRPWD and  CHGUSRPWD2  commands is  specified  as
TAASECURE.    Only the  security  officer can  create  the  tool.   The
commands  will  not  execute  unless  the  user  is  authorized to  the
TAASECURE library.

The validity checking  program (TAASECIC3 in TAATOOL)  must exist in  a
public library (TAATOOL) so  it can be accessed when  the user signs on
and the  operating system is validating a  new password.  The TAASECIC3
program adopts the  user profile  of it's  owner so that  the user  can
access  the secure  library  TAASECURE.   The  CPP (TAASECIC)  for  the
CHGUSRPWD command is called using a qualified name from TAASECIC3.

Any  TAA Tool  commands that  are executed  by CHGUSRPWD  or CHGUSRPWD2
are  done in a sub program which is  created as USEADPAUT(*NO).  The CL
programs are created  to prevent logging,  retrieving of CL source  and
debugging.

The  QPWDVLDPGM  system  value  requires that  the  processing  program
receive a parameter list of:

     - New password      *CHAR LEN(10)
     - Old password      *CHAR LEN(10)
     - Return code       *CHAR LEN(1)  where '0' means the password
                                         is considered valid.

While  the  TAASECIC3  program attempts  to  block  security exposures,
there is  nothing to prevent  a normal  user from  calling the  program
during the day  (e.g.  after signing  on).  The program  will perform a
SBMRMTCMD  as if the user  had done CHGPWD.   This will  cause a change
on the other system  without making the change  on the current  system.

Backup of TAASECURE Library
---------------------------

For  the  CHGUSRPWD  tool, the  TAASECURE  library  will  only  contain
source  and object.   Once it  is backed  up, you need  not back  it up
again.   However, other tools may also  use this library (e.g.  DSPPWD)
and you should consider the overall use.

A new release of the TAA Tools
------------------------------

When a new  release of TAA  Tools is shipped,  the install code  checks
the  TAASECIC  and TAASECIC2  programs  in  TAASECURE.   If  they  were
created  on a system  with a name  that begins with  TAASYS, the object
programs are replaced.   If they  were created on  a system other  than
TAASYSxx, they are  left in tact.   Therefore, if you created  the tool
on  your system,  the  install code  should not  replace  your modified
version.

The objects in TAATOOL related  to CHGUSRPWD (command and CL  programs)
are replaced on  each release, but this  should not impact your  use of
CHGUSRPWD.

You should  read the information  member from the HELPTAA  menu on each
release  regarding 'changes in  the release' to  determine if there any
changes to the  CHGUSRPWD tool  that will require  you to recreate  the
programs.   If so,  you must repeat  the process described  earlier and
recreate the tool.

Objects used by the tool
------------------------

   Object        Type        Attribute      Src member    Src file
   ------        ----        ---------      ----------    ----------

   CHGUSRPWD     *CMD                       TAASECI       QATTCMD
   CHGUSRPWD2    *CMD                       TAASECI2      QATTCMD
*  TAASECIC      *PGM           CLP         TAASECIC      QATTCL
*  TAASECIC2     *PGM           CLP         TAASECIC2     QATTCL
   TAASECIC3     *PGM           CLP         TAASECIC3     QATTCL
*  TAASECIC8     *PGM           CLP         TAASECIC8     QATTCL
*  TAASECIC9     *PGM           CLP         TAASECIC9     QATTCL
** TSTCHGPWD     *DTAARA

     * These objects are located in the TAASECURE library.

    ** The data area is created by test instructions in TAASECIC.

Structure
---------

CHGUSRPWD  Cmd
  TAASECIC   CL
    TAASECIC9   CL

CHGUSRPWD2  Cmd
  TAASECIC2   CL
    TAASECIC9   CL

Other programs

  TAASECIC3   CL  - Used as the exit program for QPWDVLDPGM
  TAASECIC8   CL  - Used as a demonstration/test program
					

Added to TAA Productivity tools April 1, 1995


Home Page Up to Top