Chapter 1 Type and Structure Reference

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

Chapter 1
Type and Structure Reference

This chapter covers the types and structures provided in the C SDK available for use to interact with Sun Java™ System Access Manager 6 2005Q1. All authentication related types and structures can be found in the C SDK include file am_auth.h. The following structures are summarized in this chapter:

am_auth_callback

am_auth_choice_callback

am_auth_confirmation_callback_info

am_auth_language_callback_info

am_auth_locale

am_auth_name_callback_info

am_auth_password_callback_info

am_auth_text_input_callback_info

am_auth_text_input_callback_info

am_log_record

am_map_entry_iter

am_map_value_iter

am_policy_result

am_properties_iter

am_string_set_t

am_auth_callback

Primary callback structure for authentication.

This structure is a C implementation of the Java 2 SDK javax.security.auth.callback interface used to submit authentication requirements to the authentication service on the Access Manager. The Access Manager authentication service framework is based on the Java 2 SDK JAAS API.

Syntax

#include "am_auth.h"
typedef struct am_auth_callback {
  am_auth_callback_type_t callback_type;
    union am_auth_callback_info {
    am_auth_choice_callback_t choice_callback;
    am_auth_confirmation_callback_t  confirmation_callback;
    am_auth_language_callback_t language_callback;
    am_auth_name_callback_t name_callback;
    am_auth_password_callback_t password_callback;
    am_auth_text_input_callback_t text_input_callback;
    am_auth_text_output_callback_t text_output_callback;
  } callback_info;
} am_auth_callback_t;

Fields

This structure has the following fields:

Field

Description

callback_type

Indicates which type of callback this represents and determines which callback structure is used in the callback_info union below.

The value is one of the following:

ChoiceCallback

ConfirmationCallback

LanguageCallback, NameCallback

TextInputCallback

TextOutputCallback

Each callback type corresponds to the callback class of the same name in the Java 2 SDK javax.security.auth.callback package.

callback_info

The union of possible callback structures. The structure in the union to use depends on the callback_type field. Each structure corresponds to the callback class of the same name in the Java 2 SDK javax.security.auth.callback package and, has a response field to submit callback requirements.

Note that memory for all fields in the callback structures except the response field is allocated by the C SDK in the am_auth_login() call, and is freed by the C SDK when the auth context is destroyed using am_auth_destroy_auth_context(). Memory for the response field must be allocated and freed by the caller.

Each callback structure is described in this chapter in detail.

am_auth_choice_callback

Choice authentication callback structure.

This is a C implementation of the javax.security.auth.callback.ChoiceCallback class used to submit authentication callback requirements to the Access Manager Authentication service.

Syntax

#include "am_auth.h"
typedef struct am_auth_choice_callback {
  const char *prompt;
  boolean_t allow_multiple_selections;
  const char **choices;
  size_t choices_size;
  size_t default_choice;
  const char **response; /* selected indexes */
  size_t response_size;
} am_auth_choice_callback_t;

Fields

This structure should be used if the callback_type is ChoiceCallback used to submit authentication callback requirements to the Access Manager authentication service.

It is a C implementation of the javax.security.auth.callback.ChoiceCallback class.

It has the following fields:

Field

Description

prompt

Prompt to describe the list of choices.

allow_multiple_selections

True if this choice allows multiple selections.

choices



Choices for this choice callback. The number of choices is indicated in the choices_size field. Memory for choices list is allocated by the C SDK in am_auth_login() and is freed by the C SDK when the authentication context is destroyed using am_auth_destroy_auth_context().

choices_size

Number of choices in the choices field.

default_choice

Default choice, as an index into the choices list.

response

Selected choices.

Memory for the response must be allocated and freed by the caller.

response_size

The number of selected choices in the response.

Details

See am_auth_test.c in the C SDK samples for an example of how to use the choice callback.

am_auth_confirmation_callback_info

Confirmation authentication callback structure.

This is a C implementation of the javax.security.auth.callback.ConfirmationCallback class used to submit authentication callback requirements to the Access Manager authentication service.

Syntax

#include "am_auth.h"
typedef struct am_auth_confirmation_callback_info {
  const char *prompt;
  const char *message_type;
  const char *option_type;
  const char **options;
  size_t options_size;
  const char *default_option;
  const char *response; /* selected index */
} am_auth_confirmation_callback_t;

Fields

This structure has the following fields:

Field

Description

prompt

prompt to describe the options, if any.

message_type

The message type: "INFORMATION", "WARNING" or "ERROR".

Memory for the message type is allocated by the C SDK in am_auth_login() and freed when the authentication context is destroyed using am_auth_destroy_auth_context().

option_type

The option type: "YES_NO_OPTION", "YES_NO_CANCEL_OPTION", "OK_CANCEL_OPTION", or "UNSPECIFIED".

Memory for the message type is allocated by the C SDK in am_auth_login() and freed when the authentication context is destroyed using am_auth_destroy_auth_context().

options

The list of confirmation options, or null if this ConfirmationCallback was instantiated with an optionType instead of options.

Memory for the options list is allocated by the C SDK in am_auth_login() and freed when the authentication context is destroyed using am_auth_destroy_auth_context().

options_size

Number options in the options list.

default_option

The default option, if any.

Memory for the default option is allocated by the C SDK in am_auth_login() and freed when the authentication context is destroyed using am_auth_destroy_auth_context().

response

The selected option.

Memory for the response must be allocated and freed by the caller.

Details

See am_auth_test.c in the C SDK samples for an example of how to use the confirmation callback.

am_auth_language_callback_info

Language callback structure.

Syntax

#include "am_auth.h"
typedef struct am_auth_language_callback_info {
  am_auth_locale_t *locale;
  am_auth_locale_t *response; /* locale */
} am_auth_language_callback_t;

Fields

This structure has the following fields:

Field

Description

locale

The locale from Access Manager.

Memory for the locale is allocated by the C SDK in am_auth_login() and freed when the authentication context is destroyed using am_auth_destroy_auth_context().

response

The locale to send back to Access Manager.

Memory for the response must be allocated and freed by the caller.

am_auth_locale

Language locale structure.

Syntax

#include "am_auth.h"
typedef struct am_auth_locale {
  const char *language;
  const char *country;
  const char *variant;
} am_auth_locale_t;

Fields

This structure has the following fields:

Field

Description

language

A valid ISO Language Code. These codes are the lower-case, two-letter codes as defined by ISO-639. You can find a full list of these codes at a number of sites, such as:

http://www.ics.uci.edu/pub/ietf/http/related/iso639.txt

country

A valid ISO Country Code. These codes are the upper-case, two-letter codes as defined by ISO-3166. You can find a full list of these codes at a number of sites, such as:

http://www.chemie.fu-berlin.de/diverse/doc/ISO_3166.html

variant

A vendor or browser-specific code. For example, WIN for Windows, MAC for Macintosh, and POSIX for POSIX.

Details

See am_auth_test.c in the C SDK samples for an example of how to use this structure with the locale callback.

am_auth_name_callback_info

Name callback structure.

This is a C implementation of the javax.security.auth.callback.NameCallback class used to submit authentication callback requirements to the Access Manager authentication service.

Syntax

#include "am_auth.h"
typedef struct am_auth_name_callback_info {
  const char *prompt;
  const char *default_name;
  const char *response; /* name */
} am_auth_name_callback_t;

Fields

This structure has the following fields:

Field

Description

prompt

Prompt for the name, if any.

Memory for the prompt is allocated by the C SDK in am_auth_login() and freed when the authentication context is destroyed using am_auth_destroy_auth_context().

default_name

Default name, if any.

Memory for the default name is allocated by the C SDK in am_auth_login() and freed when the authentication context is destroyed using am_auth_destroy_auth_context().

response

The name to be submitted to the Access Manager.

Memory for the response must be allocated and freed by the caller.

Details

See am_auth_test.c in the C SDK samples for an example of how to use the name callback.

am_auth_password_callback_info

Password callback structure.

This is a C implementation of the javax.security.auth.callback.PasswordCallback class used to submit authentication callback requirements to the Access Manager authentication service.

Syntax

#include "am_auth.h"
typedef struct am_auth_password_callback_info {
  const char *prompt;
  boolean_t echo_on;
  const char *response; /* password */
} am_auth_password_callback_t;

Fields

This structure has the following fields:

Field

Description

prompt

Prompt for the password, if any.

Memory for the prompt is allocated by the C SDK in am_auth_login() and freed when the authentication context is destroyed using am_auth_destroy_auth_context().

echo_on

Whether the password should be displayed as it is typed.

response

The password to be submitted to Access Manager.

Memory for the response must be allocated and freed by the caller.

Details

See am_auth_test.c in the C SDK samples for an example of how to use the password callback.

am_auth_text_input_callback_info

Text Input authentication callback structure.

This is a C implementation of the javax.security.auth.callback.TextInputCallback class used to submit authentication callback requirements to the Access Manager authentication service.

Syntax

#include "am_auth.h"
typedef struct am_auth_text_input_callback_info {
  const char *prompt;
  const char *default_text;
  const char *response; /* text */
} am_auth_text_input_callback_t;

Fields

This structure has the following fields:

Field

Description

prompt

Prompt for the text input, if any.

Memory for the prompt is allocated by the C SDK in am_auth_login() and freed when the authentication context is destroyed using am_auth_destroy_auth_context().

default_text

Default text for the text input, if any.

Memory for the default text is allocated by the C SDK in am_auth_login() and freed when the authentication context is destroyed using am_auth_destroy_auth_context().

response

Text input to be submitted to the Access Manager.

Memory for the response must be allocated and freed by the caller.

Details

See am_auth_test.c in the C SDK samples for an example of how to use the password callback.

am_auth_text_output_callback_info

Text Output callback structure.

Syntax

#include "am_auth.h"
typedef struct am_auth_text_output_callback_info {
  const char *message;
  const char *message_type;
} am_auth_text_output_callback_t;

Fields

This structure has the following fields:

Field

Description

message

Message to be displayed.

Memory for the message is allocated by the C SDK in am_auth_login() and freed when the authentication context is destroyed using am_auth_destroy_auth_context().

message_type

Message type, one of "INFORMATION", "WARNING" or "ERROR".

Memory for the message type is allocated by the C SDK in am_auth_login() and freed when the authentication context is destroyed using am_auth_destroy_auth_context().

Details

See am_auth_test.c in the C SDK samples for an example of how to use the text output callback.

am_log_record

Log Record

Syntax

#include "am_log.h"
typedef struct am_log_record *am_log_record_t;

Fields

This is an opaque structure and therefore has no fields accessible by the C SDK user.

Details

See am_log_test.c in the C SDK samples for an example of how to use the text output callback.

am_map_t

Opaque handle to a map object. A map object is used to manipulate key value pairs using the am_map_* interface. Map objects are used by the policy interface in the C SDK to return any policy decision results and advices from Access Manager policy service, and to pass any environment variables for to the policy interface for policy evaluation.

Syntax

#include "am_map.h"
typedef struct am_map *am_map_t;

Fields

This is an opaque structure and therefore has no fields accessible by the C SDK user.

Details

See am_policy_test.c in the C SDK samples for an example of how to use am_map_t.

am_map_entry_iter

Opaque handle to an iterator for the entries in a map object.

Syntax

#include "am_map.h"
typedef struct am_map_entry_iter *am_map_entry_iter_t;

Fields

This is an opaque structure and therefore has no fields accessible by the C SDK user.

Details

See am_policy_test.c in the C SDK samples for an example of how to use am_map_entry_iter.

am_map_value_iter

Opaque handle to an iterator for the entries in a map object am_map_t. A map object is used to manipulate key value pairs using the am_map_* interface. Map objects are used by the policy interface in the C SDK to return any policy decision results and advices from Access Manager policy service, and to pass any environment variables for policy evaluation.

Syntax

#include "am_map.h"
am_map_value_iter *am_map_value_iter_t;

Fields

This is an opaque structure and therefore has no fields accessible by the C SDK user.

Details

See am_policy_test.c in the C SDK samples for an example of how to use am_map_entry_iter_t.

am_policy_result

Policy evaulation results from the policy interface in the C SDK.

Memory for am_policy_result is allocated by am_policy_evaluate() in the C SDK and should be freed by calling am_policy_result_destroy().

Syntax

#include "am_policy.h"
typedef struct am_policy_result {
  const char *remote_user;
  const char *remote_IP;

am_map_t advice_map;
  am_map_t attr_response_map;
} am_policy_result_t;

Fields

This structure has the following fields:

Field

Description

remote_use

The remote user.

remote_IP

The remote IP.

advice_map

Any policy advices



attr_response_map

Any user attributes.

Details

See am_policy_test.c in the C SDK samples for an example of how to use am_policy_result_t in the policy interfaces.

am_properties_iter

am_resource_traits

Structure for traits of policy resources (such as URLs) to be evaluated.

The traits are used by the policy interfaces in the C SDK to determine how to compare and canonicalize policy resources to reach a policy decision during policy evaluation.

Syntax

#include "am_policy.h"
typedef struct am_resource_traits {
  am_resource_match_t (*cmp_func_ptr)(const struct am_resource_traits                                 v*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;

Fields

This structure has the following fields:

Field

Description

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);

A function that compares the policy_res_name and resource_name and returns a resource match result.

Inputs:

rsrc_traits - the resource traits structure to use.

policy_res_name - name of a resource in the policy tree.

resource_name - name of the resource in policy evaluation.

use_patterns - whether to use or recognize patterns when comparing resources.

Returns:

Return one of AM_SUB_RESOURCE_MATCH, AM_EXACT_MATCH, AM_SUPER_RESOURCE_MATCH, AM_NO_MATCH, or AM_EXACT_PATTERN_MATCH.

Example:

am_policy_compare_urls() can be used for URL resources.

boolean_t
   (*has_patterns)
        ( const char               *resource               _name);

A function to determine whether a resource has patterns.

Inputs:

resource_name - name of the resource.

Returns:

true if resource_name has patterns and false otherwise.

Example:

am_policy_resource_has_patterns can be used for URL resources.

boolean_t
   (*get_resource_root)
        ( const char
         *resource_nam,                 char *root_resource_name,
      size_t         buflength);

A function to get the root of a resource.

Inputs:

Resource_name - name of the resource.

Root_resource_name - a buffer to contain the name of the resource root.

Buflength - length of the root_resource_name buffer passed to this function.

Returns:

true if the name of the resource root was successfully inserted into the given root_resource_name buffer, false otherwise.

Examples:

am_policy_get_url_resource_root() can be used for URL resources.

ignore_case

whether case should be ignored for all functions in this structure.

separator

resource seperator. For URLs '/' should be used as the seperator.

void

(*canonicalize)

    (const char *resource,

char **c_resource);

A function to canonicalize a resource name.

Inputs:

resource - the resource name.

Outputs:

c_resource - the canonicalized resource name. Memory for the canonicalized name must be allocated by the caller. A function to free the memory allocated for the canonicalized must be set in the str_free field.

void (*str_free)
   (void *resource_str);

A function to free the c_resource string returned in the canonicalize function above, after policy results have been evaluated by am_policy_evaluate().

This field cannot be set to null.

Inputs:

resource_str - the string to be freed.

Examples:

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

Details

See am_policy_test.c in the C SDK samples for an example of how this structure is used.

am_string_set_t

Structure for containing a set of strings used by various interfaces in the SDK.

The am_string_set_allocate() and am_string_set_destroy() interfaces can be used to allocate and free space for this structure.

Syntax

#include "am_string_set.h"
typedef struct {
  int size;
  char **strings;
} am_string_set_t;

Fields

This structure has the following fields:

Field

Description

size

Number of strings in the strings field

strings

List of strings

Details

See C SDK samples for examples of how this structure is used.

Previous      Contents      Next

Copyright 2005 Sun Microsystems, Inc. All rights reserved.

Field	Description
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);	A function that compares the policy_res_name and resource_name and returns a resource match result. Inputs: rsrc_traits - the resource traits structure to use. policy_res_name - name of a resource in the policy tree. resource_name - name of the resource in policy evaluation. use_patterns - whether to use or recognize patterns when comparing resources. Returns: Return one of AM_SUB_RESOURCE_MATCH, AM_EXACT_MATCH, AM_SUPER_RESOURCE_MATCH, AM_NO_MATCH, or AM_EXACT_PATTERN_MATCH. Example: am_policy_compare_urls() can be used for URL resources.
boolean_t (has_patterns) ( const char resource _name);	A function to determine whether a resource has patterns. Inputs: resource_name - name of the resource. Returns: true if resource_name has patterns and false otherwise. Example: am_policy_resource_has_patterns can be used for URL resources.
boolean_t (get_resource_root) ( const char resource_nam, char *root_resource_name, size_t buflength);	A function to get the root of a resource. Inputs: Resource_name - name of the resource. Root_resource_name - a buffer to contain the name of the resource root. Buflength - length of the root_resource_name buffer passed to this function. Returns: true if the name of the resource root was successfully inserted into the given root_resource_name buffer, false otherwise. Examples: am_policy_get_url_resource_root() can be used for URL resources.
ignore_case	whether case should be ignored for all functions in this structure.
separator	resource seperator. For URLs '/' should be used as the seperator.
void (canonicalize) (const char resource, char **c_resource);	A function to canonicalize a resource name. Inputs: resource - the resource name. Outputs: c_resource - the canonicalized resource name. Memory for the canonicalized name must be allocated by the caller. A function to free the memory allocated for the canonicalized must be set in the str_free field.
void (str_free) (void resource_str);	A function to free the c_resource string returned in the canonicalize function above, after policy results have been evaluated by am_policy_evaluate(). This field cannot be set to null. Inputs: resource_str - the string to be freed. Examples: free() should be used if the canonicalize field is set to the am_policy_resource_canonicalize() function.

Field	Description
callback_type	Indicates which type of callback this represents and determines which callback structure is used in the callback_info union below. The value is one of the following: ChoiceCallback ConfirmationCallback LanguageCallback, NameCallback TextInputCallback TextOutputCallback Each callback type corresponds to the callback class of the same name in the Java 2 SDK javax.security.auth.callback package.
callback_info	The union of possible callback structures. The structure in the union to use depends on the callback_type field. Each structure corresponds to the callback class of the same name in the Java 2 SDK javax.security.auth.callback package and, has a response field to submit callback requirements. Note that memory for all fields in the callback structures except the response field is allocated by the C SDK in the am_auth_login() call, and is freed by the C SDK when the auth context is destroyed using am_auth_destroy_auth_context(). Memory for the response field must be allocated and freed by the caller. Each callback structure is described in this chapter in detail.

Field	Description
prompt	Prompt to describe the list of choices.
allow_multiple_selections	True if this choice allows multiple selections.
choices	Choices for this choice callback. The number of choices is indicated in the choices_size field. Memory for choices list is allocated by the C SDK in am_auth_login() and is freed by the C SDK when the authentication context is destroyed using am_auth_destroy_auth_context().
choices_size	Number of choices in the choices field.
default_choice	Default choice, as an index into the choices list.
response	Selected choices. Memory for the response must be allocated and freed by the caller.
response_size	The number of selected choices in the response.

Field	Description
locale	The locale from Access Manager. Memory for the locale is allocated by the C SDK in am_auth_login() and freed when the authentication context is destroyed using am_auth_destroy_auth_context().
response	The locale to send back to Access Manager. Memory for the response must be allocated and freed by the caller.

Field	Description
language	A valid ISO Language Code. These codes are the lower-case, two-letter codes as defined by ISO-639. You can find a full list of these codes at a number of sites, such as: http://www.ics.uci.edu/pub/ietf/http/related/iso639.txt
country	A valid ISO Country Code. These codes are the upper-case, two-letter codes as defined by ISO-3166. You can find a full list of these codes at a number of sites, such as: http://www.chemie.fu-berlin.de/diverse/doc/ISO_3166.html
variant	A vendor or browser-specific code. For example, WIN for Windows, MAC for Macintosh, and POSIX for POSIX.

Field	Description
message	Message to be displayed. Memory for the message is allocated by the C SDK in am_auth_login() and freed when the authentication context is destroyed using am_auth_destroy_auth_context().
message_type	Message type, one of "INFORMATION", "WARNING" or "ERROR". Memory for the message type is allocated by the C SDK in am_auth_login() and freed when the authentication context is destroyed using am_auth_destroy_auth_context().

Field	Description
remote_use	The remote user.
remote_IP	The remote IP.
advice_map	Any policy advices
attr_response_map	Any user attributes.

Field	Description
size	Number of strings in the strings field
strings	List of strings