## TCPware V5.7 Programmer's Guide

- Introduction
- Supported Languages
- How to Use Functions
- Header Files
- Activating Program Shareable Image
- Function Reference

Chapter 11

Token Authentication API Functions

# Introduction

This chapter is for application programmers. It describes the Application Programming Interface (API) to enable Token Authentication between the TCPware ACE/Client and the Security Dynamics ACE/Server.

See Chapter 25, Token Authentication Management, in the Management Guide for details on the TCPware ACE/Client, PASSCODES, and tokens.

The Token Authentication Application Programming Interface (API) on the TCPware ACE/Client includes the following functions:

creadcfg | Loads the Security Dynamics ACE/Server configuration file into memory
sd_auth | Combines the functions of sd_check, sd_next, and sd_pin
sd_check | Provides the PASSCODE collected from the user and the username for authentication
sd_close | Destroys the socket initialized using sd_init
sd_init | Initializes the socket and makes a verification call to the Security Dynamics ACE/Server
sd_next | Handles the processing of a second tokencode when one is required to complete an authentication
sd_pin | Handles the case of a new PIN required at login

# Supported Languages

The TCPware ACE/Client API routines support the following programming languages:

BASIC | C | MACRO | PL1
BLISS | FORTRAN | PASCAL |

# How to Use Functions

Use the creadcfg routine first. This routine loads the configuration file into memory. The sd_init routine initializes the socket and makes a call to the server to verify communication. Use this call after a successful call to creadcfg and before calling any other API function.

If your program performs the user input/output, use the three functions sd_check, sd_pin, and sd_next. Do not use sd_check without the other two functions. Use the sd_auth routine instead of these previous three routines only if stdin or stdout are available for user interaction. If using sd_auth, do not also use sd_check, sd_pin, and sd_next.

# Header Files

You must include the following header files in all programs:

• sdi_athd.h

• sdconf.h

Programs that use sd_check, sd_pin, and sd_next must also include these header files:

• sdi_size.h

• sdi_type.h

• sdi_defs.h

• sdacmvls.h

You must include a variable named configure in your code. Make the following global variable declaration:

union config_record configure;

The definition for config_record is included in the header files. The header files are located in the TCPWARE_COMMON:[TCPWARE.INCLUDE] directory.

# Activating Program Shareable Image

You can use one of two methods to activate the SYS$SHARE:TCPWARE_ACECLIENT_SHR.EXE shareable image for your application:

• Link the SYS$SHARE:TCPWARE_ACECLIENT_SHR.EXE file so that it is activated at image creation time. Add the following line in an .OPT file to link in the SYS$SHARE:TCPWARE_ACECLIENT_SHR.EXE shareable image:

SYS$SHARE:TCPWARE_ACECLIENT_SHR.EXE/SHAREABLE

See the OpenVMS Linker Utility Manual for details.

• Use the LIB$FIND_IMAGE_SYMBOL to activate the shareable image at runtime. Use the OpenVMS LIB$FIND_IMAGE_SYMBOL runtime library to activate the shareable image at runtime.

See the OpenVMS RTL Library (LIB$) Manual for details.

# Function Reference

The following pages include the function descriptions.

creadcfg

Reads the ACE/Server configuration file stored in the TCPWARE_ACECLIENT_DATA_DIRECTORY data directory and loads it into memory. The configuration file was created on the ACE/Server during installation and should be copied to the ACE/Client data directory when installing the ACE/Client. The name of the configuration file is SDCONF.REC.

Call this function before any other API function.

Format

int creadcfg(void)

Return Values

0 | Successful
-1 | Failure to load the configuration file (it may be missing or corrupted; do not call any further function

Arguments

None

sd_init

Initializes client/server communication by initializing the socket and making a call to the server to verify communication.

Call this function after a successful call to creadcfg and before calling any other API function. Use sd_close after the authentication process to close the socket initialized by sd_init.

Format

int sd_init(struct SD_CLIENT *sd)

Return Values

0 | Successful
1 | Client unable to communicate with the ACE/server (general communication or configuration problem or the server is not running)

Argument

sd

Pointer to an SD_CLIENT structure. The structure must be set to 0 by the caller before calling sd_init.

sd_auth

Performs all user input/output. This function performs SecurID© authentication dialogues, including all authentication prompts and responses (such as Enter PASSCODE or PASSCODE accepted).

Call this function only after sd_init was called successfully.

Format

int sd_auth(struct SD_CLIENT *sd)

Return Values

ACM_OK | User successfully authenticated
ACM_ACCESS_DENIED | User failed authentication

Argument

sd

Pointer to the SD_CLIENT structure. Specify the login ID by setting the username field in the data structure. If not specified, the API tries to obtain it from the environment.

sd_check

Performs user authentication by checking the validity of the PASSCODE entered by a user. The integrating application must do all input/output because sd_check does not display the authentication prompts and messages (unlike sd_auth).

Call this function only after sd_init was called successfully. Use sd_pin to complete the transaction.

Format

int sd_check(char *passcode, char *username, struct SD_CLIENT *sd)

Return Values

ACM_OK | User successfully authenticated
ACM_ACCESS_DENIED | User failed authentication
ACM_NEXT_CODE_REQUIRED | Next tokencode required; the following field is set in the SD_CLIENT structure: timeout (the number of seconds the server waits for a user to respond to the next-code prompt)
ACM_NEW_PIN_REQUIRED | New PIN required; the following fields are set in the SD_CLIENT structure: system_pinrandom PIN generated by the system min_pin_lengthminimum PIN length max_pin_lengthmaximum PIN length user_selectablecan have one of three values: • CANNOT_CHOOSE_PIN • MUST_CHOOSE_PIN • USER_SELECTABLE alphanumericsPIN can contain letters

Arguments

passcode

Pointer to the NULL-terminated PASSCODE string. The PASSCODE must contain from 4 to 16 characters.

username

Pointer to the NULL-terminated username string. The username must contain fewer than 32 characters.

sd

Pointer to the SD_CLIENT structure.

sd_next

Function used in response to an ACM_NEXT_CODE_REQUIRED return from sd_check. Performs the Next Code operation that takes a second successive tokencode from a user and checks it validity. The integrating application must do all input/output because sd_next does not display the Next Code prompt.

Call this function only in response to an ACM_NEXT_CODE_REQUIRED return from sd_check.

Format

int sd_next(char *nextcode, struct SD_CLIENT *sd)

Return Values

ACM_OK | User successfully authenticated
ACM_ACCESS_DENIED | User failed authentication

Arguments

nextcode

Pointer to the NULL-terminated PASSCODE string. The PASSCODE must contain from 4 to 8 characters.

sd

Pointer to the SD_CLIENT structure.

sd_pin

Function used in response to an ACM_NEW_PIN_REQUIRED return from sd_check. Performs the New PIN operation in which a new PIN is stored in a token record. The integrating application must do all input/output because sd_pin does not display the New PIN prompts and messages.

Call this function only in response to an ACM_NEW_PIN_REQUIRED return from sd_check.

Note! Do not treat users as authenticated as soon as they complete the New PIN operation. Require them to authenticate using the new PIN

Format

int sd_pin(char *pin, char canceled, struct SD_CLIENT *sd)

Return Values

ACM_NEW_PIN_ACCEPTED | New PIN was accepted by the ACE/Server; the user should now be required to authenticate with it
ACM_NEW_PIN_REJECTED | New PIN was rejected by the ACE/Server; the PIN may not have matched the parameters set in the return from sd_check

Arguments

pin

Pointer to the NULL-terminated PIN string. The PIN must contain from 4 to 8 characters.

cancelled

Should equal 0 if a PIN is selected. If a token is in New PIN mode but you do not want to select the PIN at that time, the value should be set to 1.

sd

Pointer to the SD_CLIENT structure.

sd_close

Closes the socket opened by sd_init.

Call this function after attempting to authenticate the user regardless whether or not the authentication was successful.

Format

void sd_close(void)

Return Values

None

Arguments

None