| CA |
4.0 Installation Considerations
4.1 Install the SDK
4.2 Uninstall the SDK
4.3 Install the Documentation
4.4 Uninstall the Documentation
5.0 General Considerations
5.1 Policy Management API
5.2 Single Sign-On Support in Custom Agents
5.3 Custom Agents and SiteMinder v6.0 SP 5
5.4 5.08 LDAP SDK Integration
6.0 Known Issues
6.1 Patch Required for Custom Agents Running on HP-UX
6.2 Configuration Issue with the smpolicyapi Sample on Unix/Linux Platforms
6.3 Hierarchical Realms Not Supported in the Java Policy Management API
6.4 SiteMinder May Not Enforce the Requirement that a Given Resource Filter Be Unique for an Agent that is a Member of Different Agent Groups (10911)
6.5 Constants Missing from Java Policy Management API (13348)
6.6 Attributes Terminated with a Space Character Cause SSO Problems in Java (13712)
6.7 Extra ServerDef Object Created with Java AgentAPI.getConfig() (14841)
6.8 Java SmPolicyApiImpl.search() Can't Search for an Object of Type Domain (15133)
6.9 Sort Order in a Java SmDmsCursor Object Can't Be Empty (15317)
6.10 General Password Validation Errors in C (16787)
6.11 Incorrect Authentication Pages No Longer Displayed When SecurID Token is in New Token Mode (23219)
6.12 Executing an Application Built with the Policy Management API on Solaris (28334)
6.13 On Windows Platforms, the Java Method getConfig() Fails (39780)
7.0 Fixes in SiteMinder SDK r6.0 SP 5
7.1 The Pure Java Agent API isProtected Method Did Not Set realmdef Members to Null (55246)
7.2 The Pure Java Agent API login Method Did Not Accept a null or '''' Value for the clientIP Parameter (55247)
7.3 The authenticateUser() method Failed for the Java Policy Management API (52937)
7.4 The Agent API connect() Method in the Perl CLI Did Not Return an Error Code (54815)
7.5 Java API SmTrustedHost.writeProperties(hash) Threw NullPointerException (54842)
7.6 Domain Scope User Could Not Get Realm Using a Perl Script (54465)
7.7 AgentTLI Failed in memcpy() Method Called from CSmSerializable::Serialize (53299) (53206)
7.8 SmPolicyApi Methods getRealmRealms and getRealmRules Were Not Working Properly (47895)
7.9 SmPolicyApiImpl.doExport() Corrupted UNICODE Characters (52969)
7.10 C++ Comments in the Code Were Not Compatible with Some C Compilers (52130) (52048)
7.11 The Java Policy Management API Did Not Contain Functions to Search for User Groups and User Attributes (52769)
7.12 No Validation For Invalid IP Address When Calling SmPolicy.setIPRestriction (48918)
7.13 Passing a Null SessionDef to the Java Agent API authorize() Method Caused the JVM to Crash (48962)
7.14 SmPolicy.getIPRestriction() Did Not Return All Restrictions (51509)
7.15 Custom Code Calling user.addToGroup() Caused smpolicysrv to Fail (48023)
7.16 SmPolicyApi.getPolicyLinks() Triggered a Full Policy Store Cache Refresh (48122)
7.17 SmPolicyApi.getUserDirSearchOrder() Returned Oids Instead of Names (48221)
8.0 Fixes in SiteMinder SDK v6.0 SP 4
8.1 Speed Increased for Fetching Domain Objects (47124)
8.2 Java Logger Class Is Added to the Standard Installation (47077)
8.3 Data that the Web Agent SDK 6.0 on Linux Sends to the Policy Server Is Fixed (44051)
8.4 Sm_Api_Reason_MaxDefined Is Updated (45062)
8.5 An Error Code Is No Longer Returned When Calling GetHostConfig (46531)
8.6 Return Code SM_AGENTAPI_UNRESOLVED Is Available (46536)
9.0 Fixes in SiteMinder SDK v6.0 SP 3
9.1 Update to search( ) Method (43246)
9.2 Update to getGlobalObjectNames() Method (42993)
9.3 Modified Linkage of Agent API Library on Solaris (41741, 41586)
9.4 Password Changes through API Validated (43063, 41644)
9.5 Two Additional Policy API Methods Supported in a Custom Authentication Scheme (41008, 40306)
10.0 Fixes in SiteMinder SDK v6.0 SP 2
10.1 Policy Server Authentication Service Calling Policy API Init and Release Functions (33966, 31579)
10.2 Updated Java API Method AgentApi.init() (38813)
11.0 Fixes in SiteMinder SDK v6.0 SP 1
11.1 AgentAPI.login() Method No Longer Crashes the Java Server When Incorrect Parameters are Passed (7517)
11.2 Sm_AgentApi_UpdateAttributes() Now Recalculates Active Responses that Originally Had No Data (C) (30912)
12.0 Fixes in SiteMinder SDK v6.0
12.1 Missing C Password Message IDs (25854)
14.0 Documentation
14.1 Java API Documentation
14.2 The Documentation Index
14.3 SiteMinder Integrated Documents
15.0 Contact Technical Support
Welcome to the CA eTrust SiteMinder SDK. This document contains information about platform support, software requirements, installation, known issues, published fixes, and how to contact Technical Support.
To learn about operating system support for the SDK, search the Platform Support Matrices on the Technical Support site.
The SDK platform support matrix is typically included with the SiteMinder general support matrix. Search for the SiteMinder Platform Matrix for 6.0. Note that some platforms in previous releases might possibly no longer be supported.
Ensure that you have the required JRE version installed. For the required version, search for the SiteMinder Platform Matrix for 6.0 on the Technical Support site. You can download the latest JRE version from the Sun Developer Network SDN.
SiteMinder SDK v6.0 SP 5 supports Policy Server v6.0, v6.0 SP 1, v6.0 SP 2, v6.0 SP 3, v6.0 SP 4, and r6.0 SP 5. Applications developed with SDK r6.0 SP 5 cannot be run against Policy Server versions prior to v6.0.
Applications developed with a previous version of the SDK and that worked with the SiteMinder Policy Server v5.0 and v5.5 will continue to work with the Policy Server v6.0, v6.0 SP 1, v6.0 SP 2, v6.0 SP 3, v6.0 SP 4, and r6.0 SP 5.
This section includes instructions for installing and uninstalling both the SiteMinder SDK and the SDK documentation.
No special accounts or privileges are required to install the SiteMinder SDK. Instructions for installing a first version of the SDK and upgrading from an existing version are the same.
Do not install the SiteMinder SDK in the installation path where the Policy Server or Web Agent is installed, because there might be different versions of the same support libraries.
On UNIX, the installation file is nete-sdk-6.0-sp5-platform.bin—for example, nete-sdk-6.0-sp5-sol.bin on Solaris platforms. You can install the SDK in GUI mode or console mode.
To Install the SDK in UNIX GUI Mode
sh ./nete-sdk-6.0-sp5-<UNIX_version>.bin
Replace <UNIX_version> with sol, aix, linux, or hp.
For example, on Solaris platforms, the command is:
sh ./nete-sdk-6.0-sp5-sol.bin
To Install the SDK in UNIX Console Mode
sh ./nete-sdk-6.0-sp5-<UNIX_version>.bin -i console
Replace <UNIX_version> with sol, aix, linux, or hp.
For example, on Solaris platforms, the command is:
sh ./nete-sdk-6.0-sp5-sol.bin -i console
To install the SDK on Windows
nete-sdk-6.0-sp5-win32.exe
To uninstall the SiteMinder SDK from the UNIX console
/export/netegrity/sdk/install_config_info/nete-sdk-uninstall
./uninstall -i console
Note: When you are uninstalling the SDK in UNIX, make sure the JRE is in the PATH variable. If the JRE is not in the PATH variable, the following error occurs:
No Java virtual machine could be found from your PATH environment variable. You must install a VM prior to running this program.
To set the JRE in your PATH, run the following two commands:
For example: PATH=$PATH:/usr/bin/jdk141/jre/bin
To uninstall the SiteMinder SDK from Windows:
You install the SDK documentation separately from the SDK software. The documentation installation program installs the SDK documentation and documentation for the SiteMinder product. By default, SDK and SiteMinder documents are installed in the following location:
Note: If you have problems with links in the PDF documents, be sure you are using Adobe Reader as the viewer, not Adobe Acrobat.
On UNIX, the installation file is nete-sm-doc-6.0-sp5-platform.bin—for example, nete-sm-doc-6.0-sp5-sol.bin on Solaris platforms. You can install the documentation in GUI mode or console mode.
To install the documentation in UNIX GUI mode
sh ./nete-sm-doc-6.0-sp5-<UNIX_version>.bin
Replace <UNIX_version> with sol, aix, linux, or hp.
For example, on Solaris platforms, the command is:
sh ./nete-sm-doc-6.0-sp5-sol.bin
To install the documentation in UNIX Console Mode
sh ./nete-sm-doc-6.0-sp5<UNIX_version>.bin -i console
Replace <UNIX_version> with sol, aix, linux, or hp.
For example, on Solaris platforms, the command is:
sh ./nete-sm-doc-6.0-sp5-sol.bin -i console
To install the documentation on Windows
nete-sm-doc-6.0-sp4-win32.exe
To uninstall the SDK and Policy Server documentation from the UNIX console
/export/netegrity/netegrity_documents/install_config_info/nete-sm-doc-uninstall
./uninstall -i console
To uninstall the SDK and Policy Server documentation from Windows
This section contains miscellaneous information about this release.
Significant changes to the Policy Management API occurred beginning with SiteMinder v4.5—for example, the introduction of the OID as an object's unique identifier, and the addition of functions such as Sm_PolicyApi_Init() and Sm_PolicyApi_Release().
Developers who continue to use Policy Management APIs from a release prior to SiteMinder v4.5 should refer to the documentation that accompanied the earlier release. Further:
When enabled with single sign-on support, custom agents can accept the SMSESSION single sign-on cookie that is created by a standard SiteMinder v4.x, v5.x, or v6.x Web Agent.
To accept an SMSESSION cookie created by a custom agent, the standard agent must be upgraded to at least:
| QMR | Supported SiteMinder Agent |
|---|---|
| 4.xQMR4 | SiteMinder v4.x agents |
| 5.xQMR1 | SiteMinder v5.x and v6.x agents |
To enable a SiteMinder v4.x, v5.x, or v6.x standard agent with the appropriate QMR upgrade to accept SMSESSION cookies created by a custom agent, the standard agent's Agent configuration file (LocalConfig.conf with IIS servers or WebAgent.conf with other servers) or central configuration object (for v5.x or higher) must contain the following entry:
AcceptTPCookie="yes"
Set AcceptTPCookie as follows:
When you build a custom agent with SDK v6.0 SP 5, you must run the custom agent only against v6.0, v6.0 SP 1, v6.0 SP 2, v6.0 SP 3, V6.0 SP 4, or r6.0 SP 5 Policy Servers.
Agents built with the SiteMinder Agent API from SDK 5.5 can be used with SiteMinder Policy Servers v5.x, v6.0, v6.0 SP 1, v6.0 SP 2, v6.0 SP3, v6.0 SP 4, and r6.0 SP 5.
Beginning with SiteMinder v5.5 SP 1, the Policy Server is integrated with the iPlanet Directory SDK for C 5.08 (5.08 LDAP SDK). If your custom code had been linked with the older version of the LDAP SDK, you may need to re-link with the new SDK.
This section describes the known software limitations in the SiteMinder SDK v6.0 SP 5. Where applicable, defect tracking numbers appear in parentheses at the end of the defect heading.
Before you install a custom agent created with the Agent API on an HP-UX machine, install the following HP patch on the agent machine:
PHSS_24303 Id & linker tools cumulative patch
This patch is available at the HP web site.
Building the smpolicyapi sample program on Unix/Linux systems requires access to several Policy Server shared libraries and the NETE_PS_ROOT environment variable set to point to them. This may be accomplished by installing the Policy Server on the system with the SDK and using nete_ps_env.ksh to set the environment.
Hierarchical realms are not supported in the Java Policy Management API for the SDK r6.0 SP 2 release.
If a given resource is defined in different realms of the same domain, and the resource is protected by the same agent, unpredictable behavior can result.
SiteMinder does not prevent you from setting up a situation such as the following:
This situation can occur when adding and/or modifying a realm.
Workaround: The sample application PolicyApiSample.java contains a method named checkRealmResourceFilter() that checks for this situation. You can copy the method and use it in your Java applications, or use it as a model for your C applications.
The Java class com.netegrity.sdk.policyapi.SmPasswordPolicy is missing the following constants:
| Constant Name | Constant Value |
|---|---|
| Sm_PasswordPolicy_StopPriorityChaining | 0x00000080 |
| Sm_PasswordPolicy_ExpireDisablePassword | 0x00000100 |
| Sm_PasswordPolicy_FailuresDisablePassword | 0x00000200 |
| Sm_PasswordPolicy_ForceCase | 0x00000400 |
| Sm_PasswordPolicy_CaseSelect | 0x00000800 |
| Sm_PasswordPolicy_CaseBits | 0x00000c00 |
| Sm_PasswordPolicy_StripLeadingWhiteSpace | 0x00001000 |
| Sm_PasswordPolicy_StripTrailingWhiteSpace | 0x00002000 |
| Sm_PasswordPolicy_StripFlankingWhiteSpace | 0x00003000 |
| Sm_PasswordPolicy_StripEmbeddedWhiteSpace | 0x00004000 |
| Sm_PasswordPolicy_WhiteSpaceBits | 0x00007000 |
| Sm_PasswordPolicy_PreProcessBits | 0x00007c00 |
Workaround: If you need to set these values, use the literal values directly instead of referencing the constant name.
When decodeSSOToken() returns, each attribute (byte array) returned in the AttributeList parameter is terminated with a space character.
Workaround: Before you use the session specification and session id attributes in a login() call to validate the session, trim the terminating space from each byte array.
If the Java AgentAPI.getConfig() method is used to read the configuration file, it creates an InitDef object having one more ServerDef object than is actually present. The extra object does not point to any Policy Server and is just an empty object.
In package com.netegrity.sdk.policyapi, the method PolicyApiImpl.search() returns an empty list when the object type to search for is type Domain, even if valid search parameters are given.
In the Java DMS API, any call (such as search(), getGroups(), and getMembers() ) that uses an SmDmsCursor object with an empty sort order will fail.
Password validation error IDs are reported in the nMsgId parameter of Sm_PolicyApi_GetPasswordMsg(). Specific error IDs are enumerated in Sm_PolicyApi_PasswordMsgId_t. Any error ID that is not enumerated in Sm_PolicyApi_PasswordMsgId_t should be considered a general password validation error. General password validation error IDs are reported in nMsgId when Sm_PolicyApi_GetPasswordMsg() returns -38.
An ACE HTML Forms authentication scheme that returns any of the following access event reason codes (Sm_Api_Reason_t) must have the redirect URL as the last element of the authentication scheme's parameter list:
A semicolon (;) separates the URL from the first part of the parameter list.
To avoid a core dump, applications built with the Policy management API must not link with internal Policy Server libraries, for example, libsmutilities.so. This restriction does not apply to libraries libsmpolicyapi45.so and libsmplatform.so.
In the Java class AgentAPI, the method getConfig() fails because it cannot locate the specified agent. This error only occurs on Windows platforms.
The pure Java Agent API isProtected method now sets realmdef members to null for unprotected resources.
The pure Java method Agent API login now accepts a null or '''' value for the clientIP parameter.
The Java Policy Management API method authenticateUser() now properly returns the user's authentication status.
The Agent API method connect() returns the correct status (SM_AGENTAPI_FAILURE) when connection to policy server is not successful.
The Java Policy Management API function SmTrustedHost.writeProperties(hash) now properly handles null pointers.
Domain Scope user can now successfully call function GetRealm() in Perl. This behavior is now in synch with that available through the Siteminder Admin UI.
Add additional length checking for strings passed to the Java API to ensure that overly long strings do not crash the TLI layer. If a string longer than the maximum permitted length is passed in, an error is returned.
The Java Policy Management API method getRealmRealms() now returns only the realms under the specified realm instead of all realms under the given domain. Similarly, the method getRealmRules will now return only the rules under the specified realm instead of all rules under all realms under the given domain.
The Java API functions doExport() and doImport() now properly handle UTF-8 encoding of data.
Replaced C++ style comments with C style comments in the C API header files SmApi.h and SmAgentAPI.h to eliminate problems when they are compiled by a C compiler that does not support C++ style comments.
Added capabilities to the Java Policy Management API to return user groups and user attributes.
An exception is thrown when an invalid IP address is set for com.netegrity.sdk.policyapi.SmPolicy.setIPRestriction (java.util.Vector ipRestriction) provided by the Java SDK. This validation check will prevent the policy from being rendered non-editable in the admin GUI due to an invalid IP address passed in custom code.
Passing a null SessionDef to the Java AgentAPI authorize() method no longer causes the JVM to crash.
The Java Policy Management method SmPolicy.getIPRestriction() now properly returns all IP restrictions for a SiteMinder policy.
Custom code calling user.addToGroup() no longer causes smpolicysrv to fail.
Performance has been improved by ensuring that Java API function SmPolicyApi.getPolicyLinks() does not unnecessarily trigger a full policy store cache refresh.
Fixed an issue with the Java Policy Management SDK returning OID strings instead of object names for some methods. The corrected behavior is to return OID strings only for SiteMinder objects that cannot be identified by name (that is, certificate and directory mappings).
A problem in the Policy Server domain property fetch code has been fixed, which means that the performance of the Java Policy Server API v6.x is comparable to the performance of the Java Policy Server API 4.x.
The Java sample application Active Response failed to build. This was a kitting issue and has been resolved.
In the call to SmAgentApiInit(), the send() function was transmitting corrupt data to the Policy Server. The client saw a security handshake error. This issue has been corrected.
Sm_Api_Reason_MaxDefined has been updated in SmAgentApi.h to reflect additional reason codes for federation.
The call to GetHostConfig() failed when it passed a host config object name. It was always successful when it passed in the OID of the host config object. Now the call is successful passing either parameter.
This return code is now listed in SmAgentApi.h.
In the Java Policy Management API, the search() method of the class SmPolicyApiImpl now finds the Domain, Agent Config and Host Config objects as expected. Earlier the search() API failed for these objects.
In the Java Policy Management API, the getGlobalObjectNames() method of the SmPolicyApiImpl class now returns the list of Agent or Host configuration objects as required if the property is set as SmAgentConfig.PropAgentConfigs or SmHostConfig.PropHostConfigs.
This fix to the SiteMinder Agent API modifies the linkage for the Agent API shared library on the Solaris platform to be self-contained with respect to other third-party libraries used in the same process.
The policy server has been fixed to ensure that any password changes performed through the DMS API are validated to conform to policy restrictions set through the Admin UI.
The policy server authentication service now supports calling the Policy API initialization Sm_PolicyApi_Init() and Policy API release Sm_PolicyApi_Release() methods inside the respective hook functions SmAuthInit() and SmAuthRelease() in a custom authentication scheme.
The Policy Server authentication service now accommodates calling the Policy Management API Sm_PolicyApi_Init() and Sm_PolicyApi_Release() functions at any location inside a custom authentication scheme.
The Java-based API method AgentApi.init() is corrected to accommodate conditions when a null ServerDef object is added to an InitDef object that is used as a parameter to the init() method.
This crash used to occur when the spec field of the SessionDef object was null and the UserCredentials object was empty.
In the past, this C function would not recalculate an active response that initially held no data (that is, the active response attribute was 0 or null). Now, an active response attribute is considered valid if its return value has a non-zero length or its TTL value is set.
The following password message IDs are now enumerated in Sm_PolicyApi_PasswordMsgId_t:
An internationalized product is an English product that runs correctly on local language versions of the required operating system and required third-party products, and supports local language data for input and output. Internationalized products also support the ability to specify local language conventions for date, time, currency and number formats.
A translated product (sometimes referred to as a localized product) is an internationalized product that includes local language support for the product's user interface, online help and other documentation, as well as local language default settings for date, time, currency, and number formats.
In addition to the English release of this product, CA supports only those languages listed in the following table.
| Language | Internationalized | Translated |
|---|---|---|
| Brazilian-Portuguese | Yes | No |
| Chinese (Simplified) | Yes | No |
| Chinese (Traditional) | Yes | No |
| Czech | Yes | No |
| Danish | Yes | No |
| Dutch | Yes | No |
| Finnish | Yes | No |
| French | Yes | No |
| German | Yes | No |
| Greek | Yes | No |
| Hungarian | Yes | No |
| Italian | Yes | No |
| Japanese | Yes | No |
| Korean | Yes | No |
| Norwegian | Yes | No |
| Polish | Yes | No |
| Russian | Yes | No |
| Spanish | Yes | No |
| Swedish | Yes | No |
| Turkish | Yes | No |
Note: If you run the product in a language environment not listed in the table, you may experience problems.
The file names for the SiteMinder 6.0 SP 5/6.x QMR 5 guides are as follows:
| Guide Name | File Name |
|---|---|
| SiteMinder Release Summary | siteminder_release_enu.pdf |
| Developer's Reference for Java | siteminder_java_dev_enu.zip |
| Developer's Guide for Java | siteminder_java_dev_enu.pdf |
| Developer's Guide for C | siteminder_c_dev_enu.pdf |
| Federation Security Services Guide | siteminder_fs_config_enu.pdf |
| Policy Server Installation Guide | siteminder_ps_install_enu.pdf |
| Policy Design Guide | siteminder_ps_config_enu.pdf |
| Policy Server Management | siteminder_ps_sysmgmt_enu.pdf |
| Policy Server Readme | readme-policy-server.html |
| Policy Server, Web Agent Option Pack Readme | readme-option-packs.html |
| Scripting Guide for Perl | siteminder_perl_scripting_enu.pdf |
| SDK Overview | siteminder_sdk_overview_enu.pdf |
| SDK Readme | readme-sdk.html |
| SAML Affiliate Agent Guide | siteminder_saa_config_enu.pdf |
| SAML Affiliate Agent Readme | readme-saml-affiliate-agent.html |
| SiteMinder Upgrade Guide | siteminder_upgrade_enu.pdf |
| SiteMinder Integrated Documents | siteminder_integdocs_ref.enu.zip |
| Tier II Directory Configuration Guide | siteminder_dir_config_enu.pdf |
| Web Agent Guide | siteminder_wa_config_enu.pdf |
| Web Agent Installation Guide | siteminder_wa_install_enu.pdf |
| Web Agent Readme | readme-web-agent.html |
To view PDF files, you must download and install the Adobe Reader from the Adobe website if it is not already installed on your computer.
Updated guides will be available at the CA Technical Support site.
Open the Java API documentation through:
netegrity_documents\javadoc\index.html
The integrated HTML version of the CA eTrust SiteMinder Developer's Reference includes two parts:
The integrated CA eTrust SiteMinder Developer's Reference also includes hyperlinks between the Javadoc Reference and the Developer's Guide where necessary to cross-reference relevant information.
Note: The PDF version of the CA eTrust Developer's Guide for Java does not include the Javadoc Reference information.
All documentation in the netegrity_documents directory can be opened through the documentation index file doc_index.htm. This file is located in netegrity_documents. Normally, the Policy Server GUI Help uses this file to access the installed documentation.
If there are .PDF-format guides in the netegrity_documents directory whose titles do not appear in the documentation index file, run the executable file getdocs.exe (Windows systems) or getdocs (UNIX systems). This file is also located in netegrity_documents.
The program ends immediately after starting, with no visual cue of completion. Open doc_index.htm again. All PDF documents should now be listed.
Integrated Documents lets you access all of the SiteMinder documentation from a central location. Viewing Integrated Documents requires an Internet browser.
Integrated Documents includes a:
For online technical assistance and a complete list of locations, primary service hours, and telephone numbers, contact Technical Support at http://ca.com/support.