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

Authen-ACE documentation Contained in the Authen-ACE distribution.

Index

Code Index:

NAME

Top

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

SYNOPSIS

Top

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

DESCRIPTION

Top

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

Top

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

Top

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

Top

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

Authen-ACE documentation Contained in the Authen-ACE distribution. 
# $Id: ACE.pm,v 1.8 1997/12/09 18:33:45 carrigad Exp $

# Copyright (C), 1997, Interprovincial Pipe Line Inc.

package Authen::ACE;

use strict;
use Carp;
use vars qw($VERSION @ISA @EXPORT @EXPORT_OK $AUTOLOAD);

require Exporter;
require DynaLoader;

@ISA = qw(Exporter DynaLoader);
@EXPORT = qw(
	ACM_OK
	ACM_ACCESS_DENIED
	ACM_NEXT_CODE_REQUIRED
	ACM_NEW_PIN_REQUIRED
	ACM_NEW_PIN_ACCEPTED
	ACM_NEW_PIN_REJECTED
	CANNOT_CHOOSE_PIN
	MUST_CHOOSE_PIN
	USER_SELECTABLE
);
$VERSION = '0.90';

sub PIN {
  my $self = shift;
  my $pin = shift;
  my $canceled = shift;

  return sd_pin($pin, $canceled, $self->{"sd"});
}

sub Next {
  my $self = shift;
  my $token = shift;
  return sd_next($token, $self->{"sd"});
}

sub Auth {
  my $self = shift;
  my $username = shift;
  return sd_auth($self->{"sd"}, $username);
}

sub Check {
  my $self = shift;
  my ($passcode, $username) = @_;
  die 'usage: $ace->check(passcode, username)' if ($passcode eq "" or $username eq "");

  my @results = sd_check($passcode, $username, $self->{"sd"});
  if ($results[0] == ACM_NEW_PIN_REQUIRED()) {
    $results[1] = {"system_pin" => $results[1],
		   "min_pin_len" => $results[2],
		   "max_pin_len" => $results[3],
		   "user_selectable" => $results[4],
		   "alphanumeric" => $results[5]};
    $#results = 1;
  }
  return @results;
}

sub new {
  my $type = shift;
  my %parms = @_;
  my $self = {};

  $ENV{"VAR_ACE"} = "/var/ace" unless defined($ENV{"VAR_ACE"});
  $ENV{"VAR_ACE"} = $parms{"config"} if defined $parms{"config"};

  if (creadcfg() != 0) {
    die "Could not read ACE client configuration file in " . $ENV{"VAR_ACE"} . "\n";
  }

  $self->{"sd"} = sd_init();
  die "Failed call to sd_init\n" unless defined $self->{"sd"};

  bless $self, $type;
}

sub DESTROY {
  my $self = shift;
  if (ref($self->{"sd"}) eq "SDClientPtr") {
    sd_close();
    undef $self->{"sd"}
  }
}

sub AUTOLOAD {
    my $constname;
    ($constname = $AUTOLOAD) =~ s/.*:://;
    my $val = constant($constname, @_ ? $_[0] : 0);
    
    if ($! != 0) {
	if ($! =~ /Invalid/) {
	    $AutoLoader::AUTOLOAD = $AUTOLOAD;
	    goto &AutoLoader::AUTOLOAD;
	}
	else {
		croak "Undefined ACE macro $constname";
	}
    }
    eval "sub $AUTOLOAD { $val }";
    goto &$AUTOLOAD;
}

bootstrap Authen::ACE $VERSION;


1;
__END__