ActivID SKI Connector Service API Functions

Summary

Login

Call Description

Login

Use this call for static administrative user authentication in order to log in to the ActivID SKI Connector. The handle returned is used for all subsequent calls to the SKI Connector service.

LoginDynamic

Use this call for dynamic administrative user authentication to the ActivID SKI Connector. You must dynamically generate the password using a challenge obtained by GetChallenge.

GetChallenge

The challenge returned by this call is stored in memory. It is associated with the request unique client identifier (challenge handle) and handle for retrieval when using LoginDynamic.

Logout

Logs out of the ActivID SKI Connector. The associated login handle is invalid after the logout and should not be used.

Credential Management

Call Description
GetCredentials Unpublished
canActivateDevice Check if the given user belongs to a group that has right to activate device of the given type. For Soft Token v2 device types, also check if max count of soft tokens allowed per user is reached or not.
deleteDevice Deletes the specified device. The device is removed from the administration and server databases. No checking is done as to whether the device is assigned or not in the directory.
lockDevice Locks the specified device (equivalent to Manual Locking).
unlockDevice Unlocks the specified device (equivalent to Unlock and Reset Number of Tries).
AssignDeviceToUser Assigns the specified device to the specified user.
UnassignDevice Unbinds the specified device from the specified user.
addDevice Add a newly activated device in the admin database, and assign it to the given user. For soft token v2 device types, the function prevents the adding if max count of soft tokens allowed per user is reached.
getDeviceInfo Retrieves device information.
getDeviceInfoEx Return device information.
getUnlockPINCode Retrieves credentials with which to unlock the device PIN code.
HasMiniTokenPIN Returns a Boolean indicating whether or not the PIN code is set for the specified Mini Token.
SetMinTokenPinCode Sets the PIN code of the specified Mini Token.
SynchronousAHAndResynchronize Performs an extended authentication of the registry settings. The registry flag ExtendedAuthCounter indicates the number of counters in advance the authentication takes into account If authentication is successful:
AssignDeviceToUserEx Assigns the specified device to the specified user. The bIgnoreAlreadyAssigned parameter allows you to assign a device that is already assigned to another user.
GetDeviceInitialPIN Retrieves the initial PIN code of a device. If the logged operator does not have sufficient rights, the call returns “” (an empty string) as the PIN.
AssignSMSToken Creates a new SMS Token device in the database, and then assigns that new token to the specified user.
setSMSTokenPIN Set (and thereby change if already set) the PIN on an existing token for a user.

Resynchronization

Call Description

ResynchronizeByPasswordEx

Resynchronizes the devices.

ResynchronizeByPassword

Obsolete; use ResynchronizeByPasswordEx instead.

ResynchronizeByCounterAndClock

Resynchronizes the device using counter and clock values.

ResynchronizeSoftToken

Resynchronizes a soft token on the server and returns the counter value for use on the client.

Consolidation

Call Description

consolidateServerAhLog

Starts log consolidation.

getConsolidationStatus

Returns the consolidation status. For example, when consolidation has started, but the number of logs to consolidate is unknown, then the totalLogs parameter returned in the structure is –1.

getAhLog

Returns logs. The ordering of the logs depends on “orderBy,” that is, 1 for server name ordering, 2 for user ID, or 3 for log time ordering.

getAhLogEx

The ordering of the logs depends on the orderBy parameter; that is, 1 for server name ordering, 2 for user ID, or 3 for log time ordering.

ClearLogs

Clears all log rows where the date is anterior to the date passed in parameter.

Other High-Level Calls

Call Description

GetVersion

Warning: Signature changed, handle no longer to be passed for this call. To be communicated to existing integrators.

GetUserInfo

Gets the user information.

Emergency Passwords

Call Description

SetLdapEmergencyPassword

Sets the LDAP emergency password.

SetTempPassword

Empty - allow removal of temporary password activation

SetSMSBackup

Sets the SMS Backup for the user.

UserHasMobilePhone

Verify that the user has a mobile phone.

getRandomAlphaNum

Retrieves a random alphanumerical string. This call gives the administrator the ability to randomly generate a temporary password.

Low-Level Calls

Call Description

GetQueries

Returns all available LDAP queries

GetServers

Retrieves an array of servers.

GetGroups

Retrieves the list of the defined AAA Server groups as an array.

SearchUsers

Search for users.

SearchUsersFromGroup

Retrieves the list of the users who are members of the specified AAA Server group.

GetParameters

Get SKI Group parameters.

Echo

Echo the given message back.

Login Calls

Login

Use this call for static administrative user authentication in order to log in to the ActivID SKI Connector. The handle returned is used for all subsequent calls to the SKI Connector service.

Parameters

BSTR LoginUid

User login ID

BSTR LoginPwd

User password

long Timeout

Timeout in seconds to use in all calls thereafter.

Returns

long

Login handle, to pass to all calls after successful login.

SOAP Exceptions

ACTIVPACK_HDAPI_INVALID_CREDENTIALS

ACTIVPACK_HDAPI_CANNOT_OPEN_DB

ACTIVPACK_HDAPI_CANNOT_UPDATE_DB

ACTIVPACK_HDAPI_DBINTEGRITY

ACTIVPACK_HDAPI_AUDIT_CANNOT_LOG_TO_HD

ACTIVPACK_HDAPI_DB_ERR

All administrative users:

  • Administrator
  • Help Desk Operator
  • Device Manager

SUID

Administrative userID

OBJECT

Logon

OBJNAME

HostName

OPERATION

Success / Failure

LoginDynamic

Use this call for dynamic administrative user authentication to the ActivID SKI Connector. You must dynamically generate the password using a challenge obtained by GetChallenge.

Parameters

BSTR LoginUid

User login ID

BSTR LoginPwd

User password

long chalHandle

Challenge handle

long Timeout

Tmeout in seconds to use in all calls thereafter.

Returns

long

Login handle to pass to all calls after successful login.

SOAP Exceptions

ACTIVPACK_HDAPI_INVALID_CREDENTIALS

ACTIVPACK_HDAPI_CANNOT_OPEN_DB

ACTIVPACK_HDAPI_CANNOT_UPDATE_DB

ACTIVPACK_HDAPI_DBINTEGRITY

ACTIVPACK_HDAPI_AUDIT_CANNOT_LOG_TO_HD

ACTIVPACK_HDAPI_DB_ERR

Authorization Required

All administrative users:

  • Administrator
  • Help Desk Operator
  • Device Manager

Audit

SUID

Administrative userID

OBJECT

Logon

OBJNAME

HostName

OPERATION

Success / Failure

GetChallenge

The challenge returned by this call is stored in memory. It is associated with the request unique client identifier (challenge handle) and handle for retrieval when using LoginDynamic.

Only a given number of successive calls (registry set, DWORD value ChallengeRetryAllowed, default: 10) for a single IP address unique client identifier, without any successful call to LoginDynamic, are allowed per given period of time (registry set, DWORD value ChallengeRetryInterval in minutes, default: 60). This method is used to avoid a certain class of brute force attacks against the challenge.

It is the responsibility of the integrator to build the unique client identifier.

Use of the client IP address as a unique identifier is not recommended if a NAT or proxy is located between the client and the application integrating the ActivID SKI Connector.

Parameters

long chalHandle

Challenge handle

Returns

BSTR Challenge

SOAP Exceptions

None

Authorization Required

Authorization: Public call, no administrative privilege required.

Audit

None

Logout

Logs out of the ActivID SKI Connector. The associated login handle is invalid after the logout and should not be used.

Parameters

long handle

Login handle

SOAP Exceptions

None

Authorization Required

Authorization: All operators already connected and End Users.

  • Administrator
  • Help Desk Operator
  • Device Manager
  • End User (Self Help Desk)

Audit

SUID

Administrative userID/end user ID

OBJECT

Logoff

OBJNAME

HostName

Credential Management

GetCredentials

Unpublished

This call generates the SKI keys for a given device. These keys can then be injected in the target device in order to allow for the generation of OTP credentials. The keys are also pushed into the AAA Servers so that they can subsequently validate the OTP generated by the devices.

The structure returned contains SDB info and is defined as follows:

struct skiCredentials {

BSTR syncdesalgorithmversion;

BSTR syncdessynchronouskey;

int syncdevicemaskversion;

int syncresponseformat;

int syncresponselength;

int syncusecheckdigitonresponse;

int syncauthenticationcountervalue;

int syncclockextractbitnumber;

int syncderivationmode;

int syncdeviceoffset;

int syncincrementcounteronsuccess;

BSTR asyncdesasynchronouskey;

BSTR asyncdesalgorithmversion;

int asyncusecheckdigitonchallenge;

int asyncresponseformat;

int asyncresponselength;

BSTR asynclastchallenge;

};

Parameters

long handle

Login handle

BSTR deviceType

Device type

BSTR deviceSn

Device serial number

int type

Encryption: 0 for DES, 1 for 3DES

Returns

skiCredentials

SOAP Exceptions

ACTIVPACK_HDAPI_BAD_RIGHTS

ACTIVPACK_HDAPI_ADIM_NOT_FOUND

ACTIVPACK_HDAPI_PROFILE_FILE_NOT_FOUND

ACTIVPACK_HDAPI_ERROR_GENERATING_SDB

ACTIVPACK_HDAPI_CANNOT_CIPHER_DATA

ACTIVPACK_HDAPI_DEVICE_ALREADY_EXISTS

ACTIVPACK_HDAPI_DB_ERR

Authorization Required

Authorization: All operators already connected except Audit Manager.

  • Administrator
  • Device Manager

Audit

SUID

Administrative userID

OBJECT

Device

OBJNAME

DeviceID

OPERATION

Initialization

canActivateDevice

Checks if the given user belongs to a group that has the right to activate the device of the given type. For Soft Token v2 device types, also checks if the maximum number of soft tokens allowed per user is reached or not.

ActivID AAA Web Help Desk/Self Help Desk side (Java):

Copy 
public String canActivateDevice(
long hLogin,
java.lang.String userID,
java.lang.String deviceType)

ActivID SKI Connector side (C++):

Copy 
HRESULT canActivateDevice(
IN         __int64 hLogin,
IN         BSTR userID,
IN         BSTR deviceType,
OUT         BSTR* pReturnString)

Parameters

hLogin

handle to the user session

userID

User ID for which the check is applied. If the handle to the session corresponds to a self-desk user, then the User ID should be the self-desk user ID (otherwise the function fails).

deviceType

Device type for which the check is applied. Following strings are supported:

  • "DEVICE_TYPE_SOFT_TOKEN"
  • "DEVICE_TYPE_PC_SOFT_TOKEN"
  • "DEVICE_TYPE_WEB_SOFT_TOKEN"
  • "DEVICE_TYPE_MOBILE_SOFT_TOKEN"

Returns

NULL

If "Soft Token v2" activation is not allowed and device type provided as input parameter is not "DEVICE_TYPE_SOFT_TOKEN".

FALSE

If "Soft Token v2" activation is not allowed and device type provided as input parameter is "DEVICE_TYPE_SOFT_TOKEN".

TRUE

If "Soft Token v2" activation is allowed and max number of soft tokens per user is not reached and device type provided as input parameter is "DEVICE_TYPE_SOFT_TOKEN".

TOO_MANY_SOFT_TOKENS

If "Soft Token v2" activation is allowed but max number of soft tokens per user is reached.

The Soft Token v2 init. string corresponding to the device type provided as input parameter

If "Soft Token v2" activation is allowed, the maximum number of Soft Tokens per user is not reached, and the device type provided as input parameter is not "DEVICE_TYPE_SOFT_TOKEN".

In this version of the product, one init string value per type of Soft Token v2 (PC, Mobile, Web) is configurable through the Web Help Desk interface.

SOAP Exceptions

None

Authorization Required

Authorization:

  • Administrator
  • End User

Audit

None

deleteDevice

Deletes the specified device. The device is removed from the administration and server databases. No checking is done as to whether the device is assigned or not in the directory.

Parameters

long handle

Login handle

BSTR deviceType

Device type

BSTR deviceSn

Device serial number

long Reason

Reserved for future use

Returns

bool

True for success

SOAP Exceptions

ACTIVPACK_HDAPI_CANNOTREVOKE_CRED

ACTIVPACK_HDAPI_BAD_RIGHTS

ACTIVPACK_HDAPI_DB_ERR

Authorization Required

Authorization:

  • Administrator
  • Device Manager. If Device Manager is used, then check that the device is in a folder that the Device Manager is allowed to use.

Audit

SUID

Administrative userID

OBJECT

Device

OBJNAME

DeviceID

OPERATION

Delete

lockDevice

Locks the specified device (equivalent to Manual Locking).

Parameters

long handle

Login handle

BSTR deviceType

Device type

BSTR deviceSn

Device serial number

Returns

bool

True for success

SOAP Exceptions

None

Authorization Required

Authorization:

  • Administrator
  • Device Manager. User bound to the device must belong to a user group the operator can manage.
  • Help Desk Operator. User bound to the device must belong to a user group the operator can manage.
  • End User. Only for a device to which the End User is bound.

Audit

SUID

Administrative userID / end user ID

OBJECT

Device

OBJNAME

DeviceID

OPERATION

Helpdesk

OPDETAIL

Lock

unlockDevice

Unlocks the specified device (equivalent to Unlock and Reset Number of Tries).

Parameters

long handle

Login handle

BSTR deviceType

Device type

BSTR deviceSn

Device serial number

Returns

bool

True for success

SOAP Exceptions

None

Authorization Required

Authorization:

  • Administrator
  • Device Manager. User bound to the device must belong to a user group the operator can manage.
  • Help Desk Operator. User bound to the device must belong to a user group the operator can manage.
  • End User. Only for a device to which the End User is bound.

Audit

SUID

Administrative userID / end user ID

OBJECT

Device

OBJNAME

DeviceID

OPERATION

Helpdesk

OPDETAIL

Unlock and reset number of tries

AssignDeviceToUser

Warning: This API still exists but is obsolete; Use AssignDeviceToUserEx.

Assigns the specified device to the specified user.

Parameters

long handle

Login handle

BSTR UserId

User assigned to device

BSTR deviceType

Device type

BSTR deviceSn

Device serial number

Returns

bool

True for success.

SOAP Exceptions

None

Authorization Required

Authorization:

  • Administrator
  • Device Manager. To bind a user to the device, the user must belong to a user group the operator can manage. The device must be in a folder the operator can manage.
  • End User. Can only bind a device to themselves.

Audit

PARAM1

User

PARAM2

End user ID

UnassignDevice

Unbinds the specified device from the specified user.

Parameters

long handle

Login handle

BSTR UserId

User assigned to device

BSTR deviceType

Device type

BSTR deviceSn

Device serial number

Returns

bool

True for success

SOAP Exceptions

None

Authorization Required

Authorization:

  • Administrator
  • Device Manager. To bind a user to the device, the user must belong to a user group the operator can manage. The device must be in a folder the operator can manage.

Audit

SUID

Administrative user ID / end user ID

OBJECT

Device

OBJNAME

DeviceID

OPERATION

Unassign

PARAM1

End user ID

addDevice

Adds a newly activated device to the ActivID AAA Server administration database, and assigns it to the given user. For Soft Token v2 device types, the function prevents the addition if the maximum number of Soft Tokens allowed per user is reached.

ActivID AAA Web Help Desk/Self Help Desk side (Java):

Copy 
public String addDevice (
long hLogin,
java.lang.String userID,
java.lang.String pskcPayload,
java.lang.String[] parameters)

ActivID SKI Connector side (C++):

Copy 
HRESULT addDevice(
IN        __int64 hLogin,
IN         BSTR userID,
IN         BSTR pskcPayload,
IN         int nSizeIn,
IN         BSTR* parameters,
OUT     BSTR* pReturnString)

Parameters

hLogin

User session handle

userID

User ID of the user who is the owner of the device. If the handle to the session corresponds to a self-desk user, then the User ID should be the self-desk user ID (otherwise the function fails).

pskcPayload

PSKC payload (in Base64) describing the device to add. In this version of the product, the User ID should be present in the PSKC payload (and should be equal to the User ID provided as input parameter).

parameters

Set of string parameters. Each parameter is of the form “Attribut=Value”. In this version of the product, only the following string parameter is supported: “Description=xxx”. With “xxx” a string of length limited to 25 characters. This parameter value is used to associate a description to a Soft Token v2.

Returns

In case of success, it returns the device serial number added, otherwise it raises an exception.

SOAP Exceptions

None

Authorization Required

Authorization:

  • Administrator
  • End User

Audit

None

getDeviceInfo

Retrieves device information.

Parameters

long handle

Login handle

BSTR deviceType

Device type

BSTR deviceSn

Device serial number

Returns

SkiDeviceInfo structure containing the information for the device:

Copy 
struct skiDeviceInfo {bool isMIDSoftToken;
bool isSoftToken;
bool deviceExist;
bool isDeviceAlreadyAssigned;
};

SOAP Exceptions

ACTIVPACK_HDAPI_BAD_RIGHTS

Authorization Required

Authorization: all administrative users, no End User.

Audit

None

getDeviceInfoEx

Returns the device information.

ActivID AAA Web Help Desk/Self Help Desk side (Java):

Copy 
public StructDeviceInfo getDeviceInfoEx(
long hLogin,
String serialNumber)
 
StructDeviceInfo has following members:
java.lang.String szSerialNumber;
int nType;
java.lang.String szDescription;
boolean bIsAlreadyAssigned;

ActivID SKI connector side (C++):

Copy 
HRESULT getDeviceInfoEx(
IN      __int64 hLogin,
IN         BSTR serialNumber,
OUT    structDeviceInfo* pDeviceInfo)
 
struct structDeviceInfo{
BSTR szSerialNumber;
int nType;
BSTR szDescription;
bool bIsAlreadyAssigned;
};

Parameters

hLogin

User session handle

serialNumber

Device serial number

Returns

The device information as described by the “StructDeviceInfo” structure.

SOAP Exceptions

None

Authorization Required

Authorization:

  • Administrator
  • End User

Audit

None

getUnlockPINCode

Retrieves credentials with which to unlock the device PIN code.

Parameters

long handle

Login handle

BSTR UserId

User assigned to device

BSTR deviceType

Device type

BSTR deviceSn

Device serial number

BSTR Challenge

The challenge to unlock the device PIN code.

Returns

BSTR

The response to the challenge

SOAP Exceptions

None

Authorization Required

Authorization:

  • Administrator
  • Device Manager. To bind a user to the device, the user must belong to a user group the operator can manage.
  • Help Desk Operator. To bind a user to the device, the user must belong to a user group the operator can manage.
  • End User. Only for a device that is not already bound to a user.

Audit

SUID

Administrative user ID / end user ID

OBJECT

Device

OBJNAME

DeviceID

OPERATION

Helpdesk

OPDETAIL

Unlock device PIN code

HasMiniTokenPIN

Returns a Boolean indicating whether or not the PIN code is set for the specified Mini Token.

Parameters

long handle

Login handle

BSTR UserID

User ID of the user being assigned with the Mini Token.

BSTR deviceType

Type of device. “” if none

BSTR deviceSN

Device serial number

Returns

bool result

True for success

SOAP Exceptions

None

Authorization Required

  • Administrator
  • Device Manager
  • Help Desk

Audit

None

SetMinTokenPinCode

Sets the PIN code of the specified Mini Token.

Parameters

long handle

Login handle.

BSTR UserId

User ID of the user to whom the Mini Token is to be assigned.

BSTR deviceType

Type of device. “ ” if none.

BSTR deviceSn

Device serial number.

BSTR PINCode

New PIN code value.

int PINMode

0 for PIN removal, 1 for check PIN before OTP and 2 for check PIN after OTP.

Returns

int

0 -- Mini Token has no PIN code set.

1 -- Mini Token PIN code is set.

SOAP Exceptions

  • Administrator
  • Device Manager
  • Help Desk

Authorization Required

None

Audit

Mini Token serial number

SynchronousAHAndResynchronize

Performs an extended authentication of the registry settings. The registry flag ExtendedAuthCounter indicates the number of counters in advance the authentication takes into account.

If authentication is successful:

  • The credentials of the device are updated on the administration database.
  • Reexport device to AAA Servers.

If a AAA Server is down, this call could return a false output. The export operation is saved so that the next time a manual export is performed, the device is exported.

Parameters

long handle

Login handle

BSTR deviceType

Device type

BSTR deviceSn

Device serial number

BSTR syncPwd

Synchronous password for authentication.

Returns

long

ACTIVPACK_HDAPI_OK: Successful authentication and device exported to all servers.

ACTIVPACK_HDAPI_NEED_TO_EXPORT: Successful authentication, but device was not successfully exported to all servers.

ACTIVPACK_HDAPI_INVALID_CREDENTIALS: Authentication failure.

SOAP Exceptions

ACTIVPACK_HDAPI_BAD_RIGHTS

ACTIVPACK_HDAPI_INVALID_CREDENTIALS

ACTIVPACK_HDAPI_DB_ERR

Authorization Required

Authorization:

  • Administrator
  • Device Manager
  • End User

Audit

SUID

Administrative user ID / end user ID.

OBJECT

Authentication success / Authentication failure.

OBJNAME

DeviceID

OPERATION

Synchronous

OPDETAIL

Synchronous

AssignDeviceToUserEx

Assigns the specified device to the specified user. The bIgnoreAlreadyAssigned parameter allows you to assign a device that is already assigned to another user.

Parameters

long handle

Login handle

BSTR UserId

User assigned to device

BSTR deviceType

Device type

BSTR deviceSn

Device serial number

bool bForceReplace

Replace the device if the user already has one.

bool bIgnoreAlreadyAssigned

Assign the device even if it is already assigned.

Returns

Long

0 if assignment succeeded; else one of the following error codes:

ACTIVPACK_HDAPI_DEVICE_NOT_FOUND 14

ACTIVPACK_HDAPI_DEVICE_ALREADY_ASSIGNED 21

ACTIVPACK_HDAPI_TIMEOUT 22

ACTIVPACK_HDAPI_BAD_RIGHTS 23

ACTIVPACK_HDAPI_LDAP_ERROR 24

ACTIVPACK_HDAPI_USER_HAS_DEVICE_ASSIGNED 31

SOAP Exceptions

None

Authorization Required

Authorization:

  • Administrator
  • Device Manager. To bind a user to the device, the user must belong to a user group the operator can manage. The device must be in a folder the operator can manage.
  • End User. Can only bind a device to the end user. For end users, the Flag bIgnoreAlreadyAssigned is always considered false. An end user cannot assign themselves a device that is already assigned.

Audit

In case of replacement of existing assignment:

SUID

Administrative user ID / end user ID

OBJECT

Device

OBJNAME

DeviceID

OPERATION

Assign

OPDETAIL

Replace

PARAM1

User

PARAM2

End user ID

In case of assignment for a user without device:

SUID

Administrative user ID / end user ID

OBJECT

Device

OBJNAME

DeviceID

OPERATION

Assign

PARAM1

User

PARAM2

End user ID

GetDeviceInitialPIN

Retrieves the initial PIN code of a device. If the logged operator does not have sufficient rights, the call returns “” (an empty string) as the PIN.

This call gives the administrator and device manager the ability to manage a device repository under which the device is stored.

Parameters

long handle

Login handle

BSTR deviceType

Device type

BSTR deviceSn

Device serial number

Returns

BSTR PIN

The device initial PIN code

SOAP Exceptions

None

Authorization Required

Authorization:

  • Administrator
  • Device Manager. You must assign the device to a user that the operator can manage.
  • End User. Only on a device that is not already assigned.

Audit

SUID

Administrative user ID / end user ID

OBJECT

Device

OBJNAME

DeviceID

OPERATION

Get PIN code

AssignSMSToken

Creates a new SMS Token device in the database, and then assigns that new token to the specified user.

Parameters

long handle

Login handle

string UserID

User ID of user for which a new SMS Token is generated and subsequently assigned to it.

string PINCode

The PIN that is set for the newly created SMS Token

Returns

boolean

On success, true is returned.

SOAP Exceptions

None

Authorization Required

Authorization:

  • Administrator
  • Device Manager. You must assign the device to a user that the operator can manage.
  • Help Desk Operator. You must assign the device to a user that the operator can manage. Check policy - HD operator can assign Temporary password.
  • End User. Only on a device that is not already assigned.

Audit

None

setSMSTokenPIN

Set (and thereby change if already set) the PIN on an existing token for a user.

Parameters

long handle

Login handle

string UserID

User ID of user for which a new SMS Token is generated and subsequently assigned to it.

string TokenID

The serial number of the token for which to change the PIN.

string PINCode

The new PIN for the specified token

Returns

boolean

On success, true is returned.

SOAP Exceptions

None

Authorization Required

Authorization:

  • Administrator
  • Device Manager. You must assign the device to a user that the operator can manage.
  • Help Desk Operator. You must assign the device to a user that the operator can manage. Check policy - HD operator can assign Temporary password.
  • End User

Audit

None

Resynchronization

ResynchronizeByPasswordEx

Resynchronizes the devices.

Parameters

long handle

Login handle

BSTR UserId

User assigned to device

BSTR deviceType

Device type

BSTR deviceSn

Device serial number

BSTR Password

Password

long counterRange

Resynchronization counter range. The counterRange is rounded to the nearest multiple of 10 lower than the value. Use –1 for the default, which is currently 30.

long timeSteps

Resynchronization time range. The timeSteps parameter the number of clock steps on either side of the current time. One clock step is 128 seconds. Set this parameter to null to specify the default, which is equivalent to + /–23 hour.

Returns

bool

True for success

SOAP Exceptions

None

Authorization Required

Authorization:

  • Administrator
  • Device Manager. You must assign the device to a user that the operator can manage.
  • Help Desk Operator. You must assign the device to a user that the operator can manage.
  • End User. Only if the device is already assigned to the connected end user.

Audit

SUID

Administrative user ID / end user ID

OBJECT

Device

OBJNAME

DeviceID

OPERATION

HelpDesk

OPDETAIL

Resynchronize

ResynchronizeByPassword

Obsolete; use ResynchronizeByPasswordEx instead.

This call resynchronizes the device. It is the same as ResynchronizeByPasswordEx, but it uses default values for counter range and clock.

Parameters

long handle

Login handle

BSTR UserId

User assigned to device

BSTR deviceType

Device type

BSTR deviceSn

Device serial number

BSTR Password

Password

Returns

bool

True for success

SOAP Exceptions

None

Authorization Required

Authorization:

  • Administrator
  • Device Manager. You must assign the device to a user that the operator can manage.
  • Help Desk Operator. You must assign the device must to a user that the operator can manage.
  • End User. Only if the device is already assigned to the connected end user.

Audit

SUID

Administrative user ID / end user ID

OBJECT

Device

OBJNAME

DeviceID

OPERATION

HelpDesk

OPDETAIL

Resynchronize

ResynchronizeByCounterAndClock

Resynchronizes the device using counter and clock values.

Parameters

long handle

Login handle

BSTR UserId

User assigned to device

BSTR deviceType

Device type

BSTR deviceSn

Device serial number

long counter

Device counter

long clock

Device clock (seconds elapsed since 1/1/1970).

Returns

bool

True for success

SOAP Exceptions

None

Authorization Required

Authorization:

  • Administrator
  • Device Manager. You must assign the device to a user that the operator can manage.
  • Help Desk Operator. You must assign the device to a user that the operator can manage.
  • End User. Only if the device is already assigned to the connected end user.

Audit

SUID

Administrative user ID / end user ID

OBJECT

Device

OBJNAME

DeviceID

OPERATION

HelpDesk

OPDETAIL

Resynchronize

ResynchronizeSoftToken

Resynchronizes a soft token on the server and returns the counter value for use on the client.

Parameters

long handle

Login handle

BSTR UserId

User assigned to device

BSTR deviceType

Device type

BSTR deviceSn

Device serial number

Returns

BSTR

Counter value for resynchronization

SOAP Exceptions

None

Authorization Required

Authorization:

  • Administrator
  • Device Manager. You must assign the device to a user that the operator can manage.
  • Help Desk Operator. You must assign the device to a user that the operator can manage.
  • End User. Only if the device is already assigned to the connected End User.

Audit

SUID

Administrative user ID / end user ID

OBJECT

Device

OBJNAME

DeviceID

OPERATION

HelpDesk

OPDETAIL

Resynchronize

Consolidation

consolidateServerAhLog

Starts log consolidation.

Parameters

long handle

Login handle

BSTR server

The server name to consolidate

SOAP Exceptions

None

Authorization Required

Authorization: Administrative operator, no End User.

  • Administrator
  • Device Manager
  • Help Desk Operator

Audit

SUID

Administrative user ID / end user ID

OBJECT

Log

OBJNAME

ServerName

OPERATION

Consolidate

OPDETAIL

nb AH rows consolidated

getConsolidationStatus

Returns the consolidation status. For example, when consolidation has started, but the number of logs to consolidate is unknown, then the totalLogs parameter returned in the structure is –1.

Parameters

long handle

Login handle

BSTR server

The server to consolidate

Returns

skiAhLogStatus structure description:

Copy 
struct skiAhLogStatus {
        long    totalLogs;
        long    completedLogs;
};

SOAP Exceptions

None

Authorization Required

Authorization: Administrative operator, no End User.

  • Administrator
  • Device Manager
  • Help Desk Operator

Audit

None

getAhLog

Returns logs. The ordering of the logs depends on “orderBy,” that is, 1 for server name ordering, 2 for user ID, or 3 for log time ordering.

Parameters

long handle

Login handle

long from

Logs start time (seconds since 1/1/1970).

long to

Logs end time (seconds since 1/1/1970).

BSTR server

The server to consolidate

BSTR serverIP

Server IP address

BSTR UserId

The userid for who retrieving logs

bool ErrOnly

Whether to get all logs or only errors

long orderBy

Indicator of ordering

long maxNbLogs

Maximum number of logs to return

Returns

skiAhLog array; Structure description:

Copy 
struct skiAhLog {
BSTR     serverName;
BSTR ServerIP;
BSTR     date;
BSTR     suid;
BSTR     group;
BSTR     ipAddress;
BSTR     info1;
BSTR     info2;
bool     accepted;
BSTR     reason;
};

SOAP Exceptions

None

Authorization Required

Authorization: Administrative operator, no End User.

  • Administrator
  • Device Manager. If disallow read rights for unauthorized users is set in the Admin console, then retrieve only logs for the user group the Device Manager can manage.
  • Help Desk Operator. If disallow read rights for unauthorized users is set in Admin console, then retrieve only logs for the user group the Device Manage can manage.

Audit

None

getAhLogEx

The ordering of the logs depends on the orderBy parameter; that is, 1 for server name ordering, 2 for user ID, or 3 for log time ordering.

Parameters

long handle

Login handle

long from

Logs start time (seconds since 1/1/1970).

long to

Logs end time (seconds since 1/1/1970).

BSTR server

The server to consolidate

BSTR serverIP

Server IP address

BSTR UserId

The userid for who retrieving logs

bool ErrOnly

Whether to get all logs or only errors

long orderBy

Order in which logs are to be returned:

1 for server name ordering,

2 for user ID, or

3 for log time ordering

long maxNbLogs

Maximum number of logs to return

Returns

skiAhLogEx array; Structure description:

Copy 
struct skiAhLogEx     {
BSTR     serverName;
BSTR     serverIP;
int      date;
int      millisecond;
BSTR     suid;
BSTR     group;
BSTR     ipAddress;
BSTR     info1;
BSTR     info2;
bool     accepted;
BSTR     reason;
};

SOAP Exceptions

None

Authorization Required

Authorization: Administrative operator, no End User.

  • Administrator
  • Device Manager. If disallow read rights for unauthorized users is set in the Admin console, then retrieve only logs for the user group the Device Manager can manage.
  • Help Desk Operator. If disallow read rights for unauthorized users is set in the Admin console, the retrieve only logs for the user group the Device Manage can manage.

Audit

None

ClearLogs

Unpublished

Clears all log rows where the date is anterior to the date passed in parameter.

Parameters

long handle

Login handle

int time

Clear all logs until this time (seconds since 1/1/1970).

Returns

bool

True for success

SOAP Exceptions

None

Authorization Required

Authorization: Administrative operator, no End User.

  • Administrator
  • Audit Manager

Audit

SUID

Administrative user ID / end user ID

OBJECT

Log

OPERATION

Clear

PARAM1

Date

Other High-Level Calls

GetVersion

Warning: Signature changed, handle no longer to be passed for this call. To be communicated to existing integrators.

Parameters

long handle

Login handle

Returns

skiVersion structure:

Copy 
struct skiVersion {
int     databaseversion;
BSTR     activpackversion;
};

SOAP Exceptions

None

Authorization Required

Public API

Audit

None

GetUserInfo

Gets the user information.

Parameters

long handle

Login handle

BSTR UserId

User assigned to device

BSTR deviceType

Device type

BSTR deviceSn

Device serial number

Returns

skiUserInfo array; structure:

Copy 
struct skiUserInfo {
BSTR    ServerName;
BSTR    ServerGates;
long    NbTries;
bool    Locked;
long    TmpPwd;
long    Referent;
__int64        Until;
__int64        FirstConn;
__int64        LastConn;
long    MaxNbTries;
bool    HasBackup;
long    Result;
BSTR    MasterRouting;
BSTR    SlaveRouting;
long    SMSBackupAH;
__int64        SMSUntil;
bool    LDAPAHOnNoDeviceDefined;
bool    ExternalAHOnDeviceNotFound;
BSTR    GroupName;
long    AuthType;
};

SOAP Exceptions

ACTIVPACK_HDAPI_USER_GROUP_NOT_FOUND

ACTIVPACK_HDAPI_BAD_RIGHTS

ACTIVPACK_HDAPI_BAD_PARAMETER

ACTIVPACK_HDAPI_DB_ERR

Authorization Required

Authorization: Administrative operator, no End User.

  • Administrator
  • Device Manager. You must assign the device to a user that the operator can manage.
  • Help Desk Operator. You must assign the device to a user that the operator can manage.

Audit

None

Emergency Passwords

SetLdapEmergencyPassword

Sets the LDAP emergency password.

Parameters

long handle

Login handle

BSTR UserId

User assigned to device

BSTR deviceType

Device type

BSTR deviceSn

Device serial number

bool LdapEmergency

True to set and false to reset

long time

Date until which password is valid (seconds since 1/1/1970).

Returns

bool

True for success

SOAP Exceptions

None

Authorization Required

  • Administrator
  • Device Manager. You must assign the device to a user that the operator can manage.
  • Help Desk Operator. You must assign the device to a user that the operator can manage. Check policy – HD operator can assign LDAP password.

Audit

SUID

Administrative user ID / end user ID.

OBJECT

Device

OBJNAME

DeviceID

OPERATION

HelpDesk

OPDETAIL

Activate LDAP temporary password.

SetTempPassword

Empty - allow removal of temporary password activation

Parameters

long handle

Login handle

BSTR UserId

User assigned to device

BSTR deviceType

Device type

BSTR deviceSn

Device serial number

BSTR TmpPwd

Temporary password

long time

Date until which the password is valid (secs since 1/1/1970).

Returns

bool

True for success

SOAP Exceptions

None

Authorization Required

  • Administrator
  • Device Manager. You must assign the device to a user that the operator can manage.
  • Help Desk Operator. You must assign the device to a user that the operator can manage. Check policy – HD operator can assign Temporary password.

Audit

SUID

Administrative user ID / end user ID

OBJECT

Device

OBJNAME

DeviceID

OPERATION

HelpDesk

OPDETAIL

Activate temporary password / Deactivate temporary password.

SetSMSBackup

Sets the SMS Backup for the user.

Parameters

long handle

Login handle

BSTR UserId

User assigned to device

BSTR deviceType

Device type

BSTR deviceSn

Device serial number

BSTR pinCode

Pin code to set

bool activate

Whether to activate or deactivate

long validUntil

Date until which the password is valid (seconds since 1/1/1970).

Returns

bool

True for success

SOAP Exceptions

None

Authorization Required

  • Administrator
  • Device Manager. You must assign the device to a user that the operator can manage.
  • Help Desk Operator. You must assign the device to a user that the operator can manage. Check policy – HD operator can assign SMS backup password.

Audit

SUID

Administrative user ID / end user ID.

OBJECT

Device

OBJNAME

DeviceID

OPERATION

HelpDesk

OPDETAIL

Activate SMS backup authentication.

UserHasMobilePhone

Verify that the user has a mobile phone.

Parameters

long handle

Login handle

BSTR UserId

User name

Returns

bool

True for success

SOAP Exceptions

None

Authorization Required

  • Administrator
  • Device Manager
  • Help Desk Operator

Audit

None

getRandomAlphaNum

Retrieves a random alphanumerical string. This call gives the administrator the ability to randomly generate a temporary password.

Parameters

long handle

Login handle

Int len

Length of randomly generated alphanumeric value.

Returns

BSTR randomAlphaNum

The randomly generated alphanumeric value.

SOAP Exceptions

None

Authorization Required

Authorization:

  • Administrator
  • Device Manager. You must assign the device to a user that the operator can manage.
  • Help Desk Operator. You must assign the device to a user that the operator can manage. Check policy - HD operator can assign Temporary password.
  • End User

Audit

None

Low-Level Calls

GetQueries

Returns all available LDAP queries

Parameters

long handle

Login handle

Returns

BSTR array

SOAP Exceptions

None

Authorization Required

  • Administrator
  • Device Manager. If disallow read, then rights set in the admin console -> retrieve only queries available for this operator (groups assigned).
  • Help Desk Operator. If disallow read, then rights set in the admin console -> retrieve only queries available for this operator (groups assigned).

Audit

None

GetServers

Retrieves an array of servers.

Parameters

long handle

Login handle

Returns

BSTR array

SOAP Exceptions

None

Authorization Required

  • Administrator
  • Device Manager
  • Help Desk Operator

Audit

None

GetGroups

Retrieves the list of the defined AAA Server groups as an array.

Parameters

long handle

Login handle

Returns

BSTR array

List of groups

SOAP Exceptions

None

Authorization Required

  • Administrator
  • Device Manager
  • Help Desk

Audit

None

SearchUsers

Search for users.

Parameters

long handle

Login handle

BSTR query

The LDAP query to use

BSTR[]

Parameters

Returns

BSTR array containing users

SOAP Exceptions

None

Authorization Required

  • Administrator
  • Device Manager
  • Help Desk Operator

Audit

None

SearchUsersFromGroup

Retrieves the list of the users who are members of the specified AAA Server group.

This call is similar to the SearchUsers call, except that an AAA Server group is specified instead of an LDAP query.

Parameters

long handle

Login handle

BSTRgroup

The LDAP query to use

BSTR[]

Parameters

Returns

BSTR array

Array containing users

SOAP Exceptions

None

Authorization Required

  • Administrator
  • Device Manager
  • Help Desk

Audit

None

GetParameters

Get SKI Group parameters.

Parameters

long handle

Login handle

Returns

BSTR array containing:

Copy 
struct skiGroupParams {    
bool    ExternalAH;
bool    LDAPStaticAH;
};

SOAP Exceptions

None

Authorization Required

  • Administrator
  • Device Manager
  • Help Desk Operator

Audit

None

Echo

Echo the given message back.

BSTR message

A message

Returns

BSTR

The given message

SOAP Exceptions

None

Authorization Required

  • Administrator
  • Device Manager
  • Help Desk Operator
  • End User

Audit

None