Chapter 11
Token Authentication API Functions
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 |
The TCPware ACE/Client API routines support the following programming languages:
|
BASIC |
C |
MACRO |
PL1 |
|
BLISS |
FORTRAN |
PASCAL |
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.
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.
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.
The following pages include the function descriptions.
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
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.
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.
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.
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.
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.
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
