Sun OpenSSO Enterprise 8.0 C API Reference for Application and Web Policy Agent Developers

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 Chapter 4, Managing Policies, in Sun OpenSSO Enterprise 8.0 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 agent 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 agent 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 agent 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.