Introduction

IBM Lotus Notes Release 8.5.1 brings XPages technology to the Notes Client so developers can create rich internet applications that now run in both a Web Browser and in the Notes Client.

XPages applications are highly programmable and almost every user interface component has some computable aspect that can be programmed via JavaScript and Java code. Users need to be protected against this code or "active content" - active content refers to anything that can be executed on a user workstation and includes formulas, scripts, agents, actions, buttons, and executable code, etc.

To protect users when running XPages applications in the Notes Client, XPages integrates with the existing Notes Client security model of Execution Control Lists (ECLs) to control what operations applications are allowed perform on a users workstation. When an XPages application executes a protected operation - for example, access the current database or file I/O - the user will be presented with an Execution Security Alert (ESAs) to inform them which operation the application is attempting to perform and gives the user the opportunity to either allow or prevent the operation from executing. Integrating XPages with this security model provides a familiar user experience for Notes Client users that should already be understood. See the Background section below for more information on ECLs.

Note: Whether it is an XPages application or some other application, it is never a good idea to run executable code on your workstation that does not come from a source you can trust. If you downloaded an NSF from the internet, open up and examine the code the code in Domino Designer. If you don't trust the signer, and you cannot view the code, think again about whether should run this application on your workstation.

There are a number of important aspects to security for XPages in the Notes Client and these can be categorized under two broad areas :

1. the XPages Notes Client embedded Browser that renders the XPages application (this can be considered the 'Client Side') and
2. the XPages Runtime that generates the components that make up an XPages application and that executes any computed properties or embedded code (this can be considered the 'Server Side').

While this article will focus on the XPages Runtime and its integration with the existing Notes Client ECL security model there are several other important aspects of security for XPages in the Notes Client that developers and users should be aware of and the reader is directed to see Client Side Security in the Background section below for more details.

The following sections will be covered in this article:

• Introduction
• Background
• XPages Client Side Security
• Signatures and Signers
• Execution Control Lists
• Execution Security Alerts
• XPages and Notes Client ECL
• Overview
• Back-end Classes
• Custom Java Code
• How it Works for XPages
• Protected Operations
• Managing the user Execution Control List
• Developer Information
• Administration Information
• Limitations and Restrictions
• Summary
• Resources

Background

This section provide some additional information on the following topics :

• XPages Client Side Security
• Signatures and Signers
• Execution Control Lists
• Execution Security Alerts

XPages Client Side Security

XPages in the Notes Client provides the following security features:

• each XPages embedded browser is associated with just one XPages application database and cannot switch, for example, by opening a URL to a different XPages application on the Notes Client
• to guard against the embedded browser executing 'client-side' malicious code in the JVM, a "white list" of acceptable messages is defined that can be passed between the browser and XPages for XPages to execute on the browser's behalf. These functions provide Eclipse SWT functionality to improve the XPages in the Notes Client user experience. The first three functions take two parameters, the title for the dialog box and the text to appear in the dialog box. The fourth message takes 4 parameters that are required for property broker: name, value, type and viewID.
• XSP.alert
• XSP.error
• XSP.confirm
• XSP.publishEvent (note that this capability is also controlled by Notes Client ECL - see below)
• running an XPages as a Composite Application will generates an Exception Security Alerts to notify the user that the ability to read from and write to Property Broker will be required by the XPages application and is controlled by the Notes Client ECL
• remote external browsers can not connect to the Web Container running the XPages application
• Active Content Filtering (ACF) is available for developers to remove possibly malicious active content( scripts, tags ) in an input/output text control. An ACF engine is a library that performs the filtering during run time. For example, opening a text field in an XPage in Domino Designer in Eclipse( DDE) will reveal two properties, “htmlFilter” and “htmlFilterIn”, in the “All properties” category. The “htmlFilter” property defines the ACF engine to use when the control sends data to the client, and the “htmlFilterIn” property defines the engine to use when the control receives text from the client. These two properties can be changed to enable/disable ACF for that text field.
• In addition, a System Administrator or lead developer can configure default global ACF settings for Rich Text items at the Server or NSF level by adding the following two lines to the xsp.properties file (which is located in the /data/properties directory)
• xsp.richtext.default.htmlfilter=acf
• xsp.richtext.default.htmlfilterin=

Signatures and Signers

One of the key strengths of Lotus Notes and Domino is the ability to create a digital signatures to identify a particular user and then control access to applications data and the ability to perform certain operation based on that signature. Notes and Domino use ID files to identify users. When a user is registered, the Notes ID file is created and this ID file typically contains the users name - the owner of the ID, a Lotus Notes certificate to verify that the name of the owner of the ID is correctly associated with a specific public key, and a private key to sign messages, encrypt data, and sign design elements.

Design elements are the building block of a Notes Domino application. For example the forms, views, scripts, agents, XPages, etc., that are created by developers as part of an application are called design elements. In Domino Designer, when a when new design element is created, or if an existing design element is modified, the signature of the creator (or the user to last modify) and a checksum is stored with the design element. The signature used is the one owned by user who is currently logged into Designer doing the creating or modifying. That user, or owner of the signature, is generally referred to as the Signer.

The signature is also used to prevent unauthorized changes of design elements. Typically, modifying design elements happens though Designer but design elements can also be modified programmatically. Changes to a design element would result in a different checksum being calculated and therefore invalidates the signature. In this scenario a call to programmatically sign the design element should be made and will use the ID, or signature, for the user that is logged into the Note session.

Design elements in a Notes application that can execute code on a users workstation will have a signer associated with them. The XPages runtime retrieves all the signers for an XPages application and will check with the Notes Client Execution Control Lists (ECL) to determine if the user has granted the signer permission to execute certain operations. See the following section for more details on ECL.

Execution Control Lists

Execution Control Lists (ECL) are designed to protect a users workstation against executable code from unknown sources. ECLs list trusted authors of active content. The author (also known as the signer or the signature) is the ID of the user who created or last modified a particular design element (e.g forms, views, XPages, formulas, scripts, agents, etc.). In order for active content to be trusted, and thereby allowed run on the workstation, the signer must be listed in the ECL and also be allowed access to, or have the ability to perform, the particular operation for which permission is being requested. For example, in Figure 1 below, the user has listed the signer "Trusted User" as being trusted, but only for access to the file system and not to perform any other operations.

A users ECL can be found by selecting, File -> Security -> User Security..., expanding the What Others Do tab and selecting the Using Workstation section (this permissions in this section apply to Agents and XPages).

For each signer listed in the ECL, workstation security settings - "Allow access to:" and "Allow ability to:" - can be enabled to grant the signer access to specific protected operations by selecting the appropriate check box.

When an XPages application is running and code attempts to execute a protected operation the ECL determines if the signer is allowed perform the operation on the users workstation. If the signer is allowed, then execution continues, otherwise the user will be presented with a dialog box, an Execution Security Alert (ESA). The ESA provide two functions,

1. inform the user that the application running on the workstation is attempting to execute a protected operation and
2. allow the user the opportunity to either trust the signer to perform the operation (and have execution continue) or not to trust the signer and prevent execution.

The next section will explain more about Execution Security Alerts.

Execution Security Alerts

Execution Secuity Alerts go hand in hand with the Execution Control List - they provide run-time interaction with the user for ECL checking. If the user has been granted all the necessary permissions for an XPages application then the user will never see the ESA. For example when a developer creates an XPages application and runs it they will not see any ESAs because, by default, a user is allowed access to all operations and has the ability to perform all functions on their own workstation. As described above, when an XPages application code attempts to perform an operation for which the signer of the code does not have the permission to perform - the user will be presented with an Execution Security Alert. See Figure 2 below.

The user will have a number or options in how they wish to respond to the ESA:

• If the user selects "Do NOT execute the action" then execution of the operation will be cancelled.
• If the user selects "Execute this action this one time" then the operation is permitted and execution continues as normal. If the code attempts to execute the same operation again the user will again be presented with an ESA.
• If the user selects "Start trusting the signer to execute this action" the signer will be added to the ECL and the appropriate permission will be granted for the operation that is being attempted and any subsequent attempt to execute this specific operation will succeed automatically.
• If the user selects "Trust the signer to execute this action for this Notes session" then the operation is permitted to execute and execution continues as normal. If the code attempts to execute the same operation again in a subsequent request then the user will again be presented with an ESA.
• Note For XPages in the Notes Client that the option "Trust the signer to execute this action for this Notes session" is limited compared to standard Notes Client applications - it is only effective for the current request, e.g. button click or link selection (XPages in the Notes Client is essentially a web application). Should the user retry the operation they will find that they will be presented with an Execution Security Alert again. See Limitation and Restrictions section for more details.

XPages and Notes Client ECL

Overview

The code sections in an XPages application that can execute security sensitive operations are typically the Back-end Classes/formulas and custom Java code. Being part of the Notes Domino technology stack, the back-end Classes security checks are directly tied to the Notes Client ECL. However, custom Java code and the standard Java API libraries know nothing about the Notes Client ECL. What it does know about is the Java Security Manager. XPages uses a custom Java Security Manager to determine when custom Java code is executing a security sensitive operations and then routes the permission check to the Note Client ECL that will verify if the signers of the XPages application have the permission to perform the operation.
Java Security Activation for XPages
XPages in the Notes Client is a web-based application that runs on a local web container. Launching an XPages application, clicking on links and buttons while an XPages application is running is essentially sending an HTTP request to the web server which in turn passes them to the XPages Servlet runtime that process the request and provides that repsonse to the browser. Each

Back-end Classes

XPages can be viewed as having a 'design-time' side and a 'run-time' side. The design-time side is experienced through Domino Designer in Eclipse (DDE) when creating an XPages application and the run-time is experienced when an XPages application runs in the Notes Client. The DDE design-time experience makes it easy to create XPages applications by dragging and dropping user interface controls onto an XPages design area and by selecting built-in simple actions from drop down menus to tie the various controls and data sources together to create a useful application with little or no programming.

The XPages run-time is a Java-based web application development framework for Notes and Domino applications. Within an NSF, an actual XPage is saved and compiled into a Java class and this Java class leverages the XPages Runtime (along with the supporting Web Container) to present the application to the user. To deliver the functionality of an XPages application created at design-time, the XPages run-time framework utilizes the Notes and Domino Java APIs for the back-end classes to access various components of the Domino Object Model that represent the underlying application database components (for example, its documents and views).

Back-end classes and their methods are affected by the Execution Control List (ECL). The properties belonging to these classes cannot be accessed or set, and their methods do not execute on the users workstation, unless the appropriate ECL privileges have been granted to the signer. For a link to more details, see the Properties and methods with ECL security entry in the Resources sections below. When a back-end class is about to execute a protected operation it will check with the ECL if the signer of the XPages application is permitted to perform the operation - if not, the ECL check will present the user with an Execution Security Alert (ESA).

For example, an XPages application has a submit button that executes a simple action to open a new page, and that new page has a document data source, for a data entry form, that by default creates a new document, then this will trigger a number of ESAs for the various backend operations required to complete the task. See Figure 3 below.

Custom Java Code

An XPages application developer can also add their own Java code an XPages application and there several ways in which this can be achieved.

• XPages - which are XML as source but are distributed in an NSF as compiled Java classes. An XPage can contain Computed Fields, properties of controls (Computed Values), or Simple Actions, that use JavaScript as the programming language to perform a computation dynamically. A developer can embedded Java code in the JavaScript to make calls to the standards Java API libraries and also reference Java classes from other sources (see below).
• JARs - XPages developers can add their own, or third-party, JARs to an XPages application NSF (stored under WEB-INF/ folder) and reference these classes from XPages JavaScript through embedded Java statements.
• Java Classes - XPages developers can add their own Java classes to an XPages application NSF (contained under the WEB-INF/classes) and reference them from XPages code.
• Server-side JavaScript Libraries - A JavaScript library allows a developer to store classes, functions, and variables as a resource for common use within an application. A JavaScript library is either a Client JavaScript Library or a Server JavaScript Library. Server-side JavaScript is the only option for formulas and actions in XPages only a server-side JavaScript can include references to Java code statements.

For example, see Figure 4 below.

How it Works for XPages

XPages applications are Java based. When an XPages application executes, the XPages class loader (the XPages classloader is a SecureClassLoader that assigns Protection Domain to classes, see Java2 Platform Security Architecture link in Resources section below for more details) finds and loads all the requested Java artifacts from within the NSF. The interesting artifacts typically include, the actual XPages, any imported JARs and Java Classes, and Server-side JavaScript libraries. All the JARs for the XPages Run-time and supporting Web Container and Eclipse Framework are signed by IBM and trusted by the Java Security Manager - however, the custom Java classes, including the classes for XPages, in an NSF are not and will trigger the Java Security manager to perform an ECL check when any of these classes try to execute a protected operation.

As each artifact is loaded, including the top level XPage, the XPages classloader will extract the the name of the creator, or last 'modified by' signer name, of the design element, create a security context for each one, add them to a list - the ECL context handle - and finally save the ECL context handle to the Notes Session. Although JavaScript libraries are not loaded though a class loader XPages will create a security context for the JavaScript library being loaded and will appended to the ECL context handle. Note that JavaScript code, and ultimately any embedded Java code, is executed within the protection domain of the XPages class.

At run time, when a protected operation is to be performed by an XPages application, the list of security contexts and the operation that is to be performed is passed to the Notes Client ECL to determine if the operation should be allowed. When formulas are executed via the back-end classes the context handle is pushed from the Back-end Class Session into the formula context, this enables formula ECL checking with the correct context.

When a protected operation is called from the backend classes - the Compute Engine and the @Formula classes - the current operation directly checks with the Notes Client ECL that the operation is permitted to be executed for all the Security Contexts that have been created for the XPages application.

Note: What this means is that if two different names are signers for code artifacts in an XPages application then both signers must be granted the appropriate access or ability for the operation to complete successfully.

When a protected operation is called from custom Java code, the Java Security Manager is asked to check the permission. The Java permission is mapped to an ECL code and XPages calls helper backend classes to check the Notes Client ECL with the permission to check and the list of security contexts saved in the ECL context handle. The helper backend classes then check the Notes Client ECL to see if the code signers are allowed perform the operation.

Note: The XPages Java Security Manager permission checking is only active if the executing thread is an XPages thread.

Protected Operations

For details on protected operation in the Notes Domino back-end classes see the link under "Properties and methods with ECL security" in the Resource section below.

For custom Java code in an XPages application, either embedded in server-side JavaScript or imported as a Java class, the XPages Java Security Manager is quite restrictive in what permissions for security sensitive operations it allows. Essentially, all security sensitive Java operations are prevented except for those governed by the three Java permissions listed below which cover access to the Java system properties (e.g. System.getProperty("java.home")), File I/O, and Network I/O.

For these three permisisons, the ability for the user to grant access to the signer is possible, for all others it is not possible, even if the user does trust the signer. For example, the Java statement

java.lang.System.exit(-1);

would require the Java permisison

RuntimePermission("exitVM")

which is not allowed and can not be granted by the user to the code signer via the Notes Client ECL.

Managing the user Execution Control List

As explained in the Background - Execution Control Lists section above, the Execution Control List (ECL) maintains a list of names (signers) and the operations they are allowed to perform. XPages uses the access right granted under the "Using Workstation" tab for User Security to grant or deny access to protected operations to signers of XPages applications.

All the access rights apply to the back-end classes but only the three access right highlighted in figure 5 apply to custom Java code.

Note: XPages uses the same ECL as Java Agents - any access or ability granted to a signer of Agents will be granted to the same signer of an XPages application, and vice versa.

Developer Information

This section provides some information that may be useful for XPages developers building applications to run on the Notes Client.

It contains the following:

• Handling java.lang.SecurityException
• Dependant APIs

Handling java.lang.SecurityException

If some custom Java code in an XPages application attempts to execute a protected operation and the user selects "Do NOT execute the action" when presented with a Execution Security Alert then the XPages Java Security Manager will throw a Java run time exception, java.lang.SecurityException.

throw new SecurityException("ECL Permission Denied");

As this is a run time exception it is not necessary to catch this specific exception, however, if it remains unhandled, it can make it to the Web Container running the XPages application and result in a unexpected runtime error.

The SecurityException can be caught in the JavaScript code for better error handling. For example this sample piece tries to display the values of the "java.home" system property and will catch the SecurityException and display the message "ECL Permission Denied", which can be replaced with something more user friendly.

var javahome = "";
var errmsg = "Excetpion: ";
var outbox = getComponent("javahomebox");
try {
javahome = java.lang.System.getProperty("java.home");
outbox.setValue(javahome);
} catch (e){
outbox.setValue(errmsg + e.getMessage());
}

Listing 1: JavaScript with embedded Java call to static method

Other times, depending on the code to be executed (i.e. calling a static method versus creating a new Java object ) the actual exception caught in the JavaScript exception block may not be a SecurityException, but could be a Java reflection exception returned by the the XPages run time framework, and the root cause, the SecurityException, is further down in the exception chain.

For example, the following code will try to open a network connection and the chained exception could be the SecurityException("ECL Permission Denied") or some other expected exception, such as UnknownHostException (in this case the actual exception name is more informative that then exception message that just contains the host name).

var h = getComponent("networkhost").getValue();
var p = getComponent("networkport").getValue();

var errmsg = "Exception: ";
var statuscomp = getComponent("networkstatus");

try {

var s:java.net.Socket = new java.net.Socket(h, parseInt(p));
if (s != null) {s.close(); }
statuscomp.setValue("OK: ");

} catch (e) {
var msg = e.getMessage();
if (msg == null){
var e2 = e.getCause();
msg = e2.getMessage();
for UnknownHostException msg==hostname, exception name more informative in this case.
if (msg == null || msg.equalsIgnoreCase(h)){
msg = e2.getClass().getName();
}
}
statuscomp.setValue(errmsg + msg);
}

Listing 2: JavaScript with embedded Java to create a new Socket object.

Dependant APIs

When developing custom Java code that will execute as part of an XPages application ,the code should just depend on the standard Java and Notes Domino APIs, and custom JARs and classes imported into the NSF. Access to any other APIs such as the Eclipse Platform APIs may not be available.

Debugging ECL Permission Denied

If an XPages application displays the "Unexpected runtime error" error page when running in the Notes Client and the Exception section indicates that the error is "ECL Permission Denied" then turn on tracing to help diagnose the reasons the XPages security manager is throwing the exception .

In the \Data\workspace\.config\rcpinstall.properties file, add the following line,

com.ibm.xsp.adapter.notescontext.level=FINEST

Exit the Notes Client and rerun the XPages application that produces the ECL Permisison Denied error. Then view the Notes Trace file by going to the main menu and selecting,

Open Help->Support->View Trace

In this file there will be additional logging informaiton related to the XPages Security Manager. There should be a line similar to this,

NotesContext checkEcl: No permission for (java.lang.RuntimePermission getClassLoader)

this identifies that specific Java permission that was denied. In this case, java.lang.RuntimePermission is not one of the three Java permisison classes managed by the XPages ECL and is denied as malicious code that had access to a class's class loader could allow it to load other classes, available to that class loader, that would not normally not be accessible by that code.

However, it is possible to work around this by doing either of the following,

1. add the permission identified in the trace file to the XPages java.policy file or
2. move the code that requires the permission to a trusted location, jvm/lib/ext, mark the code as privileged, and then call it from the untrusted XPage.

See the Administration Information section below for more details on modifying the java.policy file and putting code in the jvm/lib/ext directory.

Adminstration Information

This section provide some information that may be useful for XPages developers, users and system administrators building, using and supporting XPages in the Notes Client applications.

It contains the following:

• java.policy
• jvm/lib/ext

java.policy

The XPages Java Security Manager uses java Policy files to specify which permissions are available for code from various sources that are trusted in the XPages environment.

There is by default a single system-wide policy file,

${java.home}/lib/security/java.policy

then additional permissions are added from from the file

${notes.home}/java.policy

which is specified during Standard Notes Client startup via the command line parameter java.policy=${notes.home}/java.policy.

The set of permissions is a combination of both these files. Note: Users should not modify these files without guidance from the system administrator.


If there is an issue with ECL Permisison Denied that needs to be worked around then the permission identified in XPages logging (see Debugging ECL Permisison Denied above) can be added to the java.policy.

For example, if a trace file shows the following permission is being denied ,

NotesContext checkEcl: No permission for (java.lang.RuntimePermission getClassLoader)

it can be specified to be allowed by adding the following to the java.policy file under the Notes home directory

grant {
permission java.lang.RuntimePermission "getClassLoader";
};

Note: this permission grant will apply to all Signers in all XPages applications and should be added with caution.

If the permission has a target and a specific action, for example,

(java.util.PropertyPermission osgi.os read)

add the following to the java.policy

grant {
permission java.util.PropertyPermission "osgi.os","read";
};

jvm/lib/ext

As noted in the section above, the default java policy file, ${java.home}/lib/security/java.policy, used by Notes Client Java Agents is also used by XPages, and just as you can add JARs to the ${java.home}/jvm/lib/ext folder that will be trusted by Java Agents, the same JARs will also be trusted by the XPages Java Security Manager if classes are referenced from embedded Java code in an XPages application. Only copy JARs to this location as directed by the system administrator.


If there is an issue with ECL Permisison Denied that needs to be worked around then an option is to move the JAR with the classes that call the security sensitive Java operations out of the NSF and into the /jvm/lib/ext folder. The means that the classes in this JAR will be considered trusted. Then, if the code that executes the Java security sensitive operation is called from inside a doPrivileged() block, see listing 3 below, the Java Security Manager will only walk the execution stack to this point and not consider the untrusted XPages class that is on the stack and allow the operation to succeed.

String result = AccessController.doPrivileged(
new PrivilegedExceptionAction() {
public String run() throws Exception {

your code code here
return "result";

}
}
);

Listing 3: Example doPrivileged block of code.

Note that this work around involves distributing part of the XPages application outside the NSF and will incur an administrative overhead.

Limitations and Restrictions

This section provide information on limitations and restrictions related to security for XPages in the Notes Client.

It contains the following:

• Java Permissions managed by the Notes Client ECL
• Trusting signer for the XPages application Session
• Calling Java Agents from an XPages application

Java Permissionsmanaged by the Notes Client ECL

For custom Java code embedded in an XPages application, the initial set of Java Permission that can be managed, i.e. allowed or denied, through the Notes Client ECL is limited to the following three Java Permissions.
By default, all others Java Permission are not permitted by the XPages Java Security Manager. The list is restrictive for the initial release.

Trusting signer for the XPages application Session

When a user is presented with a Execution Security Alert (ESA) and they select "Trust the signer to execute this action for this Notes session", it may not behave as expected compared to a standard Notes Client application.

The reason is that XPages on the Notes Client is based on a Request/Response model - a new security context is created for each request. Every time the XPages Runtime processes a request it creates a new Notes Session, consequently, if the user selects "Trust the signer to execute this action for this Notes session" it can appear to have no effect as the user may assume that it will be in effect for the duration of the XPages application when it is only effective for the current request. Should the user retry the operation they will find that they will be presented with an Execution Security Alert again. This is effectively the same as selecting "Execute the action this one time".

Calling Java Agents from an XPages application

Calling Java Agents directly from an XPages application (running in the Notes Client) to run locally on the users workstation is not supported in this release. Calling a Java Agent to run on a Domino Server is supported.
The table below shows the supported configurations:

(*) This is not an XPages in the Notes Client configuration, it is the Domino XPages configuration and is shown for completeness.

Note that calling LotusScript Agents from an XPages application in the Notes Client is supported. Access to the standard Java APIs is possible through Java Connector and the XPages Java Security Manager will manage security for protected operations and enforce the XPages ECL checking.

Summary

This article should help the reader understand the role the existing Notes Client security mechanisms (Execution Control Lists and Execution Security Alerts) play in protecting a users workstation when running an XPages application.

Security for XPages in the Notes Client is integrated with the existing Notes Client security mechanisms to provide a familiar user experience for controlling and managing security on a user workstation. XPages gathers and stores all the design element signers for later use by the Notes Client ECL when a check to execute a protected operation is made. While back-end classes APIs were already ECL aware XPages uses a Java Security Manager to detect when custom Java code embedded in an XPages application attempts to execute protected operations from the standard Java API libraries and then maps the permission request to the Notes Client ECL checking.

In addition, various aspects of security from a user, developer and administrator were also highlighted.

Resources

Staying alert with Execution Control Lists
http://www.ibm.com/developerworks/lotus/library/ls-ECLs/

Java SE Security
http://java.sun.com/javase/technologies/security/

Java2 Platform Security Architecture
http://java.sun.com/j2se/1.5.0/docs/guide/security/spec/security-spec.doc.html

IBM Lotus Domino and Notes Information Center - IBM Lotus Domino Designer 8.5 - Properties and methods with ECL security
http://publib.boulder.ibm.com/infocenter/domhelp/v8r0/index.jsp?topic=/com.ibm.help.domino.designer85.doc