Chapter 5 Policy Functions

Previous Contents Next
Sun Java System Access Manager 2005Q1 Developer's Reference

Chapter 5
Policy Functions

This chapter provides a reference to the public functions for using Sun Java™ System Access Manager 6 2005Q1 Access Management SDK policy objects. Function summaries include a short description, syntax, parameters and returns.

The following functions are contained in the header file am_policy.h.

am_policy_compare_urls()

am_policy_destroy()

am_policy_evaluate()

am_policy_get_url_resource_root()

am_policy_init()

am_policy_is_notification_enabled()

am_policy_notify()

am_policy_resource_canonicalize()

am_policy_resource_has_patterns()

am_policy_result_destroy()

am_policy_service_init()

am_policy_compare_urls()

Takes two url resources compares theme, and returns an appropriate result.

Syntax

#include "am_policy.h"
AM_EXPORT am_resource_match_t
am_policy_compare_urls(const am_resource_traits_t *rsrc_traits,
     const char *policy_resource_name,
     const char *resource_name,
           boolean_t use_patterns);

Parameters

If the usePatterns is AM_TRUE, this function will consider occurrences of '*' in the policy resource name as wildcards. If usePatterns is AM_FALSE, '*' occurrences are taken as a literal characters.

Returns

This function returns am_resource_match_t with one of the following values:

Value

Description

EXACT_MATCH

If both the resource names exactly matched.

SUB_RESOURCE_MATCH

If the resourceName is a sub-resource to the resource name defined in the policy.

SUPER_RESOURCE_MATCH

If the resourcName is a ancestor of the policy resource name.

NO_MATCH

If the there is no kind of match between the policy resource and the requested resource name.

EXACT_PATTERN_MATCH

This result will be returned only if the policy is matches resource name. Distinction is not made whether it was a EXACT_MATCH or a pattern match.

Details

In cases of SUB/SUPER_RESOURCE_MATCH, if the usePatterns is * AM_TRUE, the patterns are sub/super matching patterns.

am_policy_destroy()

Frees an initialized policy evaluator.

Syntax

#include "am_policy.h"
AM_EXPORT am_status_t
am_policy_destroy(am_policy_t policy);

Parameters

This function takes the following parameters:

Parameter

Description

policy

Opaque handle to the policy service to destroy.

Returns

This function returns am_status_t with one of the following values:

Value

Description

AM_SUCCESS

If the call was successful.

AM_*

If any error occurs, the type of error indicated by the status value.

am_policy_evaluate()

Evaluates a policy for a given resource and returns the policy result.

Syntax

#include "am_policy.h"
AM_EXPORT am_status_t
am_policy_evaluate(am_policy_t policy_handle,
     const char *sso_token,
     const char *resource_name,
     const char *action_name,
     const am_map_t env_parameter_map,
     am_map_t policy_response_map_ptr,
          am_policy_result_t *policy_result);

Parameters

This function takes the following parameters:

Parameter

Description

policy_handle

Opaque handle to the policy service created by policy_service_init.

sso_token

User's SSO token to be used for evaluation.

resource_name

Name of resource to evaluate.

action_name

User's access action, such as GET or POST.

env_parameter_map

Any environment variables to be used for evaluation.

policy_response_map_ptr

Map to store user attributes from the policy evaluation call.

policy_result

Evaluation results.

Returns

This function returns am_status_t with one of the following values:

Value

Description

AM_SUCCESS

If the call was successful.

AM_*

If any error occurs, the type of error indicated by the status value.

am_policy_get_url_resource_root()

Populates the pointer resourceRoot with the resource root.

Syntax

#include "am_policy.h"
AM_EXPORT boolean_t
am_policy_get_url_resource_root(const char *resource_name,
         char *resource_root, size_t length);

Parameters

This function takes a URL resource name.

Returns

This function returns boolean_t with one of the following values:

Value

Description

AM_TRUE

Successful root extraction.

AM_FALSE

Otherwise

am_policy_init()

Initializes the policy evaluation engine.

Syntax

#include "am_policy.h"
AM_EXPORT am_status_t
am_policy_init(am_properties_t policy_config_properties);

Parameters

This function takes the following parameters:

Parameter

Description

properties

The properties to initialize the policy service with.

Returns

This function returns am_status_t with one of the following values:

Value

Description

AM_SUCCESS

If the call was successful.

AM_*

If any error occurs, the type of error indicated by the status value.

am_policy_is_notification_enabled()

Checks if notification is enabled in the SDK.

Syntax

#include "am_policy.h"
AM_EXPORT boolean_t
am_policy_is_notification_enabled(am_policy_t policy_handle);

Parameters

This function takes the following parameters:

Parameter

Description

policy_handle

The opaque policy service handle created from am_policy_service_init().

Returns

This function returns boolean_t with one of the following values:

Value

Description

0

If notification is disabled.

non-zero

If notification is enabled.

am_policy_notify()

Refreshes policy cache when a policy notification is received by the client.

Syntax

#include "am_policy.h"
AM_EXPORT am_status_t
am_policy_notify(am_policy_t policy_handle,
     const char *notification_data,
     size_t notification_data_len);

Parameters

This function takes the following parameters:

Parameter

Description

policy_handle

Opaque handle to the policy service

notification_data

The notification message as an XML String.

notification_data_len

Length of the notification data.

Returns

This function returns am_status_t with one of the following values:

Value

Description

AM_SUCCESS

If the call was successful.

AM_*

If any error occurs, the type of error indicated by the status value.

am_policy_resource_canonicalize()

Canonicalize the given resource name.Syntax

#include "am_policy.h"
AM_EXPORT void
am_policy_resource_canonicalize(const char *resource, char **c_resource);

Parameters

This function takes the following parameters:

Parameter

Description

resource

Name of resource to be canonicalized

c_resource

Pointer to location where the canonicalized string will be placed.

the value returned should be freed using free().

Returns

None

am_policy_resource_has_patterns()

Returns whether the given resource name has patterns such as '*'.Syntax

#include "am_policy.h"
AM_EXPORT boolean_t
am_policy_resource_has_patterns(const char *resource_name);

Parameters

This function takes the following parameters:

Parameter

Description

resource_name

Name of the resource.

Returns

This function returns boolean_t with one of the following values:

Value

Description

true

If the resource has patterns.

false

Otherwise.

am_policy_result_destroy()

Destroys am_policy_result internal structures.

Syntax

#include "am_policy.h"
AM_EXPORT void
am_policy_result_destroy(am_policy_result_t *result);

Parameters

This function takes the following parameters:

Parameter

Description

result

The policy result to be destroyed.

Returns

None

am_policy_service_init()

Initializes one specific instance of service for policy evaluation.

Syntax

#include "am_policy.h"
AM_EXPORT am_status_t
am_policy_service_init(const char *service_name,
     const char *instance_name,
     am_resource_traits_t rsrc_traits,
     am_properties_t service_config_properties,
         am_policy_t *policy_handle_ptr);

Parameters

This function takes the following parameters:

Parameter

Description

service_name

A name for the policy service.

instance_name

A name for the policy service instance.

rsrc_traits

Resource traits - see description of am_resource_traits_t in the structure section for more information.

service_config_properties

The properties to initialize the policy service with.

policy_handle_ptr

Handle to the policy service created.

Returns

This function returns am_status_t with one of the following values:

Value

Description

AM_SUCCESS

If the call was successful.

AM_*

If any error occurs, the type of error indicated by the status value.

Previous      Contents      Next

Copyright 2005 Sun Microsystems, Inc. All rights reserved.

Value	Description
EXACT_MATCH	If both the resource names exactly matched.
SUB_RESOURCE_MATCH	If the resourceName is a sub-resource to the resource name defined in the policy.
SUPER_RESOURCE_MATCH	If the resourcName is a ancestor of the policy resource name.
NO_MATCH	If the there is no kind of match between the policy resource and the requested resource name.
EXACT_PATTERN_MATCH	This result will be returned only if the policy is matches resource name. Distinction is not made whether it was a EXACT_MATCH or a pattern match.

Parameter	Description
policy	Opaque handle to the policy service to destroy.

Value	Description
AM_SUCCESS	If the call was successful.
AM_*	If any error occurs, the type of error indicated by the status value.

Parameter	Description
policy_handle	Opaque handle to the policy service created by policy_service_init.
sso_token	User's SSO token to be used for evaluation.
resource_name	Name of resource to evaluate.
action_name	User's access action, such as GET or POST.
env_parameter_map	Any environment variables to be used for evaluation.
policy_response_map_ptr	Map to store user attributes from the policy evaluation call.
policy_result	Evaluation results.

Value	Description
AM_TRUE	Successful root extraction.
AM_FALSE	Otherwise

Parameter	Description
properties	The properties to initialize the policy service with.

Value	Description
0	If notification is disabled.
non-zero	If notification is enabled.

Parameter	Description
resource	Name of resource to be canonicalized
c_resource	Pointer to location where the canonicalized string will be placed. the value returned should be freed using free().

Value	Description
true	If the resource has patterns.
false	Otherwise.

Parameter	Description
result	The policy result to be destroyed.

Parameter	Description
service_name	A name for the policy service.
instance_name	A name for the policy service instance.
rsrc_traits	Resource traits - see description of am_resource_traits_t in the structure section for more information.
service_config_properties	The properties to initialize the policy service with.
policy_handle_ptr	Handle to the policy service created.