Chapter 6 Policy Functions

This chapter provides a reference to the public functions for using Sun Java^TM System Access Manager 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:

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:

policy

Opaque handle to the policy service to destroy.

Returns

This function returns am_status_t with one of the following values:

AM_SUCCESS

If the call was successful.

AM_*

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

Details

This function destroys a policy service instance. Memory Concerns: Caller must call make sure the same service instance not be destroyed more than once.

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:

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:

AM_SUCCESS

If the call was successful.

AM_*

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

Details

This function destroys a policy service instance. Memory Concerns: After using the results the caller must call am_policy_result_destroy on the policy_result to cleanup the memory allocated by the evaluation operation. am_map_destroy must also be called on response and env_parameter_map after their respective usage scope.

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:

AM_TRUE

Successful root extraction.

AM_FALSE

Otherwise

Details

This function is takes a URL and extracts a root of the URL. For example, http://www.sun.com/index.html will return http://www.sun.com/ and http://www.sun.com:8080/index.html will return http://www.sun.com:8080/. Memory Concerns: In an implementation for a different resource other than URLs, the service writer implementing this function must make accurate judgement about the minimum size of resourceRoot.

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:

properties

The properties to initialize the policy service with.

Returns

This function returns am_status_t with one of the following values:

AM_SUCCESS

If the call was successful.

AM_*

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

Details

This function initializes a policy service instance. Memory Concerns: Caller must call am_policy_destroy structure or free the memory.

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:

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:

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:

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:

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:

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().

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 parameter:

resource_name

Name of the resource.

Returns

This function returns boolean_t with one of the following values:

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:

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:

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:

AM_SUCCESS

If the call was successful.

AM_*

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