Sm_PolicyApi_AddTrustedHost()

Programming Guides › Programming Guide for C › Policy Management API Guidance › Function Declarations for the Policy Management API › Sm_PolicyApi_AddTrustedHost()

Sm_PolicyApi_AddTrustedHost()

Creates or modifies a trusted host object in the object store.

Use this function to register the trusted host "offline"-that is, without a connection between the agent and the Policy Server. When you use this function, you must run the SiteMinder smreghost tool to define the shared secret in the host configuration file (default name SmHost.conf). You define the shared secret with the -sh option of the smreghost tool.

Type

Agent configuration function, global scope.

Syntax

int SM_EXTERN Sm_PolicyApi_AddTrustedHost (
     void*                            pSessionHandle,
     Sm_PolicyApi_TrustedHost_t*      pstructTrustedHost,
     bool                             bUpdate,
     bool                             bGenSharedSecret
);

Parameter	I/O	Description
pSessionHandle	I	Specifies the identifier of the session.
pstructTrustedHost	I/O	The address of a structure of type Sm_PolicyApi_TrustedHost_t. The structure is filled by a caller prior to a function call.
bUpdate	I	Specifies whether the function was called to update the existing object in the object store.
bGenSharedSecret	I	Indicates whether to generate the shared secret.

Remarks

If bGenSharedSecret is true, the function generates a 128-byte value and updates the pszSecret field of pstructTrustedHost. If bGenSharedSecret is false, the value of the shared secret for a new or updated trusted host object is taken from the pszSecret field of the pstructTrustedHost structure.

If both bGenSharedSecret and bUpdate are true, the function ignores the value specified in the pszSecret field of pstructTrustedHost, generates a new value, and updates the object in the object store and in the pszSecret field of pstructTrustedHost.

If the function generates the shared secret, you must retrieve the generated shared secret in clear text so that you can define it in the -sh option of the smreghost tool. To retrieve the shared secret, call Sm_PolicyApi_GetTrustedHost().

In past releases, agent registration with the Policy Server always used 128-byte random ASCII shared secrets. The new model makes it possible to use a user-defined string value as a shared secret. This is a potential security weakness. The administrator who chooses offline agent host configuration must create a strong shared secret and store it safely. It is strongly recommended that you call the function Sm_PolicyApi_AddTrustedHost() with the bGenSharedSecret parameter set to true. This enforces automatic generation of a hard-to-guess shared secret.

Use of this function is not required to either create a trusted host or to define the host configuration. SiteMinder automatically creates and configures the trusted host during installation, and also when you run smreghost without using the -sh option.

Returns

Sm_PolicyApi_Success. The trusted host object was created or modified.
Sm_PolicyApi_Failure. Generalized failure.
Sm_PolicyApi_InvalidOid. The unique ID does not correspond to a Trusted Host object.
Sm_PolicyApi_NoPrivilege. The caller does not have the proper privileges to add or modify a trusted host object.
Sm_PolicyApi_InvalidHandle. The session pointer is not valid.
Sm_PolicyApi_NotUnique. The shared secret already exists.
Sm_PolicyApi_NoSession. The API user is not properly logged in.
Sm_PolicyApi_InvalidProp. Invalid shared secret value specified.
Sm_PolicyApi_GenSharedSecretFailure. Failed to generate a 128‑byte shared secret value.