ArmorTrustedUserCOMAPI-8 1 0-DeveloperGuide

Armor
TRUSTEDUSER COM API

Version 8.1.0
Developer’s Guide
ORBITECH SOLUTIONS
SHAKTHI TOWERS, 766 ANNA SALAI CHENNAI 600002, INDIA
Tel: 91-44-8566317
COPYRIGHT NOTICE
Copyright  2001, 2002 by OrbiTech Solutions
All rights reserved. These materials are confidential and proprietary to OrbiTech
Solutions and no part of these materials should be reproduced, published in any form
by any means, electronic or mechanical including photocopy or any information storage
or retrieval system nor should the materials be disclosed to third parties without the
express written authorization of OrbiTech Solutions
June 2002
CONTACT PERSONS
N. Siva Subramanian siva.subramanian@orbitech.co.in

Seshadri S. Nathan seshadri.nathan@orbitech.co.in
ORBITECH SOLUTIONS
3rd PHASE, SPENCER PLAZA, 765 ANNA SALAI, CHENNAI 600002, INDIA
Tel: 91-44-8566317
TABLE OF CONTENTS
1 INTRODUCTION................................................................................................................................. 1
1.1 BACKGROUND ................................................................................................................................ 1
1.2 EXECUTIVE SUMMARY .................................................................................................................. 1
1.3 ENVIRONMENT ............................................................................................................................... 1
1.4 CONSTRAINTS................................................................................................................................. 1
1.5 ABOUT THIS GUIDE ....................................................................................................................... 1
1.5.1 Audience ............................................................................................................................... 1
1.5.2 Assumptions........................................................................................................................ 1
1.5.3 How this guide is organized ........................................................................................... 1
1.6 REFERENCES ................................................................................................................................. 2
1.7 GLOSSARY ...................................................................................................................................... 2
2 FUNCTIONAL COVERAGE.............................................................................................................. 3
2.1 FUNCTIONAL OVERVIEW ............................................................................................................... 3
2.1.1 Non Interactive User Authentication Service .............................................................. 3
2.2 OTHER FEATURES ......................................................................................................................... 3
2.2.1 Logging.................................................................................................................................. 3
2.3 COMPILATION AND RUNTIME SETTINGS ...................................................................................... 3
2.3.1 Compilation Settings ......................................................................................................... 3
2.3.2 Run-Time Settings.............................................................................................................. 3
3 API USAGE........................................................................................................................................... 4
3.1 API LIBRARY INITIALIZATION ........................................................................................................ 4
3.1.1 API Instantiation................................................................................................................. 4
3.2 AUTHENTICATION........................................................................................................................... 4
3.3 TICKET RETRIEVAL .......................................................................................................................... 5
3.4 LOGOUT .......................................................................................................................................... 6
3.5 ERROR HANDLING ......................................................................................................................... 7
1 INTRODUCTION
1.1 Background
Armor provides the feature of non-interactive User to authenticate with the underlying
Security Provider and get an Armor Authentication Ticket. Credential for the Trusted
Non Interactive User is the Client Machine IP Address which is maintained at the
underlying Security Provider.
Armor Trusted User COM API provides method to Login to the underlying Security
Provider, to get the Armor Authentication Ticket and to logout from the underlying
Security Provider. The current implementation of Armor Trusted User COM API have 4C
SMS as its Security Provider.
1.2 Executive Summary

Armor Trusted User COM API can communicate with 4C SMS server over TCP/HTTP or
HTTPS mode, which are configurable. In case of HTTPS communication, will use
dependent DLLs of Internet Explorer Version 5.5 or above.
1.3 Environment
Usage of Armor Trusted User COM API requires presence of the following software
environment:
Operating System : Windows NT Version 4.0 ( Service Pack 6 )
1.4 Constraints
The usage of Armor Trusted User COM API configured to communicate with 4C SMS
Server over SSL will require presence of Internet Explorer Version 5.5 or above.
1.5 About this Guide
1.5.1 Audience
This guide is intended for application which requires an Armor Authentication Ticket for
a Non Interactive Trusted User.
1.5.2 Assumptions
This guide is written with an assumption that the reader is familiar with the Microsoft
COM development environment.
1.5.3 How this guide is organized

This guide consists of the following chapters:
Chapter 1: Introduction
This chapter gives an overview of the Armor Trusted User COM API, its features
and the platform it supports.
Chapter 2: Functional Coverage

This chapter gives an overview of functional features supported in Armor
Trusted User COM API.
Armor: Developer’s Guide – Trusted User COM API Page 1 of 7

Chapter 3: API Usage
This chapter shows the sequence and flow of the Armor Trusted User COM APIs
calls.
1.6 References
The CISO Intranet site contains the CISO policy and documents and other references.
• http://citiweb.citicorp.com/ctopics/ciso
1.7 Glossary
Abbreviation Description
4C A OrbiTech product that is a suite containing 4 applications
i.e. a Security Management system, a Tool for Batch Job
Automation, a System Monitoring Daemon and a
Configuration Management Utility.
APIs Application Programming Interfaces
SMS Security Management System
SSL Secure Sockets Layer

2 Functional Coverage
2.1 Functional Overview
The Armor Trusted User COM APIs for 4C provide interfaces to the following 4C SMS
Services:
q Non Interactive Trusted User Login
q Non Interactive Trusted User Logout
2.1.1 Non Interactive User Authentication Service

Armor Trusted User COM API support the following 4C SMS authentication features:
Authentication of Non Interactive Trusted User with IP Address of the Client
Machine as the Credential.
Refresh of Armor Authentication Ticket for the Non Interactive Trusted User on
Ticket Expiry.
Logout of Non Interactive Trusted User.
2.2 Other Features

In addition to interfacing with an underlying Security Provider, Armor Trusted User
COM APIs support the following feature too:
2.2.1 Logging
In order to aid debugging, Armor Trusted User COM APIs generates a trace of various
activities being performed by it. It provides a facility for logging of trace messages to a
file. The granularity of trace messages to can be controlled through configuration.
Details for configuring and setting up the API for tracing have been described in the
Armor Trusted User COM API 8.1.0 Installation Guide and may be referred to from
there.
2.3 Compilation and Runtime Settings

The Armor Trusted User COM API should have been installed.
2.3.1 Compilation Settings

2.3.2 Run-Time Settings


3 API Usage
The Usage of Armor Trusted User COM APIs can be categorized under the following
heads:
1. API Library Initialization
2. Non Interactive Trusted User Login
3. Retrieval of Armor Authentication Ticket for Non Interactive Trusted User
4. Non Interactive Trusted User Logout
3.1 API Library Initialization

This section depicts the sequence of steps involved in initiating an Armor Trusted User
COM API. Ideally, the steps depicted in this section should be performed by
Applications as a part of their start-up processing.
3.1.1 API Instantiation

The Application will require creating an object of the ArmorTrustedUser component as
depicted by the following code snippet:
Dim objATU as New TrustedUser
‘Object reference should be kept in global storage.
3.2 Authentication
Authentication refers to creation of a User specific Session within 4C SMS. The Non
Interactive Trusted User is authenticated with his credential. As mentioned earlier,
credential for the Non Interactive Trusted User is the IP Address of the Client Machine
on which the API is installed.
An application should invoke the method DoLogin to authenticate the Non Interactive
Trusted User. DoLogin method should be invoked only once after the object
instantiation.
VARIANT DoLogin ( void )
Parameter
Nothing
Return Value
1 - Success
0 - Armor Error
-1 - System Call Failure
Application should proceed only if the DoLogin method returns Success Flag. Incase of
Login failure, GetArmorError gives the error message. The following code depicts how
DoLogin method should be invoked.
Dim varRetVal as Variant, varError as Variant
varRetVal = ObjATU.DoLogin()

If varRetVal = 1 then
MsgBox “User Logged in Successfully”
Else if varRetVal = 0 then
‘User is unable to login, get the ArmorError for the reason of login failure.
varRetVal = GetArmorError ( varError )
MsgBox “Armor Error : “ & varError
Endif
Else
‘Else Failure in the System call.
‘ArmorTrustedUser writes the error in the logfile called ArmorTrustedUser.log will
be generated in the Temp folder.
MsgBox “DoLogin Method is failed, Contact Armor Support”
Endif
3.3 Ticket Retrieval

This pertains to retrieval of Armor Authentication Ticket. On the authentication of a
Non Interactive Trusted User, an Armor Authentication Ticket is issued for a valid User.
The ticket can be retrieved by invoking the method GetTicket. This method should be
invoked every time when an Armor Authentication Ticket is required.
VARIANT GetTicket ( VARIANT *varTicket )
Parameter
varTicket
[out] - Pointer to the buffer that receives the Ticket.
Return Value
1 - Success
0 - Armor Error
This method checks the validity of Armor Authentication Ticket. If the Ticket has
expired, Armor Authentication Ticket is refreshed and returned to the application.
Refresh of Armor Authentication Ticket on expiry is transparent to the application. The
following code depicts how GetTicket method should be invoked.
Dim varRetVal as Variant, varError as Variant, varTicket as Variant
varRetVal = ObjATU.GetTicket( varTicket)
‘Application can use the ticket in varTicket
MsgBox “Ticket :” & varTicket
‘Unable to get the ticket, Display the ArmorError for the reason of GetTicket failure.
Endif
Else

MsgBox “ GetTicket Method is failed, Contact Armor Support”
Endif
3.4 Logout
This refers to the closure of a User’s Session with the Application. In this scenario, the
Application should inform the Security Provider that the User is attempting to logout.
Based on this, the Security Provider may require to perform some operations i.e. audit
logging, security updates etc. The method DoLogout logs out the User and invalidates
the Armor Authentication Ticket. Invocation of the method GetTicket after the DoLogout
method invocation returns ArmorError. This processing is required to be done when an
Application chooses to close it’s Session with Armor. This would generally be done as a
part of the Application’s shutdown process.
VARIANT DoLogout ( void )
Parameters
Nothing
Return Value
1 - Success
0 - Armor Error
The following code depicts how DoLogout method should be invoked.
Dim varRetVal as Variant, varError as Variant
varRetVal = ObjATU.DoLogout( )
MsgBox “User logged out successfully”
‘Unable to logout the user, Display the ArmorError for the reason of logout failure.
Endif
Else
MsgBox “DoLogout Method is failed, Contact Armor Support”
Endif

3.5 Error Handling
The method GetArmorError returns the last Armor Error Message. This method should
be invoked to get the Error Message if any method invocation returns Armor Error.
VARIANT GetArmorError( VARIANT *varError );
Parameters
varError
[out] Pointer to the buffer will contain the last armor error message.
Return Value
1 - Error is set.
0 - Error is not set.
The following code depicts how GetArmorError method should be invoked.
Dim varError as Variant, varRetVal as Variant
if varRetVal = 1 then
‘Armor Error is set
MsgBox “ Armor Error :” & varError
Else
‘Armor Error is not set
MsgBox “ Armor Error is not set”
Endif

ArmorTrustedUserCOMAPI-8 1 0-DeveloperGuide

Diunggah oleh

Informasi Dokumen

Deskripsi Asli:

Judul Asli

Hak Cipta

Format Tersedia

Bagikan dokumen Ini

Bagikan atau Tanam Dokumen

Opsi Berbagi

Apakah menurut Anda dokumen ini bermanfaat?

Apakah konten ini tidak pantas?

Hak Cipta:

Format Tersedia

ArmorTrustedUserCOMAPI-8 1 0-DeveloperGuide

Diunggah oleh

Hak Cipta:

Format Tersedia

Armor

TRUSTEDUSER COM API

Copyright  2001, 2002 by OrbiTech Solutions

N. Siva Subramanian siva.subramanian@orbitech.co.in

1.2 Executive Summary

1.5 About this Guide

1.5.3 How this guide is organized

Chapter 2: Functional Coverage

Armor: Developer’s Guide – Trusted User COM API Page 1 of 7

Armor: Developer’s Guide – Trusted User COM API Page 2 of 7

2.1.1 Non Interactive User Authentication Service

2.2 Other Features

2.3 Compilation and Runtime Settings

2.3.1 Compilation Settings

2.3.2 Run-Time Settings

Armor: Developer’s Guide – Trusted User COM API Page 3 of 7

3.1 API Library Initialization

3.1.1 API Instantiation

Dim objATU as New TrustedUser

‘Object reference should be kept in global storage.

VARIANT DoLogin ( void )

Dim varRetVal as Variant, varError as Variant

Armor: Developer’s Guide – Trusted User COM API Page 4 of 7

3.3 Ticket Retrieval

VARIANT GetTicket ( VARIANT *varTicket )

Dim varRetVal as Variant, varError as Variant, varTicket as Variant

varRetVal = ObjATU.GetTicket( varTicket)

Armor: Developer’s Guide – Trusted User COM API Page 5 of 7

VARIANT DoLogout ( void )

The following code depicts how DoLogout method should be invoked.

Dim varRetVal as Variant, varError as Variant

Armor: Developer’s Guide – Trusted User COM API Page 6 of 7

VARIANT GetArmorError( VARIANT *varError );

The following code depicts how GetArmorError method should be invoked.

Dim varError as Variant, varRetVal as Variant

varRetVal = GetArmorError ( varError )

Armor: Developer’s Guide – Trusted User COM API Page 7 of 7

Anda mungkin juga menyukai