NAME

Authen::ACE - Perl extension for accessing a SecurID ACE server

SYNOPSIS

  use Authen::ACE;
  $ace = new Ace([config => /config/directory])
  $ace->Check(code, username);
  $ace->PIN(PIN, [cancel]);
  $ace->Next(code);
  $ace->Auth([username]);

DESCRIPTION

Authen::ACE provides a client interface to a Security Dynamics SecurID ACE server. SecurID authentication can be added to any Perl application using Authen::ACE.

Instantiation of an object into the Authen::ACE class will establish a connection to the ACE server; destruction of the object will close the connection. Programs can then use the Check/PIN/Next methods to authorize a user. TTY programs can also use the Auth method, which handles all authorization tasks normally done by Check/PIN/Next.

METHODS

new

 $ace = new Ace(["config" => "/config/directory"])

Creates a new Authen::ACE object. The config parameter specifies the location of the sdconf.rec file. It defaults to the value of the VAR_ACE environment variable, or the directory /var/ace if this variable isn't set.

Check

 ($result,$info) = $ace->Check(code, username)

This is the primary user authentication function. code is the PIN+token (or just the token if the user has no PIN), and username is the user's name, as it is listed in the ACE database.

Check returns a two-element list. The first element contains the results of the check; the second element contains extra, result-specific information.

Possible results for $result are

ACM_OK

The check succeeded. $info contains the shell specified for this user.

ACM_ACCESS_DENIED

The check failed. No other information is included.

ACM_NEXT_CODE_REQUIRED

The check succeeded, but requires a second token to finish the authentication. $info contains the number of seconds the server will waits for the next code. Authen::ACE::Next should be called with the next code upon receiving this result.

ACM_NEW_PIN_REQUIRED

A new PIN is required. $info is a ref to an anonymous hash with the following elements

system_pin

The system generated PIN.

min_pin_len

The minimum PIN length.

max_pin_len

The maximum PIN length.

alphanumeric

True is the PIN is allowed to be alphanumeric

user_selectable

Will have one of the values CANNOT_CHOOSE_PIN, MUST_CHOOSE_PIN, USER_SELECTABLE, which mean that the user must accept the system generated PIN, must choose his own PIN, or can do either.

If the user accepts the system PIN or chooses his own, then a call should be made to Authen::ACE::PIN with the selected PIN. If the user rejects the system PIN, then a call should be made to Authen::ACE::PIN with the value of the cancel parameter set to 1.

Next

 ($result,$info) = $ace->Next(code)

This method should be called after receiving a ACM_NEXT_CODE_REQUIRED result from Check. code should be the next to display on the user's token. Return value is the same as for Authen::ACE::Check, except that there will never be a ACM_NEW_PIN_REQUIRED or ACM_NEXT_CODE_REQUIRED result.

PIN

 $result = $ace->PIN(pin, [cancel]);

This method should be called after receiving a ACM_NEW_PIN_REQUIRED result from Check. pin should be the new PIN, while cancel should be set to one if the user wishes to cancel the new PIN operation. Authen::ACE::PIN will return a result of either ACM_NEW_PIN_ACCEPTED or ACM_NEW_PIN_REJECTED.

Auth

 ($result,$info) = $ace->Auth([username]);

This method is a convenience method which will handle calling Check, and reading a new PIN or requesting the next token if required. It should only be called if the running process is attached to a tty. username will be determined by the real PID of the process running the program if it isn't passed as a parameter.

The return value is the same as for Authen::ACE::Check, except that there will never be a ACM_NEW_PIN_REQUIRED or ACM_NEXT_CODE_REQUIRED result.

AUTHOR

Dave Carrigan <Dave.Carrigan@iplenergy.com>

Copyright (C) 1997 Dave Carrigan, Interprovincial Pipe Line Inc. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

SEE ALSO

perl(1), ACE/Server Administration Manual, ACE/Server Client API Guide