Chapter 5 Logging Data Types and Functions

Sun OpenSSO Enterprise contains public data types and functions you can use for logging on the local system or on Sun OpenSSO Enterprise. Reference summaries include a short description, syntax, parameters and returns. The code is contained in the <am_log.h> header file. The sample source am_log_test.c demonstrates the basic usage of the logging API to record information such as user activity, traffic patterns and authorization violations. This chapter contains the following sections:

• The Logging API for C

• Logging Data Types

• Logging Functions

The Logging API for C

The logging API is designed to allow C applications to produce messages of interest and write them to the OpenSSO Enterprise logs. When some type of event occurs in an external application, the application code first determines if the logging module (a file created for messages usually relevant to a specific function or feature) to which the event is relevant has a level high enough to log the event. (A level specifies importance and defines the amount of detail that will be logged.) If the determination is affirmative, a log message is generated and a log record created in the relevant logging module. Information in the log record can be updated as necessary. The following notes regard the logging API for C functionality:

• The am_log_init() function by the application must be called before using any other am_log_* interfaces. If either the SSO, authentication, or policy initialization functions (am_sso_init(), am_auth_init(), or am_policy_init()) are called, am_log_init() does not need to be called as each of the three aforementioned functions call am_log_init() internally.

• The am_log_record_* interfaces can be used to set or update information in the log record. They include:

  • am_log_record_add_loginfo()

  • am_log_record_create()

  • am_log_record_destroy()

  • am_log_record_populate()

  • am_log_record_set_log_level()

  • am_log_record_set_log_message()

  • am_log_record_set_loginfo_props()

• The following are convenience functions that provide simplified access to existing log records. They include:

  • am_log_record_set_log_level()

  • am_log_record_set_log_message()

Logging Data Types

The logging data types defined in <am_log.h> are:

• am_log_record_t

• am_log_module_id_t

am_log_record_t

Represents the information and message values to be recorded.

See Chapter 15, Recording Events with the Logging Service, in Sun OpenSSO Enterprise 8.0 Technical Overview for information regarding events that are logged and the log fields to which they are written.

Syntax

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

Members

am_log_record is an opaque structure with no accessible members.

am_log_module_id_t

Represents the identifier for a logging module.

See am_log_add_module() for information on logging modules.

Syntax

#include "am_log.h"
typedef unsigned int am_log_module_id_t;

Members

am_log_module_id_t has no members.

Logging Functions

The logging functions defined in <am_log.h> are:

• am_log_add_module()

• am_log_flush_remote_log()

• am_log_init()

• am_log_is_level_enabled()

• am_log_log()

• am_log_log_record()

• am_log_record_add_loginfo()

• am_log_record_create()

• am_log_record_destroy()

• am_log_record_populate()

• am_log_record_set_log_level()

• am_log_record_set_log_message()

• am_log_record_set_loginfo_props()

• am_log_set_levels_from_string()

• am_log_set_log_file()

• am_log_set_module_level()

• am_log_set_remote_info()

• am_log_vlog()

am_log_add_module()

Adds a new logging file (for a specific function or feature) to the OpenSSO Enterprise Logging Service.

Details

The currently used module file names are:

• AuthService

• NamingService

• PolicyService

• SessionService

• PolicyEngine

• ServiceEngine

• Notification

• PolicyAgent

• RemoteLog

• all

Syntax

#include "am_log.h"
AM_EXPORT am_status_t
am_log_add_module(const char *name,
                  am_log_module_id_t *id_ptr);

Parameters

This function takes the following parameters:

name

Pointer to the name associated with the new module.

id_ptr

Pointer to the location where the identifier for the logging module is stored.

Returns

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

If a module of the same name already exists, the module identifier of the existing module is returned.

AM_SUCCESS

If the addition was successful.

AM_INVALID_ARGUMENT

If name or id_ptr is NULL.

AM_NSPR_ERROR

If unable to initialize the logging framework.

AM_NO_MEMORY

If unable to allocate memory for the new module.

AM_FAILURE

If any other error is detected.

am_log_flush_remote_log()

Flushes all the log records in the OpenSSO Enterprise log buffer.

Syntax

#include "am_log.h"
AM_EXPORT am_status_t
am_log_flush_remote_log();

Parameters

This function takes no parameters:

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 flush was successful.

AM_*

The appropriate code based on the error.

am_log_init()

Initializes the Logging Service.

Details

am_log_init() writes events to the logs on the OpenSSO Enterprise server.

Syntax

#include "am_log.h"
AM_EXPORT am_status_t
am_log_init(const am_properties_t log_init_params);

Parameters

This function takes the following parameter:

log_init_params

Properties used to initialize the Logging 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 log initialization is successful.

AM_*

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

am_log_is_level_enabled()

Checks whether an event at the specified level intended for the specified logging module should generate a logging message.

Details

If the level of the event is not equal to or higher than the level of the logging module, a logging message will not be generated.

Syntax

#include "am_log.h"
AM_EXPORT boolean_t
am_log_is_level_enabled(am_log_module_id_t moduleID,
                        am_log_level_t level);

Parameters

This function takes the following parameters:

moduleID

The identifier of the logging module.

level

The level of the event. Possible values are defined in the following am_log_level_t enumeration. The default value is AM_LOG_INFO.

typedef enum am_log_level {
    AM_LOG_ALWAYS = -1, /* always logged */
    AM_LOG_NONE,	/* never logged, typically used to turn off a module */
    AM_LOG_ERROR,	/* used for error messages */
    AM_LOG_WARNING,	/* used for warning messages */
    AM_LOG_INFO,	/* used for informational messages */
    AM_LOG_DEBUG,	/* used for debug messages */
    AM_LOG_MAX_DEBUG,    /* used for more detailed debug messages */
    AM_LOG_AUTH_REMOTE = 128, /* logged deny and/or allow */
    AM_LOG_AUTH_LOCAL = 256
} am_log_level_t;

Returns

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

The code used is dependent on the server operating system.

!0

If a message will be generated.

0

If a message will not be generated.

am_log_log()

Produces a logging message from the specified event string.

Details

When using am_log_log(), consider the following:

• The message is produced only if the level defined for the specified module is greater than or equal to the level defined for the message. See am_log_is_level_enabled().

• am_log_log() directly enumerates arguments for the format string. See am_log_vlog() for another method.

Syntax

#include "am_log.h"
AM_EXPORT boolean_t
am_log_log(am_log_module_id_t moduleID,
           am_log_level_t level,
           const char *format, ...);

Parameters

This function takes the following parameters:

moduleID

The identifier of the OpenSSO Enterprise logging module to which the message is relevant.

level

The level of the message. Each message has an associated level that defines the amount of detail that will be logged. Possible values are defined in the am_log_level_t enumeration. The default value is AM_LOG_INFO.

typedef enum am_log_level {
    AM_LOG_ALWAYS = -1, /* always logged */
    AM_LOG_NONE,	/* never logged, typically used to turn off a module */
    AM_LOG_ERROR,	/* used for error messages */
    AM_LOG_WARNING,	/* used for warning messages */
    AM_LOG_INFO,	/* used for informational messages */
    AM_LOG_DEBUG,	/* used for debug messages */
    AM_LOG_MAX_DEBUG,    /* used for more detailed debug messages */
    AM_LOG_AUTH_REMOTE = 128, /* logged deny and/or allow */
    AM_LOG_AUTH_LOCAL = 256
} am_log_level_t;

format

Pointer to a printf-style character string detailing the event.

---

Note –

The set of additional arguments needed by format are either enumerated directly or passed using the standard va_list mechanism as appropriate to the call. See am_log_vlog().

---

Returns

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

The code used is dependent on the server operating system.

!0

If the message is logged.

0

If the message will not be logged.

am_log_log_record()

Writes the given log record to the specified logging module.

Syntax

#include "am_log.h"
AM_EXPORT am_status_t
am_log_log_record(am_log_record_t record,
                  const char *log_name,
                  const char *logged_by_token_id);

Parameters

This function takes the following parameters:

record

The log record pointer.

log_name

Pointer to the name of the logging module to which the log record will be written.

logged_by_token_id

Pointer to a valid SSOTokenID identifying the user to whom the log record applies.

---

Note –

This is required to access the Logging Service on OpenSSO Enterprise.

---

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 log record is written.

AM_*

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

am_log_record_add_loginfo()

Updates a log record with additional information.

Syntax

#include "am_log.h"
AM_EXPORT am_status_t
am_log_record_add_loginfo(am_log_record_t record,
                          const char *key,
                          const char *value);

Parameters

This function takes the following parameters:

record

A log record pointer.

key

Pointer to the log field being updated.

---

Note –

See Chapter 15, Recording Events with the Logging Service, in Sun OpenSSO Enterprise 8.0 Technical Overview for information regarding events that are logged and the log fields to which they are written.

---

value

Pointer to the value with which the log field will be modified.

Returns

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

am_log_record_create()

Instantiates a log record, initializing it with a message and the message's corresponding level.

Syntax

#include "am_log.h"
 AM_EXPORT am_status_t 
am_log_record_create(am_log_record_t *record_ptr, 
                     am_log_record_log_level_t log_level,
                     const char *message);

Parameters

This function takes the following parameters:

record_ptr

Pointer to a log record pointer.

log_level

The level with which the log record will be instantiated. Each log record has an associated level that defines its relative importance and urgency. Possible values are defined in the am_log_record_log_level_t enumeration.

typedef enum am_log_record_log_level {

    /* Log Level as defined by JDK 1.4 */

    AM_LOG_LEVEL_SEVERE = 1000,
    AM_LOG_LEVEL_WARNING = 900,
    AM_LOG_LEVEL_INFORMATION = 800,
    AM_LOG_LEVEL_CONFIG = 700,
    AM_LOG_LEVEL_FINE = 500,
    AM_LOG_LEVEL_FINER = 400,
    AM_LOG_LEVEL_FINEST = 300,

    /* Log Levels defined by Access Manager */

    AM_LOG_LEVEL_SECURITY = 950,
    AM_LOG_LEVEL_CATASTROPHE = 850,
    AM_LOG_LEVEL_MISCONF = 750,
    AM_LOG_LEVEL_FAILURE = 650,
    AM_LOG_LEVEL_WARN = 550,
    AM_LOG_LEVEL_INFO = 450,
    AM_LOG_LEVEL_DEBUG = 350,
    AM_LOG_LEVEL_ALL = 250

} am_log_record_log_level_t;

message

Pointer to the log message to be written to the log record.

Returns

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

am_log_record_destroy()

Destroys the specified log record.

Syntax

#include "am_log.h" 
AM_EXPORT am_status_t 
am_log_record_destroy(am_log_record_t record);

Parameters

This function takes the following parameter:

record

A log record pointer.

Returns

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

am_log_record_populate()

Updates a log record with the user’s session identifier (also known as an SSOTokenID).

Details

See Single Sign-on Token Handles for more information.

Syntax

#include "am_log.h"
AM_EXPORT am_status_t
am_log_record_populate(am_log_record_t record,
                       const char *user_token_id);

Parameters

This function takes the following parameters:

record

A log record pointer.

user_token_id

Pointer to a valid session identifier (also known as an SSOTokenID).

Returns

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

am_log_record_set_log_level()

Sets the level for the specified log record.

Syntax

#include "am_log.h"
AM_EXPORT am_status_t
am_log_record_set_log_level(am_log_record_t record,
                            am_log_record_log_level_t log_level);

Parameters

This function takes the following parameters:

record

A log record pointer.

log_level

The level to which the log record will be set. Each log record has an associated level that defines its relative importance and urgency. Possible values are defined in the am_log_record_log_level_t enumeration.

typedef enum am_log_record_log_level {

    /* Log Level as defined by JDK 1.4 */

    AM_LOG_LEVEL_SEVERE = 1000,
    AM_LOG_LEVEL_WARNING = 900,
    AM_LOG_LEVEL_INFORMATION = 800,
    AM_LOG_LEVEL_CONFIG = 700,
    AM_LOG_LEVEL_FINE = 500,
    AM_LOG_LEVEL_FINER = 400,
    AM_LOG_LEVEL_FINEST = 300,

    /* Log Levels defined by Access Manager */

    AM_LOG_LEVEL_SECURITY = 950,
    AM_LOG_LEVEL_CATASTROPHE = 850,
    AM_LOG_LEVEL_MISCONF = 750,
    AM_LOG_LEVEL_FAILURE = 650,
    AM_LOG_LEVEL_WARN = 550,
    AM_LOG_LEVEL_INFO = 450,
    AM_LOG_LEVEL_DEBUG = 350,
    AM_LOG_LEVEL_ALL = 250

} am_log_record_log_level_t;

Returns

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

am_log_record_set_log_message()

Sets the log message to the log record before localization and formatting.

Syntax

#include "am_log.h"
AM_EXPORT am_status_t
am_log_record_set_log_message(am_log_record_t record,
                              const char *message);

Parameters

This function takes the following parameters:

record

A log record pointer.

message

Pointer to the log message to be written to the log record.

Returns

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

am_log_record_set_loginfo_props()

Updates the specified log record with additional information.

Details

log_info is expected to have the information formatted as key/value pairs in a properties map. Delete the am_properties_t pointer only when finished with the SDK. See am_properties_t for more information.

Syntax

#include "am_log.h"
AM_EXPORT am_status_t
am_log_record_set_loginfo_props(am_log_record_t record,
                                am_properties_t log_info);

Parameters

This function takes the following parameters:

record

A log record pointer.

log_info

Pointer to the properties that contain the information to be set in the log record.

Returns

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

am_log_set_levels_from_string()

Sets the level for the logging modules listed in a specified string.

Details

The format of the string must be:

ModuleName[:Level][,ModuleName[:Level]]*

Optional spaces may occur before and after any commas. The comma, brackets and asterisk in the second term signifies that it can occur 0 or more times.

Syntax

#include "am_log.h"
AM_EXPORT am_status_t
am_log_set_levels_from_string(const char *module_level_string);

Parameters

This function takes the following parameter:

module_level_string

Pointer to the string containing the list of modules and the respective levels.

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 levels were successfully set.

AM_INVALID_ARGUMENT

If module_level_string is NULL.

AM_FAILURE

If any other error is detected.

am_log_set_log_file()

Sets the name of the file to use for logging.

Syntax

#include "am_log.h"
AM_EXPORT am_status_t
am_log_set_log_file(const char *name);

Parameters

This function takes the following parameter:

name

Pointer to the name of the file to which log records are recorded.

---

Note –

If NULL or empty, logging messages are sent to the stderr stream.

---

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 logging file is successfully set.

AM_NO_MEMORY

If unable to allocate memory for internal data structures.

AM_FAILURE

If an error of any type occurs.

am_log_set_module_level()

Sets the level for the specified logging module.

Syntax

#include "am_log.h"
AM_EXPORT am_log_level_t
am_log_set_module_level(am_log_module_id_t moduleID,
                        am_log_level_t level);

Parameters

This function takes the following parameters:

moduleID

The identifier of the logging module.

level

The level to which the logging module will be set. Each module has an associated level that defines the amount of detail that will be logged. Possible values are defined in the following enumeration. The default value is AM_LOG_INFO.

typedef enum am_log_level {
    AM_LOG_ALWAYS = -1, /* always logged */
    AM_LOG_NONE,	/* never logged, typically used to turn off a module */
    AM_LOG_ERROR,	/* used for error messages */
    AM_LOG_WARNING,	/* used for warning messages */
    AM_LOG_INFO,	/* used for informational messages */
    AM_LOG_DEBUG,	/* used for debug messages */
    AM_LOG_MAX_DEBUG,    /* used for more detailed debug messages */
    AM_LOG_AUTH_REMOTE = 128, /* logged deny and/or allow */
    AM_LOG_AUTH_LOCAL = 256
} am_log_level_t;

Returns

This function returns am_log_level_t with one of the following values:

The previous logging level of the module.

If the logging level is set properly.

LOG_NONE

If the specified module is invalid.

am_log_set_remote_info()

Initializes the remote log service.

Details

This must be called before am_log_log() with AM_LOG_REMOTE_MODULE as the log module. Initialization is done only once. Subsequently, only remote logging calls are done.

Syntax

#include "am_log.h"
AM_EXPORT am_status_t
am_log_set_remote_info(const char *rem_log_url,
                       const char *sso_token_id,
                       const char *rem_log_name,
                       const am_properties_t log_props);

Parameters

This function takes the following parameters:

rem_log_url

Pointer to the URL of the OpenSSO Enterprise Logging Service being used for the remote logging.

sso_token_id

Pointer to a valid SSOTokenID identifying the user to whom the log record applies.

rem_log_name

Pointer to the logging module (file) to which log records are written.

log_props

Pointer to the properties that contain the information to initialize the OpenSSO Enterprise Logging Service.

---

Note –

log_props is expected to have the information formatted as a properties map in key/value pairs. Delete the am_properties_t pointer only when finished with the SDK. See am_properties_t for more information.

---

Returns

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

am_log_vlog()

Logs a message for the specified module at the given level.

Details

When using am_log_vlog(), consider the following:

• The message is produced only if the level defined for the specified module is greater than or equal to the level defined for the message. See am_log_is_level_enabled().

• am_log_vlog() passes the standard va_list as an argument for the format string. See am_log_log() for another method.

Syntax

#include "am_log.h"
AM_EXPORT boolean_t
am_log_vlog(am_log_module_id_t moduleID,
            am_log_level_t level,
            const char *format,
            va_list args);

Parameters

This function takes the following parameters:

moduleID

The identifier of the OpenSSO Enterprise logging module to which the message is relevant.

level

The level of the message. Each message has an associated level that defines the amount of detail that will be logged. Possible values are defined in the am_log_level_t enumeration. The default value is AM_LOG_INFO.

typedef enum am_log_level {
    AM_LOG_ALWAYS = -1, /* always logged */
    AM_LOG_NONE,	/* never logged, typically used to turn off a module */
    AM_LOG_ERROR,	/* used for error messages */
    AM_LOG_WARNING,	/* used for warning messages */
    AM_LOG_INFO,	/* used for informational messages */
    AM_LOG_DEBUG,	/* used for debug messages */
    AM_LOG_MAX_DEBUG,    /* used for more detailed debug messages */
    AM_LOG_AUTH_REMOTE = 128, /* logged deny and/or allow */
    AM_LOG_AUTH_LOCAL = 256
} am_log_level_t;

format

Pointer to a printf-style character string.

---

Note –

The set of addition arguments needed by format are either enumerated directly or passed using the standard va_list mechanism as appropriate to the call.

---

va_list

A void pointer interpreted as an argument list. va_list is the type of the void pointer passed to a function that accepts a pointer to a list of arguments.

---

Note –

The set of additional arguments needed by format are either enumerated directly or passed using the standard va_list mechanism as appropriate to the call. See am_log_log().

---

Returns

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

The code used is dependent on the server operating system. See <am_types.h> for more details.

!0

If the message can be logged.

0

If the message will not be logged.