u.trust LAN Crypt Admin API

• Overview
• API Changes
  • Changes in 11.0.0
  • Changes in 4.2.0
  • Changes in 4.1.0
  • Changes in 4.0.0
  • Changes in 3.97
• Function Reference
  • General
  • Initialization / De-initialization
    • LogonToDatabase
    • LogoffFromDatabase
    • LogonSO
    • LogoffSO
  • Remote Login
    • LogonSOGetChallenge
    • LogonSOAuthenticate
    • LogonSOProvideKeys
  • Error Handling
    • GetErrorDesc
    • GetIntErrorCode
  • Error Logging
    • ExportLogEntries
    • ExportLogEntriesToMemory
    • ArchiveLogEntries
    • DeleteLogEntries
    • CheckLogIntegrity
  • Certificate usage in API functions
  • Search Order in Database Tables
  • Function Reference
    • CreateDBTables
    • DropDBTables
    • EnumFQNOfUserName
    • EnumFQNOfGroupName
    • CreateUser / CreateUserEx
    • SetUserProperties
    • GetUserProperties
    • SetGroupProperties
    • GetGroupProperties
    • CreateGroup/CreateGroupEx/CreateGroupExEx
    • AddSubGroup
    • AddUserToGroup
    • RenameGroup
    • DeleteUser
    • DeleteGroup
    • RemoveGroupFromGroup
    • RemoveUserFromGroup
    • CreateFirstMSO
    • AddSO
    • RemoveSO
    • GrantRightsOnGroupToSO
    • GrantRightsOnSOToSO
    • GetRightsOnGroupForSO
    • GetRightsOnSOForSO
    • WriteKey
    • ImportKey
    • ImportKeyEx
    • ImportKeyFile
    • CreateCertificate
    • CheckDBIntegrity
    • GetDBIntegrityCheckReport
    • RecalcMACForRecord
    • UpdateKey
    • UpdateKeyEx
    • AddKeyToGroup
    • RemoveKeyFromGroup
    • DeleteKey
    • EnumKeys
    • ReadKey
    • ReadKeyEx
    • AssignCertificateToUser
    • RemoveCertificateFromUser
    • RemoveAllCertificatesFromUser
    • EnumCertificatesOfUser
    • GetSOCertificate
    • SetSOCertificate
    • CSetSOPermissions
    • GetSOPermissions
    • WriteRule
    • WriteRuleEx
    • StartResolverForUser
    • StartResolverForUsersOfGroup
    • StartResolverForUsersOfChangedGroup
    • AssignCertificatesToUsersOfGroup
    • CreateCertificatesForUsersOfGroup
    • SetUserKey
    • EnumUserKeysOfUser
    • DetachUserKey
    • DeleteProfile
    • EnableKey
    • EnumUsersWithFilter
    • EnumUsersOfGroup
    • EnumGroupParents
    • EnumSubGroups
    • EnumRulesForGroup
    • GetRuleProperties
    • GetRulePropertiesEx
    • SetRuleProperties
    • SetRulePropertiesEx
    • DeleteRule
    • EnumGroupsForUser
    • EnumRulesForUser
    • EnumKeysForUser
    • EnumGroupsForRule
    • EnumUsersForKey
    • EnumGroupsForKey
    • EnumRulesForKey
    • EnumSOs
    • EnumSOsForGroup
    • EnumGroupsForSO
    • GetParentOfUser
    • GetParentOfGroup
    • IsLinkedGroup
    • GetParentGroupOfKey
• Constant Values
  • Numeric values
    • Algorithms for keys
    • Rights of a Security Officer on a Group
    • Rights of a Security Officer on another Security Officer
    • Permissions for Security Officer
    • Group Types
  • String values
  • Parameter restrictions
• Required Rights and Permissions
  • For API functions
  • For GrantRightsOnGroupToSO()
  • For GrantRightsOnSOToSO()
• Example Script
  • Example Script (VB Script)
• Abbreviations
• Legal notices

Overview

The functions described in this document are used to create u.trust LAN Crypt Configuration Data through an API. The API is part of the u.trust LAN Crypt Administration.

The COM API is implemented in the class CSGLCApi. Both classes are exported from SGLCScriptAPI.DLL. The methods of the classes are described in the following chapter.

The u.trust LAN Crypt API is only available for 32 bit applications.

On 64 bit operating systems, an application using the API must be a 32 bit application. If the API is used within a vb-script, the 32 bit Windows Scripting Host must be used to execute the script (cscript.exe or wscript.exe located in %WINDIR%\SysWOW64). Multiple instances of the SGLC API can be used within one process, but all function calls must be executed from one thread.

To localize the .NET API for u.trust LAN Crypt Administration, locate the LCAdminApiNet.xml file at C:\Program Files (x86)\utimaco\u.trust LAN Crypt\Administration\ after ensuring the .NET API component was installed.

API Changes

Changes in 11.0.0

• Changes in the utilization of the .NET API

Changes in 4.2.0

• Small changes in the utilization of the .NET API

Changes in 4.1.0

• Adding of new function CreateGroupExEx

• Adding of Group Type “Special Group – Root Node of all Groups”

Update of the following functions

• IsLinked: Renamed in IsLinkedGroup and change of function signature

• GetParentOfKey: Renamed in GetParentGroupOfKey and change of function signature

Adding of new functions

• isLinked

• GetParentOfKey

Changes in 4.0.0

• No changes in the utilization of the API

Changes in 3.97

• The API Version 3.97 is the new base version of documented API changes

Function Reference

General

All functions return LCAPIERR_OK if successful or an error code if an error occurred:

Exceptions:

• GetErrorDesc()

• GetIntErrorCode

All parameters are required – that means that all parameters have to be provided and all parameters must contain valid values.

To specify a user or a group a FQN (fully qualified name) is used, however in all cases it is also possible to use the GUID of the user respectively the group. Obviously this is not the case when setting attributes (for example in SetUserProperties the first parameter is used to find the user, this can be a GUID, the other parameters are the attributes to set, and must contain the desired attribute values values).

If an Oracle database is used all text values are case sensitive. Therefore referencing an object must be done with the same name as it was created. E.g. if a group was created as “Group1”, then for all actions on this group the group name must be specified as “Group1” – using “group1” returns an error that the group was not found.

Error codes are defined as follows:

Initialization / De-initialization

All scripts, which like to use the API must LogonToDatabase. Also, it is good behavior to LogoffFromDatabase after successful operation.

LogonToDatabase

Initializes the API and logs the SO on to the Database.

COM

HRESULT LogonToDatabase (
    BSTR strODBC,
    BSTR strUID,
    BSTR strPWD,
    int  iSQLType,
    BSTR strOwner
);

Parameters:

strODBC

[in] ODBC Data Source Name (e.g. SGLCSQLServer)

strUID

[in] User Id of the SQL Account (“” if not required)

strPWD

[in] Password of the SQL Account (“” if not required)

iSQLType

[in] Type of SQL Database.

Valid options are:

0…MS SQL Server

1…Oracle Version 9.x or higher

strOwner

[in] Owner string. In case of Microsoft SQL Server it will be “DBO” (Micorsoft’s default value) with some probability. Please ask your database administrator for this name.

LogoffFromDatabase

Frees all resources and closes the connection to the database.

COM

HRESULT LogoffFromDatabase ();

LogonSO

Logon the specified Security Officer.

COM

HRESULT LogonSO (
    BSTR strSOName
);

Parameters:

strSOName

[in] Name of the security officer to be logged-on

Note

• The private key matching the certificate associated with the SO must be accessible, or the logon will fail!

LogoffSO

Clears all information, and closes all handles related to the current SO.

COM

HRESULT LogoffSO ();

Remote Login

Remote login is no longer supported. All functions return the error code LCAPIERR_GENERAL_ERROR.

LogonSOGetChallenge

HRESULT LogonSOGetChallenge(
BSTR strSOName,
VARIANT *lSize,
SAFEARRAY **abChallenge);

Parameters:

BSTR (String) strSOName

[in] Name of the SO to login in

long (Integer) lSize,

[in] Amount of byte of abChallenge

SAFEARRAY * (Array of Bytes) abChallenge,

[out] Random bytes (to be used for LogonSOAuthenticate())

Obsolte, this function always returns LCAPIERR_GENERAL_ERROR.

LogonSOAuthenticate

HRESULT LogonSOAuthenticate(
   BSTR strSOName,
   BSTR strSignedChallenge,
   VARIANT *strEncSessKey,
   SAFEARRAY **abTabData);

Parameters:

BSTR (String) strSOName

[in] Name of the SO to login in

BSTR (String) strSignedChallenge,

[in] Signed challenge you got from LogonSOGetChallenge()

VARIANT * (Array of Bytes) strEncSessKey,

[out] a session key to be used for LogonSOProvideKeys()

SAFEARRAY * (Array of Bytes) abTabData,

[out] content of database table entry

Obsolte, this function always returns LCAPIERR_GENERAL_ERROR.

LogonSOProvideKeys

HRESULT LogonSOProvideKeys(
   BSTR strSOName,
   BSTR strSKMAC_encr,
   BSTR strSKENC_enc);

Parameters:

BSTR (String) strSOName

[in] Name of the SO to login in

BSTR (String) strSKMAC_encr,

[in] Corresponding value from abTabData encrypted with the session key

BSTR (String) strSKENC_enc,

[in] Corresponding value from abTabData encrypted with the session key

Obsolte, this function always returns LCAPIERR_GENERAL_ERROR.

Error Handling

Following functions provide some additional information when an error occurs.

GetErrorDesc

Returns a textual error description for an error code returned by any other function

COM

BSTR GetErrorDesc (
    int iErrCode
);

Parameters:

iErrCode

[out] Error code to retrieve additional information for.

strErrDesc

[out] Error description.

GetIntErrorCode

In some cases, an additional error code is available and stored internally. The additional error code might be used for troubleshooting purposes and can be retrieved by using this function. Call this function immediately after the function call, which returned an error.

Please note that only the official support can evaluate this error code.

COM

long GetIntErrorCode ();

Error Logging

For details on the general logging mechanism see the manual of the SGLC Administration. Please note however that in order for the logging to work it is necessary to log on to the SGLC Administration GUI at least once to make sure the database is in a current state. This is especially important after upgrading to a newer version!

ExportLogEntries

Exports all log entries that match a specified filter to a text file.

COM

HRESULT ExportLogEntries (
    BSTR strExportFile,
    long lFilterID,
    BSTR strFilterSO,
    long lFilterSeverity,
    BSTR strFilterAfterTime,
    BSTR strFilterBeforeTime,
    BSTR strFilterLocation
);

Parameters:

strExportFile

[in] Name of the output file

long lFilterID,

[in] Filter to restrict the exported entries to events of one ID

WCHAR *strFilterSO,

[in] Filter to restrict the exported entries to events of one Security Officer

long lFilterSeverity,

[in] Filter to restrict the exported entries to a specified severity (0..7) or more severe, if the negative value (-1 .. -7) is passed it restricts to exactly the absolute value of the passed severity (e.g. 3 for a passed value of ‘-3’).

SYSTEMTIME *strFilterAfterTime,

[in] Filter to restrict the exported entries to events logged after this time.

SYSTEMTIME *strFilterBeforeTime,

[in] Filter to restrict the exported entries to events logged before this time.

WCHAR *strFilterLocation

[in] Filter to restrict the exported entries to events logged at this location

If any of the filter parameters is not used, an empty string must be passed (for string values, -1 for lFilterID and any value outside the valid range for lFilterSeverity.

ExportLogEntriesToMemory

Exports all log entries that match a specified filter an array or linked list.

COM

HRESULT ExportLogEntriesToMemory (
    VARIANT * lSize,
    VARIANT * strLogEntries,
    long lFilterID,
    BSTR strFilterSO,
    long lFilterSeverity,
    BSTR strFilterAfterTime,
    BSTR strFilterBeforeTime,
    BSTR strFilterLocation
);

Parameters:

lSize

[out] number of found log entries (COM)

strLogEntries

[out] string array containing log entries (COM)

long lFilterID,

[in] Filter to restrict the exported entries to events of one ID

WCHAR *strFilterSO,

[in] Filter to restrict the exported entries to events of one Security Officer

long lFilterSeverity,

[in] Filter to restrict the exported entries to a specified severity (0..7) or more severe, if the negative value (-1 .. -7) is passed it restricts to exactly the absolute value of the passed severity (e.g. 3 for a passed value of ‘-3’). SYSTEMTIME *strFilterAfterTime,

[in] Filter to restrict the exported entries to events logged after this time.

SYSTEMTIME *strFilterBeforeTime,

[in] Filter to restrict the exported entries to events logged before this time.

WCHAR *strFilterLocation

[in] Filter to restrict the exported entries to events logged at this location

If any of the filter parameters is not used, an empty string must be passed for string values, -1 for lFilterID and any value outside the valid range for lFilterSeverity.

If the array strLogEntries is too small to hold all found entries, the error LCAPIERR_INVALID_ARGUMENT is returned and lSize is set to the number of found entries. (COM)

All time values are passed as string values and must be in the following format: YYYY-MM-DD[ hh:mm:ss[:fff]]

Time and fractions of a second are optional, the number of digits for each part is important (e.g. use 02 instead of 2) and the punctuation must be exactly as specified!

An empty time value is interpreted as current time!

ArchiveLogEntries

Archives all log entries of the specified location that have been written before the specified time to the specified file. Each entry and the whole file is protected from unnoticed modification by a MAC.

COM

HRESULT ArchiveLogEntries (
    BSTR strArchiveFile,
    BSTR strArchiveTime,
    BSTR strLocation
);

Parameters:

strArchiveFile

[in] Name of the output file

strArchiveTime

[in] Timelimit for entries that should be archived. As String in SGLC time format.

sArchiveTime

[in] Timelimit for entries that should be archived. As SYSTEMTIME*.

strLocation

[in] Filter to restrict the archived entries

DeleteLogEntries

Deletes all log entries of the specified location that have been written before the specified time AND have already been archived. This is primarily used to clear old events that are no longer needed.

Note

• f the specified Time is not far enough in the past (the minimum log entry age can be configured in the Administration GUI in the properties of the logging node) LCAPIERR_INVALID_ARGUMENT is returned!

COM

HRESULT DeleteLogEntries (
    BSTR strPurgeTime,
    BSTR strLocation
);

Parameters:

strPurgeTime

[in] Timelimit for entries that should be deleted as string in SGLC time format.

sPurgeTime

[in] Timelimit for entries that should be deleted as SYSTEMTIME*.

strLocation

[in] Filter to restrict the deleted entries

Note

• It is only possible to delete entries from the current location and not entries replicated from a different location!

CheckLogIntegrity

Checks the MAC of all entries in the specified archive file. If the filename is empty all entries in the database originating from the specified location are checked. If the location is empty as well, all entries for the current location are checked.

COM

HRESULT CheckLogIntegrity (
    BSTR strArchiveFile,
    BSTR strLocation
);

Parameters:

strArchiveFile

[in] Name of the output file to check

strLocation

[in] Filter to restrict the checked entries.

Certificate usage in API functions

CAPICOM 2.0 is required for all certificate related functions.

All functions that use certificates (AssignCertificateToUser, CreateCertificate, AssignCertificatesToUsersOfGroup, AddSO, SetSOCertificate) use the certificate object parameter as a handle. So the certificate object has to be created before calling the API function!

See the following examples:

dim cert
set cert=CreateObject("CAPICOM.CERTIFICATE") result=lcapi.CreateCertificate("MySecurityOfficer", cert)

This also applies to other CAPICOM objects like certificate collections:

dim certlist
set certlist=CreateObject("CAPICOM.CERTIFICATES") certlist.Clear
result=lcapi.EnumCertificatesOfUser("User", certlist)

certificate objects can be created with several CAPICOM functions (Certificate.Load, Certificate.Import, …). For example Certificate.Import can be used to create a constant certificate from within the source code. The certificate content can be read from a .cer file that was exported as Base64 encoded, or the output of the CAPICOM Certificate.

Export function:

dim certBlob:certBlob="-----BEGIN CERTIFICATE----- MIICEDCCAX2gAwIBAgIQlFeVg653bYZNUWmHd3dGoDAJBgUrDgMCHQUAMDgxDDA KBgNVBAMTA2N3YTEoMCYGA1UECxMfU2FmZUd1YXJkIExBTiBDcnlwdCBDZXJ0aWZp Y2F0ZTAeFw0wNjA2MjMxMTExMDJaFw0wNzA2MjMxMTExMDJaMDgxDDAKBgNVBAM TA2N3YTEoMCYGA1UECxMfU2FmZUd1YXJkIExBTiBDcnlwdCBDZXJ0aWZpY2F0ZTCBnz ANBgkqhkiG9w0BAQEFAAOBjQAwgYkCgYEAwsJ1qrYQiZat86gY1E99TcL/zl8p+jupAzh2Y/ qctX/K2gCAecdI+xUHLVOPkjj9DB4d//moLvo7YRbTcCYxZ6rzk9CHei8UyCm7rpOHHMGT wP6TQ/ItKPBAGZtie6201rDEvPd9k25vBZHoJxuqcVtC/5Fv1VTafwatBIQrhNkCAwEAAaMj MCEwEgYGKyQP AQEBAQH/BAUwMy4wMDALBgNVHQ8EBAMCBDAwCQYFKw4DAh0F AAOBgQBLJbaOl3O5S5yXcsCATDY7BIaAxdDBD+JdscHDLOUUu2uysdLTXvvJSDE7us8iR JOCIYzjBSth/yt+1vb30ZSbrBkfzk0Ch3G3alitMSOAS1ciFF+pqjblEEPm08v8RPIPgHDAPJbh flMCbljHRGvThRkyfaiqyceJ5Xj+vyFURw==-----END CERTIFICATE-----"
dim cert
set cert=CreateObject("CAPICOM.CERTIFICATE") cert.Import(certBlob)

Search Order in Database Tables

Some functions (dealing with users, groups or keys) have to do a lookup in the database. These lookups are down via internal functions. The performance of the lookups can be adjusted via three registry setting. The three registry keys are UserSearchOrder, GroupSearchOrder, and KeySearchOrder (all are of type REG_SZ) and hold the name of database columns that are search. Valid entries are:

• us_short_name, us_import_guid, us_import_source, us_dn, us_login_name, us_email, us_comment

• co_import_guid, co_import_source, co_dn, co_short_name

• kp_ownguid, kp_driver_keyname, kp_long_keyname

The sequence of the entries determines the sequence of the search. All entries have to be seperated by a blank or a semicolon. Illegal entries causes the search alogrithm to return the error LCAPIERR_GENERAL_ERROR. If you use functions like SetGroupProperties() frequently and you use a GUID as input parameter in most cases then place co_import_guid as the first entry in the registry key.

If there is no such registry key or its value is empty than a hard wired default search sequence is used. If there are valid entries only the given columns are searched, other columns are ignored.

Function Reference

All functions require a preceding LogonToDatabase otherwise all functions will return LCAPIERR_NOT_INITIALIZED.

Additionally all functions except:

• LogoffFromDatabase

• CreateDBTables

• DropDBTables

• CreateFirstMSO and

• LogonSO

required a preceding LogonSO otherwise all functions will return LCAPIERR_NO_SO.

CreateDBTables

Creates all necessary u.trust LAN Crypt Tables/Views/Constraints/Triggers etc. in the SQL Database.

COM

HRESULT CreateDBTables ();

DropDBTables

Drops all u.trust LAN Crypt Tables/Views/Constraints/Triggers etc. in the SQL Database.

COM

HRESULT DropDBTables ();

EnumFQNOfUserName

Enumerates the fully qualified name (FQN) of a user name if available. If there’s no FQN available in the Database, the short name of the user is returned.

COM

HRESULT EnumFQNOfUserName ( BSTR strUserName, VARIANT * lSize, VARIANT * strFQNs
  );

Note

• lSize must be of type integer and strFQNs must be of type array, otherwise LCAPIERR_INVALID_ARGUMENT will be returned.

Parameters:

strUserName

[in] Name of the user (short name) from which you want the FQN

lSize

[out] contains the number of FQNs found for this user

strFQNs

[out] contains the FQNs or short names found for this user. The array is filled up to the provided size of the array. The fact, that not all FQNs could be stored in the provided array is reflected by the fact that lSize is bigger than the size of the Array returned. So, the array can be resized and the function can be called again.

EnumFQNOfGroupName

Enumerates the fully qualified name (FQN) of a group name if available. If there’s no FQN available in the Database, the short name of the group is returned.

COM

HRESULT EnumFQNOfGroupName ( BSTR strGroupName, VARIANT * lSize,
VARIANT * strFQNs
);

Note

• lSize must be of type integer and strFQNs must be of type array, otherwise LCAPIERR_INVALID_ARGUMENT will be returned.

Parameters:

strGroupName

[in] Name of the group from which you want the FQN

lSize

[out] contains the number of FQNs found for this group

strFQNs

[out] contains the FQNs or short names found for this group. The array is filled up to the provided size of the array. The fact, that not all FQNs could be stored in the provided array is reflected by the fact that lSize is bigger than the size of the Array returned. So, the array can be resized and the function can be called again.

CreateUser / CreateUserEx

Creates a new User.

COM

HRESULT CreateUser (
    BSTR strFQN,
    BSTR strEmail,
    BSTR strLoginName,
    BSTR strComment,
    BSTR strSpecificKey
);

COM

HRESULT CreateUserEx (
    BSTR strFQN,
    BSTR strEmail,
    BSTR strLoginName,
    BSTR strShortName,
    BSTR strLongName,
    BSTR strGUID,
    BSTR strComment,
    BSTR strSpecificKey
);

Parameters:

strFQN

[in] Fully qualified name, that uniquely identifies the user in the source directory

strEmail

[in] User’s e-mail address

strLoginName

[in] Logon name for user (short name)

strShortName,

[in] Shortname for user (Display Name)

strLongName,

[in] Long name for user (e.g. DN)

strGUID,

[in] String that uniquely identifies the user in the source directory

strComment

[in] Description

strSpecificKey

[in] short name of user-specific key.

Note

• The user does not get any profiles unless he belongs to a group.

SetUserProperties

Update the properties of an existing user.

COM

HRESULT SetUserProperties (
    BSTR strFQN,
    BSTR strEmail,
    BSTR strLoginName,
    BSTR strShortName,
    BSTR strLongName,
    BSTR strImportSource,
    BSTR strGUID,
    BSTR strComment,
    BSTR strSpecificKey
);

Parameters:

strFQN

[in] Fully qualified name, or GUID of the user

strEmail

[in] User’s e-mail address

strLoginName

[in] Logon name for user

strShortName,

[in] Shortname for user (Display Name)

strLongName,

[in] Long name for user (DN)

strImportSource,

[in] LDAP URL that uniquely identifies the user in the source directory

strGUID,

[in] String that uniquely identifies the user in the source directory

strComment

[in] Description

strSpecificKey

[in] short name of user-specific key.

Note

• The FQN of the user must already exist in the database and can be changed by passing a different strImportSource into this function. All other fields can be updated freely.

• If strSpecificKey is empty, no userkey is assigned to the user, but any previously assigned userkey stays active. Use DetachUserkey() and SetUserKey() functions to handle this, or use <clear> to remove an assigned userkey from the user.

GetUserProperties

Return the properties of an existing user.

COM

HRESULT GetUserProperties (
    VARIANT *strFQN,
    VARIANT *strEmail,
    VARIANT *strLoginName,
    VARIANT *strShortName,
    VARIANT *strLongName,
    VARIANT *strImportSource,
    VARIANT *strGUID,
    VARIANT *strComment,
    VARIANT *strSpecificKey,
    VARIANT *strTimeStamp
);

Parameters:

strFQN

[in] Fully qualified name, or GUID of the user

strEmail

[out] User’s e-mail address

strLoginName

[out] Logon name for user

strShortName,

[out] Shortname for user (Display Name)

strLongName,

[out] Long name for user (DN)

strImportSource,

[out] LDAP URL that uniquely identifies the user in the source directory

strGUID,

[out] String that uniquely identifies the user in the source directory

strComment

[out] Description

strSpecificKey

[out] short name of user-specific key.

strTimeStamp

[out] time this user was changed the last time

Note

• The FQN of the user must already exist in the database.

SetGroupProperties

Update the properties of an existing group.

COM

HRESULT SetGroupProperties (
    BSTR strFQN,
    BSTR strShortName,
    BSTR strLongName,
    BSTR strImportSource,
    BSTR strGUID,
    BSTR strComment,
    BSTR strSpecificKey,
    long lGroupType
);

Parameters:

strFQN

[in] Fully qualified name, or GUID of the group

strShortName,

[in] Shortname for group (Display Name)

strLongName,

[in] Long name for group (DN)

strImportSource,

[in] LDAP URL that uniquely identifies the group in the source directory

strGUID,

[in] String that uniquely identifies the group in the source directory

strComment

[in] Description

strSpecificKey

[in] short name of group-specific key.

lGroupType

[in] Type of the group. Possible values are shown in the table in section 5.1.5.

Warning: Wrong type could change the display and behavior of some operations in the Administration.

Note

• The FQN of the group must already exist in the database and can be changed by passing a different strImportSource into this function. All other fields can be updated freely.

• If no groupkey is assigned to the group then strSpecificKey is empty. If strSpecificKey is empty, no groupkey is assigned to the group; any previously assigned groupkey stays active. Use ‘' to remove an assigned groupkey from the group.

GetGroupProperties

Return the properties of an existing group.

COM

HRESULT GetGroupProperties (
    VARIANT *strFQN,
    VARIANT *strShortName
    VARIANT *strLongName,
    VARIANT *strImportSource,
    VARIANT *strGUID,
    VARIANT *strComment,
    VARIANT *strSpecificKey,
    VARIANT *lGroupType,
    VARIANT *strTimeStamp
);

Parameters:

strFQN

[in] Fully qualified name, or GUID of the group

strShortName,

[out] Shortname for group (Display Name)

strLongName,

[out] Long name for group (DN)

strImportSource,

[out] LDAP URL that uniquely identifies the group in the source directory

strGUID,

[out] String that uniquely identifies the group in the source directory

strComment

[out] Description

strSpecificKey

[out] short name of group -specific key.

lGroupType

[out] Type of the group. Possible values are shown in the table in section 5.1.5.

strTimeStamp

[out] time this user was changed the last time

Note

• The FQN of the group the must already exist in the database.

CreateGroup/CreateGroupEx/CreateGroupExEx

Creates a new Group.

• CreateGroup creates a group with minimal parameters.

• CreateGroup provides more parameters for desired group.

• CreateGroupExEx extends the function CreateGroupEx with the additional parameter root_group. The function CreateGroupEx sets the Special Group (u.trust LAN Crypt Root Node) as root node. But there are cases that another root group, e.g. Active Directory root group, should be set as root. This new parameter root_group offers this possibility.

COM

HRESULT CreateGroup (
    BSTR strGroupFQN,
    BSTR strParentGroupFQN,
    BSTR strComment
);

COM

HRESULT CreateGroupEx (
    BSTR strGroupFQN,
    BSTR strShortName,
    BSTR strLongName,
    BSTR strGUID,
    BSTR strParentGroupFQN,
    long lGroupType,
BSTR strComment
);

COM

HRESULT CreateGroupExEx (
    BSTR strGroupFQN,
    BSTR strShortName,
    BSTR strLongName,
    BSTR strGUID,
    BSTR strParentGroupFQN,
    long lGroupType,
    BSTR strComment,
    BSTR root_group
);

Parameters:

strGroupFQN

[in] Fully qualified name

strShortName,

[in] Short name for group (Display Name)

strLongName,

[in] Long name for group (DN)

strGUID,

[in] String that uniquely identifies the group in the source directory

strParentGroupFQN

[in] Fully qualified name of the parent group (use EnumFQNofGroupName) , or GUID of the parent group.

lGroupType

[in] Type of group. Possible values are shown in the table in section 5.1.5.

strComment

[in] Description

root_group

[in] Name of the root group of the group tree, in which the created group should be inserted. It can be set with the Special Group (u.trust LAN Crypt default root node) with “SpecialRootGroup” or another desired group name, i.e. a Active Directory root name.

Note

• If strParentGroupFQN is empty a root group is created, otherwise a corresponding relation is automatically added.

AddSubGroup

Defines a “contains” relation between two existing Groups.

COM

HRESULT AddSubGroup (
    BSTR strGroupFQN,
    BSTR strParentFQN,
    BSTR strComment,
    long lAsLink
);

Parameters:

strGroupFQN

[in] Fully qualified name or GUID of the group

strParentGroupFQN

[in] Fully qualified name or GUID of the parent group

strComment

[in] Description

lAsLink

[in] If a sub group should have more than one parent then set this parameter to 1 for all additional parents (first parent: set it to 0)

Note

• This function fails if the new relation would cause a circular relation!

AddUserToGroup

Adds an existing user to an existing group. Both user and group are identified by their Fully Qualified names. If the FQN does not exist for a user or a group, the short name of the user or group is used to identify them. Using the short name as search criteria might lead to the error if a user or a group could not be identified distinctly by the short name.

COM

HRESULT AddUserToGroup (
    BSTR strUserName,
    BSTR strGroupName,
    BSTR strComment,
    long lAsParent
);

Parameters:

strUserName

[in] FQN or short name of user to add, or GUID of the user

strGroupName

[in] FQN or short name or GUID of group in which the user should be placed

strComment

[in] some comment

lAsParent / fAsParent

[in] not 0: the group should become the parent of the user.

Note

• If the user does not have a parent, the group will become its parent in any case no matter the value of lAsParent!

RenameGroup

Changes the FQN of a Group.

Note

• This function sets all names of the group to FQNnew, it is highly recommended to use SetGroupProperties!

COM

HRESULT RenameGroup (
    BSTR strGroupFQNOld,
    BSTR strGroupFQNNew
);

Parameters:

strGroupFQNOld

[in] current FQN of group

strGroupFQNNew

[in] new FQN of group

DeleteUser

Deletes a user from the Database. The user is identified by the Fully Qualified Name or the GUID. If the FQN and GUID do not exist for a user, the short name is used as search criteria. Using the short name as search criteria might lead to the error if a user could not be identified distinctly.

COM

HRESULT DeleteUser (
    BSTR strUserName
);

Parameters:

strUserName

[in] FQN of user do delete

Note

• The user and the user certificate are deleted from the database.

DeleteGroup

Recursively deletes a group and all it’s subgroups from the Database.

COM

HRESULT DeleteGroup (
    BSTR strGroupFQN,
    BSTR strParentGroupFQN
);

Parameters:

strGroupFQN

[in] FQN or GUID of group to delete

strParentGroupFQN

[in] FQN or GUID of parent group of the group you want to delete

To make sure, that the right group is deleted, the parent group has to be provided. To delete a root group (which does not have a parent), an empty string (“”) has to be passed to the function.

Note that the provided group, all subgroups and all users will be deleted from the Database! Only in case they (users or subgroups) are members of another OU as well, this other OU will become the new parent of the users respectively groups.

So use this function with care!

If the original parent is no OU (for example a manual group), any other membership will be promoted to parent group (the new parent does not have to be an OU).

The group is identified by the Fully Qualified Name. If the FQN does not exist for a group, the short name is used as search criteria. Using the short name as search criteria might lead to the error that a group could not be identified distinctly which leads to an error.

RemoveGroupFromGroup

Removes the “contains” relation between the two groups.

COM

HRESULT RemoveGroupFromGroup (
    BSTR strGroupFQN,
    BSTR strParentGroupFQN
);

Parameters:

strGroupFQN

[in] FQN or GUID of group to delete

strParentGroupFQN

[in] FQN or GUID of parent group of the group you want to delete

RemoveUserFromGroup

Removes the “contains” relation between the user and the group. If the user is in this group only, or the group is the parent group of the user (the containing OU in a LDAP directory) the user itself is deleted as well, to avoid unattached users in the DB.

Note

• to move a user to another group you have to first attach it to the new group and change its parent with ChangeUserProperties()!

COM

HRESULT RemoveUserFromGroup (
    BSTR strUserFQN,
    BSTR strGroupFQN
);

Parameters:

stUserFQN

[in] FQN or GUID of user to delete

strGroupFQN

[in] FQN or GUID of group from which the user will be removed

Note

• A user that does not belong to any group won’t get any profiles!

CreateFirstMSO

The first Security Officer will automatically be a Master SO.

COM

HRESULT CreateFirstMSO (
    BSTR strName,
    Certificate * certificate,
    BSTR wcsEMail,
    BSTR strComments
);

Note

• CAPICOM v2.0 is needed to use this function.

Parameters:

strName

[in] FQN of the first Master SO

certificate

[in] Certificate for the first Master SO (corresponding private key is needed)

wcsEMail

[in] E-Mail address

strComments

[in] Description

AddSO

Adds a security officer to the Database.

COM

HRESULT AddSO (
    BSTR strName,
    Certificate * certificateEnc,
    Certificate * certificateSign,
    BSTR wcsEMail,
    BSTR strComments,
    long lIsMSO,
    unsigned long ulPermissions
);

Note

• CAPICOM v2.0 is needed to use this function.

Parameters:

strName

[in] FQN of the new SO

certificateEnc

[in] Encryption certificate for the new SO

certificateSign

[in] Signature certificate for the new SO

wcsEMail

[in] E-Mail address

strComments

[in] Description

lIsMso

[in] 1 if the new SO should became a Master SO otherwise 0

ulPermissions

[in] Permissions assigned to the new SO

This function requires that another SO with sufficient rights is logged on to the u.trust LAN Crypt System.

A security officer is identified by his name and certificate. The SO can either be a master security officer, or a normal (restricted) security officer. In the later case, the exact permissions granted to the SO have to be specified.

If the new SO gets the permission “administer groups” or “administer users” then a new ACL for the root group will be created. The new SO gets the visible right on the root group.

RemoveSO

Removes a security officer from the Database.

COM

HRESULT RemoveSO (
    BSTR strName
);

Parameters:

strName

[in] FQN of the SO which should be removed

GrantRightsOnGroupToSO

Grants the specified rights to a security Officer. Rights are granted per group, and are inherited in the group hierarchy. Rights can also be revoked for a group, which denies the specified rights for the group and it’s subgroups.

To remove the ACL Entry for the SO, pass 0 for ulRights and ulDeniedRights.

LCAPIERR_INSUFFICIENT_RIGHTS is returned if the SO does not have the permissions corresponding to the rights to be set. Note that this is one of two functions where this return code might refer not only to the logged on SO but also to the SO passed to the function.

Note

• that MSOs can not be added to an ACL. If the passed SO is a MSO, LCAPIERR_INSUFFICIENT_RIGHTS is returned.

The rights passed will replace the existing rights, this function does not merge the new rights with existing ones.

In order to change rights, retrieve the existing rights with GetRightsOnGroupForSO with 2 as lFlags parameter first and pass the combined rights into GrantRightsOnGroupToSO.

COM

HRESULT GrantRightsOnGroupToSO (
    BSTR strGroupFQN,
    BSTR strSOName,
    unsigned long ulRights,
    unsigned long ulDeniedRights
);

Parameters:

strGroupFQN

[in] FQN or GUID of the group for which the SO will get some rights

strSOName

[in] Name of the SO which will get the rights

ulRights

[in] new rights to set

ulDeniedRights

[in] new rights to revoke

GrantRightsOnSOToSO

Allows some SO to do some actions on a different SO.

To remove the ACL Entry for the SO, pass 0 for ulRights.

LCAPIERR_INSUFFICIENT_RIGHTS is returned if the SO does not have the permissions corresponding to the rights to be set. Note that this is one of two functions where this return code might refer not only to the logged on SO but also to the SO passed to the function.

Note

• that MSOs can not be added to an ACL. If the passed SO is a MSO, LCAPIERR_INSUFFICIENT_RIGHTS is returned.

The rights passed will replace the existing rights, this function does not merge the new rights with existing ones.

In order to change rights, retrieve the existing rights with GetRightsOnSOForSO first and pass the combined rights into GrantRightsOnSOToSO!

COM

HRESULT GrantRightsOnSOToSO (
    BSTR strOnSOName,
    BSTR strToSOName,
    unsigned long ulRights
);

Parameters:

strOnSOName

[in] This is the name of the SO which can be changed by strToSOName

strToSOName

[in] This is the name of the SO which can change strOnSOName

ulRights

[in] new rights to set

GetRightsOnGroupForSO

Gets the rights the security Officer has on the group. Rights are returned in two parts, granted rights and denied rights. To get the effective rights, these two have to be combined in a way that clears all rights that are denied from the granted rights:

effectiveR = grantedR AND (NOT deniedR).

COM

HRESULT GetRightsOnGroupForSO (
    BSTR strGroupFQN,
    BSTR strSOName,
    VARIANT *ulRights,
    VARIANT *ulDeniedRights,
    long lFlags
);

Parameters:

strGroupFQN

[in] FQN or GUID of the group from which the SO rights should be read

strSOName

[in] Name of the SO whose rights should be read

ulRights

[out] granted rights

ulDeniedRights

[out] denied rights

lFlags

[in] read only rights on the group itself, or inherited rights as well?

1 … inherited only

2 … only defined in group

3 … combined (local and inherited)

GetRightsOnSOForSO

Gets the rights the security Officer has on another SO.

COM

HRESULT GetRightsOnSOForSO (
    BSTR strOnSOName,
    BSTR strToSOName,
    VARIANT *ulRights
);

Parameters:

strOnSOName

[in] This is the Name of the SO from which the rights should be read

strToSOName

[in] Name of the SO whose rights should be read

ulRights

[out] granted rights

WriteKey

Adds a new Key to the specified group, shortname of the key is automatically generated to be unique.

Note

• The global setting ‘Do not allow keys without value’ affects this function. If it is set, only Security Officers with the permission to create profiles can use this function!

COM

HRESULT WriteKey (
    BSTR strGroupFQN,
    BSTR strKeyLongName,
    long lAlgorithm,
    long lInheritable,
    long lIsSpecific,
    BSTR strKeyValue,
    BSTR strComment,
    VARIANT * strKeyShortName
);

Parameters:

strGroupFQN

[in] This is the FQN or GUID of the group that will get the new key; (“” if not required), ignored for specific keys (see lIsSpecific)

strKeyLongName

[in] This is the long key name

lAlgorithm

[in] number that specifies the cryptographic algorithm

lInheritable

[in]

0: key will be only available for rules in this group (strGroupFQN)

1: key will be available in this and in immediate subgroups

2: key will be available for this and all subgroups below.

ignored for specific keys (see lIsSpecific)

lIsSpecific

[in]

1 if this key should become a group- or user-specific key (not visible in GUI)

0 if this key should be used in a rule.

lstrKeyValue

[in] value of the new key as hexadezimal string (“” for random value)

lstrComment

[in] description

lstrKeyShortName

[out] generated (driver specific) short key name, must be of type array

Keys are identified by their shortnames which are stored in the header of encrypted files. Additionally they can have a long name which can be more descriptive and is displayed in the explorer extensions and usermode applications. To add a key, at least a name and a numeric algorithm identifier have to be specified. The shortname is derived from the name to be unique, and the key value is generated randomly if not specified (as string of hexadezimal values like 0x1234abcd56…., where the “0x” prefix is optional in version 3.11.2 and later).

The key name which is returned in the output parameter lstrKeyShortName must be used for further API calls which require a key name as input parameter (e.g. UpdateKeyEx, AddKeyToGroup, RemoveKeyFromGroup, ReadKey, WriteRule, EnableKey etc.)

If the key is flagged as specific, group and inheritance is ignored!

ImportKey

Adds a new Key to the specified group, shortname must not already exist in DB.

Note

• The global setting ‘Do not allow keys without value’ affects this function. If it is set, only Security Officers with the permission to create profiles can use this function!

COM

HRESULT ImportKey (
    BSTR strGroupFQN,
    BSTR strKeyLongName,
    BSTR strKeyShortName,
    long lAlgorithm,
    long lInheritable,
    long lIsSpecific,
    long lIsEnabled,
    BSTR strKeyValue,
    BSTR strComment
);

Parameters:

strGroupFQN

[in] This is the FQN or GUID of the group that will get the new key; (“” if not required), ignored for specific keys (see lIsSpecific)

strKeyLongName

[in] This is the long key name

strKeyShortName

[in] This is the short key name

lAlgorithm

[in] number that specifies the cryptographic algorithm

lInheritable

[in]

0: key will be only available for rules in this group (strGroupFQN)

1: key will be available in this and in immediate subgroups

2: key will be available for this and all subgroups below. ignored for specific keys (see lIsSpecific)

lIsSpecific

[in] 1 if this key should become a group- or user-specific key otherwise 0

lIsEnabled

[in] 1 if this key is enabled otherwise 0

lstrKeyValue

[in] value of the new key (“” for random value)

lstrComment

[in] description

Keys are identified by their shortnames which are stored in the header of encrypted files. Additionally they can have a long name which can be more descriptive and is displayed in the explorer extensions and usermode applications. To add a key, at least a name and a numeric algorithm identifier have to be specified. The key value is generated randomly if not specified (as string of hexadezimal values like 0x123456…., where the “0x” prefix is optional in version 3.11.2 and later).

If the key is flagged as specific, group and inheritance is ignored!

ImportKeyEx

Adds a new Key to the specified group, shortname must not already exist in DB.

Note

• The global setting ‘Do not allow keys without value’ affects this function. If it is set, only Security Officers with the permission to create profiles can use this function!

COM

HRESULT ImportKeyEx (
    BSTR strGroupFQN,
    BSTR strKeyLongName,
    BSTR strKeyShortName,
    long lAlgorithm,
    long lInheritable,
    long lIsSpecific,
    long lIsEnabled,
    BSTR strKeyValue,
    BSTR strComment,
    BSTR strGUID
);

Parameters:

strGroupFQN

[in] This is the FQN or GUID of the group that will get the new key; (“” if not required), ignored for specific keys (see lIsSpecific)

strKeyLongName

[in] This is the long key name

strKeyShortName

[in] This is the short key name

lAlgorithm

[in] number that specifies the cryptographic algorithm

lInheritable

[in] 0: key will be only available for rules in this group (strGroupFQN)

1: key will be available in this and in immediate subgroups

2: key will be available for this and all subgroups below.

ignored for specific keys (see lIsSpecific)

lIsSpecific

[in] 1 if this key should become a group- or user-specific key otherwise 0

lIsEnabled

[in] 1 if this key is enabled otherwise 0

strKeyValue

[in] value of the new key (“” for random value)

strComment

[in] description

strGUID

[in] Key GUID

Keys are identified by their shortnames which are stored in the header of encrypted files. Additionally they can have a long name which can be more descriptive and is displayed in the explorer extensions and usermode applications. To add a key, at least a name and a numeric algorithm identifier have to be specified. The key value is generated randomly if not specified (as string of hexadezimal values like 0x123456…., where the “0x” prefix is optional in version 3.11.2 and later).

If the key is flagged as specific, group and inheritance is ignored!

ImportKeyFile

Imports all keys from a SGLC 2.x keyfile. If there already is a key of the same name in the DB, it is ignored without warning!.

This function can return the following errors in case the import fail (in addition to the usual error codes):

LCAPIERR_INSUFFICIENT_RIGHTS: the keyfile does not allow export of keys (or SO has not enough rights to import key).

LCAPIERR_USER_NOT_FOUND: username or password are wrong.

LCAPIERR_OBJECT_NOT_FOUND: the specified file was not found.

LCAPIERR_FILE_IO: the keyfile must not be read only.

COM

HRESULT ImportKeyFile (
    BSTR strFileName,
    BSTR strGroupFQN,
    BSTR strUserName,
    BSTR strPassword,
    long lInheritable,
    long lIsSpecific,
    long lIsEnabled,
    BSTR strComment
);

Parameters:

strFileName

[in] This is the filename of the SGLC 2.x keyfile.

strGroupFQN

[in] This is the FQN or GUID of the group that will get the new keys; (“” if not required), ignored for specific keys (see lIsSpecific)

strUserName

[in] username to access the keyfile

strPassword

[in] password to access the keyfile

lInheritable

[in]

0: key will be only available for rules in this group (strGroupFQN)

1: key will be available in this and in immediate subgroups

2: key will be available for this and all subgroups below.

ignored for specific keys (see lIsSpecific)

lIsEnabled

[in] 1 if this key is enabled otherwise 0

lIsSpecific

[in] 1 if this key should become a group- or user-specific key otherwise 0

lstrComment

[in] description

Keys in SGLC 2.x only had a shortname, this name will also be used as longname.

If the key is flagged as specific, group and inheritance is ignored!

CreateCertificate

Creates a new certificate and the corresponding private key.

Note

• The certificate is also stored with its private key in the Windows certificate store (addressbook, other persons).

COM

HRESULT CreateCertificate (
    BSTR strName,
    Certificate * Cert
);

CAPICOM v2.0 is needed to use this function.

Before this function is called, the Certificate object must be created!

See example:

dim cert
set cert=CreateObject("CAPICOM.CERTIFICATE") result=lcapi.CreateCertificate("MySecurityOfficer", cert)

Parameters:

strName

[in] Name that will be inserted in the certificate’s subject field

Cert

[out] Certificate handle that can be used with the Microsoft Crypto API

CheckDBIntegrity

Runs an integrity check for the tables and the entries of the database (requires SO logon).

COM

HRESULT CheckDBIntegrity (
    VARIANT * lNumErrors
);

Parameters:

lNumError

[out] Number of found errors, must be of type long

GetDBIntegrityCheckReport

Returns the errors found by CheckDBIntegrity().

COM

HRESULT GetDBIntegrityCheckReport (
    VARIANT * strArrmag
);

Parameters:

strArrmag

[out] Array of strings with error description

RecalcMACForRecord

This function recalcs the MAC for a given record in an given table. It can be used to correct an existing MAC error.

COM

HRESULT RecalcMACForRecord (
    BSTR strTableName,
    long lRecordInTable,
    BSTR strObjectInTable,
    long lFlags
);

Parameters:

strTableName

[in] Name of database table that holds the record which will be updated. Possible values are (not case sensitive):

ACLMAC, ADMINISTRATORS, APPCONFIG, CERTIFICATES, KEYPOOL, KEYUSAGEPLACE, KEYUSAGEPLACEMAC, LCGROUPINLCGROUP, LCGROUPLCGROUPMAC, LCGROUPRULES, LCGROUPS, LOCATIONS, LOGDATA, MASTERKEYS, OWNLOCATION, RECOVERYKEY, SERVER, USERCERTIFICATES, USERINLCGROUP, USERLCGROUPMAC, USERS.

lRecordInTable

[in] ID of the record which will be updated

strObjectInTable

[in] For some tables it is possible to use a name to identify a record (only used if lRecordInTable is <= 0).

This is possible for the following tables: User, LCGroups, KeyPool, Server.

Note

• Records in some tables can ONLY be identified by name and not by ID: AppConfig, Location, OwnLocation.

lFlags

[in] reserved for future use

UpdateKey

Changes some properties of a key.

COM

HRESULT UpdateKey (
    BSTR strFQNGroup,
    BSTR strKeyName,
    BSTR strKeyLongName,
    BSTR strComment,
    long lInherited
);

Parameters:

strFQNGroup

[in] FQN or GUID of the Group that holds the key

strKeyName

[in] short name of the key which will be updated

strKeyLongName

[in] new long key name, use “” if you want to keep the current value

strComment

[in] description, use “” if you want to keep the current value

lInherited

[in]

0 not inheritable,

1 inheritable one level,

2 inheritable,

-1 keep current value

Note

• strKeyName is the unique short (or driver) key name which is returned by WriteKey in the last parameter (because it is generated automatically). This unique key name can also be seen in the admin GUI as a property of the key and it can be retrieved by calling EnumKeys.

UpdateKeyEx

Changes some properties of a key. Use this function with extra caution; it can be used to circumvent mechanisms that protect keys from accidental deletion! Note also that a key that is flagged as specific is automatically also flagged as ‘InUse’ even if the last parameter says otherwise. This is to get the same behavior as in the GUI.

Requires MSO rights!

COM

HRESULT UpdateKeyEx (
    BSTR strKeyShortName,
    BSTR strKeyLongName,
    long lIsSpecific,
    long lIsInUse
);

Parameters:

strKeyShortName

[in] short name of the key which will be updated

strKeyLongName

[in] new long key name, use “” if you want to keep the current value

lIsSpecific

[in]

0 normal key,

1 specific key (USERKEY, GROUPKEY),

-1 keep current value

lIsInUse

[in]

0 set key to ‘never used in a rule’,

1 set key to ‘already used in a rule’,

-1 keep current value

AddKeyToGroup

Adds a key to a group. By passing -1 as lInheritable flag the key is added as a reference, this means the key can be used for rules in the target group, but not in subgroups of the target group. This is the same behavior as with the copy&paste or drag&drop feature in the GUI.

This function fails if the key is already available in the target group because of inheritance, or if the key is already assigned to another group!

Specific keys cannot be assigned to a group. To change the specific key of a group, SetGroupProperties has to be used.

COM

HRESULT AddKeyToGroup (
    BSTR strKeyShortName,
    BSTR strGroupFQN,
    long lInheritable
);

Parameters:

strKeyShortName

[in] short name of the key which will be added to the group

strGroupFQN

[in] FQN or GUID of the group that should contain the key

lInheritable

[in] 0: key will be only available for rules in this group (strGroupFQN)

1: key will be available in this and in immediate subgroups

2: key will be available for this and all subgroups below.

-1:key will be added as reference/copy (see SGLCAdmin manual for details)

RemoveKeyFromGroup

Removes a key from a group. Afterwards the key can no longer be used for rules in this group. If the group is the primary location of the key, the key is removed from all secondary locations (if any) as well. This is to get the same behavior as in the GUI.

COM

HRESULT RemoveKeyFromGroup (
    BSTR strKeyShortName,
    BSTR strGroupFQN
);

Parameters:

strKeyShortName

[in] short name of the key which will be removed

strGroupFQN

[in] FQN or GUID of the group that contains the key

DeleteKey

Deletes a key from the database. This is only possible, if

• a Master Security Officer is logged on

• the key is not used in any encryption rule

• the key is not present in any group

• specific keys must not be assigned to a group or user • the key must be deactivated.

Note

• Delete a key only if you are really sure that it is no longer needed. Files encrypted with this key can no longer be accessed and there is no recovery option, except restoring the key from a database backup!

COM

HRESULT DeleteKey (
    BSTR strKeyShortName
);

Parameters:

strKeyShortName

[in] short name of the key which will be deleted

EnumKeys

Return the shortnames of all keys that belong to a group.

COM

HRESULT EnumKeys ( BSTR strGroupFQN, VARIANT * lSize,
VARIANT * strNames,
    long    fIncludeInherited
);

Parameters:

strFQNGroup

[in] FQN or GUID of the Group that holds the keys

lSize**

[out] required size of strNames

strNames

[out]

string array of size lSize (COM)

fIncludeInherited

[in] should inherited keys be returned as well?

1 .. yes include inherited keys;

0 .. only keys defined in the group.

ReadKey

Returns information about a key.

COM

HRESULT ReadKey (
  BSTR strKeyShortName,
  VARIANT * strParentGroupFQN,
  VARIANT * lAlgorithm,
  VARIANT * lInheritable,
  VARIANT * lIsSpecific,
  VARIANT * strKeyValue,
  VARIANT * strComment,
  VARIANT * strKeyLongName,
  VARIANT * lIsEnabled
);

Parameters:

strKeyShortName

[in] Key name for which you want to get the information

strParentGroupFQN

[out] FQN of the group that holds the key, must be of type array

lAlgorithm

[out] cryptographic algorithm that is connected to this key, must be of type long

lInheritable

[out] reports if the key is inheritable or not, must be of type long

0: key is only available for rules in the parent group (strParentGroupFQN)

1: key is available in the parent and in the direct below subgroups

2: key is available in the parent group and all subgroups below.

lIsSpecific

[out] reports if the key is a group or a user specific key or a ordinary key, must be of type long

strKeyValue

[out] key value (either encrypted or plain depending on the rights of the currently logged on SO). Returns an empty key value (empty string) if an additional authorization is defined for displaying the key values. The function itself return success in such a case. Must be of type array.

strComment

[out] description, must be of type array

strKeyLongName

[out] long key name, must be of type array

lIsEnabled

[out] reports if the key is enabled or disabled

ReadKeyEx

Returns information about a key.

COM

HRESULT ReadKeyEx (
  BSTR strKeyID,
  VARIANT * strParentGroupFQN,
  VARIANT * lAlgorithm,
  VARIANT * lInheritable,
  VARIANT * lIsSpecific,
  VARIANT * strKeyValue,
  VARIANT * strComment,
  VARIANT * strKeyLongName,
  VARIANT * strKeyShortName,
  VARIANT * strGUID,
  VARIANT * lIsEnabled
);

Parameters:

strKeyID

[in] Short key name or GUID for which you want to get the information

strParentGroupFQN

[out] FQN of the group that holds the key, must be of type array

lAlgorithm

[out] cryptographic algorithm that is connected to this key, must be of type long

lInheritable

[out] reports if the key is inheritable or not, must be of type long

0: key is only available for rules in the parent group (strParentGroupFQN) 1: key is available in the parent and in the direct below subgroups

2: key is available in the parent group and all subgroups below.

lIsSpecific

[out] reports if the key is a group or a user specific key or a ordinary key, must be of type long

strKeyValue

[out] key value (either encrypted or plain depending on the rights of the currently logged on SO). Returns an empty key value (empty string) if an additional authorization is defined for displaying the key values. The function itself return success in such a case. Must be of type array.

strComment

[out] description, must be of type array

strKeyLongName

[out] long key name, must be of type array

strKeyShortName

[out] short key name, must be of type array

strGUID

[out] key GUID, must be of type array

lIsEnabled

[out] reports if the key is enabled or disabled

AssignCertificateToUser

Assigns a certificate to a user

COM

HRESULT AssignCertificateToUser (
  BSTR strUserFQN,
  Certificate  * Cert
);

Note

• CAPICOM v2.0 is needed to use this function.

Parameters:

strUserFQN

[in] FQN or GUID of user for which you want to assign a certificate

Cert

[in] Certificate handle

RemoveCertificateFromUser

Remove a certificate from a user.

COM

HRESULT RemoveCertificateFromUser ( BSTR strUserFQN,
Certificate * Cert
);

Note

• CAPICOM v2.0 is needed to use this function.

Parameters:

[in] CCertificate handle / Certificate Object.

RemoveAllCertificatesFromUser

Removes all certificates from a user.

COM

HRESULT RemoveAllCertificatesFromUser ( BSTR strUserFQN
);

EnumCertificatesOfUser

Returns all certificates for a specific user.

COM

HRESULT EnumCertificatesOfUser ( BSTR strUserFQN, Certificates2 *Certificates
);

Parameters:

strUserFQN

[in] FQN or GUID of user for which you want to retrieve the certificates

Certificates

[out] Collection of certificate handles

GetSOCertificate

Reads the certificates currently assigned to a security officer. The executing SO must have read access to the target SO.

COM

HRESULT GetSOCertificate (
BSTR strName,
Certficate * CertificateEnc, Certficate * CertificateSign
);

Note

• CAPICOM v2.0 is needed to use this function.

Parameters:

strName

[in] FQN of the security officer

CertificateEnc

[in] Encryption certificate handle

CertificateSign

[in] Signature certificate handle

SetSOCertificate

Assigns a certificate to a security officer. If the Target SO is a MSO or has the permission to create profiles (meaning the SO has cryptographic access to the DB encryption key) the executing SO must have access to the encryption key as well in order to perform the necessary recrypting.

COM

HRESULT SetSOCertificate (
BSTR strName,
Certficate * CertificateEnc, Certficate * CertificateSign
);

Note

• CAPICOM v2.0 is needed to use this function.

Parameters:

strName

[in] FQN of the security officer

CertificateEnc

[in] Encryption certificate handle

CertificateSign

[in] Signature certificate handle

CSetSOPermissions

Set the permission of a given security officer.

COM

HRESULT SetSOPermissions (
    BSTR strName,
    unsigned long ulPermissions
);

Parameters:

strName

[in] FQN of the security officer

ulPermissions

[in] set of permissions that the SO gets

If the SO gets the permission “administer groups” or “administer users” and there is no ACL for this SO on the root group then such an ACL is created. It holds the visible right. Existing ACLs are not changed.

GetSOPermissions

Reads the permissions and MSO state of a given security officer.

COM

HRESULT GetSOPermissions (
    BSTR strName,
    VARIANT *fIsMSO,
    VARIANT *ulPermissions
);

Parameters:

strName

[in] FQN of the security officer

fIsMSO

[out] 1 if the SO is a MSO, 0 otherwise

ulPermissions

[out] set of permissions that the SO has

WriteRule

Adds a new rule to the specified group.

COM

HRESULT WriteRule (
    BSTR strGroupFQN,
    BSTR strPath,
    BSTR strKeyShortName,
    BSTR strFlags
);

Parameters:

strGroupFQN

[in] FQN or GUID of the group that gets the rule

strPath

[in] Path that describes to files for which the rule apply or the name of the encryption tag.

strKeyShortName

[in] Name of the key that will be used in this rule, or one of the special names “” or “”. The key must be enabled.

strFlags

[in] flags that describes if subdirectories should be included, etc.

Rules consist of a path (including filespecs with wildcards), a keyname and optional flags (/S include subdrirectories; /I ignore this path; /X exclude this path from encryption; /T for an encryption tag). If /X or /I is specified, no key is used for this rule. If /T is used, no other flags are allowed.

A rule that only consists of a keyname is valid. Such a rule does not trigger encryption, but allows a user to read files that are encrypted with this key.

Note

• That this rule also applies to any group that is a subgroup of the specified group!

WriteRuleEx

Adds a new rule to a specified group. This function is identical with WriteRule but has an additional input parameter for a rule comment.

COM

HRESULT WriteRuleEx (
    BSTR strGroupFQN,
    BSTR strPath,
    BSTR strKeyShortName,
    BSTR strFlags,
    BSTR strComment
);

Parameters:

strGroupFQN

[in] FQN or GUID of the group that gets the rule

strPath

[in] Path that describes to files for which the rule apply or the name of the encryption tag

strKeyShortName

[in] Name of the key that will be used in this rule, or one of the special names <USERKEY> or <GROUPKEY>. The key must be enabled. strFlags

[in] flags that describes if subdirectories should be included, etc.

strComment

[in] holds a comment for this rule

StartResolverForUser

Generates a profile for the specified user. Such a profile contains all rules that apply to the user through all groups or subgroups the user is member of. Also contained in the profiles are all keys that are referenced in this rules.

There is only one profile creation at one time per Windows-session possible. If more than one SGLC API instance is running within one session, the API calls for profile generation must be in a sequence and not parallel.

COM

HRESULT StartResolverForUser (
    BSTR strUserFQN,
    BSTR strOutputDir
);

Parameters:

strUserFQN

[in] FQN or GUID of the user for which you want to create a profile

strOutputDir

[in] Path in which the profile file should be stored

The profile file is cryptographically secured against modification and access to the key values.

StartResolverForUsersOfGroup

Generates profiles for all users in the specified group regardless of the state of the changed flag.

Note

• If the function is called as SO, all users are skipped for which the SO has not the proper rights. A user is processed if the SO has the right Create Profiles on the users parent group or the right Create Profiles for all Members in one of the processed groups.

There is only one profile creation at one time per Windows-session possible. If more than one SGLC API instance is running within one session, the API calls for profile generation must be in a sequence and not parallel.

COM

HRESULT StartResolverForUsersOfGroup ( BSTR strGroupFQN,
BSTR strOutputDir,
long lWithSubgroups
);

Parameters:

strGroupFQN

[in] FQN or GUID of the group

strOutputDir

[in] Path in which the profile file should be stored

lWithSubgroups

[in] 0 if other groups in strGroupFQN should be ignored, 1 if all other groups in strGroupFQN and all the user should also receive a profile.

It is possible to start the resolver for all users in a group and all subgroups below this group. This allows to generated profiles for every user in a certain part of the organization. The changed flags of the groups are ignored, that means new profiles are generated even if it is not set. After generating profiles all changed flags are cleared.

StartResolverForUsersOfChangedGroup

Generates profiles for all users in the specified group if the group has been marked as changed.

Note

• If the function is called as SO, all users are skipped for which the SO has not the proper rights. A user is processed if the SO has the right Create Profiles on the users parent group or the right Create Profiles for all Members in one of the processed groups.

There is only one profile creation at one time per Windows-session possible. If more than one SGLC API instance is running within one session, the API calls for profile generation must be in a sequence and not parallel.

COM

HRESULT StartResolverForUsersOfChangedGroup (
    BSTR strGroupFQN,
    BSTR strOutputDir,
    long lWithSubgroups
);

Parameters:

strGroupFQN

[in] FQN or GUID of the group

strOutputDir

[in] Path in which the profile file should be stored

lWithSubgroups

[in]

0 if other groups in strGroupFQN should be ignored,

1 if all other groups in strGroupFQN and all the user should also receive a profile.

It is possible to start the resolver for all users in a group and all subgroups below this group. This allows to generated profiles for every user in a certain part of the organization. Only profile of groups which are marked as changed will be generated. After generating profiles all changed flags are cleared.

AssignCertificatesToUsersOfGroup

Tries to find Objects in the specified directory (LDAP or ActiveDirectory) that correspond to the users in the specified Group (optionally also for all Users in Subgroups) and assigns any certificates attached to the Directory Object to the user in the u.trust LAN Crypt Database.

Note

• If the function is called as SO, all users are skipped for which the SO has not the proper rights. A user is processed if the SO has the right Assign Certificate on the users parent group or the right Assign Certificates to all Members in one of the processed groups.

COM

HRESULT AssignCertificatesToUsersOfGroup (
    BSTR strGroupFQN,
    long lWithSubgroups,
    BSTR strLDAPServer,
    long lLCAttr,
    long lLDAPAttr
);

Parameters:

strGroupFQN

[in] FQN or GUID of the group

lWithSubgroups

[in] 0 ignore subgroups, otherwise 1

strLDAPServer

[in] DNS name of LDAP or AD server, if it starts with “LDAP::” then LDAP is used otherwise Active Directory is assumed

lLCAttr

[in] specifies the attribute from the LC database which is used for matching 0 username

1 logon name

2 email address

lLDAPAttr

[in] specifies the attribute from the LDAP directory database which is used for matching

0 common name

1 display name

2 NT account name

3 email address

4 LDAP UPN (user principle name)

Example:

if lLCAttr = 0 and lLDAPAttr = 0 then the user name form the LC database is used as a search criteria for common name in LDAP or AD.

CreateCertificatesForUsersOfGroup

Creates self-signed Certificates for all Users in a Group without assigned certificates (optionally also for all Users in Subgroups) and assigns them to the users.

Note

• If the function is called as SO, all users are skipped for which the SO has not the proper rights. A user is processed if the SO has the right Assign Certificate on the users parent group or the right Assign Certificates to all Members in one of the processed groups.

COM

HRESULT CreateCertificatesForUsersOfGroup (
    BSTR strGroupFQN,
    long lWithSubgroups
);

Parameters:

strGroupFQN

[in] FQN or GUID of the group

lWithSubgroups

[in] 0 ignore subgroups, otherwise 1

SetUserKey

Sets the userkey of a specified user.

This function can also be used to renew the userkey for this user, optionally keeping the previous userkey attached to the user to allow encrypted files to still be accessible. Such ‘old userkeys’ will automatically be added to the userprofiles until they are explicitly detached from the user. Fails with LCAPIERR_KEY_NOT_DISTINCT if the key is already a userkey.

COM

HRESULT SetUserKey (
    BSTR strUserFQN,
    BSTR strSpecificKey,
    long lOption
);

Parameters:

strUserFQN

[in] FQN or GUID of the user for which the userkey should be set.

strSpecificKey

[in] short name of an existing key that is not yet in use as a userkey.

lOption

[in] Flag to control the behaviour of this function.

Possible values for lOption are:

USERKEY_ADD_AS_PRIMARY_KEY (1)

Set as ‘normal’ userkey. Fails with LCAPIERR_KEY_ALREADY_EXISTS if user already has a userkey.

USERKEY_ADD_AS_OLD_KEY (2)

Set as ‘old userkey’ and leaves the normal userkey unaffected.

USERKEY_REPLACE_PRIMARY_KEY (4)

Set as normal userkey; previous userkey will not stay attached to the user.

USERKEY_RETIRE_PRIMARY_KEY (8)

Set as normal userkey; previous userkey will stay attached to the user as ‘old userkey’. Fails with LCAPIERR_KEY_NOT_FOUND if there is no primary key.

EnumUserKeysOfUser

Return the shortnames of all specific userkeys that belong to a user (see SetUserKey, EnumKeysForUser).

Note

• Userkeys are only included in the users profile if they are used in a rule. However ‘old userkeys’ are always included in the profile.

COM

HRESULT EnumUserKeysOfUser (
    BSTR     strUserFQN,
    VARIANT *lSize,
    VARIANT *strNames
);

Note

• If strNames is too small then an error is returned and the needed size is returned in lSize.

Parameters:

strUserFQN

[in] FQN or GUID of the user

lSize

[out] required size of strNames

strNames

[out]

string array of size lSize (COM)

DetachUserKey

Removes a normal or old userkey from a specified user.

COM

HRESULT DetachUserKey (
    BSTR strUserFQN,
    BSTR strSpecificKey
);

Parameters:

strUserFQN

[in] FQN or GUID of the user.

strSpecificKey

[in] short name of an userkey.

DeleteProfile

Clears the profile for a specified user. An empty profile is created that will overwrite the cached profile on the clients.

Note

• This clears only the profile in the specified location, it is still possible that there are profiles in different directories!

COM

HRESULT DeleteProfile (
    BSTR strUserFQN,
    BSTR strOutputDir
);

Parameters:

strUserFQN

[in] FQN or GUID of the user for which you want to clear the profile.

strOutputDir

[in] Path in which the profile file has been stored

EnableKey

Enables or disables a key.

Specific keys can be enabled or disabled by a Master Security Officer or by an Security Officer which has the global permissions Use specific Keys granted in addition to Create Key.

COM

HRESULT EnableKey (
    BSTR strKeyShortName,
    long lEnable
);

Parameters:

strKeyShortName

[in] Short name of the key.

lEnable

[in] Change the activation state of a key.

1 … enable key

0 … disable key

EnumUsersWithFilter

Enumerates the fully qualified name (FQN) of all users that match a defined filter.

COM

HRESULT EnumUsersWithFilter ( int iAttr1,
    BSTR strFilterAttr1,
    int iNegate1
    int iAttr2,
    BSTR strFilterAttr2,
    int iNegate2
    int iAndOr
    VARIANT * lSize,
    VARIANT * strUserFQNs
);

Note

• If strUserFQNs is too small then an error is returned and the needed size is returned in lSize.

Parameters:

iAttr1, iAttr2

[in] which attribute of the user should match strFilterAttr

IMPORTANT: Set iAttr2 to a value outside the valid range if the second condition is not used. Otherwise the parameters for the second condition are evaluated!

strFilterAttr1, strFilterAttr2

[in] text pattern that is compared with the attribute specified in iAttr. Can contain SQL wildcards:

iNegate1, iNegate2

[in] (1) inverts the condition, NOT (strFilterAttr like Attr(iAttr)); (0) is normal

iAndOr

[in] are both conditions required (1) or any of them (0)

lSize

[out] required size of strUserFQNs

strUserFQNs

[out] string array of size lSize (COM)

pFilter

[in] array of struct _UserFilter

iKind … use constants as described in iAttr

iFilterMode … a combination of the following flags:

szAnyUserAttr … string that should match the specified attribute

Structure info (defined in sglccoreapi.h):

typedef struct _UserFilter
{
      int iKind, iFilterMode;
      WCHAR szAnyUserAttr[504];
} UserFilter, *PUserFilter;

EnumUsersOfGroup

Enumerates the fully qualified name (FQN) of all users that belong to a group.

COM

HRESULT EnumUsersOfGroup (
    BSTR strGroupFQN,
    VARIANT * lSize,
    VARIANT * strNames
);

Note

• If strNames is too small then an error is returned and the needed size is returned in lSize.

Parameters:

strGroupFQN

[in] FQN or GUID of the Group that holds the users or “” for all users in the database.

lSize

[out] required size of strNames

strNames

[out]

string array of size lSize (COM)

EnumGroupParents

Enumerates the fully qualified name (FQN) of all parent groups of a group.

COM

HRESULT EnumGroupParents (
    BSTR strGroupFQN,
    VARIANT * lSize,
    VARIANT * strParentGroupFQNs
);

Note

• If strParentGroupFQNs is too small then an error is returned and the needed size is returned in lSize.

Parameters:

strGroupFQN

[in] FQN or GUID of the Group that holds the groups

lSize

[out] required size of strParentGroupFQNs

strParentGroupFQNs

[out]

string array of size lSize (COM)

EnumSubGroups

Enumerates the fully qualified name (FQN) of all subgroups that belong to a group.

COM

HRESULT EnumSubGroups (
  BSTR strGroupFQN,
  VARIANT * lSize,
  VARIANT * strSubGroupFQNs
);

Note

• If strSubGroupFQNs is too small then an error is returned and the needed size is returned in lSize.

Parameters:

strGroupFQN

[in] FQN or GUID of the Group that holds the groups. Use “SpecialRootGroup” to get the top groups.

lSize

[out] required size of strSubGroupFQNs

strSubGroupFQNs

[out]

string array of size lSize (COM)

EnumRulesForGroup

Returns the IDs and paths of all rules that are visible in a group, or for all rules if “” is passed as GroupFQN.

COM

HRESULT EnumRulesForGroup ( BSTR strGroupFQN, VARIANT * lSize, VARIANT * strRuleIDs VARIANT * strRulePaths
);

Note

• If strRuleIDs is too small then an error is returned and the needed size is returned in lSize. strRuleIDs and strRulePaths must be of the same size! strRulePaths can be 0 / NULL.

Parameters:

strGroupFQN

[in] FQN or GUID of the Group that holds the rules, or “” for all rules.

lSize

[out] required size of strRuleIDs

strRuleIDs

[out]

string array of size lSize (COM)

strRulePaths

[out]

string array of size lSize (COM)

Note

• To get the group where the rule has been defined, use GetRuleProperties().

• Encryption tags are also returned by this function and the tag name is stored in strRulePaths. To distinguish between encryption rules and encryption tags, GetRuleProperties has to be called.

GetRuleProperties

Returns the properties of an existing rule.

COM

HRESULT GetRuleProperties (
    BSTR strRuleID,
    VARIANT * strRulePath
    VARIANT * strKeyShortName,
    VARIANT * strFlags,
    VARIANT * strInherited
);

Parameters:

strRuleID

[in] ID of the rule.

strRulePath

[out] Defined path of the rule or the name of the encryption tag.

strKeyShortName

[out] Short name of the key.

strFlags

[out] Flags of the rule.

strInherited

[out] The group, in which the rule is defined.

Note

• The ID of the rule must already exist in the database.

GetRulePropertiesEx

Returns the properties of an existing rule. This function is identical to GetRuleProperties but has additional parameters for the rule comment.

COM

HRESULT GetRulePropertiesEx (
  BSTR strRuleID,
  VARIANT * strRulePath
  VARIANT * strKeyShortName,
  VARIANT * strFlags,
  VARIANT * strInherited,
  VARIANT * strComment
);

Parameters:

strRuleID

[in] ID of the rule.

strRulePath

[out] Defined path of the rule or the name of the encryption tag.

strKeyShortName

[out] Short name of the key.

strFlags

[out] Flags of the rule.

strInherited

[out] The group, in which the rule is defined.

strComment

[out] Comment of the rule.

ulCommentSize

[in] Size of strComment in characters.

Note

• The ID of the rule must already exist in the database. If the allocated memory of strComment is too small nothing will be returned.

SetRuleProperties

Change the properties of an existing rule.

Note

• In order to change the owner group of a rule it is necessary to delete and re-create the rule in the new group!

COM

HRESULT SetRuleProperties (
    BSTR strRuleID,
    BSTR strRulePath
    BSTR strKeyShortName,
    BSTR strFlags
);

Parameters:

strRuleIDs

[in] ID of the rule

strRulePath

[in] Defined path of the rule or the name of the encryption tag.

strKeyShortName

[in] Short name of the key

strFlags

[in] Flags of the rule. An encryption tag (/T) cannot be turned to an encryption rule and vice versa.

Note

• The ID of the rule must already exist in the database.

SetRulePropertiesEx

Change the properties of an existing rule. This function is identical to SetRuleProperties but has an additional input parameter for a rule comment.

Note

• In order to change the owner group of a rule it is necessary to delete and re-create the rule in the new group!

COM

HRESULT SetRulePropertiesEx (
    BSTR strRuleID,
    BSTR strRulePath
    BSTR strKeyShortName,
    BSTR strFlags,
    BSTR strComment,
);

Parameters:

strRuleIDs

[in] ID of the rule

strRulePath

[in] Defined path of the rule or the name of the encryption tag.

strKeyShortName

[in] Short name of the key

strFlags

[in] Flags of the rule. An encryption tag (/T) cannot be turned to an encryption rule and vice versa.

strComment

[in] Comment for the rule

Note

• The ID of the rule must already exist in the database.

DeleteRule

Deletes a rule from the Database.

COM

HRESULT DeleteRule (
    BSTR strRuleID
);

Parameters:

strRuleID

[in] ID of the rule

EnumGroupsForUser

Returns all groups in which the user is member of.

COM

HRESULT EnumGroupsForUser (
  BSTR strUserFQN,
  VARIANT * lSize,
  VARIANT * strGroupFQNs
);

Note

• If strGroupFQNs is too small then an error is returned and the needed size is returned in lSize.

Parameters:

strUserFQN

[in] Fully qualified name or GUID of the user

lSize

[out] required size of strGroupFQNs

strGroupFQNs

[out]

string array of size lSize (COM)

EnumRulesForUser

Returns all rules that belong to a user.

COM

HRESULT EnumRulesForUser (
    BSTR strUserFQN,
    VARIANT * lSize,
    VARIANT * strRuleIDs
);

Note

• If strRuleIDs is too small then an error is returned and the needed size is returned in lSize.

Parameters:

strUserFQN

[in] Fully qualified name or GUID of the user

lSize

[out] required size of strRuleIDs

strRuleIDs

[out]

string array of size lSize (COM)

EnumKeysForUser

Returns all keys that a user will get through rules.

Note

• The user’s profile will also contain userkeys (see SetUserKey, EnumUserKeysOfUser).

COM

HRESULT EnumKeysForUser (
    BSTR strUserFQN,
    VARIANT * lSize,
    VARIANT * strKeyShortNames
);

Note

• If strKeyShortNames is too small then an error is returned and the needed size is returned in lSize.

Parameters:

strUserFQN

[in] Fully qualified name or GUID of the user

lSize

[out] required size of strKeyShortNames

strKeyShortNames

[out]

string array of size lSize (COM)

EnumGroupsForRule

Returns all groups to which the rule applies.

COM

HRESULT EnumGroupsForRule (
  BSTR strRuleID,
  VARIANT * lSize,
  VARIANT * strGroupFQNs
);

Note

• If strGroupFQNs is too small then an error is returned and the needed size is returned in lSize.

Parameters:

strRuleID

[in] ID of the rule

lSize

[out] required size of strGroupFQNs

strGroupFQNs

[out]

string array of size lSize (COM)

EnumUsersForKey

Returns all users which have the specified key in their profiles.

COM

HRESULT EnumUsersForKey (
  BSTR strKeyShortName,
  VARIANT * lSize,
  VARIANT * strUserFQNs
);

Note

• If strUserFQNs is too small then an error is returned and the needed size is returned in lSize.

Parameters:

strKeyShortName

[in] Short name of the key.

lSize

[out] required size of strUserFQNs

strUserFQNs

[out]

string array of size lSize (COM)

EnumGroupsForKey

Returns all groups for which the key belongs.

COM

HRESULT EnumGroupsForKey (
    BSTR strKeyShortName,
    VARIANT * lSize,
    VARIANT * strGroupFQNs
);

Note

• If strGroupFQNs is too small then an error is returned and the needed size is returned in lSize.

Parameters:

strKeyShortName

[in] Short name of the key.

lSize

[out] required size of strGroupFQNs

strGroupFQNs

[out]

string array of size lSize (COM)

EnumRulesForKey

Returns all rules in which the key is used.

COM

HRESULT EnumRulesForKey (
  BSTR strKeyShortName,
  VARIANT * lSize,
  VARIANT * strRuleIDs
);

Note

• If strRuleIDs is too small then an error is returned and the needed size is returned in lSize.

Parameters:

strKeyShortName

[in] Short name of the key.

lSize

[out] required size of strRuleIDs

strRuleIDs

[out]

string array of size lSize (COM)

EnumSOs

Returns all Security Officers that match the specified criteria.

COM

HRESULT EnumSOs (
    BSTR      strRegionFilter,
    unsigned long  ulPermissionFilter,
    VARIANT * lSize,
    VARIANT * strSONames
);

Note

• If strSONames is too small then an error is returned and the needed size is returned in lSize.

Parameters:

strRegionFilter

[in] empty string or name of a region if only SOs of this region should be returned

ulPermissionFilter

[in] required permissions; only SOs that have this permissions are returned to get SOs that can be used for LogonSO, set to SO_R_LOGINDB

lSize

[out] required size of strSONames

strSONames

[out]

string array of size lSize (COM)

EnumSOsForGroup

Returns all Security Officers that have rights on a group (MSOs are not included).

COM

HRESULT EnumSOsForGroup (
    BSTR      strGroupFQN,
    VARIANT * lSize,
    VARIANT * strSONames
);

Note

• If strSONames is too small then an error is returned and the needed size is returned in lSize.

Parameters:

strGroupFQN

[in] FQN or GUID of the group of which a list of SOs should be returned

lSize

[out] required size of strSONames

strSONames

[out]

string array of size lSize (COM)

EnumGroupsForSO

Returns all groups a given Security Officers has rights on (when called with a MSOs this will return all groups!)

COM

HRESULT EnumGroupsForSO (
    BSTR      strSOName,
    VARIANT * lSize,
    VARIANT * strGroupFQNs,
    long      lWithSubgroups
);

Note

• If strGroupFQNs is too small then an error is returned and the needed size is returned in lSize.

Parameters:

strSOName

[in] name of the Security Officer for which a list of groups should be returned

lSize

[in, out] required size of strGroupFQNs

strGroupFQNs

[out]

string array of size lSize (COM)

lWithSubgroups/fWithSubgroups

[in] if not 0 respectively if TRUE all groups are returned including those where the SO has inherited rights, otherwise only the groups are returned where the SO was added to the ACL.

GetParentOfUser

Returns the group (most likely an organizational unit) that is the parent of the user in the directory hierarchy. If the user has no parent, LCAPIERR_GROUP_NOT_FOUND is returned.

COM

HRESULT GetParentOfUser (
    BSTR      strUserFQN,
    VARIANT * strParentFQN
);

Parameters:

strUserFQN

[in] name of the user for which the parent should be returned

strParentFQN

[out] name of the parent

GetParentOfGroup

Returns the group (most likely an organizational unit) that is the parent of the group in the directory hierarchy. If the group has no parent, LCAPIERR_GROUP_NOT_FOUND is returned.

COM

HRESULT GetParentOfGroup (
    BSTR      strGroupFQN,
    VARIANT * strParentFQN
);

Parameters:

strGroupFQN

[in] name of the group for which the parent should be returned

strParentFQN

[out] name of the parent

IsLinkedGroup

This function checks if a group g_1 has a parent group g_p and if this association is consistently stored in the data base. That means that group g_1 has the parent group g_p and group g_1 is associated as subgroup with parent group g_p. The result is stored in the value isLinked.

Formally the value of isLinked is exactly true if the following is true:

• There are groups with the names strGroupFQN and strParentFQN in the data base

• It exists in table LCGROUPS a row with CO_ID=group_id and CO_PARENT=parent_Id or CO_PARENT=NULL

• It exists in table LCGROUPINLCGROUP exactly one row with (CC_MEMBER_LCGROUP, CC_LCGROUP_GROUP) = (group_ID, parent_group_ID)

In other cases, isLinked is false. If one group does not exist or group has another parent, then return value is not LCAPIERR_OK.

COM

HRESULT IsLinkedGroup (
  BSTR strGroupFQN,
  BSTR strParentFQN,
  VARIANT *isLinked
);

Parameters:

strGroupFQN

[in] name of the group which should have the passed parent

strParentFQN

[in] name of the parent group

isLinked

[out] long value, which is SGMERR_OK if the above conditions are fulfilled.

GetParentGroupOfKey

This function gets the name of the parent group of the group, which is owner of the key with passed key name.

If group or parent group do not exist or callee has not the defined roles and rights, then an error code is returned and strParentGroupFQN is an empty string.

If group or parent group do not exist or callee has not the defined roles and rights, then a error code is returned, else SGMERR_OK.

COM

HRESULT GetParentGroupOfKey (
    BSTR      strKeyID,
    VARIANT * strParentGroupFQN
);

Parameters:

key_name

[in] FQN of the key

strParentGroupFQNd

[out] Name of the parentgroup, if it exists, else it is an empty string

Constant Values

Numeric values

The following tables contain constant values that are used as input parameters in several of the functions. Values for permissions and rights usually are combinations (OR) of several constants.

Algorithms for keys

Rights of a Security Officer on a Group

Rights of a Security Officer on another Security Officer

Permissions for Security Officer

Group Types

Explanation:

• Special Group: u.trust LAN Crypt default root node of all groups

String values

Special Group Names:

• SpecialRootGroup

The special group name can be used in the functions WriteKey, ImportKey, WriteRule, GrantRightsOnGroupToSO, StartResolverForUsersOfGroup, StartResolverForUsersOfChangedGroup and EnumSubGroups and refers to the top- level “groups” node.

If this special name is passed to the function CreateGroup as parent group, the semantics is the same as passing an empty parent (the new group is displayed below the top-level node).

Special Group Names:

• <USERKEY>
• <GROUPKEY>
• <CLEAR>

<USERKEY> and <GROUPKEY> can be used in rules (see manual for details).

<CLEAR> can be used in SetUserProperties() and SetGroupProperties() to clear a specific key assignment.

Parameter restrictions

If these characters are used in logon names, short names or SO names some operations will fail that use this names to build filenames (for profiles, certificates or keyfiles).

So all of these characters are rejected with the return code LCAPIERR_INVALID_ARGUMENT.

If these characters are used in logon names, short names, SO names or email addresses, some functions in the Admin GUI and the API function CreateCertificate() will replace this characters with ‘_’ when creating distinguished names of newly created certificates.

However all of these characters are rejected when found in email addresses with the return code LCAPIERR_INVALID_ARGUMENT.

When passing a date value to the COM version of the API, this format must be used.

Required Rights and Permissions

For API functions

The following table lists the permissions and rights required for all functions. Target as in the last column can be a group or a security officer depending on the context. Some functions can only be called by a MSO. Permissions in brackets are only required in certain situations or certain parameter values.

Note

• a function also returns LCAPIERR_INSUFFICIENT_RIGHTS if additional authorization is configured for the corresponding action.

For GrantRightsOnGroupToSO()

The following table lists the permissions a SO must have in order to be granted or denied rights on a group. The SO who performs this operation needs the permissions “ Administer Groups” and “Change ACL” plus the rights that are being grant or denied.

For GrantRightsOnSOToSO()

The following table lists the permissions a SO must have in order to be granted or denied rights on another SO. The SO who performs this operation needs the permission “Change ACL” plus the rights that are being grant or denied.

Example Script

Example Script (VB Script)

'********************** SGLC TestScript ***********
'***                                            ***
'*** requires an existing DB with an MSO        ***
'*** "Master Security Officer"                  ***
'*** none of the objects created in the script  ***
'*** must exist (TestSO, user, groups)          ***
'***                                            ***
'**************************************************

dim SGLCAPIERR_OK : SGLCAPIERR_OK = 0
dim LCAPIERR_INSUFFICIENT_RIGHTS : LCAPIERR_INSUFFICIENT_RIGHTS = 32 dim LCAPIERR_INVALID_ARGUMENT : LCAPIERR_INVALID_ARGUMENT = 14

dim lcapi
dim res

'*** Create LCScript API Object ***
set lcapi = WScript.CreateObject("SGLCScriptApi.SGLCApi")


'*** Init DB Connection and logon SO *** res=lcapi.LogonToDatabase("SGLCSQLServer", "", "", 0, "")
if res <> SGLCAPIERR_OK then
  err.raise res, "LogonToDatabase", lcapi.GetErrorDesc(res), , 0
end if


res=lcapi.LogonSO("Master Security Officer")
if res <> SGLCAPIERR_OK then
  err.raise res, "LogonSO", lcapi.GetErrorDesc(res), , 0
end if

'************** write some groups and users

res=lcapi.CreateGroupEx("gruppe", "gruppe", "gruppe", "", "", 528, "")
if res <> SGLCAPIERR_OK then
  err.raise res, "CreateGroup", lcapi.GetErrorDesc(res), , 0
end if

res=lcapi.CreateGroupEx("gruppe1", "gruppe1", "gruppe1", "", "gruppe", 516, "")
'res=lcapi.CreateGroup("gruppe1", "gruppe", "") if res <> SGLCAPIERR_OK then
  err.raise res, "AddSubGroup", lcapi.GetErrorDesc(res), , 0
end if

res=lcapi.CreateGroup("gruppe2", "", "")
if res <> SGLCAPIERR_OK then
  err.raise res, "CreateGroup", lcapi.GetErrorDesc(res), , 0
end if

res=lcapi.CreateGroup("gruppe3", "gruppe2", "") if res <> SGLCAPIERR_OK then
  err.raise res, "CreateGroup", lcapi.GetErrorDesc(res), , 0
end if

res=lcapi.CreateUser("markus", "markus@utimaco.de", "markus", "Markus", "")
if res <> SGLCAPIERR_OK then
  err.raise res, "CreateUser", lcapi.GetErrorDesc(res), , 0
end if

res=lcapi.AdduserToGroup("markus", "gruppe", "comment", 0)
if res <> SGLCAPIERR_OK then
  err.raise res, "AddUserToGroup", lcapi.GetErrorDesc(res), , 0
end if

res=lcapi.CreateUser("gustav", "gustav@utimaco.de", "gustav", "gustav","")
if res <> SGLCAPIERR_OK then
  err.raise res, "CreateUser", lcapi.GetErrorDesc(res), , 0
end if

res=lcapi.AdduserToGroup("gustav", "gruppe1", "comment", 0)
if res <> SGLCAPIERR_OK then
  err.raise res, "AddUserToGroup", lcapi.GetErrorDesc(res), , 0
end if

res=lcapi.CreateUser("christian", "christian@utimaco.de", "christian", "halt der christian","")
if res <> SGLCAPIERR_OK then
  err.raise res, "CreateUser", lcapi.GetErrorDesc(res), , 0
end if

res=lcapi.AdduserToGroup("christian", "gruppe2", "comment", 0)
if res <> SGLCAPIERR_OK then
  err.raise res, "AddUserToGroup", lcapi.GetErrorDesc(res), , 0
end if

res=lcapi.CreateUser("norbert", "norbert@utimaco.de", "norbert", "halt norbert", "")
if res <> SGLCAPIERR_OK then
  err.raise res, "CreateUser", lcapi.GetErrorDesc(res), , 0
end if

res=lcapi.AdduserToGroup("norbert", "gruppe1", "comment", 0)
if res <> SGLCAPIERR_OK then
  err.raise res, "AddUserToGroup", lcapi.GetErrorDesc(res), , 0
end if

res=lcapi.CreateCertificatesForUsersOfGroup("gruppe", 1)
if res <> SGLCAPIERR_OK then
  err.raise res, "CreateCertificatesForUsersOfGroup", lcapi.GetErrorDesc(res), , 0
end if

res=lcapi.CreateCertificatesForUsersOfGroup("gruppe2", 1)
if res <> SGLCAPIERR_OK then
  err.raise res, "CreateCertificatesForUsersOfGroup", lcapi.GetErrorDesc(res), , 0
end if


'************** generate certificates

res=lcapi.CreateCertificatesForUsersOfGroup("gruppe", FALSE)
if res <> SGLCAPIERR_OK then
  err.raise res, "CreateCertificatesForUsersOfGroup 1", lcapi.GetErrorDesc(res), , 0
end if

res=lcapi.CreateCertificatesForUsersOfGroup("gruppe1", FALSE)
if res <> SGLCAPIERR_OK then
  err.raise res, "CreateCertificatesForUsersOfGroup 2", lcapi.GetErrorDesc(res), , 0
end if

res=lcapi.CreateCertificatesForUsersOfGroup("gruppe2", TRUE)
if res <> SGLCAPIERR_OK then
  err.raise res, "CreateCertificatesForUsersOfGroup 3", lcapi.GetErrorDesc(res), , 0
end if



'************** display certificates

dim certs
set certs = CreateObject("CAPICOM.Certificates")
certs.Clear

res=lcapi.EnumCertificatesOfUser("markus", certs)
if (res <> SGLCAPIERR_OK) AND (res <> LCAPIERR_INVALID_ARGUMENT)
then
  err.raise res, "EnumCertificatesOfUser", lcapi.GetErrorDesc(res), ,0
end if

dim thecert
WScript.Echo certs.Count & " certs found"
for i=1 to certs.Count
   set thecert = certs.Item(i)
   WScript.Echo thecert.SubjectName
next


'************** create SO and assign some rights

const ACL_GR_CREATEKEY = &H00000001&
const ACL_GR_COPYKEY = &H00000002&
const ACL_GR_DELETEKEY = &H00000004&
const ACL_GR_CREATERULES = &H00000008&
const ACL_GR_ASSIGNCERT = &H00000010&
const ACL_GR_ADDUSER = &H00000020&
const ACL_GR_DELETEUSER = &H00000040&
const ACL_GR_ADDGROUP = &H00000080&
const ACL_GR_DELSUBGROUP = &H00000100&
const ACL_GR_MOVEGROUP = &H00000200&
const ACL_GR_CHANGEGROUPPROP = &H00000400&
const ACL_GR_DELGROUP = &H00000800&
const ACL_GR_CREATEPROFILE = &H00001000&
const ACL_GR_CHANGEACL = &H00002000&
const ACL_GR_READ = &H00004000&
const ACL_GR_VISIBLE = &H00008000&
const ACL_SOR_CHANGENAME = &H01000000&
const ACL_SOR_CHANGECERT = &H02000000&
const ACL_SOR_CHANGEREG = &H04000000&
const ACL_SOR_ASSIGNCONF = &H08000000&
const ACL_SOR_DELSO = &H10000000&
const ACL_SOR_CHANGEPERM = &H20000000&
const ACL_SOR_CHANGEACL = &H40000000&
const ACL_SOR_READ = &H80000000&
const SO_R_LOGINDB = &H00000400&
const SO_R_CREATEKEY = &H00000004&


'defines to set all rights
const ACL_SOR_ALL = &HFF000000&
const ACL_GR_ALL = &H00FFFFFF&

res=lcapi.CreateCertificate("TestSO", thecert)
if (res <> SGLCAPIERR_OK) AND (res <> LCAPIERR_INVALID_ARGUMENT)
    then
    err.raise res, "CreateCertificate", lcapi.GetErrorDesc(res), , 0
end if

res=lcapi.AddSO("TestSO", thecert, thecert, "TestSO@utimaco.de", "", 0, SO_R_LOGINDB)
if (res <> SGLCAPIERR_OK) AND (res <> LCAPIERR_INVALID_ARGUMENT) then
  err.raise res, " AddSO ", lcapi.GetErrorDesc(res), , 0
end if    

'********** SO does not have SO_R_CREATEKEY permission, so it is not possible to grant ACL_GR_CREATEKEY.

res=lcapi.GrantRightsOnGroupToSO("gruppe", "TestSO", ACL_GR_VISIBLE OR ACL_GR_READ OR ACL_GR_CREATEKEY, 0)
if res <> LCAPIERR_INSUFFICIENT_RIGHTS then
  err.raise res, "GrantRightsOnGroupToSO", lcapi.GetErrorDesc(res), ,0
else
  WScript.Echo lcapi.GetErrorDesc(res)
end if


res=lcapi.SetSOPermissions("TestSO", SO_R_LOGINDB OR SO_R_CREATEKEY) if res <> SGLCAPIERR_OK then
  err.raise res, " SetSOPermissions ", lcapi.GetErrorDesc(res), , 0
end if


'*****retry

res=lcapi.GrantRightsOnGroupToSO("gruppe", "TestSO", ACL_GR_VISIBLE OR ACL_GR_READ OR ACL_GR_CREATEKEY, 0)
if res <> SGLCAPIERR_OK then
  err.raise res, "GrantRightsOnGroupToSO", lcapi.GetErrorDesc(res),  ,0
end if


'************** write some keys and rules
dim a
res=lcapi.WriteKey("gruppe", "gruppe", 15, 0, 0, "0x12345678", "comment", a)
if res <> SGLCAPIERR_OK then
  err.raise res, "WriteKey", lcapi.GetErrorDesc(res), , 0
end if

res=lcapi.WriteKey("gruppe1", "gruppe1", 15, 0, 0, "0xdeadbeef", "comment", a)
if res <> SGLCAPIERR_OK then
  err.raise res, "WriteKey", lcapi.GetErrorDesc(res), , 0
end if

res=lcapi.WriteKey("gruppe2", "gruppe2", 15, 2, 0, "0xabcdefabcdef", "comment", a)
if res <> SGLCAPIERR_OK then
  err.raise res, "WriteKey", lcapi.GetErrorDesc(res), , 0
end if

res=lcapi.WriteKey("gruppe3", "gruppe3", 15, 3, 0, "0x87654321", "comment", a)
if res <> SGLCAPIERR_OK then
  err.raise res, "WriteKey", lcapi.GetErrorDesc(res), , 0
end if

res=lcapi.WriteRule("gruppe1", "c:\lctest\*.*", "gruppe1", "")
if res <> SGLCAPIERR_OK then
  err.raise res, "WriteRule 1", lcapi.GetErrorDesc(res), , 0
end if

res=lcapi.WriteRule("gruppe", "c:\test\*.*", "<GROUPKEY>", "/S")
if res <> SGLCAPIERR_OK then
  err.raise res, "WriteRule 2", lcapi.GetErrorDesc(res), , 0
end if

res=lcapi.WriteRule("gruppe", "c:\user\*.*", "<USERKEY>", "/S")
if res <> SGLCAPIERR_OK then
  err.raise res, "WriteRule 2", lcapi.GetErrorDesc(res), , 0
end if

res=lcapi.WriteRule("gruppe2", "c:\error\*.*", "", "/X")
if res <> SGLCAPIERR_OK then
  err.raise res, "WriteRule 3", lcapi.GetErrorDesc(res), , 0
end if

res=lcapi.WriteRule("gruppe3", "c:\ignore\*.*", "", "/I")
if res <> SGLCAPIERR_OK then
  err.raise res, "WriteRule 4", lcapi.GetErrorDesc(res), , 0
  end if


'************** generate profiles
'res=lcapi.StartResolverForUser("markus", "c:\polfiles\")
'if res <> SGLCAPIERR_OK then
  ' err.raise res, "StartResolverForUser", lcapi.GetErrorDesc(res), , 0
'end if

res=lcapi.StartResolverForUsersOfGroup("gruppe","c:\polfiles\", 1) if res <> SGLCAPIERR_OK then
  err.raise res, "StartResolverForUsersOfGroup 1", lcapi.GetErrorDesc(res), , 0
end if

res=lcapi.StartResolverForUsersOfGroup("gruppe2","c:\polfiles", 1) if res <> SGLCAPIERR_OK then
  err.raise res, "StartResolverForUsersOfGroup 3", lcapi.GetErrorDesc(res), , 0
end if


'************** dump all keys

dim keynames()
dim keys:keys = 0
dim size: size = keys

res=lcapi.EnumKeys("<ALL>", size, keynames, 0)
if (res <> SGLCAPIERR_OK) AND (res <> LCAPIERR_INVALID_ARGUMENT) then
  err.raise res, "EnumKeys", lcapi.GetErrorDesc(res), , 0
end if

if (size>keys) then
  redim preserve keynames(size)
  res=lcapi.EnumKeys("<ALL>", size, keynames, 0)
end if

dim parentname
dim algo
dim inherit
dim specific
dim enabled
dim value
dim comment
dim longname
dim name

str = "Seite #1" & vbCr & vbCr
for i=1 to size
  res=lcapi.ReadKey(keynames(i-1), parentname, algo, inherit, specific, value, comment, longname, enabled)
  if (res <> SGLCAPIERR_OK) AND (res <> LCAPIERR_INVALID_ARGUMENT) then
    err.raise res, "ReadKey", lcapi.GetErrorDesc(res), , 0
  end if

  str=str& keynames(i-1)+"::"+value&vbCr&vbCr
  if ((i mod 8) = 7) then
      WScript.Echo str
      str = "Seite #" & Round((i / 8)+1) & vbCr & vbCr
  end if
next

WScript.Echo str & vbCr


'************

res=lcapi.LogoffSO()
if res <> SGLCAPIERR_OK then
  err.raise res, "LogoffSO", lcapi.GetErrorDesc(res), , 0
end if

res=lcapi.LogoffFromDatabase
if res <> SGLCAPIERR_OK then
  err.raise res, "LogoffFromDatabase", lcapi.GetErrorDesc(res), , 0
end if

WScript.Echo "Fertig"

set lcapi = nothing

Abbreviations

FQN -> Full qualified name

MSO -> Master Security Officer

SO -> Security Officer

Legal notices

Copyright © 2024 Utimaco IS GmbH, 2018 - 2024 conpal GmbH, 1996 - 2018 Sophos Limited and Sophos Group. All rights reserved. conpal®, AccessOn® and AuthomaticOn® are registered trademarks of conpal GmbH.

All other product and company names mentioned are trademarks or registered trademarks of their respective owners.

No part of this publication may be reproduced, stored in a retrieval system, or transmitted, in any form or by any means, electronic, mechanical, photocopying, recording or otherwise unless you are either a valid license where the documentation can be reproduced in accordance with the license terms or you otherwise have the prior permission in writing of the copyright owner.

You find copyright information on third party suppliers in the 3rd Party Software document in your product directory.

Last updated 27.03.2024