NAME
SecurID::ACEdb - Perl extension to use the ACE/Server Administration Toolkit API
SYNOPSIS
use SecurID::ACEdb qw(:basic func1 func2 ...)
use SecurID::ACEdb qw(:all);
ApiInit();
...
ApiEnd();DESCRIPTION
The ACE/Server Administration Toolkit API is used to create custom administration applications for ACE/Server, specifically functions that can read and modify the ACE/Server databases.
FUNCTIONS
All functions must be explicitly imported into the namespace. The import tag basic imports ApiInit, ApiEnd, and Result. The import tag all imports all functions.
Unless otherwise documented, all function calls return 1 if the function succeeded, 0 otherwise.
Result
$result = Result();Returns the result of the last operation as a string. This should be called whenever any function fails to determine the cause of the failure.
ApiInit
ApiInit([commitFlag => v]);Initializes and connects to the ACE/Server databases. This is required before subsequent SecurID::ACEdb functions can be called. The commitFlag should be set to true to automatically commit database changes. If not set, then the Commit and Rollback functions can be used to define transactions. This function can only be called once in any program. It cannot even be called a second time after calling ApiEnd. Don't blame me; blame Security Dynamics.
Commit
Commit();Commits all API function calls to the database since the last commit or rollback. Only needed if ApiInit was not called with a commitFlag of true.
Rollback
Rollback();Rolls back all API function calls since the last commit or rollback. Only needed if ApiInit was not called with a commitFlag of true.
ApiEnd
ApiEnd();Finishes the API session. Once this function is called, no subsequent API functions can be called, including ApiInit.
ApiRev
$rev = ApiRev()Returns the revision number of the API, as a string.
AssignToken
AssignToken($lastname, $firstname, $login, $shell, $serial);Adds a user to the database and assigns the token specified by $serial. The token is enabled, the PIN is cleared, and both BadTokenCodes and BadPINs are set to zero.
SetUser
SetUser($lastname, $firstname, $login, $shell, $serial);Sets an existing user's information as specified by the parameters. The token serial number is used to locate the user in the database, so this function cannot be used to change a user's token.
ListUserInfo
$userinfo = ListUserInfo($serial);Returns user information for a user who owns the specified token. The user information is returned in a hashref which contains the keys userNum, lastName, firstName, defaultLogin, createPIN, mustCreatePIN, defaultShell, tempUser, dateStart, todStart, dateEnd, and todEnd. Returns undef if there was an error.
UnassignToken
UnassignToken($serial)Unassigns the token and deletes the user from the database. The user must be removed from all groups and not be enabled on any clients before calling this function.
SetCreatePin
SetCreatePin($state, $serial);Sets the createPIN modes for the user related to $serial. $state should be a string containing one of the values USER, SYSTEM, or EITHER.
AddUserExtension
AddUserExtension($key, $data, $serial);Adds a user extension record for the user related to $serial. The data field can be no more than 80 characters, while the key field must be no more than 48 characters.
DelUserExtension
DelUserExtension($key, $serial);Deletes a user extension record for the user related to $serial.
ListUserExtension
$ext = ListUserExtension($key, $serial);Returns the user extension data for the specified key of the user related to $serial. Returns undef if there was an error.
SetUserExtension
SetUserExtension($key, $data, $serial);Sets data in an existing extension field for the user related to $serial.
DisableToken
DisableToken($serial);Disables the token so that the related user cannot authenticate.
EnableToken
EnableToken($serial);Enables the token so that the related user can authenticate.
ListTokens
@list = ListTokens();Returns a list of all tokens in the database, or an empty list if there was an error. Note that the underlying C API requires this function to be called multiple times to get the entire list; the Perl version does not require this. If a call to the function other than the first results in an error, ListTokens will return a partial list, and will not notify the caller of any error condition. The caller should examine the value of Result(); if it is not Done, then the entire list was not returned.
ListTokenInfo
$info = ListTokenInfo($serial);Returns a hashref containing token information, or undef if there was an error. The hashref contains the keys serialNum, pinClear, numDigits, interval, dateBirth, todBirth, dateDeath, todDeath, dateLastLogin, todLastLogin, type, hex, enabled, newPINMode, userNum, nextTCodeStatus, badTokenCodes, badPINs, datePIN, todPIN, dateEnabled, todEnabled, dateCountsLastModified, and todCountsLastModified.
ResetToken
ResetToken($serial);Resets the token to a known state, so that the token is enabled, next token code mode is off, bad token codes is zero, and bad PINs is zero. This should be done before assigning the token to a user or to remedy token problems.
NewPin
NewPin($serial)Puts the token into new PIN mode.
AddLoginToGroup
AddLoginToGroup($login, $group, $shell, $serial);Adds the user login to a group in the database. The group must exist and the login must be unique to the group. The shell can be an empty string.
DelLoginFromGroup
DelLoginFromGroup($login, $group);Deletes the login name from a group.
ListGroupMembership
$groups = ListGroupMembership($serial);Lists the groups that a token has been assigned to. Returns a listref or undef if there was a problem. Each element of the list is a hashref containing the keys userName, shell, and group.
ListGroups
$groups = ListGroups();Lists the groups in the ACE/Server database. Returns a listref or undef if there was a problem. Each element of the list is a hashref containing the keys group and siteName.
EnableLoginOnClient
EnableLoginOnClient($login, $client, $shell, $serial);Enables a user login on a client. The client must exist and the login must be unique to the client. The shell can be an empty string.
DelLoginFromClient
DelLoginFromClient($login, $client);Disables a user login from a client.
ListClientActivations
$list = ListClientActivations($serial);Lists the clients that a token is activated on. Returns a listref or undef if there was an error. Each element of the list is a hashref containing the keys login, shell, clientName, and siteName.
ListClientsForGroup
$list = ListClientsForGroup($group);Lists the clients associated with a group. Returns a listref or undef if there was a problem. Each element of the list is a hashref containing the keys clientName and siteName.
ListClients
$list = ListClients();Returns a list of all clients in the database. Returns a listref or undef if there was a problem. Each element of the list is a hashref containing the keys clientName and siteName.
ListSerialByLogin
@serial = ListSerialByLogin($login, [$count]);Looks up the token serial number belonging to the user with login name $login. $count specifies which instance of $login to use if there are multiple instances, and defaults to 1. Returns a listref to the serial numbers assigned to $login. Returns an empty listref if the user does not exist, or if the count was too high, and returns undef if there was another error.
ListHistory
$hist = ListHistory($days, $serial, [$filter]);Lists the events in the activity log affecting token $serial. $days specifies the number of days prior to the present date to list the history for. If $filter is true, events performed by an administrator will be filtered from the list, making it easier to view authentication events. Returns a listref or undef if there was a problem. Each element of the list is a hashref containing the keys msgString, localDate, localTOD, login, affectedUserName, groupName, clientName, siteName, serverName, and messageNum.
MonitorHistory
MonitorHistory([$filename, [$close]]);Docs tbd.
DumpHistory
DumpHistory($month, $day, $year, [$days, [$filename, [$truncate]]]);Dumps the affected events in the log. If $filename is provided, specifies a filename to dump the log to. $filename can also be the empty string. The affected events start at the beginning of the log and end one day prior to the date specified by the $month, $day, and $year parameters. $year should be a 4-digit number. If the $days parameter is non-zero, then the first three parameters are ignored, and the $days parameters specifies the number of days prior to today's date that are not affected. If the $truncate option is set, the entries will be removed from the log.
AUTHOR
Dave Carrigan <Dave.Carrigan@cnpl.enbridge.com>
SEE ALSO
perl(1).