u.trust LAN Crypt Admin API

Overview
API Changes
Function Reference
Constant Values
Required Rights and Permissions
Example Script
- Example Script (VB Script)
Abbreviations
Reporting Security Vulnerabilities
Legal notices

Overview

The functions described in this document are used to create u.trust LAN Crypt Configuration Data through the COM API. The COM 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 COM API is only available for 32 bit applications.

On 64 bit operating systems, an application using the COM API must be a 32 bit application. If the COM 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.

Note

The COM API has been deprecated. The currently supported API is the .NET API.

API Changes

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:

Code	Description	Name
0	The Function succeeded normally.	LCAPIERR_OK
1	General Failure. This indicates an error in the provided data as well as an internal error. An illegal registry entry (namely search orders for user, key or group) can also result in this error.	LCAPIERR_GENERAL_ERROR
2	A required or specified object was not found.	LCAPIERR_OBJECT_NOT_FOUND
3	General Failure. This indicates an error in the provided data as well as an internal error.	LCAPIERR_DB_ERROR
4	The Scripting API was not initialized using Initialise(…) or the initialization failed.	LCAPIERR_NOT_INITIALIZED
5	The SQL Dialect parameter passed to Initialise(…) is unknown.	LCAPIERR_INVALID_SQL_DIALECT
6	Log on to the u.trust LAN Crypt Database failed. This can happen because of wrong Database credentials, because of a missing/wrong Security Officer Certificate or because of wrong or missing ODBC Client settings.	LCAPIERR_DB_LOGON_FAILED
7	The System failed to create the DB Tables. (only returned by CreateDBTables)	LCAPIERR_CREATE_TABLES_FAILED
8	The System failed to drop the DB Tables (only returned by DropDBTables)	LCAPIERR_DROP_TABLES_FAILED
9	A function that requires a logged on security officer was called before a successful call to LogonSO	LCAPIERR_NO_SO
10	The user was not found in the database	LCAPIERR_USER_NOT_FOUND
11	There is more than one user in the database, which matches the provided search criteria. So, the system could not decide which one to use for the desired operation.	LCAPIERR_USER_NOT_DISTINCT
12	The group was not found in the database	LCAPIERR_GROUP_NOT_FOUND
13	There is more than one group in the database, which matches the provided search criteria. So, the system could not decide which one to use for the desired operation.	LCAPIERR_GROUP_NOT_DISTINCT
14	The Argument passed is of an invalid type. This happens in conjunction with [in/out] parameters passed to e.g. EnumFQNOfGroupName.	LCAPIERR_INVALID_ARGUMENT
15	Failed to add a SO to the Database. An extended Error code might be available (GetIntErrorCode)	LCAPIERR_INSERT_SO_FAILED
16	The desired key could not be found in the Database.	LCAPIERR_KEY_NOT_FOUND
17	There is more than one key in the database, which matches the provided search criteria. So, the system could not decide which one to use for the desired operation.	LCAPIERR_KEY_NOT_DISTINCT
18	The strFlags Parameter passed to WriteRule is invalid. Valid parameters are /S, /I, /X, /T or a combination, where /X and /I cannot be combined and /T cannot be combined with any other flag.	LCAPIERR_INVALID_FLAGS
19	Failed to add a group to the database.	LCAPIERR_CREATE_GROUP_FAILED
20	Failed to add a group to another group.	LACPIERR_INSERT_GROUP_FAILED
21	Failed to add a user to the database.	LCAPIERR_CREATE_USER_FAILED
22	Failed to delete a group from the database.	LCAPIERR_REMOVE_GROUP_FAILED
23	Failed to delete a user from the database.	LCAPIERR_REMOVE_USER_FAILED
24	Failed to insert a user into a group or the database.	LCAPIERR_INSERT_USER_FAILED
25	A SO with this name already exists.	LCAPIERR_SO_NOT_DISTINCT
26	No SO with this name exists.	LCAPIERR_SO_NOT_FOUND
27	Could not grant rights on a group to a SO.	LCAPIERR_GRANT_RIGHTS_GROUP _FAILED
28	A database inconsistency (MAC error) was found.	LCAPIERR_INVALID_MAC
29	Could not grant rights on another SO to a SO.	LCAPIERR_GRANT_RIGHTS_SO_FAILED
30	There is already a key with this name in the	LCAPIERR_KEY_ALREADY_EXISTS
31	The function itself succeeded, but the subsequent logging failed.	LCAPIERR_LOGGING_ERROR
32	The current SO does not have all rights required for this operation.	LCAPIERR_INSUFFICIENT_RIGHTS
33	An error related to file system access occurred.	LCAPIERR_FILE_IO
34	Failed to find a certificate or failed to assign a certificate.	LCAPIERR_CERTIFICATE
35	A cryptographic operation failed.	LCAPIERR_CRYPT
36	The specified key is disabled and cannot be used to create or change a rule.	LCAPIERR_KEY_DISABLED
37	The desired rule could not be found in the Database.	LCAPIERR_RULE_NOT_FOUND
38	Failed to delete a profile.	LCAPIERR_DELETE_PROFILE_FAILED
39	No database owner specified for LogonToDatabase and not default owner configured.	LCAPIERR_INVALID_DB_OWNER
40	An error occurred during the SO authentication. This may happen because the private key of the certificate is not available or the certificate cannot be used (e.g. expired,revoked,..).	LCAPIERR_SO_AUTHENTICATION_FAILED
41	Logon of SO failed for some unknown reason. This error can occur if the database key is missing for the SO. A database key should be available if the SO has the global permission Create Profiles.	LCAPIERR_SO_LOGON_FAILED
42	Unknown Error	LCAPIERR_END

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 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 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 ();

u.trust LAN Crypt Admin API

Overview

API Changes

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