Sun Java System Access Manager 7.1 C API Reference

Chapter 3 Policy Data Types and Functions

Sun™ Java System Access Manager contains public data types and functions you can use to communicate with the Policy Service. Reference summaries include a short description, syntax, parameters and returns. The code is contained in the <am_policy.h> header file (located in the /AccessManager-base/SUNWam/include directory). The sample source am_policy_test.c (located in the /AccessManager-base/SUNWam/samples/csdk directory) demonstrates the basic usage of the policy API. This chapter contains the following sections:

The Policy API for C

Access Manager provides policy APIs for use by developers to integrate a resource authorization functionality within their external C applications. The policy API for C determines if a user has been given permission by a recognized authority to access a particular protected resource. The result of the policy evaluation is called an action value and may be boolean or binary.

A boolean action value might be allow/deny or yes/no.
A binary action value might be, for example, a mailbox quota. Assuming John Smith can only hold 100 MB of email in his mailbox, the value 100 would be the action value.

Tip –
As policy evaluation results in string values only, the policy evaluation returned is 100 numeric and not 100 MB. It is up to the application developer to define the appropriate metric for the values.

Resources Strings

The Policy API for C mandates that any resource be represented in a string format. Thus, resources on a web server must be represented as URLs. The Policy Service is then able to compare the resource string to the policy string and determine a relative relationship between the two. This relationship will be defined as one of the following:

exact match
no match
subordinate match
superior match
exact pattern match

Note –
Exact pattern match is a special case where resources may be represented collectively as patterns. The information is abstracted from the Policy Service and the comparison operation must take a boolean parameter to trigger a pattern matched comparison. During the caching of policy information, the policy engine does not care about patterns, whereas during policy evaluation, the comparisons are pattern sensitive.

Resource Traits

The set of characteristics needed to define a resource is called a resource trait. Resource traits are taken as a parameter during service initialization in the am_resource_traits_t. Using the resource traits, the Policy Service constructs a resource graph for policy evaluation in which the relation between all resources in the system spans out like a tree from the root of the given resource. Thus, the service developer must provide the means to extract the root of the given resource. In a URL, the protocol://Access Manager-host.domain:port portion represents the root.

Policy Evaluation

The two typedef structures that are used for information exchange to and from the policy evaluation interfaces are:

am_map_t provides a key to multiple key/value mapping. If the evaluation requires certain environment parameters like the IP address of the requester, it may be passed using this structure. See am_map_t for more information.
am_properties_t provides a key to single value mapping. am_properties_t provides the additional functionality of loading a configuration file and getting values of specific data types. See am_properties_t for more information.

Policy Data Types

The types defined in <am_policy.h> are:

`am_policy_result_t`

Carries the evaluation results from the Policy Service.

Details

am_policy_result_t unifies various components of a policy evaluation including information regarding the user attempting to perform an action on the resource, advice messages as recommended during policy evaluation, if any, and attribute response maps providing specific key/values as set in policy definition or user entries.

Syntax

#include "am_policy.h"
typedef struct am_policy_result {
    const char *remote_user;
    const char *remote_user_passwd;
    const char *remote_IP;
    am_map_t advice_map;
    am_map_t attr_profile_map;
    am_map_t attr_session_map;
    am_map_t attr_response_map;
    const char *advice_string;
} am_policy_result_t;

Members

remote_user

Pointer to the user attempting access.

remote_user_passwd

Pointer to the password for the remote user.

remote_IP

Pointer to the IP address of the resource the user is attempting to access.

advice_map

Takes a value based on the am_map_t defined in the <am_map.h> header file that represents any advice messages that might have resulted from the policy evaluation.

Note –

For information on advices, see Policy Advices in Sun Java System Access Manager 7.1 Administration Guide.

attr_profile_map

Takes a value based on the am_map_t (defined in the <am_map.h> header file) that represents one or more user profile attributes and a corresponding value. This member is enabled when the following two properties in AMAgent.properties are configured:

com.sun.am.policy.agents.config.profile.attribute.fetch.mode takes a value of HTTP_HEADER or HTTP_COOKIE.
com.sun.am.policy.agents.config.profile.attribute.map takes a list of LDAP attributes and their mapped values in the format attribute_name|value.

attr_session_map

Takes a value based on the am_map_t (defined in the <am_map.h> header file) that represents one or more session attributes and a corresponding value. This member is enabled when the following two properties in AMAgent.properties are configured:

com.sun.am.policy.agents.config.session.attribute.fetch.mode takes a value of HTTP_HEADER or HTTP_COOKIE.
com.sun.am.policy.agents.config.session.attribute.map takes a list of session attributes and their mapped values in the format attribute_name|value.

attr_response_map

Takes a value based on the am_map_t (defined in the <am_map.h> header file) that represents one or more response attributes and a corresponding value. This member is enabled when the following two properties in AMAgent.properties are configured:

com.sun.am.policy.agents.config.response.attribute.fetch.mode takes a value of HTTP_HEADER or HTTP_COOKIE.
com.sun.am.policy.agents.config.response.attribute.map takes a list of response names and their mapped values in the format attribute_name|value.

advice_string

Pointer to a string that defines a value for further authentication if dictated by the policy condition.If no condition is specified, the advice string will have an empty value.

Memory Concerns

Memory for am_policy_result_t is allocated by am_policy_evaluate() and freed by am_policy_result_destroy().

`am_policy_t`

Declares an unsigned integer as a type for a policy object.

Syntax

#include "am_policy.h"
typedef unsigned int am_policy_t;

Members

am_policy_t has no members.

`am_resource_traits_t`

Contains the functions to return resource traits that will be used to compare with a user's defined policy and evaluate the access request.

Syntax

#include "am_policy.h"
typedef struct am_resource_traits {
    am_resource_match_t (*cmp_func_ptr)(const struct am_resource_traits *rsrc_traits,
                                        const char *policy_res_name,
                                        const char *resource_name,
                                        boolean_t use_patterns);
    boolean_t (*has_patterns)(const char *resource_name);
    boolean_t (*get_resource_root)(const char *resource_name,
                                   char *root_resource_name,
                                   size_t buflength);
    boolean_t ignore_case;
    char separator;
    void (*canonicalize)(const char *resource, char **c_resource);
    void (*str_free)(void *resource_str);
} am_resource_traits_t;

Members

cmp_func_ptr

Pointer to a function that compares policy_res_name and resource_name to return one of the following values of the am_resource_match_t enumeration (defined in the <am_policy.h> header file):

typedef enum am_resource_match {
    AM_SUB_RESOURCE_MATCH,
    AM_EXACT_MATCH,
    AM_SUPER_RESOURCE_MATCH,
    AM_NO_MATCH,
    AM_EXACT_PATTERN_MATCH
} am_resource_match_t;

Tip –

cmp_func_ptr can point to am_policy_compare_urls() to evaluate URL resources.

rsrc_traits: Pointer to the resource traits structure containing data regarding a policy.
policy_res_name: Pointer to the name of the resource being protected.
resource_name: Pointer to the name of the resource being requested.
use_patterns: Based on the boolean_t defined in the <am_types.h> header file, B_TRUE indicates that the function will use or recognize patterns when comparing resources.

has_patterns

Pointer to a function that determines whether a resource has patterns and returns one of the following values of the boolean_t enumeration defined in the <am_types.h> header file:

B_TRUE: If resource_name has patterns.
B_FALSE: Otherwise.

Tip –

has_patterns can point to am_policy_resource_has_patterns() for URL resources.

resource_name: Pointer to the name of the resource being requested.

get_resource_root

Pointer to a function that extracts the root of the specified resource and returns one of the following values of the boolean_t enumeration defined in the <am_types.h> header file:

B_TRUE: If the resource root was successfully inserted into the specified root_resource_name buffer.
B_FALSE: Otherwise.

Tip –

get_resource_root can point to am_policy_get_url_resource_root() for URL resources.

resource_name: Pointer to the name of the resource being requested.
root_resource_name: Buffer to hold the resource root.
buflength: Value based on the size_t defined in the standard <stddef.h> header file that reflects the length of the root_resource_name buffer.

ignore_case

Value that takes one of the following values of the boolean_t enumeration defined in the <am_types.h> header file:

B_TRUE: Ignore case for all functions in this structure.
B_FALSE: Otherwise.

separator

Defines the resource separator. For URLs / should be used.

canonicalize

Pointer to a function that converts the specified resource name into a standard representation for comparative purposes.

resource

Pointer to a resource name. This could be the resource being requested or the resource defined in the policy.

c_resource

Output of the canonical resource name.

Note –

Memory for the canonical name must be allocated by the caller. A function to free the allocated memory must be set in str_free.

str_free

Pointer to a function to free a c_resource string after the results have been evaluated by am_policy_evaluate(). This field cannot be set to NULL.

Note –

free() should be used if canonicalize is set to the am_policy_resource_canonicalize() function.

resource_str: Pointer to the string returned in the canonicalize function.

Policy Functions

The functions defined in <am_policy.h> are:

`am_policy_compare_urls()`

Compares the URLs of two resources, and returns the 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

This function takes the following parameter:

rsrc_traits

Pointer to a am_resource_traits_t type containing data regarding a policy.

Note –

See am_resource_traits_t for more information.

policy_resource_name

Pointer to the name of the resource being protected.

resource_name

Pointer to the name of the resource being requested.

use_patterns

Based on the boolean_t defined in the <am_types.h> header file, B_TRUE indicates that the function will consider occurrences of * in policy_resource_name as wild cards. If B_FALSE, occurrences of * are taken as a literal characters.

Note –

In cases of SUB_RESOURCE_MATCH and SUPER_RESOURCE_MATCH when usePatterns is B_TRUE, the patterns are sub or super matching patterns, respectively.

Returns

This function returns one of the following values of the am_resource_match_t enumeration as defined:

#include "am_policy.h"
typedef enum am_resource_match {
    AM_SUB_RESOURCE_MATCH,
    AM_EXACT_MATCH,
    AM_SUPER_RESOURCE_MATCH,
    AM_NO_MATCH,
    AM_EXACT_PATTERN_MATCH
} am_resource_match_t;

AM_EXACT_MATCH: If both URLs match exactly as in, for example, if the URL for the resource is http://example.sun.com:90/index.html and the URL in the policy is http://example.sun.com:90/index.html.
AM_EXACT_PATTERN_MATCH: This result is returned if the URL to which the policy applies matches the URL to which access is requested as in, for example, if the URL for the resource is http://example.sun.com:90/index.html and the URL in the policy is http://example.sun.com:90/*. Distinction is not made between an EXACT_MATCH or a pattern match.
AM_NO_MATCH: If the URLs do not match.
AM_SUB_RESOURCE_MATCH: If the requested URL is found to be a sub-resource of the URL defined in the policy.
AM_SUPER_RESOURCE_MATCH: If the requested URL is found to be a parent of the URL defined in the policy.

`am_policy_destroy()`

Destroys an initialized instance of a policy evaluator object.

Details

An instance is initialized for each policy request.

Note –

The caller must ensure that the same instance is not destroyed more than once.

Syntax

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

Parameters

This function takes the following parameter:

policy: Integer specifying the object being destroyed.

Returns

This function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):

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 request and returns a non-boolean result.

Note –

am_policy_evaluate() has been deprecated. See am_policy_evaluate_ignore_url_notenforced().

Details

am_policy_evaluate() was used to evaluate policy for URLs on the not-enforced list and those not on the not-enforced list. Since there is not a need to evaluate URLs on the not-enforced list, am_policy_evaluate() has been deprecated. Although it can still be used, the SDK invokes am_policy_evaluate_ignore_url_notenforced().

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

Integer specifying the object being evaluated.

sso_token

Pointer to the session token (SSOTokenID) of the authenticated user.

Note –

The Access Manager Session Service creates a session data structure (also known as an SSOToken) that stores information such as login time, authentication scheme, and authentication level. It also generates a session token (also known as an SSOTokenID, a randomly-generated string that identifies an instance of an SSOToken.

resource_name

Pointer to the name of the resource being requested.

action_name

Pointer to the action requested.

Note –

An action is the operation to be performed on the resource. Web server actions are POST and GET. An allowable action for a human resources service , for example, can change a home telephone number.

env_parameter_map

Map object which contains environment variables (IP address, host name, etc.) used for evaluation by the Policy Service.

Note –

See am_map_t for more information.

policy_response_map_ptr

Pointer to a map object which contains all the profile, session and response attributes fetched.

Note –

This must be enabled in AMAgent.properties. See am_policy_result_t for information on how this is done. See am_map_t for more information on map objects.

policy_result

Pointer to the am_policy_result_t type to store the result.

Note –

See am_policy_result_t for more information.

Returns

This function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):

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

Memory Concerns

After using the results the caller must call am_policy_result_destroy() on policy_result to cleanup the allocated memory. Also, am_map_destroy() must be called on policy_response_map_ptr and env_parameter_map after their respective usage.

`am_policy_evaluate_ignore_url_notenforced()`

Evaluates a policy for a given request and returns a non-boolean result.

Details

am_policy_evaluate_ignore_url_notenforced() will evaluate a policy for the specified URL only if the URL does not appear on the not-enforced list defined in AMAgent.properties.

Note –

See Sun Java System Access Manager Policy Agent 2.2 User’s Guide for more information.

Syntax

#include "am_policy.h"
AM_EXPORT am_status_t
am_policy_evaluate_ignore_url_notenforced(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,
                                          am_bool_t ignorePolicyResult),
                                          char **am_revision_number;

Parameters

This function takes the following parameters:

policy_handle

Integer specifying the object being evaluated.

sso_token

Pointer to the session token (SSOTokenID) of the authenticated user.

Note –

resource_name

Pointer to the name of the resource being requested.

action_name

Pointer to the action requested.

Note –

env_parameter_map

Map object which contains environment variables (IP address, host name, etc.) used for evaluation by the Policy Service.

Note –

See am_map_t for more information.

policy_response_map_ptr

Pointer to a map object which contains all the profile, session and response attributes fetched.

Note –

This must be enabled in AMAgent.properties. See am_policy_result_t for information on how this is done. See am_map_t for more information on map objects.

policy_result

Pointer to the am_policy_result_t type to store the result.

Note –

See am_policy_result_t for more information.

ignorePolicyResult

Based on the am_bool_t defined in the <am_types.h> header file, AM_TRUE indicates that policy evaluation will not be done for the URL.

am_revision_number

Takes a value equal to the version of the instance of Access Manager with which the SDK is communicating. When communicating with Access Manager 7.0, the value will be 7.0, otherwise 6.3. It can also be set to NULL.

Returns

This function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):

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

Memory Concerns

`am_policy_get_url_resource_root()`

Extracts the root of a given URL.

Details

am_policy_get_url_resource_root() populates the resource_root pointer with the extracted information. 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/.

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 the following parameters:

resource_name

Pointer to the protected resource URL.

resource_root

Pointer to the location where the resource root will be written.

length

Value based on the size_t defined in the standard <stddef.h> header file that reflects the size of the resource_root buffer.

Note –

When using resources other than URLs, the developer implementing this function must make accurate judgement about the minimum size of resource_root.

Returns

This function returns one of the following values of the boolean_t enumeration (defined in the <am_types.h> header file):

B_TRUE: If the root was successfully extracted.
B_FALSE: If not.

`am_policy_init()`

Initializes the Access Manager Policy Service.

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

policy_config_properties

Pointer to the properties used to initialize the Policy Service.

Note –

See am_properties_t for more information.

Returns

This function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):

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

Memory Concerns

The caller must call am_policy_destroy() to free the memory.

`am_policy_invalidate_session()`

Cancels the specified session.

Syntax

#include "am_policy.h"
AM_EXPORT am_status_t
am_policy_invalidate_session(am_policy_t policy_handle,
                             const char *ssoTokenId);

Parameters

This function takes the following parameters:

policy_handle

Integer specifying the object being evaluated.

ssoTokenId

Pointer to the session token of the authentication user.

Note –

The session token is a randomly-generated string that represents an authenticated user.

Returns

This function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):

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 whether the notification functionality is enabled.

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

policy_handle: Integer specifying the object being evaluated.

Returns

This function returns the standard boolean_t with one of the following values:

0: If notification is disabled.
non-zero: If notification is enabled.

`am_policy_notify()`

Refreshes the 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: Integer specifying the object being evaluated.
notification_data: Pointer to the notification message as an XML string.
notification_data_len: Value based on the size_t defined in the standard <stddef.h> header file that reflects the size of the notification_data string.

Returns

This function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):

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

Converts the specified resource name into a standard representation for comparison purposes.

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: Pointer to the name of the resource to be converted.
c_resource: Pointer to a pointer to the location where the converted string will be placed.

Returns

This function does not return a value.

`am_policy_resource_has_patterns()`

Checks whether the specified resource name has patterns (such as the wildcard *).

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: Pointer to the resource being evaluated.

Returns

This function returns one of the following values of the boolean_t enumeration (defined in the <am_types.h> header file):

B-TRUE: If the resource has patterns.
B_FALSE: Otherwise.

`am_policy_result_destroy()`

Destroys the specified am_policy_result_t structure type.

Note –

See am_policy_result_t for more information.

Syntax

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

Parameters

This function takes the following parameter:

result: Pointer to the am_policy_result_t structure type being destroyed.

Returns

This function does not return a value.

`am_policy_service_init()`

Initializes one instance of Access Manager Policy 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

Pointer to the name for the Policy Service.

instance_name

Pointer to the name of the instance being initialized.

rsrc_traits

Pointer to a am_resource_traits_t structure type.

Note –

See am_resource_traits_t for more information.

service_config_properties

Pointer to the properties used to initialize the Policy Service instance.

Note –

See am_properties_t for more information.

policy_handle_ptr

Pointer to the integer specifying the object being evaluated.

Returns

This function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):

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