GatewayforBlackberry 7 2 AdministratorsGuide

Liquid Machines
Gateway for BlackBerry

Administrator’s Guide
Version 7.2
Liquid Machines, Inc.

100 Fifth Avenue, 5th Floor
Waltham, MA 02451
1.877.88LIQUID (1.877.885.4784)
www.liquidmachines.com
Copyright/Disclaimer
Copyright © 2003 - 2010 Liquid Machines, Inc. All rights reserved. Confidential and proprietary
information of Liquid Machines, Inc.
The material in this document may not in whole or in part be copied, photocopied, reproduced,
translated, or converted to any electronic or machine-readable form without the prior written
consent of Liquid Machines. The information in this document is for informational use only, is
subject to change without notice, and should not be construed as a commitment by Liquid
Machines. Liquid Machines assumes no responsibility or liability for any errors or inaccuracies that
may appear in this document.
This document and the software described in this document are furnished under a license
accompanying the software and may be used only in accordance with the terms of such license.
By using this document, you agree to the terms and conditions of that license.
>> For other copyright and trademark information, see the Liquid Machines Copyright, included in
this document package.
How to Contact Liquid Machines, Inc.

Liquid Machines, Inc.
100 Fifth Avenue, 5th Floor
Waltham, MA 02451
Phone: 1.877.88LIQUID (1.877.885.4784)
www.liquidmachines.com
Liquid Machines, Inc. Page ii

Table of Contents
Copyright/Disclaimer ....................................................................................................................... ii
Preface ..................................................................................................................................vii
Book Conventions ......................................................................................................................vii
Intended Audience .....................................................................................................................vii
Related Documents ................................................................................................................... viii
Using this Manual ...................................................................................................................... viii
Chapter 1: Introducing the Liquid Machines Gateway for BlackBerry ........................................A-1
About Liquid Machines .............................................................................................................A-2
About the Liquid Machines Gateway for BlackBerry .................................................................A-2
Deployment Options .............................................................................................................A-2
Theory of Operation ..............................................................................................................A-3
Client Capabilities .....................................................................................................................A-3
Client-level Encryption ..........................................................................................................A-3
Protected Email Messages ...................................................................................................A-3
Copy and Paste ....................................................................................................................A-3
Attachment Security Options .................................................................................................A-4
Secure Attachment Rendering ..............................................................................................A-4
Secure Attachment Viewing ..................................................................................................A-4
Saving Protected Attachments ..............................................................................................A-4
Forwarding Protected Messages via Email, PIN and SMS ....................................................A-4
Expiration ..............................................................................................................................A-5
International Character Set Support ......................................................................................A-5
About Security Services ...........................................................................................................A-6
Protection Systems ...............................................................................................................A-6
Microsoft Windows Rights Management Services (RMS) ......................................................A-8
Liquid Machines Document Control.....................................................................................A-10
More About Unprotecting at the Gateway ...............................................................................A-11
Microsoft Windows Rights Management Services (RMS) ....................................................A-11
Liquid Machines Document Control.....................................................................................A-12
Installation Architecture ..........................................................................................................A-14
Rights Management Services (RMS) ..................................................................................A-14
BlackBerry Enterprise Server for Exchange ........................................................................A-14
Liquid Machines, Inc. Page iii

Gateway for BlackBerry: Processing Messages as They Pass Through the BlackBerry
Enterprise Server ........................................................................................................... A-14
Liquid Machines Client for BlackBerry: User Interface, Smartphone Maintenance .............. A-15
Message Handling ................................................................................................................. A-16
Priority of Protection Requests ........................................................................................... A-16
Attachment Handling .......................................................................................................... A-16
Message Controls Prevent Sending.................................................................................... A-16
Chapter 2: Installing the Gateway Server .................................................................................. A-1
System Requirements .............................................................................................................. A-2
Hardware (Minimum Requirements) ..................................................................................... A-2
Software ............................................................................................................................... A-2
Important Information About Upgrading From Previous Versions ............................................. A-2
Preinstallation Requirements ................................................................................................... A-3
Installing the Liquid Machines Gateway for BlackBerry ............................................................ A-4
Upgrading from a Previous Version of the Liquid Machines Gateway for BlackBerry ............... A-6
Uninstalling the Liquid Machines Gateway for BlackBerry ........................................................ A-7
Chapter 3: Administering the Gateway Server .......................................................................... A-1
System Tasks .......................................................................................................................... A-2
Enabling Protection Systems ................................................................................................ A-2
Configuring Protected Attachment Rendering Options .......................................................... A-2
Configuring Systematic Throttling ......................................................................................... A-3
Configuring RMS Templates ................................................................................................. A-4
Configuring the ODBC Connection String for the Gateway Database ................................... A-4
Enabling the Gateway........................................................................................................... A-5
Disabling the Gateway .......................................................................................................... A-5
Upgrading or Reinstalling BlackBerry Enterprise Server ....................................................... A-5
Monitoring the Gateway ........................................................................................................... A-6
Application Event Logs ......................................................................................................... A-6
Recipient Activity for Protected Messages ............................................................................ A-6
Diagnostic Logging ............................................................................................................... A-6
Tracking the Number of Active Users ....................................................................................... A-6
Creating an Active Users Report .......................................................................................... A-7
Chapter 4: Installing the Client .................................................................................................. A-1
System Requirements .............................................................................................................. A-2
Hardware .............................................................................................................................. A-2
Software ............................................................................................................................... A-2
Liquid Machines, Inc. Page iv

Preinstallation Requirements ....................................................................................................A-2
Installing and Uninstalling the Client .........................................................................................A-3
Installing the Client................................................................................................................A-3
Installing or Uninstalling Using the Application Loader Tool ..................................................A-3
Chapter 5: Administering the Client ...........................................................................................A-1
Configuring the Apply Policies Menu on BlackBerry Smartphones ...........................................A-2
Delivering Policies to the Smartphone ......................................................................................A-2
Plain Text Email ....................................................................................................................A-2
IT Policy Push .......................................................................................................................A-5
Built-In Do Not Forward Policy ..............................................................................................A-6
Setting Client Application Permissions......................................................................................A-8
Configuration on the Handheld..............................................................................................A-8
Central Configuration through the Application Control Policy ................................................A-8
Accessing Client Diagnostic Functions .....................................................................................A-9
Change the Scrubbing Frequency .........................................................................................A-9
Enabling Diagnostic Logging ...............................................................................................A-10
Appendix A: Gateway Configuration File Syntax ..........................................................................A-1
Overview ..................................................................................................................................A-2
Specifying Units of Time .......................................................................................................A-3
Sections ...................................................................................................................................A-3
Settings ....................................................................................................................................A-4
logging settings .....................................................................................................................A-4
gateway-service-settings.......................................................................................................A-4
services settings ...................................................................................................................A-5
protection-config settings ......................................................................................................A-5
reporting settings ..................................................................................................................A-6
monitoring settings ................................................................................................................A-8
adapter settings ....................................................................................................................A-9
Variables ................................................................................................................................A-12
Appendix B: Application Event Log Entries ..................................................................................B-1
Critical Errors............................................................................................................................B-2
Warnings ..................................................................................................................................B-3
Informational Messages ...........................................................................................................B-5
Appendix C: Adding RMS Servers to the Local Intranet Sites ..................................................... C-1
Index ......................................................................................................................... Index-1
Liquid Machines, Inc. Page v

Liquid Machines, Inc. Page vi
Preface
Welcome to the Liquid Machines Gateway for BlackBerry Administrator’s Guide. The Liquid
Machines Gateway for BlackBerry extends access to content protected with Microsoft Rights
Management Services (RMS) beyond the desktop. BlackBerry smartphone users can now send
and receive protected messages and attachments using the same policies available in Microsoft
Outlook.
This document introduces the Liquid Machines Gateway for BlackBerry and describes how to
install and administer the Gateway Server and the Client. The Gateway for Blackberry Server and
Client components operate together to provide the capabilities described in this document. The
document also provides the Gateway Configuration File Syntax.
Book Conventions
CAUTION: Cautions the user of actions that may result in operational issues or data
loss.
NOTE: Identifies important points, helpful hints, special circumstances, or
alternative methods.
This guide also uses the following typographical conventions:

>> Blue indicates a cross-reference. A cross reference provides the location of additional
information related to the topic. For example:
>> For more information, see Intended Audience on page vii.

Bold Indicates a selection from a menu or a button name. For example:
From the Settings menu, select Document Settings Library.
Bold is also used for file names, field names and values, and emphasis.
Intended Audience
This guide is intended for administrators who are responsible for installing and administering the
Liquid Machines Gateway for BlackBerry and the Client for BlackBerry.
Liquid Machines, Inc. Page vii

Related Documents
This section lists documents related to the Gateway for BlackBerry:
 Liquid Machines Client for BlackBerry User’s Guide
Using this Manual

This user guide contains the following chapters and appendices:
 Chapter 1: Introducing the Liquid Machines Gateway for BlackBerry – Describes the
features of the Gateway for BlackBerry.
 Chapter 2: Installing the Gateway Server – Provides the system requirements for
installing the Gateway Server and also provides information on installing, upgrading, and
uninstalling the Gateway Server.
 Chapter 3: Administering the Gateway Server – Describes how to perform important
system and monitoring tasks. It also describes the message handling workflow.
 Chapter 4: Installing the Client – Provides the system requirements for installing the
Client for BlackBerry and also provides information on installing and uninstalling the Client.
 Chapter 5: Administering the Client – Describes how to make RMS templates available
to the Gateway before you can use them, how to deliver policies to the Smartphone, and
how to use the client diagnostics functions that are provided.
 Appendix A: Gateway Configuration File Syntax – Describes the syntax of the Gateway
Configuration file (an XML file) that controls the behavior of the Gateway for BlackBerry.
 Appendix B: Application Event Log Entries – Provides a listing of the application event
log entries that you may see while using the Gateway for BlackBerry.
 Appendix C: Adding RMS Servers to the Local Intranet Sites – Describes how to add
RMS Servers to the local intranet sites.
 Index – Provides an index to aid you in locating information.
Liquid Machines, Inc. Page viii

Chapter 1: Introducing the Liquid
Machines Gateway for
BlackBerry
This chapter introduces the Liquid Machines Gateway for BlackBerry.

Topics included in this chapter are:
 About Liquid Machines
 About Liquid Machines Gateway for BlackBerry
 Enhanced Security Options
 About Security Services
 More About Unprotecting
 Installation Architecture
Liquid Machines, Inc. Page A-1

About Liquid Machines
Liquid Machines provides a powerful suite of products that enables users to work normally, while
providing strong data protection and enterprise-class administration features. Liquid Machines
provides a variety of gateway products that extend Liquid Machines Document Control and/or
Microsoft RMS protection to additional products and components within the IT infrastructure.
About the Liquid Machines Gateway for BlackBerry

The Liquid Machines Gateway for BlackBerry extends the ability to create and work with rights-
managed messages and documents to BlackBerry smartphones.
The Gateway for BlackBerry consists of a server-based gateway and a BlackBerry client agent,
which allows authorized BlackBerry users to work with protected messages and attachments and
optionally create new protected messages. This section describes several options and features.
Deployment Options
The Liquid Machines Gateway for BlackBerry can be used in a variety of configurations. Based on
your environment and security preferences, you can take advantage of different features.
When deployed together with Microsoft Rights Management Services (RMS), the Liquid Machines
Gateway for BlackBerry can allow users to work with both protected email messages and
documents. When deployed with Liquid Machines Document Control, using the Liquid Machines
Security Service, the gateway processes protected attachments only.
Additional deployment options may be made, depending on your organization’s preferences
around security, performance, viewing options and client software management:

Theory of Operation
The Liquid Machines Gateway for BlackBerry extends enterprise rights management to the
BlackBerry smartphone. The Liquid Machines gateway intercepts protected messages and
attachments from the BlackBerry Enterprise Server, removes the encryption on the content and
then re-encrypts the message and attachment(s) in a way that can be decrypted securely on the
device. Additionally, RIM’s software encrypts the message during transport and RIM further
provides the ability to password protect the device itself.
Once the protected message is delivered to the smartphone, the Liquid Machines client can
decrypt and display the protected message and attachment. If a BlackBerry user replies to or
forwards a protected message, it will maintain the original policy. When the message returns to the
gateway, the gateway scans the message for special markers indicating that it should be protected
with a specific rights-management policy and reapplies that policy before forwarding to recipients.
The Liquid Machines Client for BlackBerry allows senders to apply a rights management policy to
new or previously unprotected messages in an intuitive and friendly way.
Client Capabilities
Client-level Encryption
Messages, and optionally attachments, that are decrypted at the gateway are re-encrypted prior to
delivery to the smartphone. Encryption of content on the smartphone blocks the leakage of
sensitive data via saving to USB or other memory device, or sending via PIN or SMS.
 The Gateway for BlackBerry packages the rights and content of a protected message
together in a custom format and stores them that way on the smartphone. The smartphone
must have the Liquid Machines Client for BlackBerry installed for the recipient to be able to
read the message and attachment(s). The package is encrypted using AES-128 (symmetric
key encryption), which means that the client can open the package and verify the rights of
the user without communicating with a key distribution service. Although the message is
encrypted, users can read it offline, even if they have not read it before. Attachments are
also encrypted, but the user must have requested that the attachment be downloaded and
decrypted to be subsequently available offline.
Note that the Liquid Machines Client for BlackBerry interprets the rights to a message upon
delivery, so they will not be updated dynamically on the device if the policy is changed.
Protected Email Messages

The Liquid Machines Client for BlackBerry provides RMS users the ability to protect new or
previously unprotected messages. From the smartphone, BlackBerry users can select RMS policy
templates to be applied to messages and attachments by the Gateway.
Copy and Paste

The Liquid Machines Client for BlackBerry further controls protected messages and attachments by
blocking the ability to cut or copy. The client prevents the user from selecting protected content to
copy it.

Attachment Security Options
Attachments, like messages, are decrypted at the gateway for appropriately permissioned
recipients. There are several configuration options for the management of attachments to consider.
Secure Delivery of P rotected Attachm ents

Typically, the gateway is configured so that protected attachments are unprotected and then re-
encrypted and delivered in an encrypted format that can be managed by the Liquid Machines client
on the BlackBerry device. This ensures that attachments can be accessed on the handheld
without risk of data leakage. This option utilizes the Liquid Machines attachment viewing capability.
Unencrypted Delivery of P rotected Attachm ents

The gateway can be configured to unprotect attachments and deliver them to the device
unencrypted. This option may be appropriate for organizations that are not concerned with security
on the attachments and want to optimize the user experience (for example, organizations that have
a requirement to use Documents to Go software to modify the document on the device). This
configuration utilizes the native BlackBerry attachment viewer or Documents to Go.
Secure Attachment Rendering

Secure attachments are rendered on the server into MHTML, compressed, encrypted, and Base64
encoded. Many rendering configuration options are available to the administrator to optimize the
end user experience.
This experience is composed of download latency and document richness. Tuning factors include
typical document types/sizes/complexity, average network coverage/bandwidth, device display
sizes, user tolerance for download latency, etc. The administrator can configure a variety of global
and document-type-specific options to provide the best end user experience.
Secure Attachment Viewing

Secure attachments are downloaded entirely to the client, where they are unpacked at view time
and securely displayed in the Liquid Machines Client for BlackBerry secure attachment viewer.
This viewer is browser-based and prevents copy and paste actions. The attachment file is stored in
its secure, encoded state on the device, effectively preventing data leaks.
Saving Protected Attachments

Secure attachments are decrypted and displayed only as an attachment. If the protected
attachment is stored to memory, it cannot be opened via another program.
Forwarding Protected Messages via Email, PIN and SMS

Users are able to forward protected messages as email, PIN, or SMS. Forwarded messages can
only be decrypted if sent via email. Encrypted messages sent as PIN or SMS bypass the Liquid
Machines Gateway and cannot be read by the recipient.

Expiration
Protected messages whose expiration dates have passed do not appear. If client-level encryption
is enabled, a message warns the user that the message has expired, and the message text is not
decrypted. If client-level encryption is not enabled but the client is installed, expired messages are
periodically erased from the smartphone.
NOTE: It is possible to deploy the Liquid Machines Gateway for BlackBerry in such
a way that both messages and attachments are delivered and stored
completely decrypted on the device. In this case, messages and
attachments protected in Outlook can be read on the BlackBerry device
without the Liquid Machines client, but there is no security enforcement on
the device and none of the client security features described are available.
International Character Set Support

The Liquid Machines Gateway for BlackBerry and Client for BlackBerry are locale independent;
that is, they support non-ASCII text characters for text bodies and file attachments. They support
the same code pages the BlackBerry operating system supports.

About Security Services
The access control of Liquid Machines products comes from enterprise rights management, an
important concept in information control. It means that access controls, along with rules about how
data can be used, travel with copies of that data. Taking a copy out of a server and placing it onto
a workstation or sending it out of a company's infrastructure and into the Internet does not remove
the controls from the data. You can think of rights-managed mail as traveling in a locked container.
Authorized recipients can look inside and see the data, but they cannot take it out. They can only
copy the whole container.
Control is accomplished through encryption. Messages and documents are protected by encrypting
them, and access to them is controlled by permitting or denying access to the key that was used to
encrypt them.
Security Services define the way in which content is protected and determine who gets the rights to
open each message. Rights Management (RM) client applications, such as Outlook 2007 and
2003 or the Liquid Machines Gateway for BlackBerry, allow recipients to view and manipulate the
data and to send copies elsewhere if the controls allow.
Protection Systems
When enabled, the Gateway for BlackBerry decrypts content that was protected using any or all of
the following systems:
 Microsoft Rights Management Services (RMS)
 RMS policies may be applied to both messages and attachments, either on the desktop
or by the Liquid Machines Client for BlackBerry
 RMS policy encryption and decryption is based on RMS Super User capability, granted
by a Windows RMS server V1 SP2 or AD RMS in Windows Server 2008.
 Liquid Machines Document Control can protect attachments using RMS security
services. (See Liquid Machines Document Control documentation for more details.)
 Liquid Machines Document Control Security Service
 Liquid Machines Document Control Security Service-based policies apply only to
message attachments and are typically applied at the desktop.
 Encryption and decryption is based on Liquid Machines policy permissions, granted on
a Liquid Machines Document Control server, version 6 or 7.

The Gateway does not decrypt content protected using other kinds of rights management or
encryption systems. In general, the Gateway can unprotect any format produced by Office 2003,
Office 2007, or Liquid Machines Document Control, version 6 or 7.
The following types of content are not decrypted:
 Emails or documents encrypted by a scheme other than RMS or Liquid Machines
Document Control.
 File attachments representing email messages. These could include.EML files, .MSG files,
if not attached using Outlook, or any unknown format.
 .RPMSG files. This kind of file is normally a hidden attachment to an RMS-protected email
message. If a user manually detaches this hidden attachment from a protected email
message and then reattaches it separately to any message, it will not be decrypted.
 Contents of archive files; for example, .ZIP, .ARJ, .GZ, .RAR, and .TAR files are not
examined and therefore are not decrypted.
 Any other document file that is not protected by a Microsoft RMS or Liquid Machines
managed application.

Microsoft Windows Rights Management Services (RMS)
Microsoft RMS provides infrastructure that enables messages and documents to be protected and
controlled.
I nform ation Rights M anagem ent

Information Rights Management (IRM) enables users of Microsoft Office 2003 Professional Edition
PowerPoint, Excel, and Word; as well as users of Microsoft Office 2007 Professional Plus,
Enterprise, or Ultimate Edition PowerPoint, Excel, and Word, to restrict their documents.
RM S Server: I ssuing Access Licenses and Authenticating Users

The RMS server provides the encryption keys, or, in Microsoft terminology, licenses, that are used
to protect messages. Rights-managed applications, like Microsoft Office 2007 and the Gateway for
BlackBerry, need access to RMS servers to get licenses to access protected content.
When an Office user requests access to read a message or a document, the RMS server also
handles authenticating that user. That is, the RMS server gathers the user's credentials, verifies
them against Active Directory or another trusted RMS installation, and then checks to see if they
are part of the access control list on the message.
The Gateway for BlackBerry, however, is authenticated using its own credentials. Because the
Gateway’s service account is an RMS Super User, it is able to access the licenses used to protect
messages and attachments. The Gateway then verifies that the smartphone recipient is part of the
access control list on the message, blocking delivery if the recipient should not be allowed to view
its content.
RM S Client: Enabling Applications to Com m unicate w ith the R M S Server

Rights-managed applications, like Office 2007 and the Gateway for BlackBerry, decrypt protected
messages and documents so that the appropriate recipients can read them. Desktop applications
like Office 2007 may also preserve or carry forward protections when a recipient alters, replies,
copies, or forwards a message or saves or alters an attachment.
To do all this, the applications must request access to licenses from the RMS server on behalf of
the user, submitting the user's credentials in the process. They may also need to generate new
keys to encrypt materials and must share these with the RMS server. This interaction with the RMS
server happens through the RMS client. The RMS client is a piece of middleware, standing
between the server and an RMS-enabled application. It provides an API that applications use to
access the Microsoft RMS system. The RMS client must be installed on the same computer as the
rights-managed applications and the server with the Gateway for BlackBerry.
The Gateway for BlackBerry uses RMS Super User rights for decryption.
The Liquid Machines Client for BlackBerry can apply an RMS template, a collection of Rights
Management controls, to a message as it passes from a user’s BlackBerry smartphone into the
Exchange email system.

A system administrator creates these templates, stores them in a central location, and then
configures RMS clients to search this location. A user can choose a template to protect a
message. Some of the controls that can be included in a template are:
 Expiration: After a certain date, RMS servers will deny access to a message no matter
who requests it. The message sender can be exempted from this restriction, or included
in it.
 Group Access Only: RMS will give access to anyone in the specified list of users and
groups. The groups are defined in your Windows Active Directory, and you specify them in
the template by their email address. You can define this right for several different groups
that represent departments, divisions, or your whole company.
 Protected Access: Anyone who can obtain credentials within the RMS system can read
the message. This typically means anyone with an Active Directory account in your
company. If your RMS installation was configured to trust other RMS installations, such as
Microsoft Passport, this setting will also include users on those systems.
 Forwarding Prevention: The recipient will be prevented from sending the message on to
anyone else.
RM S I nstallations and Trusts

When you install the first RMS server into an Active Directory domain and register the service
connection point with Active Directory, it is called an RMS installation, and it is associated,
attached, installed into, or bound to the Active Directory forest in which the domain exists. You can
install additional servers into this installation, for load-balancing or redundancy.
While it is possible to install RMS servers into this same Active Directory in a way that is not
associated with this installation, you cannot register the service connection point of these new
servers with this Active Directory, and they are not the ones that rights-managed applications
would typically use if they are members of this Active Directory. If, for some reason, you are
deploying this kind of infrastructure, contact Liquid Machines Product Support before installing the
Gateway for BlackBerry.
An RMS installation can be configured to trust other RMS installations. For example, you can
configure yours to trust one in a different Active Directory in a different company. The general
result is that content protected under one installation can be viewed by users in another
installation, assuming the correct permissions have been set. An RMS installation can also be
configured to trust the Microsoft Passport Service, which is available to individual consumers on
the Internet. But if RMS Installation A trusts RMS Installation B, and Installation B trusts Installation
C, it is not true that A trusts C. In other words, just because you trust a company does not mean
you have to trust the other companies that they trust.
The Gateway processes content using the RMS installation bound to the Active Directory in which
the Gateway computer and the BlackBerry® Enterprise Server service account reside. The
Gateway can only decrypt content bound for the smartphone that was protected using this same
RMS installation. If the Gateway cannot decrypt the message, it will pass it through unprocessed.
For more information, see your Microsoft RMS documentation.

Liquid Machines Document Control
Liquid Machines Document Control provides encryption and rights management of documents. In
addition, it extends RMS protection beyond Office 2007 and 2003 Professional to Office XP and
Office 2000, as well as to leading desktop and enterprise applications, such as Adobe Acrobat,
Adobe Reader, and Microsoft Visio.
Liquid M achines Docum ent Control Server: P roviding P olicies, K eys, and
Security
Liquid Machines Document Control provides enhanced enforcement options based on policies
downloaded from a Liquid Machines Document Control server. The physical security (encryption)
can be provided either by RMS or by a Liquid Machines Key Service (LMKS), which is part of the
Liquid Machines Document Control server. The combination of a Liquid Machines Document
Control server, various physical security services, and various clients is referred to as Universal
Enforcement Services (UES).
To be able to obtain policy information and cryptographic keys, the Gateway for BlackBerry must
communicate with one or more Liquid Machines Document Control servers, version 6.4 or later.
The Gateway caches policies and keys locally, which maximizes performance and allows offline
operation. It contacts the servers on startup and polls them for policy changes periodically, based
on a frequency specified by the Liquid Machines Document Control server. The cache can also be
updated dynamically if the Gateway encounters a document protected by a new policy that is not
yet in the cache. The cache is stored in an encrypted form that is only accessible to the Gateway.
When policies and keys are available in the cache, the Gateway can unprotect documents that use
LMKS Security without communicating with any server. Liquid Machines Document Control
documents that use RMS Security still require communications in order to obtain a document-
specific license.
Liquid M achines Docum ent Control Enforcem ent Agents: P rotecting

Docum ents
The Liquid Machines Document Control client provides enforcement by integrating with
applications on a user's workstation. Liquid Machines Document Control can protect documents
using ad hoc permissions, an RMS template, or a policy defined by Liquid Machines Document
Control.
Ad hoc permissions and templates always make use of an RMS license and are always compatible
with Microsoft Office IRM when used in IRM-supported applications (Word, Excel, and
PowerPoint). Unprotection of such documents by the Gateway is based on RMS Super User
capability.
The Liquid Machines Document Control client can interact with both Liquid Machines Document
Control servers and RMS servers. The Liquid Machines Document Control server provides policy
information to Liquid Machines Document Control clients.
The Gateway for BlackBerry interacts directly with Liquid Machines Document Control servers to
provide its unprotection services, so there is no prerequisite for installing any Liquid Machines
Document Control software before installing the Gateway.
Liquid Machines Document Control policy permissions can be enforced using security from either
RMS or LMKS. The Gateway’s service account must be granted access to the policy and have the
Remove policy right in order to unprotect a document. A message recipient must be granted
access to the policy in order to receive the unprotected document.

More About Unprotecting at the Gateway
Microsoft Windows Rights Management Services (RMS)
P rocessing w ith R M S if Liquid M achines Docum ent Control is Disabled
If the deployment includes both RMS and the Liquid Machines Document Control policy server, if
RMS is enabled, but Liquid Machines Document Control server is disabled, the Gateway for
BlackBerry can unprotect all content from Microsoft Office IRM, as well as some documents
produced by the Liquid Machines Document Control client: those that can be unprotected without
any need for a Liquid Machines policy. This includes documents from any application protected
using ad hoc permissions or an RMS template. It also includes documents from applications that
use a Liquid Machines policy using RMS security in IRM-Compatible mode. The Gateway makes a
best effort for such cases and unprotects only if it knows that the document can be unprotected
without any auditing requirements. Because of details of the file formats used by the Liquid
Machines Document Control client, the Gateway for BlackBerry (in RMS-only mode) can unprotect
such documents only from Word, Excel, PowerPoint, and sometimes Visio (based on the version of
the Liquid Machines Document Control client used).
Any Liquid Machines Document Control document that cannot be unprotected because of the
limitations above is identified as a foreign document and passed through. To ensure unprotection
of all Liquid Machines Document Control documents with proper auditing, it is recommended that
Liquid Machines Document Control functionality be enabled, and that the appropriate permissions
be granted on the Liquid Machines Document Control server.
Foreign P rotection Checking w ith R M S

If the Gateway fails to unprotect a document or message that it expects to be able to unprotect, it
determines whether to treat the content as foreign or local content:
 A foreign document or message contains content that the Gateway will never be able to
unprotect because it cannot resolve or communicate with the foreign RMS server.
 A local document or message contains content that the Gateway should be able to
unprotect, but may not be able to at a given moment because of a presumably temporary
error condition, such as a network failure.
When the deployment includes the Liquid Machines Document Control policy server and it is
disabled, or the Gateway encounters a document or message that was not protected by a Liquid
Machines policy, it determines whether the content is foreign or local based on the primary RMS
server and the configured domain suffixes:
 The primary RMS server (the one used to configure the RMS client as part of the
prerequisites) is always treated as local. This server does not need to be listed in the
Gateway’s configuration, and it cannot be removed.
 By default, the Gateway machine’s DNS domain is treated as local. This domain is explicitly
listed in the default configuration using a special variable, but it can be removed.
 The DNS domain of any RMS installation, including the primary RMS server, must be
explicitly added to the Gateway’s configuration if its domain suffix does not exactly match
the Gateway’s DNS domain suffix.

For example, if your RMS installation is rms.acme.com, and the Gateway is installed on
bes.acme.com, the default configuration automatically includes both rms.acme.com and
*.acme.com. The default list of domain suffixes in the Gateway’s configuration must be modified if
the Gateway needs to support multiple domains.
If a blank DNS domain is listed in the configuration, all RMS-protected documents are treated as
local, including those that were protected by foreign RMS installations.
When the Gateway fails to unprotect a message, it logs an error in the Event log.
When the Gateway fails to unprotect an attached document, the failure is handled as follows:
 If the attachment’s content should be treated as local, the Gateway logs an error message
in the Event log and delivers the attachment still protected.
 If the attachment’s content should be treated as foreign, the Gateway logs an informational
message in the Event log and delivers the attachment still protected.
Liquid Machines Document Control

Unprotection of Liquid M achines Docum ent Control Docum ents
The Gateway for BlackBerry can be configured to unprotect documents protected by Liquid
Machines Document Control. A list of policy servers can be included by host name or URL.
If a configured server cannot be contacted when it is initially configured, the Event log shows an
error, and Liquid Machines policy operations fail. Otherwise, the server is polled for policy updates
on startup and periodically, based on the poll interval configured on the server.
The Gateway can also be configured to automatically discover additional servers when it
encounters documents protected by those servers’ policies. In such cases, unprotection will
succeed only if the Gateway Service user can properly authenticate to the appropriate server and
obtain appropriate permissions. If a discovered server is contacted successfully, it will be kept
active and polled for updates for a period specified in configuration, or until the Gateway Service is
restarted. After that, it will become inactive and will need to be discovered again.
When Liquid Machines Document Control is enabled, the Gateway can unprotect documents
protected by the configured Liquid Machines Document Control servers in exactly the same way as
a Liquid Machines Document Control client. The Gateway User must have appropriate policy
permissions, and the Liquid Machines policy permissions always take precedence over RMS Super
User rights for documents protected by a Liquid Machines policy. For documents with non-Liquid
Machines policies (RMS Ad Hoc or template), the RMS Super User rights are used as usual.
When Liquid Machines Document Control is enabled, and a document with a Liquid Machines
policy is unprotected (or if unprotecting is denied because of insufficient permissions), an audit
message is generated, if required by the policy.
Liquid M achines Docum ent Control Operation w ith R M S Disabled

If UES is enabled and RMS is disabled, the Gateway for BlackBerry unprotects only Liquid
Machines documents protected using LMKS security. Any RMS-protected documents are identified
as foreign and passed through. The Gateway blocks RMS-protected messages and notifies
smartphone users that there was a problem processing a protected message on their behalf.

Foreign P rotection Checking w ith Liquid M achines Docum ent Control
If a document is in a format with a policy type that the Gateway for BlackBerry expects to be able
to unprotect, but the unprotect fails, the Gateway determines whether to treat the document as
foreign content or local content. For RMS documents with no Liquid Machines policy, even if Liquid
Machines Document Control is enabled, foreign protection checking is the same as with RMS, only
enabled (see Foreign Protection Checking with RMS on page A-11).
For documents with a Liquid Machines policy, the check is performed slightly differently. The
document's protection information is compared against the list of manually configured Liquid
Machines Document Control servers (not auto-discovered services), based on both the Service ID
and the Service Locator stored in the document. Any match indicates content that should be
unprotectable. The identity of the RMS security service used for a document protected by a Liquid
Machines policy is not used for this check. This may be important to the results if the RMS server
and the Liquid Machines Document Control server are in different subdomains.

Installation Architecture
Liquid Machines Gateway for BlackBerry integrates with BlackBerry Enterprise Server for
Exchange 4.x, Windows Active Directory 2000, Exchange 2003, and Microsoft Windows Rights
Management Services Service Pack 1 or Service Pack 2.
Rights Management Services (RMS)

Liquid Machines Gateway for BlackBerry requires Rights Management Services. RMS is used to
apply access controls to protected messages. Recipients need RMS clients, such as Office 2007
or the Windows Rights Management Add-on for Internet Explorer, to read protected messages. For
more information, see Microsoft Windows Rights Management Services ( on page A-11.
You should be familiar with RMS and have a working production deployment before installing the
Gateway for BlackBerry. For more information, refer to Microsoft documentation and your
Microsoft-certified RMS provider.
BlackBerry Enterprise Server for Exchange

BlackBerry Enterprise Server detects messages that have entered a user’s Exchange mailbox and
sends copies of them out over a wireless network to that user’s BlackBerry smartphone. It also
accepts messages sent from the smartphone and routes them back into the Exchange system.
The BlackBerry Enterprise Server also provides additional services, such as synchronizing address
books and calendars between the smartphone and Outlook, and allowing the smartphone to
display translated versions of certain types of attachments.
Gateway for BlackBerry: Processing Messages as They Pass

Through the BlackBerry Enterprise Server
The Gateway for BlackBerry is a program that intercepts messages, scans them for certain key
information, and then takes action on them based on what it finds.
When the Gateway is enabled, it inserts itself into the Windows Services information such that the
Gateway is automatically started when the administrator starts the BlackBerry Controller Service.
After initialization, the Gateway then starts the BlackBerry Controller Service.
The Gateway initiates communications with RMS or Liquid Machines Document Control servers
based on its configuration. It handles caching of Liquid Machines policies and keys for offline
operation and polling the servers for updated information. It also enforces Liquid Machines and
RMS View, Reply, and Forward permissions and expiration and offline access limits.

When a message goes from the BlackBerry Enterprise Server to the smartphone, the Gateway
decrypts the message and its attachments and sends them along in a readable format (unless you
are using the client-level encryption option), so long as the user is authorized to read the message.
When a message goes from the smartphone to the BlackBerry Enterprise Server, the Gateway
may protect it using RMS, depending on the type of message:
 For a new message, the Gateway protects the message according to the template specified
by the smartphone user.
 For a reply to or a forward of a protected message, the reply or forward is protected using
the same policy as the original message. The smartphone user cannot override the original
policy.
When a message with an attachment is forwarded, the original attachment (protected or
unprotected) is included with the message, provided that the original message still exists in the
smartphone user’s Exchange mailbox. Replies do not include any attachments from the original
message. Forwards do not include any attachments if the original message has been deleted
from the smartphone user’s Exchange mailbox.
In general, you will want to install the Gateway on all your BlackBerry Enterprise Servers, so that
you can intercept messages in all circumstances you deem appropriate. Liquid Machines primarily
recommends this approach. You may choose to install the Gateway on only some servers if you do
not wish to extend any protected content functionality to the users on the other servers.
Liquid Machines Client for BlackBerry: User Interface, Smartphone

Maintenance
Liquid Machines client software is installed on users’ BlackBerry smartphones to enforce message
and attachment security on the device.
The Liquid Machines Client for BlackBerry provides a friendly, intuitive interface. It allows users to:
 Read Liquid Machines encrypted messages and attachments.
 Securely reply to encrypted messages
 Select RMS templates under which new (or previously unprotected) messages will be
protected by the Gateway.
As a system administrator, you compose a specially formatted email or IT policy and send it to
the smartphone in order to populate the interface with the RMS templates you choose (see
Configuring the Apply Policies Menu on BlackBerry Smartphones on page A-2). Use this
functionality if you want users to be able to protect new messages they compose on the
BlackBerry smartphone and you want them to be able to choose what protection template is
applied.
If you want to protect new messages but not give the user choices, and instead want to control
what happens centrally according to policy, contact your Liquid Machines representative about
Liquid Machines Gateway for Exchange and SMTP.
The client also periodically searches through the message store, or NVRAM, on the smartphone. It
finds protected unencrypted messages that include an expiration date in the controls, and, if the
expiration date has passed, deletes them. It covers both messages received and copies of sent
messages, and it runs automatically every 24 hours. The frequency is configurable (see Accessing
Client Diagnostic Functions on page A-9). Use this functionality to prevent access to expired
messages that have been stored in the clear on the BlackBerry smartphone. The Client does not
currently support the automatic deletion of expired attachments.

Message Handling
This section describes how the Gateway for Blackberry handles messages.
Priority of Protection Requests

If a message sent from a smartphone is a reply to or forward of another protected message, the
permissions applied to the reply or forward will be exactly the same as those on the original. There
are no exceptions to this. Any protection manually requested by the smartphone user forwarding
or replying to the message is overridden.
Attachment Handling
The Liquid Machines Gateway for BlackBerry supports the BlackBerry Attachment Service.
Authorized message recipients can read attachments that have been protected with RMS or Liquid
Machines policies on their BlackBerry smartphones.
When an Outlook user protects an email message and attaches an unprotected Office document,
the message policy automatically protects the document as well. In this case, they gateway will
unprotect both the message and attachment and encrypt both the message and attachment before
delivering them to the BlackBerry smartphone.
There are other scenarios where the attachment is not automatically protected when a message is
protected. Non-Office files, like PDF for example, are not supported by Outlook’s implementation
of IRM and so are not automatically protected with an RMS policy. In this case, the gateway
removes the RMS protection from the message and applies encryption to the message, but does
not apply encryption directly to the document itself. Since the message is encrypted and these
attachments are stored inside the encrypted message envelope, they cannot be accessed without
accessing the protected message. Once these attachments are extracted from the envelope
however, they are no longer protected.
Message Controls Prevent Sending

Under certain circumstances, the Gateway may detect that protected messages sent by a
smartphone user may not be readable by the recipient. In other cases, the Gateway may
completely block smartphone users from replying to or forwarding a protected message. When the
Gateway determines that a message should not be delivered or may not be readable, it sends a
return message to the smartphone to explain what happened.
M essages to Unauthorized Recipients

When a smartphone user sends a protected message, and some of the recipients are not
authorized to view the message, the Gateway sends an alert back to the sender explaining that
some of the recipients may not be able to view the message.
RM S R eply and Forw ard P rivileges

The controls on an RMS-protected message can include the ability to block replies to protected
messages. RMS refers to this as granting or denying the Reply privilege. In Outlook IRM, this
becomes evident because the Reply button is disabled.
If a protected message does not grant the recipient the permission to reply, and a smartphone user
sends a reply to such a message, the Gateway blocks delivery of the message and the sender
receives a notification indicating that the message was not delivered.

RMS also includes separate Reply to All and Forward privileges, which are handled similarly. Note
that if the BlackBerry Enterprise Server detects that the list of recipients on the reply is the same as
the list of recipients on the original message, it treats the user action as a Reply All. The
conversion can affect which restrictions are applied, as is the case when the Reply privilege has
been granted, but the Reply All privilege has not.
Ex pired M essages
If the user attempts to reply to or forward an expired message, the action is blocked, and the
sending user receives a notification indicating that the message was not delivered.

Chapter 2: Installing the Gateway
Server
This chapter describes the installation requirements for the Gateway Server and how to install,
upgrade, or uninstall the Gateway Server.
 System Requirements
 Important Information About Upgrading From Previous Versions
 Preinstallation Requirements
 Installing the Liquid Machines Gateway for BlackBerry
 Upgrading from a Previous Version of the Liquid Machines Gateway for BlackBerry

System Requirements
Hardware (Minimum Requirements)
 Pentium IV, 2GHz or greater
 1.5 GB RAM
 60 MB disk space on the BlackBerry Enterprise Server
Software
 Windows Server 2003 SP1 or SP2 or Windows Server 2008 (including R2).
 The server must be installed in an Active Directory 2000, 2003, or 2008 domain. For an
RMS installation, a Microsoft Rights Management Services server 1.0 SP2 or AD RMS
server must have been installed and provisioned for the production environment in this
domain.
 BlackBerry Enterprise Server for Exchange 4.0, 4.1 or 5.0. We strongly recommend that
you install the latest service packs for 4.0 or SP6 for 4.1 (version 4.1.6).
 If Microsoft Windows Rights Management (RMS) is enabled:
 Microsoft Rights Management Client 1.0 SP2 or ADM RMS.
Important Information About Upgrading From

Previous Versions
All versions of the Liquid Machines Gateway for BlackBerry prior to version 6.7.0 stored protection
information in a hidden Exchange folder. As of version 6.7.0, this information is stored in a SQL
Server database.
To upgrade from a previous version, you must follow the steps summarized below:
1. Make a backup copy of the Gateway Configuration file. The name of this file is
lmbesgateway-config.xml, and it is located in the Gateway’s installation directory,
usually C:\Program Files\Liquid Machines\Gateway for BlackBerry.
2. Satisfy each of the Preinstallation Requirements described on page A-3.
3. Install the Liquid Machines Gateway for BlackBerry, as described in Installing the Liquid
Machines Gateway for BlackBerry on page A-4.
4. Migrate your protection information from the hidden Exchange folder to the SQL Server
database, as described in Upgrading from a Previous Version of the Liquid Machines
Gateway for BlackBerry on page A-6.
5. Configure and enable the Gateway as described in Chapter 3: Administering the Gateway
Server on page A-1, using the backup copy of the Configuration file from step 1, above, as
a reference. Do not copy the old Configuration file over the newer version that was installed
in step 3 above.

Preinstallation Requirements
Complete these steps before installing the Liquid Machines Gateway for BlackBerry 7.0 from the
software CD. Local administrator privileges are required to install the Gateway.
 Install Microsoft Rights Management Client 1.0 SP1 or SP2 on the Gateway machine, if you
have not already done so.
 Your BlackBerry Enterprise Server is configured with a service account whose credentials it
uses to access various parts of your infrastructure. This account is typically known as the
BESAdmin account. For the Gateway to operate correctly, the BESAdmin account must:
 Have a mailbox in your Exchange organization. This mailbox need not be located on the
Gateway machine.
 Be an RMS Super User. Refer to your RMS documentation for instructions on how to
grant this privilege.
 Have rights to log on as a service to the Gateway machine. This right should have been
granted to the account during the installation of the BlackBerry Enterprise Server
software. However, if you make use of Active Directory Group Policies, you should
make sure they will not override this local setting.
 Have sufficient rights in your Active Directory so that it can query for security and
distribution groups and get a list of their members.
 As stated in the Microsoft RMS documentation, the user account must be granted the right
to run as an RMS service.
 To accomplish this, on each of your RMS servers, find the file
ServerCertification.asmx. This will typically be located in
c:\Inetpub\wwwroot\_wcms\Certification. Change the security permissions on this file
so that the user account has Read and Execute permissions on it.
 You must also give a group that your RMS installation created, called RMS Service
Group, these same Read and Execute permissions. This group exists in the builtin
groups local to each RMS server machine. If one or more RMS server machines are
also domain controllers, you may find this group in the Users or Builtins container in
your Active Directory. When you have made the permissions changes, restart IIS on the
RMS servers.
 You must initialize the Windows user profile of the user account on the Gateway machine.
To do this, log in on the console, or via Terminal Services or Remote Desktop, to the
Gateway machine with the user account’s login credentials and then log out.
 On Windows 2003 Server only, in the profile of the user account you created above, the
machine name of the RMS server, as it appears in the RMS Licensing URL, may need to
be included in the list of local intranet sites in Internet Explorer. This will be true if the URL
contains a dot (.) in the server name. For example, for the URL
http://rms1.acme.com/_wcms/licensing, you need to make this change. For
http://rms1/_wcms/licensing, you would not.
If your Licensing URL does contain a dot (.) it is a good practice to make this Internet
Explorer settings change for all users in your environment. Instructions on ways you can
accomplish this, for example using Active Directory Group Policy, can be found on our
Customer Care web site, in Knowledge Base Article KE-376. If you only want to make the
change locally on the Gateway machine, see Appendix C: Adding RMS Servers to the
Local Intranet Sites on page C-1.

 If you have previously installed any version of the Liquid Machines Gateway for BlackBerry,
you must uninstall it before installing version 7.0. Make a backup copy of the current
Gateway Configuration file before uninstalling the old version. You will use this backup copy
as a reference when configuring version 7.0.
 If you plan to enable RMS protection, you must provide a SQL Server 2000 or later
database where the Gateway will save RMS license information for protected messages
sent to smartphone users. The BESAdmin account must have the appropriate permissions
to create tables and insert, update, or delete rows. The default configuration expects the
database name to be lmbes. However, the database name can be configured as described
on page A-10. Liquid Machines strongly recommends that you create a new database
specifically for this purpose.
This database must have enough free space to store approximately 40K per protected message
sent to or from a smartphone.
If you are upgrading from the Liquid Machines Gateway for BlackBerry version 6.6.2 or earlier, you
will need to migrate information from the BESAdmin’s Exchange mailbox to the new database, as
described in Upgrading from a Previous Version of the Liquid Machines Gateway for BlackBerry
on page A-6.
The Gateway also supports any version of MSDE or SQL Server Express that is supported by the
BlackBerry Enterprise Server. However, due to the size limits imposed on MSDE or SQL Server
Express databases, this approach is recommended only for small organizations with a low volume
of protected messages that will expire in a relatively short timeframe.
 If you plan to enable UES protection, you must install and configure the Liquid Machines
Document Control server, version 6.4 or later. The Liquid Machines Document Control
server must be accessible from the BlackBerry Enterprise Server using the BESAdmin’s
Windows credentials.
 If you plan to enable UES protection, the BESAdmin account must be granted permission
on all relevant policies. These must include permissions to Read Content and to Remove
Policy.
Installing the Liquid Machines Gateway for BlackBerry

To install the Gateway for BlackBerry:
1. To start the installation wizard, double-click the Setup or Setup.exe file in the Gateway for
BlackBerry\Gateway folder. The Preparing to Install window appears. Follow the
Installation wizard through the process. The remaining steps describe the windows that
appear during the installation and the action required.
2. On the Welcome screen, read the welcome information and then click the Next button to
continue.
3. On the License Agreement screen, read and accept the license agreement and then click
the Next button.
4. On the Customer Information screen, enter your name and company information. Make
sure you leave the radio button labeled Anyone who uses this computer checked. Then
click the Next button.

5. On the Setup Type screen, select either a complete or a custom installation and then
click Next.
 If you select Custom, you can select the directory in which the Gateway software will
be installed on the Custom Setup screen (see Figure 2-1). To select an alternate
location, click the Change button on this screen.
Figure 2-1: Custom Setup Screen
 Select a directory and then click the Next button.

6. On the Ready to Install the Program screen, click the Install button to continue. A series
of progress bars appears while the Gateway software is installed.
7. The InstallShield Wizard Complete screen appears indicating that the installation process
is completed. To continue, click the Finish button.
After installing the software, you must complete the following steps before the Gateway will be fully
operational:
1. If you are upgrading from a previous version of the Gateway, perform the procedure
described in Upgrading from a Previous Version of the Liquid Machines Gateway for
BlackBerry on page A-6.
2. Configure the Gateway as described in System Tasks on page A-2.
3. Enable the appropriate protection systems as described in Enabling Protection Systems on
page A-2.
4. Enable the Gateway as described in Enabling the Gateway on page A-5.

Upgrading from a Previous Version of the Liquid
Machines Gateway for BlackBerry
To apply protection to replies and forwards sent from smartphones, the Gateway must save
information about how the original message was protected. Previous versions of the Liquid
Machines Gateway for BlackBerry saved this license information in the Associated Contents folder
of the BESAdmin’s Exchange Inbox. As of version 6.7, license information is saved in a SQL
Server database. If you are upgrading from a previous version of the Gateway, you must migrate
the license information saved by the previous version to the SQL Server database.
1. Before migrating the license information, stop the BlackBerry Controller service.
2. Log on to the Gateway machine using the BESAdmin’s credentials.
3. Open a command window and cd to the installation directory, which is by default
C:\Program Files\Liquid Machines\Gateway for BlackBerry.
4. Execute the following command exactly as it is typed below and entered as a single
command all on one line, making only substitutions for the strings localhost and lmbes as
described below:
lmbesupdatecl --profile=BlackBerryServer
--connection-string="DRIVER={SQL Server};SERVER=localhost;
DATABASE=lmbes;Trusted_Connection=yes"
Replace localhost with the hostname or IP address of your SQL Server. Replace lmbes
with the name of the database you created. For more information on constructing the
connection-string, see Configuring the ODBC Connection String for the Gateway Database
on page A-4.
The utility does not remove any license information from the BlackBerry Administrator's Inbox. You
can manually delete this information after you are sure the Gateway is properly configured and
operational.

Uninstalling the Liquid Machines Gateway for
BlackBerry
To uninstall the Gateway for BlackBerry:
 Before uninstalling the Gateway for BlackBerry, stop the BlackBerry Controller service.
 Disable the Gateway, as described on page A-5.
 If you will be reinstalling any version of the Gateway for BlackBerry, keep a backup copy of
the Gateway Configuration file to use as a reference when reconfiguring the Gateway after
reinstalling.
 On the Start menu, click Control Panel and then click Add or Remove Programs.
 Click Liquid Machines Gateway for BlackBerry and then click Remove.
 The uninstall will not automatically remove the Gateway's diagnostic logs. The logs may be
manually deleted when they are no longer needed.
 If you used the default log configuration, you will find the logs in
%ALLUSERSPROFILE%\Application Data\Liquid Machines\Gateway for
BlackBerry\logs.
 If you did not use the default data configuration, the uninstall will not automatically
remove the Gateway's cached data files usually stored in the
%ALLUSERSPROFILE%\Application Data\Liquid Machines\Gateway for
BlackBerry\SCache directory. This sensitive data is encrypted and only accessible
by the BESAdmin account; however, you should manually remove this directory
immediately following the uninstall to prevent the unlikely accidental distribution of
sensitive information.

Chapter 3: Administering the Gateway
Server
This chapter describes how to administer the Gateway Server.

 System Tasks
 Message Handing
 Monitoring the Gateway

System Tasks
Enabling Protection Systems
You must enable one or more protection systems before the Gateway will be able to decrypt and
encrypt messages and attachments. For more information about protection systems, see
Protection Systems on page A-6.
To enable protection systems, you must edit the protection-config settings in the Gateway
Configuration file, as described in protection-config settings on page A-5.
Configuring Protected Attachment Rendering Options

You will need to configure the rendering options for encrypted attachments. This set of options
allows the BES Administrator great flexibility in tuning the system to optimize the user experience.
Given the transport-level requirements of this feature, there are various format richness versus
download latency decisions to be made.
These configuration options consist of the following:
 A global maximum rendered attachment size to deliver to the device.
 Profiles for each major type of document.
 An option to failover to text-only mode when exceeding the threshold.
The following is an example configuration to illustrate usage:

 Maximum rendered file size = 200 Kb
 Word document profile = text-with-images
 Failover to text = true
When rendering a Word document with these settings, if the output of the text-with-images version
exceeds 200 Kb, it will be rendered as text-only. If this output exceeds 200 Kb, the attachment will
not be delivered to the device. Instead, the user will receive a descriptive error message.
To configure the encryption and rendering options beyond the defaults, you must edit the client-
config settings in the Gateway Configuration file, as described in protection-config settings on page
A-5.

Configuring Systematic Throttling
This section describes adapter size limits and gateway request limits.
Adapter Size Lim its

The Adapter for BlackBerry (which integrates with the BES Agents) now enforces a maximum size
on messages or attachments when unprotecting. This limit avoids excessive resource consumption
when processing a burst of large messages or attachments. This limit applies to both messages
and attachments. Any message or attachment which exceeds the limit will not be processed at all,
and will be delivered to the user in its protected form.
This limit can be configured in the configuration file using the new max-download-size value in the
bes subsettings section on page A-9. The default value is 10 MB, but this value can be tailored to
match the size limits in your exchange organization. It is not recommended that you raise this limit
without consulting with Liquid Machines Product Support.
Gatew ay Request Lim its

The Gateway Service (which services all BES Agents) now enforces configurable limits on
processing of requests to protect or unprotect content, including messages or attachments. The
new limits control how many requests can be executed simultaneously, the amount of time a
request can wait for processing, and a maximum request size. These limits avoid excessive
memory consumption when the Liquid Machines Gateway for BlackBerry processes a burst of
large messages. If a request exceeds a size limit, or it cannot be processed within the time limit, it
will fail and the message or attachment will not be processed.
The default values allow 5 simultaneous requests, an indefinite wait time, and a limit of 20 MB per
request. The request size limit is an internal limit enforced later than the Adapter limit described on
page A-3, and should be set to a larger value to allow for request overhead. Administrators can
change these settings in the configuration file or dynamically via the registry. The new settings can
be found in the configuration file in the networking subsettings within the gateway-service-settings
section described on page A-4. There are similar settings for the gateway statistics page in the
monitoring settings section described on page A-8, but these do not affect message processing. It
is not recommended that you raise these limits without consulting with Liquid Machines Product
Support. The expected worst case memory consumption with particular settings can be predicted
using this formula:
MaxMemoryInGateway = 100 MB + (1 MB * NumAgentWorkerThreads) +
(5 * MaxRequestSize * MaxConcurrentRequests)

Configuring RMS Templates
If you enable RMS, you must configure the location where the Gateway can find RMS templates.
The location does not need to be populated with templates immediately, but the location itself must
exist. The Gateway can be configured to periodically refresh its cache of templates from this
location. By default, the Gateway will refresh its template cache once per hour. For more
information on how to configure the refresh frequency, see Gateway Configuration File Syntax on
page A-1.
If you have already created a template folder on a Windows file share for use by Microsoft IRM or
other RM-enabled applications in your environment, you can use that location for the Gateway as
well.
1. Create a folder on the BlackBerry server or on a Windows file share. Then edit the Gateway
Configuration file and set the value of the template-location variable, which is in the
protection-config section, under the ms-rms subsection, to the path of the RMS
Templates folder or share. For more information on how to edit the Configuration file, see
Gateway Configuration File Syntax on page A-1.
2. If BlackBerry users will apply template protections to messages sent from the smartphone,
whether manually or by using the Apply Policies menu in the Liquid Machines Client for
BlackBerry, you will need to provide the Gateway with the corresponding RMS templates.
Place the template files in the directory you configured in the step above.
3. In creating templates, it is helpful if the template names, which will be exposed to users,
accurately reflect the controls the template will apply. For example, a template for records
retention that includes an expiration time of one year might be named Records Retention –
1 Year. RMS template descriptions are not exposed to BlackBerry smartphone users. For
more information on this subject, see Administering the Client on page A-1. For more
information on creating templates, see the Microsoft RMS documentation.
Configuring the ODBC Connection String for the Gateway Database

You must configure an ODBC connection string for the SQL Server database where the Gateway
will store the information necessary to reapply protection to replies and forwards sent from a
Blackberry smartphone as well as internal information about active users. You will not need to
modify the default connection string if all of the following statements are true:
 Your SQL Server is running on the same host where the BlackBerry Enterprise Server is
installed.
 You named your database lmbes.
 You configured your database to support Windows authentication.
To change the ODBC connection string, you must edit the Gateway Configuration file, as described
in Gateway Configuration File Syntax on page A-1.

Enabling the Gateway
To enable the Gateway:
1. Stop the BlackBerry Controller Service.
2. Open a command window and cd to the installation directory.
3. Execute the following command:
lmbesconfigcl --bind "blackberry controller"
4. Start the BlackBerry Controller Service.
Disabling the Gateway

To disable the Gateway:
1. Stop the BlackBerry Controller Service.
lmbesconfigcl --unbind "blackberry controller"
4. Start the BlackBerry Controller Service.
Upgrading or Reinstalling BlackBerry Enterprise Server

If you uninstall and reinstall the BlackBerry Enterprise Server, you do not need to uninstall and
reinstall the Liquid Machines Gateway for BlackBerry. However, you must re-enable the Gateway,
following the instructions above. If you upgrade the BlackBerry Enterprise Server or apply service
packs, you may also be required to re-enable the Gateway.
After reinstalling or upgrading BlackBerry Enterprise Server components, you can use the
Gateway's Configuration tool to verify that the Gateway is still enabled:
lmbesconfigcl --query
The tool displays the Gateway's current status. Instances that are bound are indicated with
a plus (+) sign:
+ (service is bound)
- (service is unbound)
-----------------------
+ BlackBerry Controller

Monitoring the Gateway
Application Event Logs
The Gateway logs important information about its operations to the Application Event log on the
Gateway machine. Appendix B: Application Event Log Entries on page B-1 contains a list of
messages (designated as informational, warning, or error), what causes them, and how to resolve
the issues causing them. If you are unable to resolve problems using the procedures here, or if the
problems recur frequently, contact Liquid Machines Product Support.
Many events include diagnostic information, like stack traces of the code, which you may be asked
to provide to Liquid Machines Product Support so that they can more closely analyze the problem.
For specific details on the entries that can be generated, and what they mean, see Appendix B:
Application Event Log Entries on page B-1.
Recipient Activity for Protected Messages

Microsoft RMS tracks activity that has to do with protected messages. When a recipient tries to
access the message, RMS logs information about the time, who tried to access it, whether access
was denied, and other information about the transaction. Data is logged to Microsoft SQL Server.
Because of the way in which the Gateway functions, when a smartphone user reads a message,
the identity logged in the RMS database is that of the BlackBerry Enterprise Server service
account, or BESAdmin; it is not the identity of the recipient. For more information on how to access
and make use of this data, see your RMS documentation.
If UES is enabled, the Liquid Machines Document Control server tracks activity for protected
documents that are protected by auditable policies. As is the case with RMS, the audit information
includes the identity of the BESAdmin, rather than the identity of the recipient.
Diagnostic Logging
The Gateway is capable of generating diagnostic log file data suitable for analysis by Liquid
Machines Software Engineers. Liquid Machines Product Support may require you to enable this
logging as a part of a troubleshooting procedure. You can read more about how this is done, where
the log files are located, and so on, in Appendix C: Adding RMS Servers to the Local Intranet Sites
on page C-1.
Tracking the Number of Active Users

Starting from version 7.1.1, the Gateway for Blackberry allows auditing of users who are working
actively with protected content. Liquid Machines may request a report of such information as part
of an audit of license usage. Information is tracked based on the set of active users in each
calendar quarter. A user is considered to be active in a given quarter if:
 He or she received protected content (message or attachment) which he or she had
sufficient rights to view, or
 He or she successfully replied to or forwarded a protected message, or
 He or she successfully applied a policy to a message using Client for Blackberry.

In order to store information about active users, the Gateway uses an SQL Server database that is
configured via a connection string provided in the configuration file.
>> For more details on the configuration, see Configuring the ODBC Connection String for the
Gateway Database on page A-4.
Creating an Active Users Report

The active users reporting command-line tool allows you to get information about active users for
the following time periods:
 The current quarter
 The four most recent quarters
 The whole range of all quarters stored in the Gateway database.
To create a report:
Open a command window and cd to the installation directory.
Type the following command and press Enter:
LmGetActiveUsers --generate –p all –r <path to the report file
that should be created>
If you have configured the Gateway database with settings other than the default, use the “-c”
parameter to specify the connection string.
Example: To create a report in a file called report_all.txt:
LmGetActiveUsers –generate –p all –r report_all.txt
Options for the LmGetActiveUsers command:
Program Modes (mutually exclusive, defaults to '--generate')
Command Option Description
--generate Generates an active users report.
--validate Validate that a generated report has not been altered.

Program Options
--help Displays usage information.
-h
--connection-string=<value> The database connection string to the access table with
-c <value> active users information. Values may not be blank.
Default value is:
DRIVER={SQL Server};SERVER=localhost;
DATABASE=lmbes;Trusted_Connection=yes
--period=<value> The reporting period. Use:

-p <value> all to get all information in the database
year to get information for most recent four quarters
quarter to get information for current quarter.
Default value is all.
--report=<value> The file where the report should be stored or was stored.
-r <value> Must be a valid file name (not a directory).
--audit-info Specifies whether or not to include a list of active user
emails for each quarter, in addition to the user count.

Chapter 4: Installing the Client
The Liquid Machines Client for BlackBerry provides a means to decrypt and display protected
messages and attachments. It allows users to apply RMS policy templates to outgoing messages
sent from the BlackBerry. It also allows for automatic expunging of expired messages from the
BlackBerry.
This chapter explains how to install the Liquid Machines Client for BlackBerry using the
BlackBerry® Desktop Manager.
 System Requirements
 Preinstallation Requirements
 Installing and Uninstalling the Client
For information on how to install the Client for BlackBerry over the air, refer to Knowledge Base
Article KE-1437 on our Customer Care web site.

System Requirements
Hardware
 400MHz Pentium II processor
 128MB RAM
 10MB hard disk space
Software
Operating System
One of the following:
 Windows 2000 Service Pack 4
 Windows XP Service Pack 1, 2, or 3
 Windows Vista Service Pack 1
 Window 7
BlackBerry Softw are

 BlackBerry Desktop Software 4.0 or later for smartphones running OS version 4, 5, or 6.
 BlackBerry Runtime OS 4, 5, or 6 or later for Java-based smartphones.
 RIM Attachment Service
While Liquid Machines supports 4.0+ clients, we recommend the use of 4.2.1+, which includes a
useful content view feature called Page View. Page View allows you to use the zoom and
horizontal scroll features.
Obtain the most recent runtime OS release possible from your smartphone vendor. C++
BlackBerry smartphones are not supported.
In addition, you will need the following:
 The ability to install programs on the workstation.
 Immediate access to a working Liquid Machines Gateway for BlackBerry installation.
Remember that, to install any add-on application onto a BlackBerry smartphone using Desktop
Manager, you must install both the Desktop Manager software and the runtime OS for your
particular unit onto your workstation. You can obtain the runtime OS from the unit’s maker.
Preinstallation Requirements
The Liquid Machines Client for BlackBerry is an application developed using the BlackBerry®
Java® Development Environment. The application uses portions of the BlackBerry API that require
the BlackBerry® Browser to be enabled in order to function properly.

Installing and Uninstalling the Client
Installing the Client
To install the client:
1. Log in to the workstation with administrative privileges.
 From the software distribution media, open the Gateway for BlackBerry\Client folder
and run Setup or Setup.exe.
 Read the Welcome screen, continue and accept the license agreement, then continue
through the rest of the screens, until the installation is finished. There are no special
parameters to configure.
 To install using the application loader tool, see Installing or Uninstalling Using the
Application Loader Tool on page A-3.
Installing or Uninstalling Using the Application Loader Tool

To install using the application loader tool, the BlackBerry smartphone must be physically
connected to the desktop computer using a USB cable.
1. Start the BlackBerry Desktop Manager.
2. Double-click the Application Loader icon.
3. Move through the Application Loader screens until you come to the Device Application
Selection screen (see Figure 4-1).
Figure 4-1: Device Application Selection Screen

 To install the client, verify that Liquid Machines Client for BlackBerry is in the list and
checked. (The software may have already notified you that there are new applications
to install.) If so, complete the application loading process according to the procedures in
your BlackBerry software manual.
 If Liquid Machines Client for BlackBerry is not present, click the Add button and
add it.
 To uninstall the client, clear the check box for Liquid Machines. Then complete the
application removal process according to the procedures in your BlackBerry software
manual.
4. Navigate to the c:\Program Files\Liquid Machines\Client for BlackBerry folder and
select the LQMIBB40.alx file (see Figure 4-2).
Figure 4-2: Open the Client for BlackBerry Folder and Select the LQMIBB40.alx
Then complete the application loading process according to the procedures in your
BlackBerry software manual.

5. Once your smartphone has restarted, a new icon appears in your main applications list (see
Figure 4-3):
Figure 4-3: New Client for BlackBerry Icon on the smartphone
To further test the installation, refer to the Liquid Machines Client for BlackBerry User’s Guide and
to relevant information in this guide.

Chapter 5: Administering the Client
This chapter describes administration tasks you can perform with the Liquid Machines Client for
BlackBerry.
 Configuring the Apply Policies Menu on BlackBerry Smartphones
 Delivering Policies to the Smartphone
 Setting Client Application Permissions
 Accessing Client Diagnostic Functions

Configuring the Apply Policies Menu on BlackBerry
Smartphones
The Liquid Machines Client for BlackBerry provides a friendly interface for creating protected
emails. For more information, see the Liquid Machines Client for BlackBerry User’s Guide.
The Apply Policies menu refers to RMS templates that you have already created for use in your
RMS environment. You must make these templates available to the Gateway before you can use
them on the client. For more information, see Configuring RMS Templates on page A-4.
You have to take special measures to configure the Apply Policies menu on the smartphone. RMS
templates are not distributed to smartphones automatically.
The menu you configure for smartphones must contain one or more of the RMS templates you
have made available to the Gateway. The Gateway for BlackBerry will not apply a user-selected
template that does not match one of these.
If you protect new messages according to a company policy without requiring smartphone users to
select a template, contact your Liquid Machines representative about installing Liquid Machines
Exchange Gateway for RMS.
It is possible for smartphone users to apply a template without the aid of the Liquid Machines Client
for BlackBerry. For more information on how to do this, see the Liquid Machines Product Support
Knowledge Base.
Delivering Policies to the Smartphone

You can deliver policies to the smartphone using one of two methods:
 Plain Text Email (see Plain Text Email below)
 IT policy push (see IT Policy Push on page A-5)
Plain Text Email

Using the first method, you send the smartphone a specially designed plain text email. The
receiver will see this email in the Outlook inbox, but not on their smartphone. The smartphone
receives the message, processes it, and populates the Apply Policies menu with the policies
specified in the email. Any time a new configuration email is sent to the smartphone, it replaces the
existing policies.
M essage Form at
The message must be sent in plain text format. It must not be a protected email, or HTML or Rich
Text.
Configuration Syntax
Subject
The subject of the message must be exactly like this:
<Handheld_Policy_Settings>

Opening
The first three lines of the message body must be exactly like this:

<?xml version="1.0"?>
<Policy_Message>
Template Expiration Definition
For each RMS template you have configured for the Liquid Machines Gateway for BlackBerry that
you want to make available to the user, you must add a group of lines that specify its expiration.
You can define templates to expire in either of these ways:
 By duration, that is, after a certain length of time
 By a specific date
Expiration by Duration
To define an RMS template’s expiration by duration, add a group of lines similar to the following:
<Template>
<Name>template name</Name>
<Expires_In>nn</Expires_In>
<Time_Units>Units</Time_Units>
</Template>
For the text in bold, substitute the appropriate values. These values must conform to the RMS
protection templates you set up for the Gateway.
template name: Enter the name of the template exactly as you configured it in RMS, including any
spacing or punctuation.
nn: Enter the number of units, as a numeral.
Units: Enter one of the following values. Note that all these values are capitalized and plural.
 Hours
 Days
 Weeks
 Months
 Years
Expiration by Date
To define an RMS template’s expiration by date, add a group of lines similar to the following:
<Template>
<Name>template name</Name>
<Expires_On>yyyy-mm-ddThh:mm:ss.mmm(+/-)hh:mm</Expires_On>
</Template>
The Expires On field specifies the exact date and time the message will expire. Enter the year,
month, day, hour, minute, second, millisecond, and offset from Greenwich Mean Time. For
example, for August 1, 2007 at just before 12 midnight Pacific Daylight Time, enter 2007-08-
01T23:59:59:999-07:00.
If the message will never expire, enter Never.

Closing
The last line of the message must be exactly like this:
</Policy_Message>
Ex am ple P olicy Delivery Em ail


<?xml version="1.0"?>
<Policy_Message>
<Template>
<Name>Memos</Name>
<Expires_In>30</Expires_In>
<Time_Units>Days</Time_Units>
</Template>
<Template>
<Name>Documents</Name>
</Template>
<Policy_Category>
<Name>Records</Name>
<Time_Units>Years</Time_Units>
</Template>
<Name>Conversations</Name>
</Template>
<Template>
<Name>End Fiscal 2007</Name>
<Expires_On>2007-09-30T23:59:59.999-07:00</Expires_On>
</Template>
<Template>
<Name>HR Confidential</Name>
<Expires_On>Never</Expires_On>
</Template>
<Template>
<Name>Executive Confidential</Name>
<Expires_On>Never</Expires_On>
</Template>
</Policy_Message>

Autom ated Creation of P olicies M essage
You can use a tool to generate XML to create the policy message without having to type it by hand.
The tool takes the name and description of policies from the directory of RMS templates. The
resulting message can be sent by email or by IT policy push. Follow these steps:
1. Open a command window and cd to the Gateway installation directory.
lmmakepolicymsg -d <UNC path to the shared folder with templates on RMS server> –o
<output file name to contain the message body>
Example:
LmMakePolicyMsg.exe -d \YourRMSServer\Template -o policymsg.xml
If the output file already exists, its contents are replaced; otherwise, an output file is created
with the name specified.
Options:
--help Displays help information.
-h
--config-file=<value> The name of a file from which to fetch configuration information.
The settings in this file are merged with any settings on the
command line, with those on the command line having higher
precedence. Paths are relative to the current working directory.
If this setting is not used, and a file with the name
LmMakePolicyMsg-config.xml exists in the directory, it is
used. Must exist as a valid file.
--dump-config Dumps all config information.
--verbosity=<value> Level of verbosity of output. Legal values are: 0 to 4, with 0
-v <value> being silent and 4 being the most verbose.
The default value is 2.
--directory=<value> Path to the directory that contains the RMS templates. Must
-d <value> exist as a valid directory.
--output=<value> Name and path of xml file where template information should be
-o <value> stored. Must be a valid file or not exist. (It cannot be a directory.)
Long form names (those that begin with --) can be abbreviated, as long as the abbreviation is
unambiguous.
IT Policy Push
Another method to send templates to a smartphone is by IT Policy Push. You can automatically
distribute, or push, RMS templates that have been created to a user or a group of users. With the
plain text email message, if a user’s BlackBerry is hard-reset, the email has to be sent again. When
the RMS policies are pushed via an IT Policy, the RMS policies defined in the IT Policy Template
are automatically pushed to the BlackBerry device. By default, IT Policies are pushed immediately
after applying an IT Policy and automatically every 4 hours thereafter.

To create a new IT policy on BES version 4.x: Open the BlackBerry Manager, select the Global
tab, and click on BlackBerry Domain on the left. In the tasks area on the right, click on Edit
Properties and then select IT Policy. Under IT Policy Administration, double-click on IT Policies
and select New… Name the policy, then scroll to the bottom of the left-hand menu and select
User Defined Items. Under Policy Item Customization, double-click IT Policy Template and
select New… Select IT Policy Template Item under properties and enter LM Handheld Policy
Settings in the name field. In the type field, select Multiline String. In the destination field, select
either Handheld or Both. Click OK until you have returned to the main Global tab of the
BlackBerry Manager. Click on Edit Properties, select the policy you just created, and click the
Properties… button. Scroll down to User Defined Items and double-click the field labeled LM
Handheld Policy Settings. Paste the policy delivery XML into the text field; the IT Policy delivery
XML is constructed according to exactly the same rules as the policy delivery email (see
Configuration Syntax on page A-2), with the exception that the IT Policy XML does not include a
subject line.
Once you have entered the XML, dismiss the dialogs by clicking OK. To map the policy to a user or
user group, select the user or group from the User Groups List or All Users tabs of the BlackBerry
Manager, right-click, select Assign IT Policy, and select the policy from the drop-down menu. To
propagate changes immediately (rather than waiting for the default four-hour polling interval) right-
click the user or group and select Resend IT Policy.
To create a new IT policy rule on BES 5.x: In the BlackBerry Administration Service, on the
BlackBerry solution management menu, expand Policy, click Create an IT policy rule and enter
LM Handheld Policy Settings in the name field. In the type field, select Multiline String. In the
destination field, select either Handheld or Both. Type a description for the rule. This can be any
description you feel makes sense. Click Save.
Now the IT Policy must be edited to include the policy delivery XML for Liquid Machines Client for
BlackBerry. On the BlackBerry solution management menu, click Manage IT Policies. Click on the
IT Policy where you would like to apply the LM Handheld Policy Settings rule. Click Edit Policy.
Click the User defined tab. In the Value field of the LM Handheld Policy Settings rule paste the
policy delivery XML into the text field; the IT Policy delivery XML is constructed according to exactly
the same rules as the policy delivery email (Configuration Syntax on page A-2), with the exception
that the IT Policy XML does not include a subject line.
Once you have entered the XML click Save all.
Notes:
 Due to limitations of the BlackBerry Manager, when using an IT Policy push to propagate
policies, you cannot use template names that contain Unicode characters such as those
found in Greek, Chinese, Japanese, Korean, Russian, Arabic, Hebrew, etc.
 When a user is a member of a policy-propagating IT Policy push, that user cannot also
have policies propagated via the policy settings email. To switch a user to the email method
of policy propagation, first remove him or her from the LM Handheld Policy Settings IT
Policy push.
Built-In Do Not Forward Policy

Starting from version 7.1.1, the Gateway and Client for Blackberry includes a built-in policy named
Do Not Forward, which is similar to the corresponding option in Microsoft Outlook. This policy can
be applied from a smartphone using the same interface that is used for policies delivered to a
smartphone.

The Do Not Forward policy is not an RMS template, but instead it applies a dynamic set of rights
based on the recipients of the message. All recipients will receive rights to view and reply to the
message, but not to forward it to other users. The message sender will retain full rights to the
message.

Setting Client Application Permissions
The Liquid Machines Client for BlackBerry attachment viewer interacts with the native attachment
download mechanism by performing KeyStroke Injection. For security reasons, this is an
interaction that the RIM client operating system controls through specific permissions for each
installed application. In order to function properly, the Liquid Machines Client for BlackBerry
requires this permission to be granted.
Configuration on the Handheld

If you install the Liquid Machines Client for BlackBerry using the RIM Desktop Manager application,
you will need to manually set the application control permissions. Application Controls may be set
directly on the handheld, using the following procedure:
1. From the main menu, select: Options.
2. Select Advanced Options.
3. Select Applications.
4. Select Liquid Machines Client for BlackBerry.
5. Click the Context Menu button and select Edit Permissions.
6. Scroll down to Keystroke Injection and select Allow.
Central Configuration through the Application Control Policy

It is common for administrators to install the Liquid Machines Client for BlackBerry to all handheld
devices at once via the RIM BES Manager using an Over-the-Air deployment. When you deploy
in this manner, it is possible to specify Application Controls as part of the deployment. Please
consult the RIM administrative documentation for a full description of this procedure.

Accessing Client Diagnostic Functions
If you have direct physical access to a BlackBerry smartphone with the Liquid Machines Client for
BlackBerry installed, you can access certain functions that may be useful for diagnostic purposes.
Change the Scrubbing Frequency

Normally, the process that deletes expired unencrypted messages from the NVRAM of the
smartphone runs once every 24 hours. You can change the frequency:
1. On the main BlackBerry application menu, click the Liquid Machines icon.
2. Click About.
3. On the About screen, type the letters s and g in succession. An interface appears that
allows you to select the units of time, such as hours or minutes, and the number of units
(see Figure 5-1).
Figure 5-1: Select the Units of Time and the Number of Units
Make your selection and then click OK.

4. To have the process display a progress bar on top of the current BlackBerry smartphone
screen each time it runs, select the Show progress check box.

Enabling Diagnostic Logging
To enable diagnostic logging, follow these steps:
1. On the main BlackBerry application menu, click the Liquid Machines icon.
2. Click About.
3. Press one of four key sequences to affect logging behavior:
 To enable logging, press l and then press e (see Figure 5-2).
Figure 5-2: To Enable Logging, Press l (for Logging) and Then e (for Enable)
To disable logging, press l and then press d (see Figure 5-3).
Figure 5-3: To Disable Logging, Press l (for Logging) and Then d (for Disable)
 To get, or display, the log, press l and then press g.

 To clear the log of all entries, press l and then press c.

Appendix A: Gateway Configuration File
Syntax
This appendix provides the syntax of the Gateway Configuration File.

 Overview
 Sections
 Settings
 Variables

Overview
Behavior of the Gateway for BlackBerry, such as logging level, is controlled with the Gateway
Configuration file.
The file is located below the folder where the Gateway is installed. It can typically be found at
C:\Program Files\Liquid Machines\Gateway for BlackBerry\lmbesgateway-config.xml.
The file is written in the XML language. You can use Notepad or another text editor to make
changes to it. XML uses elements, delimited by angle brackets (<>). An element usually begins
with a start-tag (<enabled> in the first example below) and ends with an end-tag that begins with a
slash (</enabled>).
In the Configuration file, the tags surround settings (like false). Elements can include other
elements, as in the second example; we call the outer elements sections. Sections can be nested,
in which case we call the inner sections subsections.
You can use variables in the file: type in a certain string, and, when the Gateway Service runs, it
changes the string to a value particular to that computer. You can add comments to the file that the
Gateway Service will ignore when processing the file, so you can include information about your
company policies or your IT infrastructure. Enter a comment between , like this:

Example:
<enabled>false</enabled>
This setting controls how the Adapter handles messages. The enabled setting is opened, the value
false is put in, and then the setting is closed.
Example:
<logging>
<max-logfile-size>10 MB</max-logfile-size>
</logging>
This shows the tag max-logfile-size with a value of 10 MB, or 10 megabytes. It also shows
the tag embedded within the logging setting, or section.
Example:
<bind-addr>${system:host:ip-addr}</bind-addr>
This shows the setting bind-addr. A variable is used for the value. When the Gateway Service
starts, it changes the variable to the IPv4 address of the first Ethernet interface of this computer.
Extra whitespace can be included between elements and will be ignored. However, do not include
extra whitespace between the start and end tags that define a value (for example, a path).
To cause the Gateway Service to pick up changes you have made to the Configuration file, restart
the BlackBerry Controller service. If the service fails to start, check the Application Event log for an
error indicating a problem with the Configuration file, such as an invalid value or improper syntax.

Specifying Units of Time
Some settings require you to specify a time value as the number of milliseconds, seconds,
minutes, hours, or days. When configuring these settings, the following values are valid:
 infinite
 a number followed by one of the following time units:
 ms, mss
 sec, secs
 min, mins
 hr, hrs
 day, days
For example, the following setting would configure the Gateway to refresh its template cache every
30 minutes:
<template-refresh-frequency>30 min</template-refresh-frequency>
Sections
These are the main sections in the Configuration file:
 logging: Parameters that control how and where the Gateway logs diagnostic information.
 gateway-service: Parameters that control the behavior of the Gateway Service. Do not
change these settings without consulting Support.
 services: The name of the LDAP server to use.
 protection-config: Parameters that control how the Gateway Service protects and
unprotects content.
 reporting: Parameters that control the behaviors of application event logging.
 monitoring: Parameters that control monitoring statistics.
 adapters: Parameters that control behaviors of adapters that integrate Gateway
functionality into third-party applications.

Settings
Settings are grouped by section. For most settings, default values are in parentheses.
Some settings in the file are marked Do not change this without consulting Support. These settings
are not documented here.
logging settings
 root-dir: The location where the Adapter stores log files when verbose diagnostic
logging has been turned on. The default value is:
${system:dirs:common-app-data}\Liquid Machines\Gateway for BlackBerry\logs
 logfile-severity: Used to enable more verbose diagnostic logging. Do not change
this value except as directed by Liquid Machines Product Support.
 max-backup-logfile-count (2): The maximum number of old log files to keep around
before deleting the oldest. The minimum value is 0; the maximum value is 100 (inclusive). If
-1 is specified, old log files are not deleted.
 max-logfile-size (10 MB): The maximum size any log file is allowed to reach before
being rolled over to backup files. The minimum value is 100 KB; the maximum value is 1 TB
(inclusive).
 max-logfile-lifetime (1 day): The maximum amount of time any log file is allowed to
be used before being rolled over to backup files. The current remaining time is calculated
from the previous midnight. The minimum value is 1 hr; the maximum value is infinite
(inclusive). See Specifying Units of Time on page A-3.
gateway-service-settings
 data-dir (${system:dirs:common-app-data}\Liquid Machines\Gateway
for BlackBerry): Controls where the Gateway saves its private data.
netw orking subsettings

This section contains parameters that control how adapters communicate with the Gateway
Service.
 bind-addr (127.0.0.1): The IP address on which the Gateway listens for connections.
 bind-port (7888): The TCP port on which the Gateway listens for connections. The
minimum value is 1024 and the maximum value is 49151 (inclusive).
 request-limits: Configures the limits on how requests will be accepted and processed
by the gateway service.
 max-concurrent-requests (5): Configures the maximum number of requests
which will be executed simultaneously. Further requests will wait for processing until
earlier requests are complete. A value of 0 indicates no limit.
 max-request-wait-time (infinite): The maximum amount of time any given request
can wait for acceptance. Timeout will cause request to fail. The minimum value is 0 ms,
meaning requests always fail immediately when the concurrent limit is exceeded and
the maximum value is infinite.
 max-request-size (20 MB): Determines the largest request which will be accepted
for processing. The minimum value is 1 KB and the maximum value is 100 MB.

services settings
 ldap-server-name (${system:host:primary-domain-name}): The name of the
Active Directory domain controller to use to resolve groups into lists of users.
protection-config settings
unprotectable-server-suffix es subsettings
This section contains a list of domain suffixes to match against the name of the server that protects
a document or message to be unprotected. If a suffix matches, a failure to unprotect will be treated
as an error. If no suffix matches, a failure to unprotect will not be treated as an error. Matches are
not case-sensitive. An empty suffix or empty list will match anything; i.e., all domains will be treated
as local. For more information on how this variable affects the Gateway, see Foreign Protection
Checking with RMS on page A-11.
 unprotectable-server-suffix: Explicitly adds a domain suffix that the Gateway
should treat as local. The default list item, ${system:host:primary-domain-name},
includes the DNS domain of the Gateway machine.
 unprotect-attachments (true): Enables or disables unprotecting attachments on
messages going through Unprotect or Unprotect-for-Reprotect Gateways and Cleartext-
BCCs.
m s-rm s subsettings
 enabled (false): Enables or disables all RMS functionality.
 template-location (\\rms\Templates): If you will populate the Apply Policies
menu on the Client for BlackBerry (see Configuring the Apply Policies Menu on BlackBerry
Smartphones on page A-2), or if users will apply templates manually, then you must have
configured RMS templates that correspond and made them available to the Gateway. Place
the files on the BlackBerry Enterprise Server file system or a network share, and then set
this setting to the path where they are located. It must be a fully qualified local or UNC path.
You can use the same share location you have configured for other RMS-enabled
applications. For example:
<template-location>\\fileserver.acme.lan\shares\RMStemplates</template-
location>
<template-location>c:\UserFiles\RMStemplates</template-location>
 template-refresh-frequency (1 hr): Controls how often the Gateway updates its
template cache for new, modified, or deleted templates. The minimum value is 1 min, and
the maximum value is infinite. When set to infinite, the Gateway must be restarted
to force a cache update. See Specifying Units of Time on page A-3.
 licensing-servers-ad-forests: Allows specification of the Active Directory global
catalog servers to use when checking group membership while evaluating RMS rights. If
your RMS deployment includes only a single licensing server in a single Active Directory
forest, you can leave this entry blank. In a more complex multi-forest environment, each
entry should start with the host name of an RMS licensing server, followed by an equal sign
(=), followed by the name of the Active Directory forest name. For example:
rms.mydomain.com=myforestname.com

 max-cross-forest-requests (10): Specifies the maximal number of traversals
between different Active Directory forests which will be made in order to expand group
membership when evaluating RMS rights. In order to expand a group, the gateway will
make requests to different forests as necessary, but only the configured maximum number
of requests per group expansion
lm -ues subsettings
 enabled (false): Enables or disables all Universal Enforcement Services functionality,
which allows processing of content protected by Liquid Machines Document Control.
 policy-servers: Policy servers that should be contacted to obtain policy information.
Servers can be identified by host name or by URL, for example, <policy-
server>server.mydomain.com</policy-server>.
 forward-proxy-specification: Configures proxy information to be used when
communicating with Liquid Machines Document Control policy servers
 proxy-type (DIRECT): Configures the proxy type of proxy to use, whether it be
an auto-config proxy (AUTO-DETECT), a specified proxy server (TUNNEL), or no
proxy (DIRECT)
 proxy-server: Configures the proxy server to use when the proxy type is
TUNNEL
 try-direct-first (false): Controls whether a direct connection should be tried
before any attempts at using the proxy server
 allow-server-discovery (true): Enables the ability to contact new Liquid Machines
Document Control servers based on document contents.
 discovered-server-lifetime (60 min): Configures the time for which discovered
servers will be kept active (and polled) before they must be discovered again. See
Specifying Units of Time on page A-3.
 discovered-server-cleanup-period (5 min): Configures how often discovered
servers will be examined to see if they should be deactivated. See Specifying Units of Time
on page A-3.
reporting settings
 event-log severity (All): The minimum severity of events that are sent to an
Application Event log. Values are fatal, error, warning, info, and all.
 log-frequency-error (1 minute): The maximum frequency at which the same type of
error message can be reported in the Event log before multiple occurrences are batched in
a single entry, and how frequently such batches are reported. See Specifying Units of Time
on page A-3.
 log-frequency-warning (1 minute): The maximum frequency at which the same type of
warning message can be reported in the Event log before multiple occurrences are batched
in a single entry, and how frequently such batches are reported. See Specifying Units of
Time on page A-3.
 log-frequency-info (1 minute): The maximum frequency at which the same type of
info message can be reported in the Event log before multiple occurrences are batched in a

single entry, and how frequently such batches are reported. See Specifying Units of Time
on page A-3.

 batching-period (1 minute): How often the Gateway Service examines any pending
batches of log entries for reporting in the Event log. Batched log entries can be logged any
time after the time defined by their frequency has passed but are not examined for possible
logging unless another of the same event occurs or a batching period elapses. See
Specifying Units of Time on page A-3.
monitoring settings
 enabled (true): Enables or disables monitoring statistics.
netw orking subsettings

 bind-addr (127.0.0.1): The network address on which to listen for connections. Note:
127.0.0.1 makes this monitoring information available only through local-machine HTTP
requests. To enable this information to be available from clients other than on this machine,
change this to a specific IP address to which this machine is bound or '*' for any.
 bind-port (7888): The socket port on which to listen for connections. The minimum value
is 1024 and the maximum value is 49151 (inclusive).
 request-limits: Configures the limits on how requests will be accepted and processed
by the monitoring service.
 max-concurrent-requests (5): Configures the maximum number of requests
which will be executed simultaneously. Further requests will wait for processing until
earlier requests are complete. A value of 0 indicates no limit.
 max-request-wait-time (infinite): The maximum amount of time any given request
can wait for acceptance. Timeout will cause request to fail. The minimum value is 0 ms,
meaning requests always fail immediately when the concurrent limit is exceeded and
the maximum value is infinite.
 max-request-size (1 KB): Determines the largest request which will be accepted
for processing. The minimum value is 1 KB and the maximum value is 100 MB.

adapter settings
bes subsettings
 client-config: Configuration for interactions with the Liquid Machines Client for
BlackBerry.
 enable-blocked-recipients-ndrs (false): Enables or disables warning
messages sent back to senders when the gateway determines that a recipient does not
have rights to read a message which was forwarded. The recipient may still be able to
read the message if the email to which the message was sent is not the same as the
email by which they will authenticate to the RMS server. For instance, the message
may be sent to a group which is not granted rights, but individual members of the group
may still be granted rights.
 message-content: Configuration for protected email messages.
 encrypt-for-client (true): Enables encryption for content sent to the Liquid
Machines Client for BlackBerry.
 attachment-content: Configuration for protected email messages.
 encryption-config: Settings controlling the encryption and packaging of
attachment data.
 encrypt-for-client (true): Enables encryption for content sent to the Liquid
Machines Client for BlackBerry.
 max-download-size (100 KB): The largest encoded attachment which will be
downloaded to the device. This is limited by latency and user-experienced delays.
The minimum value is 1 KB and the maximum value is 1 MB (inclusive).
 rendering-config: Settings controlling the rendering of attachment contents for
secure viewing on the BlackBerry. Please note that if these settings are changed
after initial configuration, attachments to messages already present on the
BlackBerry device may no longer be viewable.
 max-image-width (320): The maximum pixel width of images rendered for
the BlackBerry. Set this value based on desired download latency, target user
screen size, and desired fidelity of graphics, particularly PowerPoint files. The
minimum value is 240 and the maximum value is 480 (inclusive).
 pdf-mode (text-only): Rendering mode to use for Adobe PDF and similar
documents. Legal values are text-only, page-images, and page-images-plus-
text.
 word-mode (text-with-images): Rendering mode to use for Microsoft Word and
similar documents. Legal values are text-only, and text-with-images.
 excel-mode (tables-with-images): Rendering mode to use for Microsoft Excel
and similar documents. Legal values are text-only, and tables-with-images.
 powerpoint-mode (slide-images-plus-text): Rendering mode to use for
Microsoft PowerPoint and similar documents. Legal values are text-only, and
slide-images, and slide-images-plus-text.
 visio-mode (page-images): Rendering mode to use for Microsoft Visio and
similar documents. Legal values are text-only, and page-images.

 other-doc-mode (default): Rendering mode to use for documents which do
not match any other configured type. Legal values are text-only, and default.
 fallback-to-text (true): Indicates whether rendering should use text-only
mode as a default if the configured rendering mode's output would exceed the
download size limit.
 license-archive: When a protected message is sent to a smartphone, the Gateway
must retain the license information necessary to reapply protection to any replies and
forwards of that message. This information is archived in a SQL Server database table.
The same database is also used to store data related to the count of active users in the
gateway, used for software licensing. This subsection determines where the Gateway
maintains its database.
 connection-string: The ODBC connection string that the Gateway should use to
establish a non-interactive connection to the database where archived licenses and active
user info should be stored. The connection string is a sequence of parameter clauses
separated by semicolons. For example, the value:
DRIVER={SQL Server};SERVER=localhost;DATABASE=lmbes;
Trusted_Connection=yes
defines a connection to a database named lmbes that is managed by an instance of SQL Server
running on the Gateway computer. The connection-string should be constructed using any of the
following parameter clauses, as appropriate for your environment.
 DRIVER: The ODBC driver used to establish a database connection. The default value
{SQL Server} should be suitable for your environment and should not be modified unless
you are explicitly asked to do so by Liquid Machines Customer Support.
 SERVER: The IP address or host name for your SQL Server. You may be required to specify
a fully qualified host name, including the domain name, depending on how DNS has been
configured in your network environment.
 DATABASE: The name of the database where the license archive should be stored. This
database must exist before starting the Gateway and must meet the requirements listed at
the beginning of this guide.
 Trusted_Connection:
 yes = The Gateway should connect to SQL Server as the BESAdmin using
Windows authentication.
 no or not present = The Gateway should connect to the database using SQL Server
authentication; the UID and PWD parameter clauses must be specified.
 UID: Indicates the SQL Server user ID that should be used to establish a
database connection.
 PWD: Indicates the password for the specified UID.
Because passwords are not encrypted in the configuration file, Liquid

Machines strongly discourages customers from configuring the Gateway to
use SQL Server authentication.
 scrubber-config: This subsection controls how often the Gateway examines the license
archive, looking for expired licenses that can be deleted.

 scrubber-frequency: How often the scrubbing process is executed, specified as a
number of seconds. The default value is 1 hr.

Variables
The following variables can be used in some configuration settings. To use one, enclose it in
braces {} and preface it with a dollar sign ($), like this:
${run:thread:id}
Place the variable in the Configuration file in the place where you want its value to be substituted.
 env: The value of any system environment variable; it is case insensitive on Windows. For
example ${env:HOMEDRIVE} yields the value of HOMEDRIVE, typically C.
 run:thread:id: The ID of the current thread.
 run:thread:name: The descriptive name of the current thread (if any).
 run:moment: The current moment in time.
 run:host:name: The current fully qualified DNS name of this host, for example,
rms1.acme.lan, as it is set at runtime.
 run:host:ip-addr: The current IPv4 address of the first Ethernet adapter on this host,
for example, 192.168.130.1, as it is set at runtime.
 system:dirs:cwd: The current working directory.
 system:dirs:temp: The current user's temp directory, typically:
C:\Documents and Settings\currentuser\Local Settings\Temp
 system:dirs:user: The current user's home directory, typically:
C:\Documents and Settings\currentuser
 system:dirs:common-app-data: The directory containing application data common to
all users, typically:
C:\Documents and Settings\All Users\Application Data
 system:dirs:user-app-data: The directory containing application data specific to the
current user, typically:
C:\Documents and Settings\currentuser\Application Data
 system:host:name: The fully qualified DNS name of this host, as it is set at system start.
 system:host:ip-addr: The IPv4 address of the first Ethernet adapter of this host, as it
is set at system start.
 system:host:primary-domain-name: The fully qualified DNS name of the domain
name of the first Ethernet adapter for this host, as it is set at runtime. For example, if this
hostname is rms1.acme.com, then the domain is acme.com.
 app:dirs:install: The installation directory for the application.
 app:logging:channel:severity: The string form of the severity of the diagnostic
logging statement.
 app:logging:channel:name: The unqualified name of the diagnostic logging channel
being used in the logging statement.

 app:logging:channel:scoped-name: The qualified name of the diagnostic logging
channel.
 app:logging:channel:scope: The qualifying portion of the scoped-name of a
diagnostic logging channel.
 app:logging:file:roll-index: The numeric index of the next log file to be cycled.

Appendix B: Application Event Log
Entries
This appendix provides a listing of application event log entries.

 Critical Errors
 Warnings
 Informational Messages
Liquid Machines, Inc. Page B-1

Critical Errors
Liquid Machines Adapter for BlackBerry initialization failed: An error occurred which
prevented the adapter from integrating with the BlackBerry Controller or BlackBerry Agents.
The message will contain more details on the specific failure which occurred. This may allow you
to resolve the issue. If not, contact Liquid Machines Product Support. You may also try to verify
that Exchange and the BlackBerry Enterprise Server are operating properly, and that the Gateway
configuration is in good order.
Liquid Machines Gateway for BlackBerry initialization failed: An error occurred which
prevented the gateway from starting. The BlackBerry Controller will also be unable to start.
The message will contain more details on the specific failure which occurred. This may allow you to
resolve the issue. If not, contact Liquid Machines Product Support. You may also try to verify that
Exchange and the BlackBerry Enterprise Server are operating properly, and that the Gateway
Liquid Machines Gateway for BlackBerry disabled due to failure: An error occurred which
prevented the gateway from starting, but the BlackBerry Controller was started with protection
functionality disabled.
The message will contain more details on the specific failure which occurred. This may allow you to
resolve the issue. If not, contact Liquid Machines Product Support. You may also try to verify that
Exchange and the BlackBerry Enterprise Server are operating properly, and that the Gateway
Adapter encountered an unexpected exception: An error has occurred, but the Gateway service
has recovered from it. The reason for the error is unknown.
Contact Liquid Machines Product Support. You may also try to verify that Exchange and the
BlackBerry Enterprise Server are operating properly, and that the Gateway configuration is in good
order.
Failed to initialize Microsoft RMS: The Gateway for BlackBerry is unable to start up its profile for
interacting with RMS.
When this event occurs, any attempt the Gateway for BlackBerry makes to protect or unprotect
RMS messages will fail (and log the events listed just above and below this one). You must
remedy the situation and restart the BlackBerry Controller Service in order to fully resolve this
issue.
Verify that your RMS infrastructure is working correctly. From an RMS and Office 2003 or Office
2007 workstation, log on as the service account under which the BlackBerry Controller Service
runs and see if you can create and send a protected email. Verify that someone else can read it.
Failed to protect a message: The Gateway was unable to encrypt a message. Protection can fail
for a variety of reasons.
You may want to follow the procedures for “Failed to initialize Microsoft RMS,” above.
Failed to unprotect a message: The Gateway was unable to decrypt a message. Protection can
fail for a variety of reasons. For example, the message may have been generated by a foreign
RMS installation.
Failed to reprotect a message: The Gateway was unable to reprotect a message. Protection can
fail for a variety of reasons.

Cancelled attempt to save unprotected message: The BlackBerry Enterprise Server attempted
to take an unprotected copy of a message out of memory and save it to the user’s Exchange
mailbox. The Gateway prevented this operation from completing.
This is an extremely rare occurrence. If you encounter this error, contact Liquid Machines Product
Support.
Attachment could not be extracted from protected message: An unprotected attachment
housed inside an RMS-protected message has been requested for download to a BlackBerry
smartphone. However, the request has failed, most likely because the RMS infrastructure is not
responding.
Failed to unprotect a document: The Gateway was unable to decrypt an attachment. Protection
can fail for a variety of reasons. For example, the document may have been protected by a foreign
RMS installation.
Failed to initialize protection environment: The generic protection features failed to initialize.
Preceding events describe the status of each protection type.
Failed to initialize Liquid Machines Policies and Keys (Universal Enforcement Services):
Liquid Machines Document Control was enabled and failed to initialize.
Failed to update data for a Liquid Machines Policy Server: A download or an upload failed for a
server.
Failed to start BES proxy: The Gateway was unable to integrate with the BlackBerry Enterprise
Server process.
Failed to register active user: The Gateway was unable to register the active user in the
Gateway Database during unprotection of a protected message or attachment while sending it to a
handheld device. If this occurs, the unprotection operation will be treated as a failed operation.
If you encounter this error, contact Liquid Machines Product Support.
Warnings
Message delivered but not processed: This is logged under the following conditions:
 Policy indicates the message should be blocked. For example, an Outlook user sends a
message to a smartphone user who does not have View rights. The smartphone user
receives a message indicating they did not have rights to read the original content, and the
Gateway logs this message to the Event log.
 Protection policy information not available. The information necessary to protect replies to
and forwards of this message, which is being sent from the smartphone, is not available.
The smartphone user receives an NDR indicating the problem, and the Gateway logs this
message to the Event log.
 Cannot identify message. The information necessary to protect replies to and forwards of
this message, which is being sent from the smartphone, is not available. The smartphone
user receives an NDR indicating the problem, and the Gateway logs this message to the
Event log.

Policy override request ignored: When creating a reply to or forward of a protected message, a
smartphone user has attempted to override the original policy by adding controls to the reply or
forward. The user's request is ignored, and this message is logged.
Message delivery blocked: A smartphone user has attempted to reply to, reply to all, or forward a
message that has controls on it that prevent these operations for this user. The smartphone user
receives an NDR indicating the restriction, and the Gateway logs this message to the Event log.
Protected message is too large to unprotect: A protected email message was not unprotected
for delivery to the smartphone because it is larger than the configured maximum size. For more
information, see Configuring Systematic Throttling on page A-3.

Informational Messages
Liquid Machines Adapter for BlackBerry has been initialized: The Gateway has successfully
integrated with the BlackBerry Enterprise Server process in order to process messages.
You may see several of these messages occur, once for each time the BlackBerry Enterprise
Server starts a new agent to handle increased traffic. For more information on agents and
scalability in the BlackBerry Enterprise Server, see your BlackBerry Enterprise Server
documentation.
Liquid Machines Adapter for BlackBerry has been deinitialized: The Gateway has terminated
integration with the BlackBerry Enterprise Server process.
Started BES Service Proxy: The Gateway has initiated integration with the BlackBerry Enterprise
Server process.
Shutdown BES Service Proxy: The Gateway has initiated termination of the BlackBerry
Enterprise Server process.
Liquid Machines Gateway for Blackberry has been initialized: The Gateway service has
started successfully. It may still be working to integrate with the BlackBerry Enterprise Server.
Liquid Machines Gateway for Blackberry has been deinitialized: The Gateway has stopped
gracefully.
Microsoft RMS session initialized: The Gateway has successfully initialized the profile it uses to
connect with your RMS infrastructure.
Liquid Machines Policies and Keys (Universal Enforcement Services) initialized: Liquid
Machines Document Control was successfully enabled and initialized.
Protection Environment Initialized: All configured protection features have been initialized.
Generic features were successful; preceding events describe the status of each protection type.
Successfully updated data for a Liquid Machines Policy Server: A poll to a Liquid Machines
Document Control server has completed successfully.
Failed to unprotect a message from external server: A message unprotection failed on content
that came from a server that is not determined to be local.
Failed to unprotect a document from external server: A message unprotection failed on content
that came from a server that is not determined to be local.
Attachment is too large to examine for protection: An attachment was not processed during
delivery to the smartphone because it was over the configured limit (see Configuring Systematic
Throttling on page A-3). As a result the adapter could not determine whether the attachment was
protected, so this message may be displayed for large attachments, even if they are not protected.

Appendix C: Adding RMS Servers to the
Local Intranet Sites
This appendix describes how to add RMS Servers to the local intranet sites.
To add RMS Servers to the local intranet sites:
1. Log on to the Gateway for BlackBerry computer as the BESAdmin account.
2. In Internet Explorer, on the Tools menu, click Internet Options.
3. In the Internet Options dialog box, click the Security tab (see Figure C-1).
Figure C-1: Security Tab on the Internet Options Dialog Box
Liquid Machines, Inc. Page C-1

4. On the Security tab, click Local intranet, and then click Sites (see Figure C-2).
Figure C-2: Select Local Intranet and Sites
5. On the Local Intranet dialog box, click Advanced.

6. In the Add this web site to the zone field, enter the common name of the RMS server, for
example, rms1.fkolabs.com. Then click Add (see Figure C-3).
Figure C-3: Select Advanced on the Local Intranet Dialog Box
7. Click OK to close all dialog boxes.
Liquid Machines, Inc. Page C-2

Index
contacting
A Liquid Machines, ii
conventions, vii
access control list (ACL), 1-8 copyright, ii
access licenses credentials, 1-8
issuing, 1-8
ACL (access control list), 1-8
Acrobat, 1-10 D
Active Directory, 1-8
data-dir, A-4
adapter settings, A-8
discovered-server-cleanup-period, A-6
adapters, A-3
discovered-server-lifetime, A-6
Ad-Hoc permissions, 1-10
documents
administering the Gateway Server, 3-1
related, viii
Adobe Acrobat, 1-10
Adobe Reader, 1-10
allow-server-discovery, A-6 E
app
enabled, A-5, A-6, A-7
logging
channel encryption keys, 1-8
name, A-10 env, A-10
event-log severity, A-6
scope, A-11
scoped-name, A-11
severity, A-10 F
file foreign content, 1-13
roll-index, A-11
app:dirs:install, A-10
audience, vii G
auditing, 1-12 gateway-service, A-3
authenticating users, 1-8
B I
Information Rights Management, 1-8
batching-period, A-7 IRM, 1-8
bes subsettings, A-8 issuing access licenses, 1-8
bind-addr, A-4, A-7
bind-port, A-4
bind-port, A-7 L
book conventions, vii ldap-server-name, A-5
license-archive, A-9
C licenses
issuing, 1-8
client Liquid Machines
Liquid Machines Document Control, 1-10 contacting, ii
RMS, 1-8 Liquid Machines Document Control, 1-11, 1-12
comments Liquid Machines Document Control Client, 1-10
Configuration file, A-2 Liquid Machines Document Control Server, 1-10
connection-string, A-9 Liquid Machines Key Service, 1-10
Liquid Machines, Inc. Index-1

LMKS, 1-10 root-dir, A-4
lm-ues subsettings, A-6 run:host:ip-addr, A-10
log-frequency-error, A-6 run:host:name, A-10
log-frequency-info, A-6 run:moment, A-10
log-frequency-warning, A-6 run:thread:id, A-10
logging, A-3 run:thread:name, A-10
logging settings, A-4
S
M
scrubber-config, A-9
max-backup-logfile-count, A-4 scrubber-frequency, A-9
max-logfile-lifetime, A-4 sections
max-logfile-size, A-4 Configuration file, A-2, A-3
Microsoft Office, 1-10 server
Microsoft Office 2000, 1-10 Liquid Machines Document Control, 1-10
Microsoft Office 2003 Professional, 1-10 RMS, 1-8
Microsoft Office 2007 Professional, 1-10 services, A-3
Microsoft Office XP, 1-10 services settings, A-5
Microsoft Visio, 1-10 settings
Microsoft Windows Rights Management Services Configuration file, A-2, A-4
(RMS), 1-11 subsections
monitoring, A-3 Configuration file, A-2
monitoring settings, A-7 Super Users, 1-10
ms-rms subsettings, A-5 system:dirs:common-app-data, A-10
system:dirs:cwd, A-10
O system:dirs:temp, A-10
system:dirs:user, A-10
Office 2000, 1-10 system:dirs:user-app-data, A-10
Office 2003 Professional, 1-10 system:host:ip-addr, A-10
Office 2007 Professional, 1-10 system:host:name, A-10
Office XP, 1-10 system:host:primary-domain-name, A-10
P T
policies, 1-10 template-location, A-5
policy-servers, A-6 template-refresh-frequency, A-5
protection-config, A-3
protection-config settings, A-5
U
R unprotectable-server-suffix, A-5
unprotecting, 1-11
Reader, 1-10 users
related documents, viii authenticating, 1-8
reporting, A-3
reporting settings, A-6
RMS, 1-10, 1-11 V
RMS client, 1-8 variables
RMS server, 1-8 Configuration file, A-2, A-10
RMS Super Users, 1-10 Visio, 1-10
RMS template, 1-10
RMS)
Liquid Machines, Inc. Index-2

GatewayforBlackberry 7 2 AdministratorsGuide

Uploaded by

Document Information

Original Description:

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

GatewayforBlackberry 7 2 AdministratorsGuide

Uploaded by

Copyright:

Available Formats

Liquid Machines

Gateway for BlackBerry

Liquid Machines, Inc.

How to Contact Liquid Machines, Inc.

Liquid Machines, Inc. Page ii

Liquid Machines, Inc. Page iii

Liquid Machines, Inc. Page iv

Liquid Machines, Inc. Page v

This guide also uses the following typographical conventions:

>> For more information, see Intended Audience on page vii.

Liquid Machines, Inc. Page vii

Using this Manual

Liquid Machines, Inc. Page viii

This chapter introduces the Liquid Machines Gateway for BlackBerry.

Liquid Machines, Inc. Page A-1

About the Liquid Machines Gateway for BlackBerry

Liquid Machines, Inc. Page A-2

Protected Email Messages

Copy and Paste

Liquid Machines, Inc. Page A-3

Secure Delivery of P rotected Attachm ents

Unencrypted Delivery of P rotected Attachm ents

Secure Attachment Rendering

Secure Attachment Viewing

Saving Protected Attachments

Forwarding Protected Messages via Email, PIN and SMS

Liquid Machines, Inc. Page A-4

International Character Set Support

Liquid Machines, Inc. Page A-5

Liquid Machines, Inc. Page A-6

Liquid Machines, Inc. Page A-7

I nform ation Rights M anagem ent

RM S Server: I ssuing Access Licenses and Authenticating Users

RM S Client: Enabling Applications to Com m unicate w ith the R M S Server

Liquid Machines, Inc. Page A-8

RM S I nstallations and Trusts

Liquid Machines, Inc. Page A-9

Liquid M achines Docum ent Control Enforcem ent Agents: P rotecting

Liquid Machines, Inc. Page A-10

Foreign P rotection Checking w ith R M S

Liquid Machines, Inc. Page A-11

Liquid Machines Document Control

Liquid M achines Docum ent Control Operation w ith R M S Disabled

Liquid Machines, Inc. Page A-12

Liquid Machines, Inc. Page A-13

Rights Management Services (RMS)

BlackBerry Enterprise Server for Exchange

Gateway for BlackBerry: Processing Messages as They Pass

Liquid Machines, Inc. Page A-14

Liquid Machines Client for BlackBerry: User Interface, Smartphone

Liquid Machines, Inc. Page A-15

Priority of Protection Requests

Message Controls Prevent Sending

M essages to Unauthorized Recipients

RM S R eply and Forw ard P rivileges

Liquid Machines, Inc. Page A-16

Liquid Machines, Inc. Page A-17

Liquid Machines, Inc. Page A-1

Important Information About Upgrading From

Liquid Machines, Inc. Page A-2

Liquid Machines, Inc. Page A-3

Installing the Liquid Machines Gateway for BlackBerry