Implementation of Password Exits for eTrust Single Sign-On on Windows

Document ID : KB000055527
Last Modified Date : 14/02/2018
Show Technical Document Details

TABLE OF CONTENTS:

  1. Introduction
    1.1 Password Change Exits
    1.2 Password Auto-Gen Exits
    1.3 Sample Password Exit Codes
  2. Password Change Exits
    2.1 Flow Diagram
    2.2 Development
    2.3 Installation
  3. Password Auto-Gen Exits
    3.1 Flow Diagram
    3.2 Development
    3.3 Installation
  1. Introduction

    In order to meet every site's requirements for passwords, eTrust Single Sign-On provides defined password rules to cater for a wide range of password possibilities. There are times however, when a site uses password rules that go beyond the rules that have been created in eTrust Single Sign-On. In order to create password rules that are unique to a site, password exits can be used.

    There are two types of password exits:
      • Password Change Exits
      • Password Auto-Gen Exits

    Implementing customized password functionality using password exits is done via a DLL (dynamic-link library).

    1.1 Password Change Exits

    There are two kinds of password change exits:
    • pre-exit
    • post-exit

    Pre-exit is essentially an exit to validate passwords.
    Post-exit is used as notification of a successful password change.

    The process that changes application passwords is executed in the following order:
    • sso password validation
    • sso pre exit
    • sso db update
    • sso post exit

    1.2 Password Auto-Gen Exits

    If the password auto-gen exit parameter is defined, you can write your own auto-gen exit instead of using ETrust Single Sign-On's auto-gen exit. Auto-gen is an SSO function that creates a new password for the user when a password expires.

    There is no hard and fast rule that both type of exit appear within the same 'DLL', but it is recommended to develop separate 'DLL's for the task.

    The process for setting up exits on Unix will be similar. Unix uses the same four entry points that Windows uses and the code for the Unix and Windows routines could be similar if Operating System-specific features are avoided. The details of setting up a shared library will be different and will probably differ between flavors of Unix. Under Unix the values stored in the Windows Registry are stored in the SSO server INI file.

    Details about Development, Implementation and Installation for each type of exits are provided in sections below.

    1.3 Sample Password Exit Codes

    For your convenience, sample Password Exit code for both Exit types are available. The compressed file: TEC418610.zip includes the following compressed files:

    • Files for Password Change Exits Sample:

      • Pass_Change_Exit.ZIP:
        • Pass_Change_Exit.c
        • Pass_Change_Exit.h

    • Files for Password Auto-Gen Exits Sample

      • Pass_AutoGen_Exit.ZIP:
        • Pass_AutoGen_Exit.c
        • Pass_AutoGen_Exit.h

    • A Sample SSO TCL Script for the sample application:

      • SAMPLE.TCL

  2. Password Change Exits

    This section of the document describes the password change exits in detail.

    2.1 FLOW DIAGRAM

    Exit checks the password for Application 1 for Quality or additional check. (ssod_Exit_PreSetPwd)

    Figure 1Ā 


    2.2 Development

    An Exit can be developed to enhance the password capabilities of SSO. For example, to check if the password is the same as the application name or a specific set of common names.

    The policy server expects the password change exit 'DLL' to implement the following 4 functions and makes calls to the functions when required. A description of each function follows:

    • ssod_Exit_Pwd_Init :
      This is called every time the SSO Policy Server starts and is used to initialize the Exit.

      Syntax:
      unsigned long
      ssod_Exit_Pwd_Init (void **ppCtxExit, unsigned long *pulExitVersion);

      Description:
      ppCtxExit: Indicates the pointer to exit specific context. This is a placeholder for any static data. (Input/Output)
      pulExitVersion: Indicates the exit version. (Output)

      Return values:
      A return value of 0 indicates success.
      A non-zero return value indicates that exit initialization failed.

    • ssod_Exit_Pwd_Term :
      Performs termination and cleanup of the password exit DLL whenever the SSO Policy Server is stopped.

      Syntax:
      unsigned long
      ssod_Exit_Pwd_Term (void **ppCtxExit);

      Description:
      ppCtxExit: Indicates the pointer to exit specific context. This is a placeholder for any static data. (Input/Output)

      Return values:
      A return value of 0 indicates success.
      A non-zero return value indicates an error.

    • ssod_Exit_PreSetPwd :
      Is called after SSO checks the quality of the new password using the password policies of SSO. Additional checks and tasks can be preformed here before the Policy Server updates the password of an application with this new password.

      Syntax:
      unsigned long
      ssod_Exit_PreSetPwd(void *pCtxExit,
      const char *szSSOUserName,
      const char *szApplName,
      const char *szLoginName,
      const char *szPassword,
      char **pszExtra );

      Description:
      pCtxExit: Exit specific context. (Input)
      szSSOUserName: The user name as it appears in the SSO database. (Input)
      szApplName: The application name. (Input)
      szLoginName: The application's login ID. (Input)
      szPassword: The password that is to be set. (Input)
      pszExtra: A pointer to a string that contains an error message if the password is rejected (output)

      Return Values:
      A return value of 0 indicates that the password is approved.
      A non-zero return value indicates that the password is rejected.

    • ssod_Exit_PostSetPwd :
      Is called after the SSO server successfully updates the SSO database with the new password. This function can also be used to perform additional tasks if required.

      Syntax: unsigned long
      ssod_Exit_PostSetPwd(void *pCtxExit,
      const char *szSSOUserName,
      const char *szApplName,
      const char *szLoginName,
      const char *szPassword,
      char **pszExtra);

      Description:
      pCtxExit : Exit specific context. (Input)
      szSSOUserName : The user name as it appears in the SSO database. (Input)
      szApplName: The application name. (Input)
      szLoginName: The application's login ID. (Input)
      szPassword : The password that is to be set. (Input)
      pszExtra : A pointer to a string that contains an error message when this password is rejected.

      Return Values:
      A return value of 0 indicates success.
      A non-zero return value indicates an error.

    Develop the code, with the functions given above. The attached sample code can also be used. To compile the attached code or to develop your own code, do the following:

    1. Create a new project in Microsoft Visual C/C++. Name the project "pwdexit". The type of the project should be "Win32 Dynamic-Link Library" and "An empty DLL Project". (You can choose another name but would need to change the PWDEXIT_EXPORTS preprocessor value in the Project Settings and the .h file.)
    2. Add the 'Pass_Change_Exit.c' and 'Pass_Change_Exit.h' files into the project. Or create the required files on your own and add logic to them.
    3. In the Project Settings, "C/C++" tab, Category: "Code Generation" set the "Use run-time library" to "Multi-threaded DLL" (or "Debug Multi-threaded DLL" for Debug builds). This is normal for DLL's that use the C Run Time library.
    4. Compile and build the DLL. Ignore the 'inconsistent DLL Linkage warning'.

    Now you have a Password Change Exit DLL in the 'debug' folder of your project.

    2.3 Installation

    To use the Password Change DLL that you have compiled, you must first successfully install the Exit with the SSO Policy Server. To do so use the following steps:

    1. On the SSO server there are two Registry entries that need to be set:
      '\\HKLM\SOFTWARE\ComputerAssociates\eTrust\Shared\policy Server\8.0\exits' , 'ExitsPath' needs to be set to the directory in which the DLL will be installed. This is normally ' C:\Program Files\CA\Policy Server\Exits\'
      '\\HKLM\SOFTWARE\ComputerAssociates\eTrust\Shared\policy Server\8.0\' , 'PasswordExits' should be set to pwdexit.dll ? ie. the name of the DLL.
    2. Using the Services Control Panel stop the "eTrust Policy Server" service.
    3. Copy the pwdexit.dll file to the directory specified in the registry.
    4. Start the SSO service again.

    Ensure that the msvcrtd.dll is available on your system, located in a PATH's folder.

    If the Sample exit is used, each call to the Password Exits will write the parameters of the call to the file C:\PASSWDEXITLOG.TXT.

    In addition the ssod_Exit_PreSetPwd routine will reject any attempt to use the application name as the password. The Password Exit passes back a message "You are not allowed to use the application name as your password" which displays on the user's client display.

    Figure 2

    There are different ways to change the password for an application :

    • A user can change the password using the ETrust Single Sign-On Tools on the SSO client
    • A script can change the password using an SSO chlogin command
    • or it can be done through one of the API's.

    Changing the password only changes the NEXTPWD field passed to SSO scripts. It is up to the scripts to recognize that there is a pending password change and to communicate with the application to change the password and to use the SSO notify command to tell the SSO server the password is updated. This process is seen in the Sample.tcl script in the attached file.

  3. Password Auto-Gen Exits

    This section of the document describes the Password Auto-Gen exits in detail.

    3.1 FLOW DIAGRAM

    Figure 3

    3.2 Development

    The Auto-Gen exit needs to be created whenever a password that is beyond the capabilities of SSO Policy Server, needs to be generated. For example, if certain applications cannot accept a capital letter as its first character.

    The policy server expects the password Auto-Gen exit 'DLL' to implement the following 3 functions and makes calls to the functions when required. A description of each function follows :

    • ssod_Exit_Auto_Init:

      This is called every time the SSO Policy Server starts and is used to initialize the Exit.

      Syntax:
      unsigned long
      ssod_Exit_Auto_Init (void **ppCtxExit, unsigned long *pulExitVersion);

      Description:
      ppCtxExit: Indicates the pointer to exit specific context. This is a placeholder for any static data. (Input/Output)
      pulExitVersion: Indicates the exit version. (Output)

      Return values:
      A return value of 0 indicates success.
      A non-zero return value indicates that exit initialization failed.

    • ssod_Exit_Auto_Term:
      The ssod_Exit_Auto_Term function terminates and cleans up the auto-gen exit DLL whenever the policy server is stopped.

      Syntax:
      unsigned long
      ssod_Exit_Auto_Term(void **ppCtxExit);

      Description:
      ppCtxExit: Indicates the pointer to exit-specific context. This is a placeholder for any static data the auto-gen exit needs. (Input/Output)

      Return values:
      A return value of 0 indicates success.
      A non-zero return value indicates an error.

    • ssod_Exit_PwdAutoGen:
      The ssod_Exit_PwdAutoGen function generates a password, which is used instead of the SSO default password auto-gen mechanism.

      Syntax:
      unsigned long
      ssod_Exit_PwdAutoGen(void *pCtxExit,
      const char *szSSOUserName
      const SEOS_PASSWDRULES *pPwdRules
      const char *szApplName,
      const char *szLoginName,
      char *szPassword,
      int iPwdSize
      char **pszExtra);

      Description:
      pCtxExit : Exit specific context. (Input)
      szSSOUserName : The user name as it appears in the SSO database. (Input)
      pPwdRules: A pointer to the SEOS_PASSWRDRULES structure. (Input)
      szApplName: The application name. (Input)
      szLoginName: The application's login ID. (Input)
      szPassword: The generated password that the exit created. (Output)
      iPwdSize: Defines the password buffer length. (Output)
      pszExtra: A pointer to a string that contains an error message. (Output)

      Return Values:
      A return value of 0 indicates success.
      A non-zero return value indicates that a password could not be generated.

    The structure SEOS_PASSWDRULES can be defined as follows:
    /* eTrustAC Passwords policy property */
    typedef struct tagSeosPasswdRules
    {
    short min_len; /* minimum length */
    short max_rep; /* maximum single char repetition */
    short must_small; /* must contain small chars */
    short must_capital; /* must contain capitals */
    short must_num; /* must contain numbers */
    short must_oth; /* must contain other chars */
    short must_alfa; /* must contain at least # alfa chars */
    short must_alfan; /* must contain at least # alfanum chars */
    short sub_name; /* must not be username's sub string */
    short sub_old; /*must not be old passwd sub string */
    short sub_str_len; /* Max len of repeated sub-string in pwd */
    short sub_str_rep; /* Max repetition of a sub-string */
    short passwd_life; /* Default # of days between pwds changes */
    short grace_logins; /* # of grace logins after pwd expiration */
    short u_block_min; /* # of minutes to block user on password */
    short wrong_pass; /* # of wrong pwds tries before set EXPIRE */
    short history; /* History length */
    short min_time; /* minimum time (days?) between changes */
    short max_len; /* maximum length */
    short dict_format; /* select the dictionary format */
    short bidirectional; /* use bidirectional encryption key */
    short unused[5]; /* Reserved for future use. */
    } SEOS_PASSWRDRULES;
    Failure to define the structure as given above may result in compilation errors.

    Develop the code with the above functions. The attached sample code can also be used.
    To compile the attached code or to develop your own code, do the following:

    1. Create a new project in Microsoft Visual C/C++. Name the project "pwdexit". The type of the project should be "Win32 Dynamic-Link Library" and "An empty DLL Project". (You can choose another name but would need to change the PWDEXIT_EXPORTS preprocessor value in the Project Settings and the .h file.)
    2. Add the 'Pass_AutoGen_Exit.c' and 'Pass_AutoGen_Exit.h' files into the project. Or create the required files on your own and add logic to them.
    3. In the Project Settings, "C/C++" tab, Category: "Code Generation" set the "Use run-time library" to "Multi-threaded DLL" (or "Debug Multi-threaded DLL" for Debug builds). This is normal for DLL's that use the C Run Time library.
    4. Compile and build the DLL. Ignore the 'inconsistent DLL Linkage warning'.

    Now you have a Password AutoGen Exit DLL in the debug' folder of your project.

    3.3 Installation

    To use the Password Change DLL that you have compiled, you must first successfully install the Exit with the SSO Policy Server. To do so use the following steps:
    1. On the SSO server there are two Registry entries that need to be set:
      '\\HKLM\SOFTWARE\ComputerAssociates\eTrust\Shared\policy Server\8.0\exits' , 'ExitsPath' needs to be set to the directory in which the DLL will be installed. This is normally ' C:\Program Files\CA\Policy Server\Exits\' '\\HKLM\SOFTWARE\ComputerAssociates\eTrust\Shared\policy Server\8.0\' , 'AutogenExit' should be set to autogen.dll ? ie. the name of the DLL.
    2. Using the Services Control Panel stop the "eTrust Policy Server" service.
    3. Copy the autogen.dll file to the directory specified in the registry.
    4. Start the SSO service again.

    Ensure that the msvcrtd.dll is available on your system, located in a PATH's folder.

    If the Sample exit is used, each call to the Password Exits will write the parameters of the call to the file C:\PASSWDAUTOGENLOG.TXT

    Every time an application password expires, the Policy Server will invoke the Auto-Gen Exit to generate a password for the application.

    The Auto-Gen exit can be customized so that a different complexity of password is generated every time a different application is invoked by the user. Alternatively, the Auto-Gen exit could be built such that a different mechanism for generation could be used for a given set of users.

    The ssod_Exit_PwdAutoGen function will return the policy server with the generated password, which in turn will pass the TCL script being executed by the SSO client.

    There are different ways to change the password for an application:

    • A user can change the password using the ETrust Single Sign-On Tools on the SSO client
    • A script can change the password using an SSO chlogin command
    • or it can be done through one of the API's.

    Changing the password only changes the NEXTPWD field passed to SSO scripts. It is up to the scripts to recognize that there is a pending password change, to communicate with the application to change the password, and to use the SSO notify command to tell the SSO server the password is updated. This process is seen in the Sample.tcl script in the attached file. The screen shots below will guide you through the process.

    Create a sample application:

    Figure 4

    Enable Password Generation for that Application (Optionally a test password policy can also be attached so that the password can be expired more frequently by changing the date on the Policy Server):

    Figure 5

    Figure 6

    Use the SSO Client to log in as User01 and run the 'Sample Application' application. The results should be similar to something as shown below if the old password has expired:

    Figure 7