u.trust LAN Crypt Client API

• Overview
  • Functionality overview
  • General configuration of the API
  • Encryption tags
• 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
• Detailed Function Reference
  • General
  • Constants
  • Structures
  • Function reference
    • ActivateEncryption
    • ClearProfile
    • DecryptFile
    • DeleteFile
    • EncryptFile
    • GetEncryptionStatus
    • GetProfile
    • GetStatus
    • RefreshPolicy
    • SetTemporaryRule
  • Command line tool
    • Display client status
    • Display activate rules
    • Display file encryption status
    • Encrypt a single file
    • Refresh encryption policies
• Examples
  • Example Code (VB Script)
• Legal notices

Overview

The API described in this document is used to access u.trust LAN Crypt File Encryption Client functionality through an API. A new type of rules – so called encryption tags – can be used that allows external applications to control encryption. Encryption tags map a tag to a special key and allow triggering the encryption of files with certain keys via the API.

The API allows two ways to access encryption u.trust LAN Crypt File encryption functionality:

• A command line tool

• A COM interface

Following figure shows the main parts of the API:

The API can only be used with an installed CP File Filter. The API requires a profile to be loaded and the API has access to the keys in the loaded profile.

The API provides several functions that control the File Encryption. The command line tool can be used without any Authentication and provides a limited set of functions than the COM API.

Authentication is based on Microsoft Authenticode:

• The access to the COM API can be restricted to specific applications that are Authenticode signed.

• Furthermore, the access to the COM API can be restricted to Authenticode signed applications that are Authenticode signed with a specific certificate.

Functionality overview

Following table lists the available functionality for the command line tool as well as the COM API.

In addition to Windows, u.trust LAN Crypt also supports macOS as well as Android and iOS for mobile devices.

General configuration of the API

Following general configuration of the SGNFE API can be done via the CP LAN Crypt Administration:

• The SGFE API must be generally enabled.

• The use of the command line tool on the client can be enabled / disabled via a central setting.

• The priority of the different rule types can be defined (e.g. Encryption tags have precedence for all other rules)

• Allowed Applications can be defined that define the applications that are allowed to access the API.

• Trusted Vendors can be defined that restrict the access to the API to applications from specific vendors (via certificates).

For further details, please see the u.trust LAN Crypt Administrator Help.

Encryption tags

For the encryption function EncryptFile respectively the encrypt parameter of the command line Encryption tags can be used. These encryption tags are a new type of File Encryption rules that map a tag to a key. Encryption tags can be defined similar to encryption rules in the Admin and get transferred to the client via the profile.

Example:

Following encryption tag is defined in the administration and available on the client:

TAG: Confidential, Key: <KEY-X-GUIDY>

Following call of the command line:

SGFEAPI encrypt /Tag:CONFIDENTIAL c:\encrypt.doc

Will result in encrypting the file c:\encrypt.doc with the KEY-X-GUID.

API changes

Changes in 11.0.0

• No changes in the utilization of the COM API

Changes in 4.2.0

• No changes in the utilization of the COM API

Changes in 4.1.0

API version 4.1.0 is part of u.trust LAN Crypt Client 4.1.0.

New API functions:

• ClearProfile

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

Detailed Function Reference

General

The COM API is implemented in the class CSGFEClientApi. Classes are exported from SGFEClientAPI.DLL. The methods of the classes are described in the following chapters. The API is part of the u.trust LAN Crypt Client. The client API must be installed and enabled in the u.trust LAN Crypt Administration. All applications which are using the client API must be configured in the u.trust LAN Crypt Administration.

Note

• All functions return LCCAPIERR_OK if successful or an error code if an error occurred.

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

Error codes are defined as follows:

Constants

Encryption Algorithm Names:

• AES-256

• AES-128

• DES

• 3DES

• IDEA

• XOR

Structures

COM

The COM implementation uses Enumerators to iterate through the encryption rules of a profile.

The COM-Enumerator is implemented through the interface IProfile:

interface IProfile : IDispatch

{

[propget, id(DISPID_VALUE), helpstring("method Item")]
HRESULT Item([in] VARIANT index, [out, retval] IEncRule** pItem);

[propget, id(1), helpstring("property Count")]
HRESULT Count([out, retval] long *pVal);

[propget, restricted, id(DISPID_NEWENUM)]
HRESULT _NewEnum([out, retval] LPUNKNOWN *pVal);

};

The IProfile implementation returns COM-Objects which implements the following interface:

interface IEncRule : IDispatch

{

[propget, id(1), helpstring("property Path")]
HRESULT Path([out, retval] BSTR *pVal);

[propget, id(2), helpstring("property Exclude")]
HRESULT Exclude([out, retval] BOOL *pVal);

[propget, id(3), helpstring("property Ignore")]
HRESULT Ignore([out, retval] BOOL *pVal);

[propget, id(4), helpstring("property Subdir")]
HRESULT Subdir([out, retval] BOOL *pVal);

[propget, id(5), helpstring("property EncOnly")]
HRESULT EncOnly([out, retval] BOOL *pVal);

[propget, id(6), helpstring("property ShortKeyName")]
HRESULT ShortKeyName([out, retval] BSTR *pVal);


[propget, id(7), helpstring("property LongKeyName")]
HRESULT LongKeyName([out, retval] BSTR *pVal);

[propget, id(8), helpstring("property KeyGUID")]
HRESULT KeyGUID([out, retval] BSTR *pVal);

[propget, id(9), helpstring("property EncryptionTag")]
HRESULT EncryptionTag([out,retval] BOOL *pVal);};


};

Function reference

ActivateEncryption

This method tells the driver to activate or deactivate the file encryption.

COM

HRESULT ActivateEncryption(
    LONG bActivateEncryption
);

Parameters:

bActivateEncryption [in]

• TRUE -> activate encryption
• FALSE -> deactivate encryption

ClearProfile

Clears user profile. Call this function to delete currently loaded encryption rules.

COM

This method is not implemented for COM.

DecryptFile

This method decrypts a single file. Decryption is only allowed if no encryption rule is active for the file.

COM

HRESULT DecryptFile(
    BSTR strFileName
);

Parameters:

strFileName [in]

• Fully qualified name of the file that should be decrypted. The file name must not contain any wildcards. Folders are not supported.

DeleteFile

This method securely deletes a single file. The encryption key is required to delete an encrypted file.

COM

HRESULT DeleteFile(
    BSTR strFileName
);

Parameters:

strFileName [in]

• Fully qualified name of the file that should be deleted. The file name must not contain any wildcards. Folders are not supported.

EncryptFile

This method encrypts a single file. The file encryption may be rejected, if an encryption rule is active. It is possible to allow encryption of files if an encryption rule is active.

COM

HRESULT EncryptFile(
    BSTR     strFileName,
    BSTR     strTag,
    BSTR     strKey,
    VARIANT* strKeyName,
    VARIANT* strKeyGUID
);

Parameters:

strFileName [in]

• Fully qualified name of the file that should be encrypted. The file name must not contain any wildcards. Folders are not supported.

strTag [in]

• Encryption tag which should be used to encrypt the file. Set strTag to NULL or empty string if it should be ignored (see remark below).

strKey[in]

• Encryption key which should be used to encrypt the file. The encryption key can be specified with the key GUID or with the short name of the key. Set strKey to NULL or empty string if it should be ignored (see remark below).

strKeyName [out]

• Short key name if the file was encrypted successfully.

cchKeyName [in]

• Size of strKeyName in characters.

strKeyGUID [out]

• GUID of the key if the file was encrypted successfully.

cchKeyGUID [in]

• Size of strKeyGUID in characters.

Note

• The key which should be used to encrypt the file can either be specified using the parameter strTag or strKey, whereby strTag is used if both are present.

• If neither strTag nor strKey is specified, the file is encrypted according to the current encryption rule. If no encryption rule is active, LCCAPIERR_INVALID_ARGUMENT is returned in this case.

GetEncryptionStatus

This method queries the encryption status of a single file.

COM

HRESULT GetEncryptionStatus(
    BSTR     strFileName
    VARIANT* bEncrypted,
    VARIANT* strKeyName,
    VARIANT* strKeyGUID,
VARIANT* strKeyAlgorithm
    VARIANT* bCompliant
    VARIANT* strProfileKeyName,
    VARIANT* strProfileKeyGUID,
    VARIANT* strProfileKeyAlgorithm
);

Parameters:

strFileName [in]

• Fully qualified name of the file for which the encryption status should be queried. The file name must not contain any wildcards. Folders are not supported.

bEncrypted [out]

• TRUE the file is encrypted FALSE the file is not encrypted

strKeyName [out]

• The short name of the key which is used to encrypt the file. The key name is only available if the key is available to the user. If no policies are loaded or the key is not included in the policy, strKeyName stays empty.

cchKeyName [in]

• Size of strKeyName in characters.

strKeyGUID [out]

• The GUID of the key which is used to encrypt the file. If the file is OFB encrypted, and the key is not available, the short key name is stored in strKeyGUID.

cchKeyGUID [in]

• Size of strKeyGUID in characters.

strKeyAlgorithm [out]

• The name of the algorithm which was used to encrypt the file. If no policies are loaded or the key is not included in the policy, strKeyAlgorithm stays empty.

cchKeyAlgorithm [in]

• Size of strKeyAlgorithm in characters.

bCompliant [out]

• TRUE the status of the file is according to the loaded encryption rules (this may be encrypted or plain) FALSE the file is plain, but should be encrypted according to the loaded encryption rules, or the file is encrypted but no encryption rule is active.

strProfileKeyName [out]

• The short name of the key if an encryption rule is set for the specified file.

cchProfileKeyName [in]

• Size of strProfileKeyName in characters.

strProfileKeyGUID [out]

• The GUID of the key if an encryption rule is set for the specified file.

cchProfileKeyGUID [in]

• Size of strProfileKeyGUID in characters.

strProfileKeyAlgorithm [out]

• The algorithm name of the profile key.

cchProfileKeyAlgorithm [in]

• Size of strProfileKeyAlgorithm in characters.

GetProfile

Get the actual loaded u.trust LAN Crypt Profile. The profile consists of one or more encryption rules.

COM

IProfile Profile()

Note

• You can access the encryption rules in Visual Basic through the For Each-Statement or directly with the methods Item() and Count().

Parameters:

pEncRules [out]

• pointer to an array of ENCRULE elements

ulEncRules [in/out]

• total number of encryption rules in the profile

Note

• To get the number of encryption rules in the profile set pEncRules to NULL.

GetStatus

This method queries the current status of the encryption client.

COM

HRESULT GetStatus(
  VARIANT* bDriverInstalled,
  VARIANT* bDriverRunning,
  VARIANT* bProfileLoaded,
  VARIANT* bEncryptionActive
  );

Parameters:

bDriverInstalled [out]

• TRUE encryption driver is installed

• FALSE encryption driver is not installed

bDriverRunning [out]

• TRUE encryption driver is active and running

• FALSE encryption driver is not running

bProfileLoaded [out]

• TRUE encryption rules are loaded

• FALSE no encryption rules are loaded

bEncryptionActive [out]

• TRUE transparent encryption is active

• FALSE transparent encryption is deactivated or no policy is loaded

RefreshPolicy

Refresh the currently loaded policy. This method must be called from a user session and has no effect if it is called from a service. The policy will be loaded, even if it was unloaded before. Policy update fails if policy loader is not running.

The function returns immediately. No information is returned if a new policy was loaded successfully or not.

COM

HRESULT RefreshPolicy();

SetTemporaryRule

This method sets a temporary encryption rule for a single file. Temporary encryption rules are automatically removed after the first file access or a timeout of 15 seconds.

If persistent encryption is enabled there is still an encryption rule for 15 seconds if the encrypted file was deleted after the temporary rule was removed.

COM

HRESULT SetTemporaryRule(
  BSTR strFileName,
  BSTR strTag,
  LONG lOptions
  );

Parameters:

strFileName [in]

• Name of the file for which the temporary encryption rule should be created. Relative paths are supported. The file name must not contain any wildcards. Folders are not supported.

strTag [in]

• Encryption tag which should be used.

lOptions [in]

• Additional options (currently not used, must be 0).

Command line tool

In addition to the COM API, a command line tool exists which provides selected functions.

The command line tool is installed together with the Client API and is located in the shared Utimaco 32-bit installation folder.

All output from the command line tool has the format:

name <tabulator>value [<tabulator> additional value [<tabulator> additional value]]

<tabulator> is displayed as ” →” in the example outputs below.

The error code is set to 0 in case of success or to one of the values mentioned in chapter 3.1.

Note

• When the command line tool is called without parameters, a short help is displayed.

Display client status

SGFEAPI status

Shows the current status of the file encryption client.

Example:

c:\>SGFEAPI status
Encryption driver installed → yes
Encryption driver running → yes
Policy loaded → yes
Transparent encryption active → yes

Output:

Encryption driver installed

• “yes” encryption driver is installed

• “no” encryption driver is not installed

Encryption driver running

• “yes” encryption driver is active and running

• “no” encryption driver is not running

Policy loaded

• “yes” encryption rules are loaded

• “no” no encryption rules are loaded

Transparent encryption acrtive

• “yes” transparent encryption is active

• “no” transparent encryption is deactivated or no policy is loaded

Display activate rules

SGFEAPI rules

Displays all rules which are currently loaded. All kind of rules are included (encryption rules, ignore rules, exclude rules, encryption tags and temporary rules).

The order of the rules is the same order how the rules are evaluated in the driver.

Example:

c:\>SGFEAPI rules
Path or Tag → Subfolder → Exclude → Ignore → Tag → Short key name → Long key
name → Key GUID
C:\WINDOWS\*.* → yes → no → yes → no
C:\PROGRAM FILES\UTIMACO\U.TRUST LAN CRYPT\APPS\*.* → no → no → yes → no
\\SERVER2016\SHARE\CONFIDENTIAL\*.* → yes → no → no → no → $UK$BOARA046F0
BE → $UK$ Board User 1 → {2B5A6F59-DCDB-48C1-918D-79C78EB36779}
\\SERVER\HOME\*.* → yes → no → no → no → $UK$BOARA046F0BE → $UK$ Board
User 1 → {2B5A6F59-DCDB-48C1-918D-79C78EB36779}

Output:

In the first line a heading is printed, then for each rule a new line is displayed with tabulator separated values:

Path or Tag

• The path for which the rule is active or the name of the encryption tag

Subfolder

• “yes” the rule is active for the path and all subfolders

• “no” the rule is only active for the path

Exclude

• “yes” the specified path is excluded from the encryption

• “no” the specified path is not excluded from encryption (e.g. encryption rule)

Ignore

• “yes” the specified path is ignored from the encryption

• “no” the specified path is not ignored from the encryption (e.g. encryption rule)

Tag

• “yes” the rule is an encryption tag and “Path or Tag” is the name of the tag

• “no” this is an encryption, ignore or exclude rule

Short key name

• Short name of the key which is used to encrypt the files. Only valid for encryption rules and encryption tags.

Long key name

• Long name of the key which is used to encrypt the files. Only valid for encryption rules and encryption tags.

Key GUID

• GUID of the key which is used to encrypt the files. Only valid for encryption rules and encryption tags.

Display file encryption status

SGFEAPI encstatus [filename]

Displays the encryption status of a single file. The filename must be fully qualified without any wildcards.

Only single files can be queried, folders or multiple files are not supported.

Example:

c:\>SGFEAPI encstatus c:\encrypt\test.txt
Encrypted → yes Encrypted with key → $GK$TESTDOMAIN → {9F267228-82DA-4B57-AE1B-096AB62BAA5 C} → AES-256
Profile compliant → yes
Profile key → $GK$TESTDOMAIN → {9F267228-82DA-4B57-AE1B-096AB62BAA5C} → AES-256

c:\>SGFEAPI encstatus c:\encrypt\plain.txt
Encrypted → no
Encrypted with key → →
Profile compliant → no
Profile key → $GK$TESTDOMAIN {9F267228-82DA-4B57-AE1B-096AB62BAA5C}

Output:

Encrypted

“yes” the file is encrypted

“no” the file is not encrypted

Encrypted with key

• Short key name, key GUID and key algorithm separated with tabulator if the file is encrypted. Empty if the file is not encrypted.The short name of the key and encryption algorithm are only displayed if the key is available in the user’s key ring.

Profile compliant

• “yes” if the file is encrypted according to an encryption rule or if the file is not encrypted and there is no encryption rule set.

• “no” if the file should be encrypted because of an encryption rule but it is not encrypted or encrypted with another key or if the file is encrypted, but no encryption rule is active.

Profile key

• Short key name, key GUID and key algorithm if an encryption rule is set for the specified file. Empty if no encryption rule is set.

Encrypt a single file

SGFEAPI encrypt /Tag:[tagname] [filename]

SGFEAPI encrypt /T:[tagname] [filename]

SGFEAPI encrypt /Key:[key GUID] [filename]

SGFEAPI encrypt /K:[key GUID] [filename]

SGFEAPI encrypt /Key:[key short name] [filename]

SGFEAPI encrypt /K:[key short name] [filename]

SGFEAPI encrypt [filename]

Encrypts a single file with the key administered for the specified encryption tag or with a given key. If both encryption tag and encryption key are specified, the encryption tag is used for encryption. Encryption is only allowed if no encryption rule is active for the file.

If only the filename is specified without an encryption tag or key, the file is encrypted according to the active encryption rule.

The filename must be fully qualified without any wildcards. Only single files can be encrypted, folders or multiple files are not supported.

Example:

c:\>SGFEAPI encrypt /T:CONFIDENTIAL c:\test\file.txt
Encrypted with key → KEY3 → {8E716D53-EF3A-475D-8344-7227C380EE48}

c:\>SGFEAPI encrypt c:\test\file.txt /K:KEY3
Encrypted with key → KEY3 → {8E716D53-EF3A-475D-8344-7227C380EE48}

c:\>SGFEAPI encrypt c:\test\file.txt
Encrypted with key → $GK$TESTDOMAIN → {9F267228-82DA-4B57-AE1B-096AB62BAA5C}

Output:

Encrypted with key

• Short name and GUID of the key which was used to encrypt the file. This is the key which is configured for the specified encryption tag.

Refresh encryption policies

SGFEAPI refresh

Example:

c:\>SGFEAPI refresh
Triggered policy refresh

Starts an update of the loaded policies or loads tries to load the policy if it was not loaded before. No error is returned if the policy cannot be loaded.

Examples

Example Code (VB Script)

********************** SGFEClientAPI TestScript ***********

Dim api
Dim profile
Dim encRule

'*** Create SGFEClientAPI Object ***
set api = WScript.CreateObject("SGFECLIENTAPI.SGFEClientApi")

'*** Get loaded profile ***
set profile = api.profile

'*** Show all encryption rules in profile ***
for each encRule in profile
    WScript.Echo "Path: " & encRule.Path & vbCrLf & _
        "Ignore: " & encRule.Ignore & vbCrLf & _
        "Exclude: " & encRule.Exclude & vbCrLf & _
        "EncOnly: " & encRule.EncOnly & vbCrLf & _
        "Subdir: " & encRule.Subdir & vbCrLf & _
        "EncTag: " & encRule.EncryptionTag & vbCrLf & _
        "ShortKeyName: " & encRule.ShortKeyName & vbCrLf & _
        "LongKeyName: " & encRule.LongKeyName & vbCrLf & _
        "KeyGUID: " & encRule.KeyGUID
next

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