Sm_PolicyApi_AddTrustedHost()

Creates or modifies a trusted host object in the object store.
casso126
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
CA Single Sign-On
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 andupdates 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 generatedshared secret in clear text so that you can define it in the -sh optionof 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.
CA Single Sign-On
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.