Chapter 1 The C SDK Application Programming Interfaces

Sun OpenSSO Enterprise provides C application programming interfaces (API) and related information to form a software development kit (SDK) that can be used to enable external C applications to participate in OpenSSO Enterprise authentication, authorization, single sign-on (SSO), and logging operations. Additionally, the C SDK is a development kit for web agents — allowing developers to create web agents for containers that have not yet been provided for OpenSSO Enterprise. This chapter covers the following topics:

• Where is the C SDK?

• What is Included in the C SDK?

• Developing Web Policy Agents

• Required C Libraries

Where is the C SDK?

The OpenSSO Enterprise C SDK can be found in the opensso directory created on the machine to which OpenSSO Enterprise is deployed. From inside the top-level opensso directory, change into the libraries/native/agent-csdk directory where you will find agent-csdk.zip and a README. Within agent-csdk.zip are the following 32–bit and 64–bit libraries:

• agent-csdk-solaris-sparc-32.tar.gz is the C SDK for the Solaris SPARC 32–bit platform.

• agent-csdk-solaris-sparc-64.tar.gz is the C SDK for the Solaris SPARC 64–bit platform.

• agent-csdk-solaris-x86.tar.gz is the C SDK for the Solaris x86 32–bit platform.

• agent-csdk-solaris-x86.tar.gz is the C SDK for the Solaris x86 64–bit platform.

• agent-csdk-linux-32.tar.gz is the C SDK for the Linux 32–bit platform.

• agent-csdk-linux-64.tar.gz is the C SDK for the Linux 64–bit platform.

• agent-csdk-windows-32.zip is the C SDK for the Windows 32–bit platform.

• agent-csdk-windows-64.zip is the C SDK for the Windows 64–bit platform.

What is Included in the C SDK?

Each library contains header files, samples, and README files containing information on how to implement the C SDK. More information is in the following sections.

• Header Files

• Code Samples

Header Files

A 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. The OpenSSO Enterprise C header files are:

<am.h>

General utility routines provided by the OpenSSO Enterprise 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 OpenSSO Enterprise host.

<am_map.h>

Data types and functions for creating, destroying, and manipulating the map objects used by OpenSSO Enterprise.

<am_notify.h>

Data types and functions for implementing notifications.

<am_policy.h>

Data types and functions for using OpenSSO Enterprise policy objects.

<am_properties.h>

Data types and functions for property maps used by clients of the OpenSSO Enterprise client API.

<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 OpenSSO Enterprise.

<am_utils.h>

Functions to encode/decode HTTP cookies.

<am_web.h>

Data types and functions intended for use by OpenSSO Enterprise web agents.

Code Samples

OpenSSO Enterprise provides code samples that demonstrate how you can use the API to connect C applications to the OpenSSO Enterprise framework. The code samples are:

am_auth_test.c

Demonstrates the basic usage of the authentication API used to login to an instance of OpenSSO Enterprise.

am_log_test.c

Demonstrates the basic usage of the logging API used to write a message to the OpenSSO Enterprise logs.

am_policy_test.c

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

am_sso_test.c

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

apache_agent.c

Demonstrates how to use the policy API 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.

---

Note –

am_web_agent_test.c, referred to in this file, is no longer used.

---

Developing Web Policy Agents

The C SDK can be used to develop web policy agents. Web agents that are currently available for OpenSSO Enterprise can be downloaded from the agents download page. Web agents that are not yet available can be developed using the C API and the included sample source files as a blueprint. See README.TXT in the samples directory for more information on using this web policy agent development toolkit.

Required C Libraries

The 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 Operating System

• Linux Application Environment

• Microsoft Windows

Solaris Operating System

For the Solaris^TM operating System, set the LD_LIBRARY_PATH environment variable to include:

/usr/lib/mps:opensso-base/is_csdk/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

For the Linux application environment, set the LD_LIBRARY_PATH environment variable to include:

/usr/lib/mps:opensso-base/is_csdk/lib:/usr/lib:/usr/ucblib

This directory contains the following shared libraries:

• libamsdk.so

• libxml2.so

• libssl3.so

• libnss3.so

• libplc4.so

• libplds4.so

• libnspr4.so

Microsoft Windows

When using Microsoft^® Windows, you must have the \\opensso-base\is_csdk\bin 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.