External Interfaces

Up to this point, any reference to establishing a dialogue between Mainframe Connector and the Bravura Pass server for password strength validation and synchronization has used a security product "new password" exit as the trigger. This section discusses an external application programming interface (API) that can be used to invoke Mainframe Connector outside the scope of the z/OS security product. This external API is PSNCSSC , the Mainframe Connector SubSystem Call.

PSNCSSC is an assembler based API and is invoked from an assembler program through a macro interface. It can be used from a stand-alone application or program to determine the validity of a potential new password value. This may be appropriate if an application uses its own internal validation method rather then making use of the installed security product.

Member EXAMPL1 in the Mainframe Connector INSTLIB dataset provides an example assembler program for invoking the PSNCSSC service as well as the linkedit information required. Member PSNCSSC in the Mainframe Connector INSTLIB provides the PSNCSSC macro used to generate the call to the PSNCSSC service. The following are some example PSNCSSC macro calls:

*   Determine if PWD1 passes Bravura Pass strength
*   rules for USRID1
         PSNCSSC USERID=USRID1,                                        X
               NPWD=PWD1,                                              X
               RQSTTYPE=TEST,                                          X
               WORKAREA=WORKA
         B     BRTBL1(R15)
BRTBL1   DS    0H
         B     TESTOK            PSNCSSC RC=0
         B     TESTFAIL          PSNCSSC RC=4
         B     TIMEOUT           PSNCSSC RC=8
         B     CONNFAIL          PSNCSSC RC=12
         B     UNKNOWN           PSNCSSC RC=16
         B     STORFAIL          PSNCSSC RC=20
         B     NOPSYNCH          PSNCSSC RC=24
         B     BADPARMS          PSNCSSC RC=28
         B     BADRQSTT          PSNCSSC RC=32
         .
         .
*   Check PWD1 for Bravura Pass strength rules and
*   synchronize if it does
         PSNCSSC USERID=USRID2,                                        X
               NPWD=PWD2,                                              X
               RQSTTYPE=CHNG,                                          X
               WORKAREA=WORKA
         B     BRTBL2(R15)
BRTBL2   DS    0H
         B     CHNGOK            PSNCSSC RC=0
         B     CHNGFAIL          PSNCSSC RC=4
         B     TIMEOUT           PSNCSSC RC=8
         B     CONNFAIL          PSNCSSC RC=12
         B     UNKNOWN           PSNCSSC RC=16
         B     STORFAIL          PSNCSSC RC=20
         B     NOPSYNCH          PSNCSSC RC=24
         B     BADPARMS          PSNCSSC RC=28
         B     BADRQSTT          PSNCSSC RC=32
         .
         .
USRID1   DC    CL8'TEST01'
PWD1     DC    CL8'GOODPWD'
USRID2   DC    CL8'TEST02'
PWD2     DC    CL8'BADPWD'
WORKA    DC    8F

Any program that uses the PSNCSSC services must be linkedited AC(1).

Using RQSTTYPE=TEST on the macro call requires READ access to the FACILITY class PSYNCAPI profile. Using RQSTTYPE=CHNG on the macro call requires update access to the FACILITY class PSYNCAPI profile. For RACF environments, the following commands would be required to create the PSYNCAPI profile and grant RQSTTYPE=CHNG access to user MTECH01 :

  RDEFINE FACILITY (PSYNCAPI) UACC(NONE)
  PERMIT PSYNCAPI ACCESS(UPDATE) CLASS(FACILITY) ID(MTECH01)
  SETROPTS RACLIST(FACILITY) REFRESH

If multiple Mainframe Connector started tasks were being used and the PSNCUIDT table had been created, the following FACILITY class changes would be required:

  RDEFINE FACILITY (PSYNCAPI.ssn) UACC(NONE)
   
  PERMIT PSYNCAPI.ssn ACCESS(UPDATE) CLASS(FACILITY) ID(MTECH01)
   
  SETROPTS RACLIST(FACILITY) REFRESH

where ssn is the subsystem name of the Mainframe Connector subsystem that is to be used by this requester.

Appropriate security definitions for ACF2 or TopSecret environments would also be required if the PSNCSSC service were invoked under those security products' control.

Under certain circumstances it would be nice to know whether or not a proposed new password value for a given userid passes the rules for a valid RACF password. These rules include:

The PSNCRCFR API provides this capability for RACF environments.

PSNCRCFR is an assembler based API and is invoked from an assembler program through a macro interface. It can be used from a stand-alone application or program to determine if a password value would pass the selected RACF password rule requirements. By default, all of the rules described above are checked. The PSNCRCFR macro call can disable any of the defined rule checks as necessary for any particular request. The default macro parameter settings for rule checking are:

OLDNEWCHK=YES   - check new password against old
HISTCHK=YES     - check new password against history list
RULECHK=YES     - check new password against RACF
                  length & content requirments
WHENCHK=YES     - check current day and time against RACF
                  WHEN day and time
UIDPWDCHK=YES   - check new password against userid
ICHPWX01CHK=YES - check new password against ICHPWX01
                  requirements

Any of these checks can be disabled by specifying NO for the corresponding parameter.

A useful application of this API is in the PSNCUX01 user exit. By default, Mainframe Connector considers any reset or resetexpire request that has been made from the Bravura Pass server as valid and will proceed in performing a RACF administrative reset of the password value. This reset will bypass any of the RACF rule checks. If this is not appropriate for your site, the PSNCRCFR API could be invoke from PSNCUX01 to determine the appropriateness of the proposed password value for the given userid. If the password value were deemed unacceptable, PSNCUX01 could return a return code of 8 and the reset would be rejected on that target z/OS system.

Member EXAMPL2 in the Mainframe Connector INSTLIB dataset provides an example assembler program for invoking the PSNCRCFR service as well as the linkedit information required. Member PSNCRCFR in the Mainframe Connector INSTLIB provides the PSNCRCFR macro used to generate the call to the PSNCRCFR service. Following are some example PSNCRCFR macro calls:

*   Determine if PWD1 for USRID1 passes the RACF password rules
*   but bypass the WHEN day time check
         PSNCRCFR USERID=USRID1,                                       X
               NPWD=PWD1,                                              X
               WHENCHK=NO,                                             X
               WORKAREA=WORKA
         B     BRTBL1(R15)
BRTBL1   DS    0H
         B     GOODPWD1          PSNCRCFR RC=0
         B     BADPARMS          PSNCRCFR RC=4
         B     OLDNEW            PSNCRCFR RC=8
         B     HISTFAIL          PSNCRCFR RC=12
         B     RULEFAIL          PSNCRCFR RC=16
         B     WHENFAIL          PSNCRCFR RC=20
         B     NOUSERID          PSNCRCFR RC=24
         B     USRIDPWD          PSNCRCFR RC=28
         B     PWX01BAD          PSNCRCFR RC=32
         .
         .
*   Determine if PWD2 for USRID2 passes the RACF password
*   rules but bypass the RACF ICHPWX01 new password exit check
         PSNCRCFR USERID=USRID2,                                       X
               NPWD=PWD2,                                              X
               ICHPWX01CHK=NO,                                         X
               WORKAREA=WORKA
         B     BRTBL2(R15)
BRTBL2   DS    0H
         B     GOODPWD2          PSNCRCFR RC=0
         B     BADPARMS          PSNCRCFR RC=4
         B     OLDNEW            PSNCRCFR RC=8
         B     HISTFAIL          PSNCRCFR RC=12
         B     RULEFAIL          PSNCRCFR RC=16
         B     WHENFAIL          PSNCRCFR RC=20
         B     NOUSERID          PSNCRCFR RC=24
         B     USRIDPWD          PSNCRCFR RC=28
         B     PWX01BAD          PSNCRCFR RC=32
         .
         .
USRID1   DC    CL8'TEST01'
PWD1     DC    CL8'GOODPWD'
USRID2   DC    CL8'TEST02'
PWD2     DC    CL8'BADPWD'
WORKA    DC    8F