Chapter 1 The C Application Programming Interface Files

Sun Java™ System Access Manager provides C application programming interfaces (APIs) that enable external C applications to participate in Access Manager authentication, authorization, single sign-on (SSO), and logging operations. This chapter covers the following topics:

• C Header Files

• C Code Samples

• Required C Libraries

C Header Files

A C header file is a text file that contains pieces of code written in the C programming language. The name of a header file, by convention, ends with the .h extension. It is inserted inside a program by coding the #include preprocessor directive. By default, Access Manager C header files are installed in the /AccessManager-base/SUNWam/include directory. The Access Manager C header files are:

<am.h>

General utility routines provided by the Access Manager library.

<am_auth.h>

Data types and functions for developing custom authentication modules.

<am_log.h>

Data types and functions for logging on the local system or the Access Manager host.

<am_map.h>

Data types and functions for creating, destroying, and manipulating the map objects used by Access Manager.

<am_notify.h>

Data types and functions for implementing notifications.

<am_policy.h>

Data types and functions for using Access Manager policy objects.

<am_properties.h>

Data types and functions for property maps used by clients of the Access Manager client APIs.

<am_sso.h>

Data types and functions for implementing SSO.

<am_string_set.h>

Data types and functions for manipulating strings.

<am_types.h>

Common types and macros provided by Access Manager.

<am_utils.h>

This is an unsupported, early access version of utility functions. Functions and data structures may change without backward compatibility.

<am_web.h>

Data types and functions intended for use by Access Manager web agents.

C Code Samples

Access Manager provides code samples that demonstrate how you can use the APIs to connect C applications to the Access Manager framework. By default, the code samples are installed in the /AccessManager-base/SUNWam/samples/csdk directory. The code samples are:

am_auth_test.c

Demonstrates the basic usage of the authentication APIs used to login to an instance of Access Manager.

am_log_test.c

Demonstrates the basic usage of the logging APIs used to write a message to the Access Manager logs.

am_policy_test.c

Demonstrates the basic usage of the policy APIs used to evaluate access for specified resources.

---

Note –

Before running the sample, be sure the password defined in the property com.sun.am.policy.am.password is in clear text as the sample does not decrypt it. Since am_policy_test.c is only a sample, this poses no security risk. For example:

com.sun.am.policy.am.username = UrlAccessAgent
com.sun.am.policy.am.password = clear-text-password

These properties are defined in AMAgent.properties.

---

am_sso_test.c

Demonstrates the basic usage of the SSO APIs to perform session operations.

apache_agent.c

Demonstrates how you can use the policy APIs to build a web agent for the Apache Web Server.

---

Caution –

This is a sample web agent and is not intended to serve as a web agent in a real deployment.

---

Makefile

Makefile for building the sample agent.

README.TXT

Provides detailed instructions for building and executing sample programs.

Required C Libraries

Sample programs are run by launching a generated executable on the command line. The following sections contain instructions for the supported platforms. Be sure to set the library path appropriately for the platform you are using.

• Solaris^TM Operating System

• Linux Application Environment

• Microsoft^® Windows

Solaris^TM Operating System

Set the LD_LIBRARY_PATH environment variable to include the following:

/usr/lib/mps:/opt/SUNWam/lib:/usr/lib:/usr/ucblib

---

Note –

The /usr/lib directory is included before the /usr/ucblib directory so that common programs (such as editors) will continue to function.

---

These directories contain the following shared libraries:

• libamsdk.so

• libxml2.so

• libssl3.so

• libnss3.so

• libplc4.so

• libplds4.so

• libnspr4.so

• libucb.so

Linux Application Environment

Set the LD_LIBRARY_PATH environment variable to include:

/AccessManager-base/agent/lib

This directory contains the following shared libraries:

• libamsdk.so

• libxml2.so

• libssl3.so

• libnss3.so

• libplc4.so

• libplds4.so

• libnspr4.so

Microsoft^® Windows

You must have the /AccessManager-base/SUNWam/lib directory in your path before launching the samples. Alternatively, you can run the run.bat script to launch the samples. The script will set your path appropriately.