This chapter covers the types and structures provided in the C SDK available for use to interact with Sun JavaTM System Access Manager. 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:
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.
#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;
This structure has the following members:
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.
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 members 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.
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.
#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;
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 members:
Prompt to describe the list of choices.
True if this choice allows multiple selections.
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().
Number of choices in the choices field.
Default choice, as an index into the choices list.
Selected choices.
Memory for the response must be allocated and freed by the caller.
The number of selected choices in the response.
See am_auth_test.c in the C SDK samples for an example of how to use the choice callback.
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.
#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;
This structure has the following members:
Prompt to describe the options, if any.
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( ).
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().
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().
Number options in the options list.
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().
The selected option.
Memory for the response must be allocated and freed by the caller.
See am_auth_test.c in the C SDK samples for an example of how to use the confirmation callback.
Language callback structure.
#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;
This structure has the following members:
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().
The locale to send back to Access Manager.
Memory for the response must be allocated and freed by the caller.
Language locale structure.
#include "am_auth.h" typedef struct am_auth_locale { const char *language; const char *country; const char *variant; } am_auth_locale_t;
This structure has the following members:
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
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
A vendor or browser-specific code. For example, WIN for Windows, MAC for Macintosh, and POSIX for POSIX.
See am_auth_test.c in the C SDK samples for an example of how to use this structure with the locale callback.
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.
#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;
This structure has the following members:
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, 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().
The name to be submitted to the Access Manager.
Memory for the response must be allocated and freed by the caller.
See am_auth_test.c in the C SDK samples for an example of how to use the name callback.
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.
#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;
This structure has the following members:
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().
Whether the password should be displayed as it is typed.
The password to be submitted to Access Manager.
Memory for the response must be allocated and freed by the caller.
See am_auth_test.c in the C SDK samples for an example of how to use the password callback.
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.
#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;
This structure has the following members:
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 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().
Text input to be submitted to the Access Manager.
Memory for the response must be allocated and freed by the caller.
See am_auth_test.c in the C SDK samples for an example of how to use the password callback.
Text Output callback structure.
#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;
This structure has the following members:
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, 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().
See am_auth_test.c in the C SDK samples for an example of how to use the text output callback.
Log Record
#include "am_log.h"typedef struct am_log_record *am_log_record_t;
This is an opaque structure and therefore has no members accessible by the C SDK user.
See am_log_test.c in the C SDK samples for an example of how to use the text output callback.
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.
#include "am_map.h"typedef struct am_map *am_map_t;
This is an opaque structure and therefore has no members accessible by the C SDK user.
This function creates an instance of am_map_t structure and returns the pointer to the structure to the caller.
Memory Concerns: You should free the allocated structure by calling am_map_destroy.
See am_policy_test.c in the C SDK samples for an example of how to use am_map_t.
Opaque handle to an iterator for the entries in a map object.
#include "am_map.h" typedef struct am_map_entry_iter *am_map_entry_iter_t;
This is an opaque structure and therefore has no members accessible by the C SDK user.
See am_policy_test.c in the C SDK samples for an example of how to use am_map_entry_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.
#include "am_map.h" am_map_value_iter *am_map_value_iter_t;
This is an opaque structure and therefore has no members accessible by the C SDK user.
See am_policy_test.c in the C SDK samples for an example of how to use am_map_entry_iter_t.
Policy evaluation 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() .
#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;
This structure has the following members:
The remote user.
The remote IP.
Any policy advices.
Any user attributes.
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.
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.
#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;
This structure has the following members:
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.
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.
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.
Whether case should be ignored for all functions in this structure.
Resource separator. For URLs ’/’ should be used as the separator.
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.
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:
The resource_str - the string to be freed.
Examples:
Method free() should be used if the canonicalize field is set to the am_policy_resource_canonicalize() function.
See am_policy_test.c in the C SDK samples for an example of how this structure is used.
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.
#include "am_string_set.h" typedef struct { int size; char **strings; } am_string_set_t;
This structure has the following members:
Number of strings in the strings field
List of strings
See C SDK samples for examples of how this structure is used.