Authen-ACE4
view release on metacpan or search on metacpan
=head1 NAME
Authen::ACE4 - Perl extension for accessing a SecurID ACE server or RSA Authenticaiotn Manager
=head1 SYNOPSIS
use Authen::ACE4;
AceInitialize();
($result, $handle, $moreData, $echoFlag, $respTimeout,
$nextRespLen, $prompt)
= AceStartAuth($username);
($result, $moreData, $echoFlag, $respTimeout,
$nextRespLen, $prompt)
= Authen::ACE4::AceContinueAuth($handle, $resp);
($result, $status)
= Authen::ACE4::AceGetAuthenticationStatus($handle);
$result = AceCloseAuth($handle);
=head1 DESCRIPTION
Authen::ACE4 provides a client interface to a Security Dynamics SecurID
ACE server. It uses the ACE/Agent client libraries.
SecurID authentication can be added to any Perl
default is /var/ace/data. If your sdconf.rec is in a different location
you must specify VAR_ACE eg:
$ENV{VAR_ACE} = '/opt/ace/data';
before calling AceInitialize.
=item AceStartAuth
($result, $handle, $moreData, $echoFlag, $respTimeout,
$nextRespLen, $prompt)
= Authen::ACE4::AceStartAuth($username);
The AceStartAuth function is designed to be used aling with
AceContinueAuth and AceCloseAuth.
AceStartAuth is the first step in authenticating a user. If the
function returns successfully, continue to call AceContinueAuth as
long as $moreData is true.
If AceStartAuth returns successfully, AceCloseAuth must be called
Returned data is
=over 4
=item result
Indicates the success or failure of the call (but not success
of the authentication, see AceGetAuthenticationStatus for that).
If the call succeeds, $handle, $moreData etc will be set. If
the call fails, only $result and $prompt will have meaningful values.
Possible results for $result are
=over 4
=item ACM_OK
The call succeeded. $handle contains the handle for this context
=item ACE_INIT_NO_RESOURCE
A flag that indicate whether more data is needed by the
authentication context.
=item echoFlag
A flag that gives a hint to the developer whether the next response
should be echoed on the screen.
=item respTimeout
A hint to the developer about how long to display this prompt
string to the user.
=item nextRespLen
Indicates the maximum number of bytes of data expected in the next
call to AceContinueAuth
=item prompt
Message string that should be shown to the user as the request for
data to be passed to the next call to AceContinueAuth.
=back
=item AceContinueAuth
($result, $moreData, $echoFlag, $respTimeout,
$nextRespLen, $prompt)
= Authen::ACE4::AceContinueAuth($handle, $resp);
AceContinueAuth should continue to be called for as long as
it succeeds and $moreData is true. Each successive call will
ask for additional data required for the authentication to be
entered by the user.
After AceContinueAuth returns with moreDat false, use
AceGetAuthenticationStatus to check the result of the
=over 4
=item handle
The opaque handle for this authentication context, previously returned
by AceStartAuth.
=item resp
The response from the user to the prompt from the previous AceStartAuth
or AceContinueAuth.
=back
Returned data is
=over 4
=item result
Indicates the success or failure of the call (but not success
of the authentication, see AceGetAuthenticationStatus for that).
If the call succeeds, $moreData, $echoFlag etc will be set. If
the call fails, only $result and $prompt will have meaningful values.
Possible results for $result are
=over 4
=item ACM_OK
The call succeeded. $handle contains the handle for this context
=item ACE_CHECK_INVALID_HANDLE
A flag that indicate whether more data is needed by the
authentication context.
=item echoFlag
A flag that gives a hint to the developer whether the next response
should be echoed on the screen.
=item respTimeout
A hint to the developer about how long to display this prompt
string to the user.
=item nextRespLen
Indicates the maximum number of bytes of data expected in the next
call to AceContinueAuth
=item prompt
Message string that should be shown to the user as the request for
data to be passed to the next call to AceContinueAuth.
=back
=item AceGetAuthenticationStatus
($result, $status) = Authen::ACE4::AceGetAuthenticationStatus($handle);
AceStartAuth(userID)
char* userID
PPCODE:
STRLEN userIDLen;
SDI_HANDLE handle;
SD_BOOL moreData;
SD_BOOL echoFlag;
SD_I32 respTimeout;
SD_I32 nextRespLen;
char promptStr[512];
SD_I32 promptStrLen = sizeof(promptStr);
SD_ERROR result;
// Need the real length of the string
userID = (char *)SvPV(ST(0), userIDLen);
result = AceStartAuth(&handle, userID, userIDLen,
&moreData, &echoFlag, &respTimeout,
&nextRespLen, promptStr, &promptStrLen);
// Always push the result, and, if successful
// the rest
EXTEND(sp, 5);
PUSHs(sv_2mortal(newSViv(result)));
PUSHs(sv_2mortal(newSViv(handle)));
PUSHs(sv_2mortal(newSViv(moreData)));
PUSHs(sv_2mortal(newSViv(echoFlag)));
PUSHs(sv_2mortal(newSViv(respTimeout)));
PUSHs(sv_2mortal(newSViv(nextRespLen)));
PUSHs(sv_2mortal(newSVpv(promptStr, strlen(promptStr))));
void
AceContinueAuth(handle, resp)
int handle
char* resp
PPCODE:
STRLEN respLen;
SD_BOOL moreData;
SD_BOOL echoFlag;
SD_I32 respTimeout;
SD_I32 nextRespLen;
char promptStr[512];
SD_I32 promptStrLen = sizeof(promptStr);
SD_ERROR result;
// Need the real length of the string
resp = (char *)SvPV(ST(1), respLen);
result = AceContinueAuth(handle, resp, respLen,
&moreData, &echoFlag, &respTimeout,
&nextRespLen, promptStr, &promptStrLen);
// Always push the result, and, if successful
// the rest
EXTEND(sp, 5);
PUSHs(sv_2mortal(newSViv(result)));
EXTEND(sp, 4);
PUSHs(sv_2mortal(newSViv(moreData)));
PUSHs(sv_2mortal(newSViv(echoFlag)));
PUSHs(sv_2mortal(newSViv(respTimeout)));
PUSHs(sv_2mortal(newSViv(nextRespLen)));
// Sigh: promptStrLen is unreliable with the 6.1 SDK and AM 7.1
PUSHs(sv_2mortal(newSVpv(promptStr, strlen(promptStr))));
int
AceGetAuthenticationStatus(handle)
int handle
PPCODE:
SD_I32 authStatus = ACM_ACCESS_DENIED;
RETVAL = AceGetAuthenticationStatus(handle, &authStatus);
EXTEND(sp, 1);
Patch contributed by "Paul Ewing Jr." <ewing@ima.umn.edu> adding
asynchronous client interface, Pin SD_Init SD_Check SD_Next etc.
Thanks Paul!
1.2 16 Jun 2004
Improved compile on Windows Server 2003 with latest Windows SDK
1.3 2008-12-16
- Added AceSetUserClientAddress, but it appears only to be useful with
AceClientCheck, which is not yet implemented.
- Reduced size of prompt strings in line with RSA suggestions.
- Workaround for a bug in the AceAgent 6.1 SDK: AceContinueAuth promptStrLen
is unreliable.
- Modified Makefile.PL to work with SDK version 6.1.
- Updated doc for SDK version 6.1, which is now preferred.
1.4 2012-01-02
- Testing against RSA AuthSDK 8.1 on Unix and Windows. Updated documentation to
reflect this. AuthSDK 8.1 is now the preferred SDK version and
RSA Authentication Manager 7.1 is preferred over ACE Server.
- Improved building with Makefile.PL
location of a writeable directory containing the sdconf.rec file, else the
make test portion may fail. The sdconf.rec file is a ACE/Agent configuration
file that specifies how to contact the ACE/Server or Authentication
Manager. You must create and download this from the Authentication Manager
(see above). The files in that directory must be readable and writeable, and
this generally means running Authen-ACE4 as root.
Because the interactive nature of SecurID requires you to enter a
time-sensitive token from a card, you cannot automate the test suite.
An ACE server will never accept the same token twice, so during the
testing, you may be prompted to wait for the token on the card
to change before continuing with the test.
The test program will display all codes in plain text.
For token authentication to succeed, it is vital that the Authentication
Manager server has the right time and timezone set.
By default Authentication Manager uses port 5500 for ACE authentication.
Caution: The Unix ACE4 client requires that the hostname on the client be the
eg/simple.pl view on Meta::CPAN
use Authen::ACE4;
my $username = 'mikem';
Authen::ACE4::AceInitialize();
print "Enter Username:\n";
$username = <>;
chomp $username;
($result, $handle, $moreData, $echoFlag, $respTimeout, $nextRespLen, $prompt) = Authen::ACE4::AceStartAuth($username);
die "AceStartAuth failed: $prompt\n"
unless $result == Authen::ACE4::ACM_OK;
while ($moreData)
{
print "$prompt\n";
$resp = <>;
chomp $resp;
($result, $moreData, $echoFlag, $respTimeout, $nextRespLen, $prompt) = Authen::ACE4::AceContinueAuth($handle, $resp);
die "AceContinueAuth failed: $prompt\n"
unless $result == Authen::ACE4::ACM_OK;
}
print "$prompt\n";
($result, $status) = Authen::ACE4::AceGetAuthenticationStatus($handle);
# If $result is ACE_SUCCESS, then $status is defined, and
# indicates ACM_OK, ACM_ACCESS_DENIED etc
$result = Authen::ACE4::AceCloseAuth($handle);
exit $status;
# your sdconf.rec. Ttry setting the VAR_ACE environment variable
# to the correct path to your data directory
Authen::ACE4::AceInitialize();
printok($testno++, 1, 'failed to initialize');
print "enter a SecurID username to test with:\n";
$username = <>;
chomp $username;
($result, $handle, $moreData, $echoFlag, $respTimeout,
$nextRespLen, $prompt)
= Authen::ACE4::AceStartAuth($username);
printok($testno++, $result == ACM_OK, "AceStartAuth failed: $prompt");
while ($moreData)
{
print "$prompt\n";
$resp = <>;
chomp $resp;
($result, $moreData, $echoFlag, $respTimeout,
$nextRespLen, $prompt)
= Authen::ACE4::AceContinueAuth($handle, $resp);
printok($testno++, $result == ACM_OK, "AceContinueAuth failed: $prompt");
}
($result, $status) = Authen::ACE4::AceGetAuthenticationStatus($handle);
# If $result is ACE_SUCCESS, then $status is defined, and
# indicates ACM_OK, ACM_ACCESS_DENIED etc
printok($testno++, $result == ACE_SUCCESS, 'AceGetAuthenticationStatus failed');
printok($testno++, $result == ACE_SUCCESS && $status == ACM_OK, "Authentication failed: $prompt");
($result, $shell) = Authen::ACE4::AceGetShell($handle);
printok($testno++, $result == ACE_SUCCESS, 'AceGetShell failed');
# These wont yield useful data, but test the calls anyway
($result, $alpha) = Authen::ACE4::AceGetAlphanumeric($handle);
printok($testno++, $result == ACE_SUCCESS, 'AceGetAlphanumeric failed');
($result, $maxpin) = Authen::ACE4::AceGetMaxPinLen($handle);
( run in 1.427 second using v1.01-cache-2.11-cpan-0b5f733616e )