Tivoli SecureWay Policy Director CDMF API Developer...

Tivoli SecureWay Policy DirectorCDMF API Developer Reference

Version 3.7.1March 30, 2001

Tivoli SecureWay Policy Director

CDMF API Developer Reference

Copyright Notice©Copyright IBM Corporation 2001 All rights reserved. May only be used pursuant to a Tivoli Systems Software License Agreement, an IBM Software License Agreement, or Addendum for Tivoli Products to IBM Customer or License Agreement. No part of this publication may be reproduced, transmitted, transcribed, stored in a retrieval system, or translated into any computer language, in any form or by any means, electronic, mechanical, magnetic, optical, chemical, manual, or otherwise, without prior written permission of IBM Corporation. IBM Corporation grants you limited permission to make hardcopy or other reproductions of any machine-readable documentation for your own use, provided that each such reproduction shall carry the IBM Corporation copyright notice. No other rights under copyright are granted without prior written permission of IBM Corporation. The document is not intended for production and is furnished “as is” without warranty of any kind. All warranties on this document are hereby disclaimed, including the warranties of merchantability and fitness for a particular purpose.U.S. Government Users Restricted Rights—Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corporation.

TrademarksIBM, the IBM logo, Tivoli, the Tivoli logo, AIX, Policy Director, and SecureWay are trademarks or registered trademarks of International Business Machines Corporation or Tivoli Systems Inc. in the United States, other countries, or both. Microsoft, Windows, Windows NT, and the Windows logo are trademarks of Microsoft Corporation in the United States, other countries, or both.UNIX is a registered trademark of The Open Group in the United States and other countries.Java and all Java-based trademarks are trademarks of Sun Microsystems, Inc. in the United States, other countries, or both.Other company, product, and service names may be trademarks or service marks of others.

NoticesReferences in this publication to Tivoli Systems or IBM products, programs, or services do not imply that they will be available in all countries in which Tivoli Systems or IBM operates. Any reference to these products, programs, or services is not intended to imply that only Tivoli Systems or IBM products, programs, or services can be used. Subject to valid intellectual property or other legally protectable right of Tivoli Systems or IBM, any functionally equivalent product, program, or service can be used instead of the referenced product, program, or service. The evaluation and verification of operation in conjunction with other products, except those expressly designated by Tivoli Systems or IBM, are the responsibility of the user. Tivoli Systems or IBM may have patents or pending patent applications covering subject matter in this document. The furnishing of this document does not give you any license to these patents. You can send license inquiries, in writing, to the IBM Director of Licensing, IBM Corporation, North Castle Drive, Armonk, New York 10504-1785, U.S.A.

Policy Director CDMF API Developer Reference iii

Contents

Chapter 1 — CDSSO and CDMF API Overview1.1 Introducing the Policy Director CDSSO and CDMF.................................... 1-2

1.1.1 Integrating a Custom CDMF Shared Library................................... 1-2

1.2 Authentication Process Flow for CDSSO with CDMF................................. 1-3

Chapter 2 — Building the CDMF Shared Library2.1 CDMF API Components ............................................................................... 2-2

2.1.1 Downloading the CDMF API Components ..................................... 2-3

2.1.2 Software Requirements .................................................................... 2-3

2.2 Implementing the CDMF Shared Library ..................................................... 2-4

2.3 Customizing the CDMF Shared Library ....................................................... 2-5

2.3.1 Providing User Attributes: cdmf_get_usr_attributes() ..................... 2-5

2.3.2 Providing Identity Mapping: cmdf_map_usr() ................................ 2-5

2.3.3 Naming the Custom Shared Library................................................. 2-6

2.4 Specifying Extended Attributes..................................................................... 2-7

Chapter 3 — CDMF C API Reference3.1 API Functions and Macros ............................................................................ 3-2

cdmf_map_usr() ............................................................................................ 3-3cdmf_get_usr_attributes() ............................................................................. 3-5cdmf_create_usr_attr_list() ........................................................................... 3-6cdmf_create_usr_attr() .................................................................................. 3-7cdmf_add_value_to_attr() ............................................................................. 3-8cdmf_add_attr_to_list() ................................................................................. 3-9CDSSO_STRDUP() .................................................................................... 3-10CDSSO_MALLOC()................................................................................... 3-11CDSSO_FREE().......................................................................................... 3-12CDSSO_REALLOC() ................................................................................. 3-13

iv Version 3.7.1

Policy Director CDMF API Developer Reference 1–1

1CDSSO and CDMF API Overview

The Policy Director 3.7 Cross Domain Single Sign-on (CDSSO) functionality allows Web users to perform a single sign-on and move seamlessly between two separate secure domains.

The Cross Domain Mapping Framework (CDMF) is a programming interface that allows a developer to customize the mapping of user identities and the handling of user attributes.

This chapter provides an overview of the Policy Director CDSSO and CDMF capabilities and introduces the components of the CDMF API.

Topic Index:

� 1.1 Introducing the Policy Director CDSSO and CDMF

� 1.2 Authentication Process Flow for CDSSO with CDMF

Chapter 1: CDSSO and CDMF API Overview

1–2 Version 3.7.1

1.1 Introducing the Policy Director CDSSO and CDMF

The Policy Director Cross Domain Single Sign-on (CDSSO) provides a mechanism for transferring user credentials across multiple secure domains. CDSSO allows Web users to perform a single sign-on and move seamlessly between two separate secure domains.

CDSSO supports the goals of scalable network architecture by allowing the integration of multiple secure domains. For example, a large corporate extranet can be set up with two or more unique domains—each with its own users and object space. CDSSO allows movement of users between the domains with a single sign-on.

When a user makes a request to a resource located in another domain, the CDSSO mechanism transfers an encrypted user identity token from the first domain to the second domain. The second domain now has the user’s identity (as authenticated in the first domain) and the user is not forced to perform another login.

1.1.1 Integrating a Custom CDMF Shared Library

In many CDSSO scenarios, the default one-to-one mapping between users in different domains may not suit all deployment requirements.

The Cross Domain Mapping FrameWork (CDMF) allows you to build a custom shared library that can handle extended user attributes and provide mapping services for the user identity.

The CDMF is a programming interface that allows flexibility in customizing the mapping of user identities and the handling of user attributes.

Authentication Process Flow for CDSSO with CDMF


1.2 Authentication Process Flow for CDSSO with CDMF

The following process flow description is illustrated in Figure 1-1.

1. Any user who wants to participate in multiple domains must have a valid user account in the primary domain and an identity that can be mapped into a valid account in each of the participating remote domains.

A user cannot invoke the CDSSO functionality without initially authenticating to an initial secure domain (A) that contains the user’s account.

2. The user makes a request to access a resource in domain B via a link on a Web page.

The link contains a special CDSSO expression:

/pkmscdsso?<destination-URL>

For example:

/pkmscdsso?https://www.domainB.com/index.html

3. The request is first processed by the WebSEAL server in domain A. WebSEAL builds an authentication token that contains the user's Policy Director identity (short name), the current domain (“A”), additional user information, and a time stamp.

The additional user information is obtained by a call out to the customized CDMF shared library (cdmf_get_usr_attributes). This library has the ability to supply user attributes that can be used by domain B during the user mapping process.

WebSEAL triple-DES encrypts this token data with the symmetric key generated by the cdsso_key_gen utility (refer to section 4.8.2 of the Tivoli SecureWay Policy Director 3.7 WebSEAL Administration Guide). This key file is shared and stored in the [cdsso-peers] stanza of the iv.conf configuration file on both domain A and domain B WebSEAL servers.

The token contains a configurable time stamp (authtoken-lifetime) that defines the lifetime of the token. The time stamp, when properly configured, can prevent replay attacks.

4. The domain A WebSEAL server re-directs the request plus the encrypted token back to the browser and then to the domain B WebSEAL server (HTTP redirection).

5. The domain B WebSEAL server uses its version of the same key file to decrypt and validate the token as coming from the referring domain.

Chapter 1: CDSSO and CDMF API Overview

1–4 Version 3.7.1

6. The domain B WebSEAL server now calls out to a CDSSO authentication mechanism library. This CDSSO library in turn calls out to the customized CDMF library which performs the actual user mapping (cdmf_map_usr).

The CDMF library passes the user’s identity, and optionally additional user attribute information, back to the CDSSO library. The CDSSO library uses this information to build a credential.

7. The domain B authorization service permits or denies access to protected objects based on the user’s credential and the specific ACL permissions associated with the requested objects.

Figure 1-1: CDSSO and CDMF Model

W ebSEALA

sing le s ign -onClient

Dom ain A

/

W ebSEALB

Dom ain B

/� Client clicks on link to Domain B.� W ebSEAL A CDSSO uses CDMF library to get

additional user information. Then builds andsends encrypted ID token w ith request.

� W ebSEAL B decrypts and validates token� W ebSEAL B CDSSO calls CDMF shared

library to map the user identity.� Credential is built and client participates in

Dom ain B

Link

S S L

C D M FSha redL ib ra ry

C D M FS haredL ib ra ry

C D S SOLibrary


2Building the CDMF Shared Library

The specific operation of a customized CDMF shared library is determined entirely by the developer. It is the responsibility of the developer to use the CDMF API functions and utilities to implement the required cross domain identity mapping and extended user attribute handling.

Topic Index:

� 2.1 CDMF API Components

� 2.2 Implementing the CDMF Shared Library

� 2.3 Customizing the CDMF Shared Library

� 2.4 Specifying Extended Attributes

Chapter 2: Building the CDMF Shared Library

2–2 Version 3.7.1

2.1 CDMF API Components

The CDMF API consists of the following components:

� API library (core and utility functions)

� API header file

� Demonstration (example) CDMF file

� Makefiles

Files Description

cdmf.c The source file that can be customized by the developer to implement the CDMF logic. This file needs to be compiled and linked into the CDMF shared library.

cdmf.c.example Example cdmf.c file This example performs a simple user mapping and performs some manipulation of the CDSSO attribute lists.

cdmf.h The header file for cdmf.c.

cdmf_utils.h The header file providing utility functions for manipulating extended user attribute lists.

cdssotypes.h The header file that provides definitions of types and macros used in cdmf.c.

Windows only:

cdmf_utils.lib The library for the utility functions in cdmf_utils.h.

Makefile.win32 The nmake Makefile used to build the custom CDMF shared library.

UNIX only:

libcdmfutils.(so, a, sl) The library for the utility functions defined in cdmf_utils.h.• .so for Solaris• .a for AIX• .sl for HP-UX

Makefile.cdmf.in The template Makefile used to build the CDMF library. Change this file to suit your platform.

CDMF API Components


2.1.1 Downloading the CDMF API Components

The CDMF API software components are not available on the Policy Director 3.7 / 3.7.1 CD distribution. You can obtain the components from the public Policy Director download page at:

http://www.tivoli.com/support/secureway/policy_dir/downloads.html

The CDMF API components are compressed into a single file and made available in the following formats:

� .tgz file for UNIX platforms

� .zip file for Windows platforms

All library files, header file, example file, and Makefiles are located in one directory. You can locate this directory anywhere on your system.

2.1.2 Software Requirements

There are no software dependencies when building the CDMF shared library.

To use CDSSO functionality with a CDMF shared library, you must have at least two Policy Director secure domains installed, each containing a WebSEAL server.

Refer to Section 1.2: “Authentication Process Flow for CDSSO with CDMF”for an overview of a CDSSO scenario.

http://www.tivoli.com/support/secureway/policy_dir/downloads.html


2–4 Version 3.7.1

2.2 Implementing the CDMF Shared Library

1. Edit the cdmf.c source file and modify the cdmf_map_usr and cdmf_get_usr_attributes functions to enable the desired user mapping and user attribute handling.

2. For UNIX platforms, edit Makefile.cdmf.in and make any modifications required to build the library for the appropriate development platform. Instructions appear in the comments at the top of the file.

For Windows platforms, Makefile.win32 requires no modification.

3. Build the custom CDMF shared library. Provide the following platform-specific name for the shared library file:

� Solaris – libcdmf.so

� AIX – libcdmf.a

� HP-UX – libcdmf.sl

� Windows – cdmf.dll

See Section 2.3: “Customizing the CDMF Shared Library”.

4. Stop the WebSEAL server process (secmgrd).

5. Replace the original CDMF library that was shipped with the Policy Director product with the customized version.

6. Start secmgrd.

Customizing the CDMF Shared Library


2.3 Customizing the CDMF Shared Library

The custom CDMF shared library must contain two application programming interfaces. The first interface, called by the local WebSEAL server, serves the CDSSO request by providing extended user attribute information.

The second interface is called by the WebSEAL server in the remote domain and provides user identity mapping services for the CDSSO request.

� Providing User Attributes: cdmf_get_usr_attributes() (Section 2.3.1)

� Providing Identity Mapping: cmdf_map_usr() (Section 2.3.2)

2.3.1 Providing User Attributes: cdmf_get_usr_attributes()

When a CDSSO request is initiated by a user accessing the /pkmscdsso page of domain A, the cdmf_get_usr_attributes interface is called.

The input parameter to this function is the short name of the user initiating the CDSSO operation.

The output parameter is the attribute list constructed by the CDMF utility functions.

The attribute list is included in the authentication token that is constructed and sent to the WebSEAL server in domain B. The CDSSO and CDMF libraries in domain B can use the information contained in this attribute list when producing a user identity.

2.3.2 Providing Identity Mapping: cmdf_map_usr()

When a CDSSO request is received by the domain B WebSEAL server, the identity of the local user must be determined. The cdmf_map_usr() interface is called to perform the mapping from the remote user (who initiated the CDSSO request) to a local user identity.

The input parameter to this function is the cdsso_usr_info_t data type, which contains the user name, domain, and an attribute list. This input information is used by the custom CDMF shared library to determine a local user identity. Any information contained in the attribute list was added by the cdmf_get_usr_attributes function call to the CDMF library in domain A.

The output information is also contained in a cdsso_usr_info_t data type. The only required field is the user name, which is the short name of the local user. The local user's attribute list is an optional field that can be filled out if the user's credential requires extended attributes.


2–6 Version 3.7.1

Because the credential’s extended attribute list only supports one value, only the first value for each attribute will become part of the user's credential. The domain field is ignored.

� If the final user mapping is successful, CDMF_SUCCESS should be returned.

� If no identity mapping occurs, CDMF_NOMAP should be returned.

� If an error occurs, CDMF_FAILURE should be returned.

� If CDMF_SUCCESS is not returned, no memory clean up is performed on the local user information.

2.3.3 Naming the Custom Shared Library

You must name the custom shared library appropriately for your platform:

Platform File Name

Solaris libcdmf.so

AIX libcdmf.a

HP-UX libcdmf.sl

Windows cdmf.dll

Specifying Extended Attributes


2.4 Specifying Extended Attributes

Both CDMF application programming interfaces support additional user information in the form of a CDSSO attribute list.

The CDSSO attribute list cdsso_attrlist_t is a name/multiple value data list that is defined in cdssotypes.h.

The utility functions that are required to construct this list are defined in the file cdmf_utils.h.

These utility functions perform the following operations:

� Create a CDSSO user attribute list

� Create a CDSSO user attribute

� Add a value to a CDSSO user attribute

� Add a CDSSO user attribute to the user attribute list

For detailed information, consult the following reference pages:

� cdmf_create_usr_attr_list()

� cdmf_create_usr_attr()

� cdmf_add_value_to_attr()

� cdmf_add_attr_to_list()


2–8 Version 3.7.1


3CDMF C API Reference

� 3.1 API Functions and Macros

Core API Functions:

� cdmf_map_usr()

� cdmf_get_usr_attributes()

Utility API Functions:




� cdmf_add_attr_to_list()

Memory Management Macros:

� CDSSO_STRDUP()

� CDSSO_MALLOC()

� CDSSO_FREE()

� CDSSO_REALLOC()

Chapter 3: CDMF C API Reference

3–2 Version 3.7.1

3.1 API Functions and Macros

The CDMF API functions are located in one directory.

Core API Functions

You implement the following two core API functions in your custom CDAS:

� cdmf_map_usr()

� cdmf_get_usr_attributes()

Utility Functions

The following four utility functions facilitate data manipulation for extended user attributes:




� dmf_add_attr_to_list()

Memory Management Macros

The following memory management macros should be used so WebSEAL can safely clean up any allocated memory:

� CDSSO_STRDUP()

� CDSSO_MALLOC()

� CDSSO_FREE()

� CDSSO_REALLOC()

Windows-specific Macros

The following two macros are required when building the shared library on a Windows platform. The macros should not be redefined or changed.

� CDMF_DECLSPEC()

� CDMF_CALLTYPE()

API Functions and Macros


cdmf_map_usr()

Map a remote user into a local user.

Syntax int cdmf_map_usr(

cdsso_user_info_t *remote_usr, cdsso_user_info_t *local_usr

);

Description

The WebSEAL cdssoauthn authentication module calls this interface during a CDSSO authentication to determine the identity of the local user.

The remote user information is received in a cdsso_usr_info_t structure. This information includes the remote user name, the remote domain name, and possibly an extended attribute list. This information should be used to determine the identity of the local user.

If the local user's identity is successfully determined, then CDMF_SUCCESS should be returned. The local user information is returned in a cdsso_usr_info_t structure. The local user information that can be returned in this structure consists of the local user name and possibly an extended attribute list.

If an attribute list is to be returned, then the functions defined in cdmf_utils.h should be used to construct the list. Information from this attribute list is included in the Policy Director credential for that client.

If the function is not able to determine the identity of the local user, CDMF_NOMAP should be returned.

Note that if CDMF_SUCCESS is not returned, no memory clean up is performed on the fields of the local user structure.

Parameters

Input

remote_usr Out of domain user.

Input/Output

local_usr User mapped to in this domain.


3–4 Version 3.7.1

Return Values

If successful, the function returns CDMF_SUCCESS.

If no user mapping is available, the function returns CDMF_NOMAP.

Upon failure, the function returns CDMF_FAILURE.



cdmf_get_usr_attributes()

Retrieves the extended attributes for the specified user.

Syntax int cdmf_get_usr_attributes(

char *usr, cdsso_attrlist_t **attr_list

);

Description

WebSEAL calls this interface when a CDSSO operation is initiated through the /pkmscdsso link.

The extended attribute list returned by this function is sent to the remote WebSEAL server inside the authentication token. The remote WebSEAL server can use these extended attributes to help in the user mapping.

The attribute list must be constructed using the functions defined in cdmf_utils.h.

If no attributes are being set, this function should set attr_list to NULL.

Parameters

Input

usr User name.

Output

attr_listExtended attributes for input user.

Return Values

If successful, the function returns CDMF_SUCCESS.

Upon failure, the function returns CDMF_FAILURE.


3–6 Version 3.7.1

cdmf_create_usr_attr_list()

Create an empty attribute list.

Syntaxcdsso_attrlist_t *cdmf_create_usr_attr_list(

void);

Description

Create an empty attribute list.

Parameters

None.

Return Values

If successful, the function returns a pointer to the newly allocated list.

Otherwise, the function returns NULL.



cdmf_create_usr_attr()

Create a new user attribute.

Syntaxcdsso_usr_attr_t *cdmf_create_usr_attr(

char *attr_name);

Description

Creates a new user attribute. A copy is made of the name.

Parameters

Input

attr_nameName of new attribute.

Return Values

If successful, the function returns a pointer to the newly allocated attribute.

Otherwise, the function returns NULL.


3–8 Version 3.7.1

cdmf_add_value_to_attr()

Add a new value to a user attribute.

Syntaxintcdmf_add_value_to_attr(

char *new_value,cdsso_usr_attr_t *attr

);

Description

Add a new value to a user attribute. A copy of the value is made. This function can be called many times to add multiple values to a user attribute.

Parameters

Input

new_valueNew value to be added to the attribute.

Output

attrUpdated user attribute object.

Return Values

If successful, the function returns TRUE.

Otherwise, the function returns FALSE.



cdmf_add_attr_to_list()

Add the specified user attribute to the specified user attribute list.

Syntaxintcdmf_add_attr_to_list(

cdsso_usr_attr_t *new_attr,cdsso_attrlist_t *list

);

Description

Add the specified user attribute to the specified user attribute list.

Parameters

Input

new_attrNew attribute to be added to the list.

Output

listUpdated list.

Return Values

If successful, the function returns TRUE.

Otherwise, the function returns FALSE.


3–10 Version 3.7.1

CDSSO_STRDUP()

Duplicate the specified string.

SyntaxCDSSO_STRDUP(

char *dest,char *src

);

Description

Duplicate the specified string.

Parametersdest

Destination string.

srcSource string.

Return Values

None.



CDSSO_MALLOC()

Allocate a portion of memory of the specified size.

Syntaxvoid *CDSSO_MALLOC(

size_t size);

Description

Allocate a portion of memory of the specified size.

Parameterssize

Size of memory to allocate.

Return Values

Returns a pointer to newly allocated memory.


3–12 Version 3.7.1

CDSSO_FREE()

Dealloocate the specified memory.

SyntaxCDSSO_FREE(

void *ptr);

Description

Dealloocate the specified memory.

Parametersptr

A pointer to the memory to be deallocated.

Return Values

None.



CDSSO_REALLOC()

Reallocate a memory block.

Syntaxvoid *CDSSO_REALLOC(

void *curr_ptr,size_t new_size

);

Description

Reallocate a memory block.

Parameterscurr_ptr

Point to the existing memory to be deallocated.

new_sizeSize of the new portion of memory.

Returns

Returns a pointer to the re-allocated (and possibly moved) memory block.


3–14 Version 3.7.1

Tivoli SecureWay Policy Director CDMF API Developer...

Documents

Transcript of Tivoli SecureWay Policy Director CDMF API Developer...