Custom agent unable to connect to policy server

Products

• SITEMINDER
• CA Single Sign On Secure Proxy Server (SiteMinder)
• CA Single Sign On Agents (SiteMinder)
• CA Single Sign On Federation (SiteMinder)

Issue/Introduction

A custom Agent API program has been deployed to a new server and cannot connect to the policy server.  This program is working as expected on other hosts.  The policy server logs a handshake failure whenever the program attempts to initialize: "Handshake error: Shared secret incorrect for this client."  The custom program reports an initialization error.

Environment

All Supported Environments

Cause

ETPKI (CAPKI) had not been installed on the new server.  This is required for custom applications to use encryption, such as when connecting to a policy server. 

Note: The ETPKI libraries are installed with SiteMinder runtime components (that is, Policy Server, Administrative UI, agents, and so on). You only need to install them on systems with no other SiteMinder product components installed.

Resolution

Be sure to install ETPKI (CAPKI) on any hosts where custom programs are to be used.  Use the following procedure:

Install the ETPKI Libraries on Windows:

       1) Open a Command window.
       2) Navigate to the SDK installer location.
       3) Execute the following command:

       setup.exe {install|remove} caller=callerID [Options...]

       -install
        Install the ETPKI libraries.
       -remove
        Uninstall the ETPKI libraries.
       -caller= callerID
        Specifies a unique identifier (callerID) for the parent application for which the ETPKI libraries are being installed. When multiple subcomponents of a product rely on CAPKI, specify a different identifier for each component.
       Limits: 255 characters

       Options
       -instdir=user_supplied_directory
        By default, setup.exe installs the ETPKI libraries to "C:/Program Files (x86)" (32-bit) or "C:/Program Files" (64-bit). Use the instdir option to specify an alternate installation directory.
        Note: The installer considers this option only when these libraries are the first CA shared component on this system.
       -verbose/veryverbose
        Enables diagnostic output with more or less detail.

       Example:
       setup.exe install caller=01010101 instdir=C:\ETPKI veryverbose

       For more information, see the readme.txt file included with the SDK installation in SDK_install_dir\etpki-install-32 or SDK_install_dir\etpki-install-64.

 

Install the ETPKI Libraries on UNIX
Use this procedure to install the ETPKI libraries on Linux.

       1) Open a shell window.
       2) Navigate to the appropriate installer location.
       3) Execute the following command:

       setup {install|remove} caller=callerID [Options...]

       -install
         Install the ETPKI libraries.
       -remove
        Uninstall the ETPKI libraries.
       -caller= callerID
        Specifies a unique identifier (callerID) for the parent application for which the ETPKI libraries are being installed. When multiple subcomponents of a product rely on CAPKI, specify a different identifier for each component.
        Limits: 255 characters

       Options
       -instdir=user_supplied_directory
        By default, setup installs the ETPKI libraries to /opt/CA/SharedComponents. Use the instdir option to specify an alternate installation directory. The installer considers this option only when these libraries are the first CA shared component on this system.
       -verbose/veryverbose
        Enables diagnostic output with more or less detail.
       -env={none|user|all}
        Specifies whether you want the ETPKI installer to set environment variables for the specified user or all users:
              none — No environment variables set (default)
              user — The current user only (SHOME/.profile)
              all — all users (/etc/profile)

        When env=user or env=is set, the ETPKI installer creates the following environment variables:

              CASHCOMP — Points to the ETPKI install directory
              CALIB — Points to the $CASHCOMP/lib directory
              CABIN — Points to the $CACHCOMP/bin

       Example:

       ./setup install caller=01010101 instdir=/home/CA/etpki verbose env=user

       4) Set the CAPKIHOME environment variable to specify the ETPKI installation directory:

       CAPKIHOME="ETPKI_install_dir"export CAPKIHOME

       For more information, see the readme.txt file included with the SDK installation in SDK_install_dir/etpki-install-32 or SDK_install_dir/etpki-install-64.
(Optional) Uninstall the SDK